Skip to content

Open cited documents and refuse in the service's words on a hosted assistant - #837

Merged
nlundee merged 5 commits into
mainfrom
ka-gaps
Nov 19, 2026
Merged

nlundee merged 5 commits into
mainfrom
ka-gaps

Conversation

@nlundee

@nlundee nlundee commented Nov 19, 2026

Copy link
Copy Markdown
Collaborator

What and why

The generic gaps for a hosted assistant (M6 in #771), on top of #832:

  • Document file route. GET /api/datasets/{id}/documents/{doc}/file opens a cited document with the access of /api/datasets/{id}: the uploaded original, or a 302 to the source's own address when the dataset's documents come from a remote source, such as Kudos. Accept: application/json says what the file is instead (kind, mediaType, url).
  • Refusals in lockdown. A person a service's frontend does not let in gets the same problem types, but words for an end user in their language: «Denne assistenten er bare åpen for ansatte i Digdir i testmiljøet», with what to do.
  • Document links under any hostname. A layout's documentLinks may be a path on the host's own site, such as /api/datasets/kudos/documents/{id}/file.
  • Host view. GET /v1/hosts/{hostname} answers languages, the service's languages the host has words for. theme stays null, Designsystemet's default, until ADR 0063 is built.

Risk

Sensitive: a new frontend route over tenant data, and lockdown texts.

  • The original file is only for a caller of the organisation that owns the dataset, or a frontend of its service (confinedTo.tenant), as Search a dataset at an organisation's own endpoint, open a dataset to all, and download original files #760 keeps it. Another organisation that may search a shared dataset gets the source link, never the upload.
  • A PDF is served inline with nosniff and frame-ancestors 'self', so the document view can frame it; anything else is a sandboxed attachment.
  • The redirect goes only to an http or https address, without user name, password or fragment. genki does not fetch the remote file.
  • A site-path link must start with one /, never // or a backslash, and the number is encoded, so it cannot leave the host.
  • The refusal texts change only words, not who is let in.

Undo

A revert is enough.

How it was tested

  • npm run typecheck, npm run build, npm run boundaries, npm run atlas:build (no change) and npm run atlas:test, prettier and eslint on the changed files.

  • Full suites of apps/api, apps/portal, packages/adapter-rest, definitions, ui-assembly, ui-blocks, strategy-builder and apps/assistant.

  • New tests that state the rules:

    • packages/adapter-rest/src/rest.test.ts ("a document file"): sends a reader to the remote source, describes it as JSON, refuses a document without an http address, keeps the dataset's access rules, serves an original inline only as PDF.
    • apps/api/src/document-originals.test.ts: never read by another organisation, nor through a frontend of its service.
    • apps/api/src/lockdown.test.ts: the end-user words for a frontend's refused person and an Entra login through a service client, in bokmål and English; platform logins keep theirs.
    • apps/api/src/hosts.test.ts: offers the languages the service answers in.
    • packages/definitions, ui-blocks and ui-assembly: a document link on the host's own site, and no other relative link.
  • npm run check passes

Checklist

  • Every new rule has a test whose name states it
  • User-facing text is in the i18n catalogues, in bokmål and English, with no em-dashes
  • Vendor SDKs stay in packages/providers-*
  • ADRs, docs and docs/architecture/modules are updated if a contract, boundary or module changed
  • No secrets, personal data or local paths

A service's assistant layout now lives in its definition as spec.interface.layout, so the builder saves to and opens from the draft instead of the browser's session storage. The layout is drafted, checked, published and versioned with the service through the existing draft and publish routes; no new route, store or right.

The shape is closed and bounded in @genai/definitions: catalogue or x- block ids, boolean or string settings, profile texts as one string or { nb, en }, https document links, the builder's profile limits and 256 KiB for the whole interface. definitionSubject leaves the interface out, so a change of look alone keeps the eval runs a gate needs.

The builder writes only what the person changes, stores blocks the draft cannot back yet where they were chosen, refuses to edit a layout it would lose part of (texts per language, x- blocks), and offers once to save or discard a layout kept in the browser before.

ADR 0065 records the decision, building on the proposal for ADR 0056 in #570. The catalogue check on publish, the read route and the hosted assistant come later.
genki can now draw a service's assistant on a hostname of its own,
from the service's interface, without code from the service owner.

- A Client with spec.hosted and hostnames is a hosted frontend; its
  origins follow its hostnames, and an operator opens each hostname to
  one tenant with GENAI_HOSTED_HOSTNAMES.
- GET /v1/hosts/{hostname} and /pages/{id} answer what the host draws
  before login, and nothing more: no Client registration id, version,
  layout or profile. Every hostname that is not active gets the same
  404 urn:genai:problem:host-not-found. GET /v1/models/{id}/interface
  answers the layout after login.
- spec.interface gains menu and pages. A publish refuses a block the
  catalogue does not hold, and an x- block while genki hosts the
  service, reported together with a missing dataset.
- In lockdown a hosted Client in the platform tenant admits the
  service groups. Only a platform operator sets spec.hosted there,
  through platform.client.hosted, audited, and a tenant cannot move a
  hosted Client's client id.
- apps/assistant draws the name, menu, pages and the assistant, with
  dev login locally and a notice in production until the BFF.
- APP=assistant in the apps image, and Bicep behind
  assistantHostEnabled: its own environment, an identity with AcrPull
  only, and a Key Vault of its own.

ADR 0065 and ADR 0033 say what is built, including what the public
host route reveals. The hostname pattern's linear-time test now uses a
hard name within the 253-character limit, beside a test of the limit.
- Layout (#817 landed on main): took main's Builder.tsx and interface.test.tsx; kept M3's menu, pages and catalogue additions in definitions (service-interface, schema-labels, tests) and strategy-builder.
- ADR 0065: M3's edits now live in the renamed docs/adr/0065-assistant-layout-in-the-definition.md; the old file name is gone.
- ADR 0061: the public host answer names the OIDC client id only, and "Not built: all of it" now says what #832 builds and what is left.
- ADR 0033: main's status and one-environment text, plus the hosted Client line.
- docs/adr/README.md: main's table, ADR 0061 row now "partly built".
- docs/development.md: main's text, size budget list includes assistant and docs.
- infra/README.md and main.bicep: main's alerts, backups and budgets, plus the assistant host row and parameter.
- System atlas regenerated.
…sistant

The generic gaps a hosted assistant has left (M6 of #771):

- GET /api/datasets/{id}/documents/{doc}/file opens a cited document
  with the access of /api/datasets/{id}: the uploaded original, only
  for a caller of the organisation that owns the dataset or a frontend
  of its service, a PDF inline and anything else as a sandboxed
  attachment; otherwise a 302 to the source's own http or https
  address, for datasets whose documents come from a remote source.
  Accept: application/json says what the file is instead.
- In lockdown, a person a service's frontend does not let in, and an
  Entra login refused through a client that is not a platform client,
  get the same problem types with words for an end user, in bokmål and
  English.
- A layout's documentLinks may be a path on the host's own site, so a
  link opens under whatever hostname draws the assistant.
- GET /v1/hosts/{hostname} answers the service's languages the host has
  words for; the theme stays Designsystemet's default until ADR 0063.

ADRs 0033, 0054 and 0065, the frontend OpenAPI and docs/api say what is
built.
# Conflicts:
#	apps/api/src/hosts.test.ts
#	apps/api/src/hosts.ts
#	apps/api/src/openapi/access.ts
#	docs/adr/0033-locked-test-environment.md
#	docs/adr/0065-assistant-layout-in-the-definition.md
#	docs/development.md
@nlundee
nlundee added this pull request to the merge queue Nov 19, 2026
Merged via the queue into main with commit edbc7d3 Nov 19, 2026
18 checks passed
@nlundee
nlundee deleted the ka-gaps branch November 19, 2026 16:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant