@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/src/definitions.ts

@@ -0,0 +1,156 @@
+/**
+ * Definition-driven rendering helpers (components/02-customer-ui-web.md
+ * §Definition-driven rendering; ADR-005). Tenant-agnostic: a Frontend renders
+ * forms and views from the Definitions the Interface API serves, and a Branded
+ * Product only adds presentation on top.
+ */
+
+import type { EntryDefinitionDetail, EntryDefinitionField, EntryKind, Field, FieldValueType, FolderNode } from "./types.js";
+
+/** The kind of an EntryDefinition as served by `/v0/definitions/entries/{arid}`; Definitions written before ADR-014 carry none and are files. */
+export function entryKind(def: Pick<EntryDefinitionDetail, "kind"> | { kind?: string } | null | undefined): EntryKind {
+  return def?.kind === "folder" ? "folder" : "file";
+}
+
+export function isFolderDefinition(def: Pick<EntryDefinitionDetail, "kind"> | { kind?: string } | null | undefined): boolean {
+  return entryKind(def) === "folder";
+}
+
+/** A folder tree flattened depth-first, each node with its depth and its trail of labels — what a "move to…" picker lists. */
+export function flattenFolders(tree: FolderNode[], depth = 0, trail: string[] = []): { node: FolderNode; depth: number; trail: string[] }[] {
+  const out: { node: FolderNode; depth: number; trail: string[] }[] = [];
+  for (const node of tree) {
+    const here = [...trail, node.label ?? "Untitled folder"];
+    out.push({ node, depth, trail: here });
+    out.push(...flattenFolders(node.children, depth + 1, here));
+  }
+  return out;
+}
+
+/** Whether `candidate` is `folder` itself or sits anywhere below it — the targets a folder must not be moved into. */
+export function isWithinFolder(tree: FolderNode[], folder: string, candidate: string): boolean {
+  const find = (nodes: FolderNode[]): FolderNode | null => {
+    for (const n of nodes) {
+      if (n.arid === folder) return n;
+      const hit = find(n.children);
+      if (hit) return hit;
+    }
+    return null;
+  };
+  const root = find(tree);
+  if (!root) return false;
+  const walk = (n: FolderNode): boolean => n.arid === candidate || n.children.some(walk);
+  return walk(root);
+}
+
+/** Declared Fields in display order (explicit `order`, then declaration order). */
+export function fieldsInOrder(def: Pick<EntryDefinitionDetail, "fields">): EntryDefinitionField[] {
+  return def.fields.map((f, i) => ({ f, i })).sort((a, b) => (a.f.order ?? a.i) - (b.f.order ?? b.i) || a.i - b.i).map((x) => x.f);
+}
+
+/** Which HTML input a value type wants. Tenants may override per Field through presentation hints. */
+export type Widget = "text" | "textarea" | "password" | "number" | "checkbox" | "date" | "datetime-local" | "email" | "tel" | "url" | "json" | "select" | "attachment";
+
+export function widgetFor(valueType: FieldValueType | undefined, opts: { enum?: unknown[]; long?: boolean } = {}): Widget {
+  if (opts.enum?.length) return "select";
+  switch (valueType) {
+    case "password":
+      return "password";
+    case "number":
+      return "number";
+    case "boolean":
+      return "checkbox";
+    case "date":
+      return "date";
+    case "datetime":
+      return "datetime-local";
+    case "email":
+      return "email";
+    case "phone":
+      return "tel";
+    case "url":
+      return "url";
+    case "json":
+      return "json";
+    case "attachment":
+      return "attachment";
+    case "text":
+    default:
+      return opts.long ? "textarea" : "text";
+  }
+}
+
+/** Turn a form string into the typed value the Interface API validates (`validateFieldValue`). */
+export function coerceInput(valueType: FieldValueType | undefined, raw: string | boolean | null | undefined): unknown {
+  if (raw === undefined || raw === null) return null;
+  if (typeof raw === "boolean") return raw;
+  const s = raw.trim();
+  if (s === "") return null;
+  switch (valueType) {
+    case "number": {
+      const n = Number(s);
+      return Number.isFinite(n) ? n : s;
+    }
+    case "boolean":
+      return s === "true" || s === "on" || s === "1";
+    case "json":
+      try {
+        return JSON.parse(s);
+      } catch {
+        return s;
+      }
+    case "datetime":
+      // `datetime-local` yields a local wall-clock time without a zone; the API wants ISO 8601.
+      return /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(:\d{2})?$/.test(s) ? new Date(s).toISOString() : s;
+    default:
+      return s;
+  }
+}
+
+/** A value for a form control (the reverse of {@link coerceInput}). */
+export function inputValue(valueType: FieldValueType | undefined, value: unknown): string {
+  if (value === null || value === undefined) return "";
+  switch (valueType) {
+    case "json":
+      return typeof value === "string" ? value : JSON.stringify(value, null, 2);
+    case "datetime":
+      if (typeof value === "string" && !Number.isNaN(Date.parse(value))) {
+        const d = new Date(value);
+        const pad = (n: number) => String(n).padStart(2, "0");
+        return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}T${pad(d.getHours())}:${pad(d.getMinutes())}`;
+      }
+      return String(value);
+    default:
+      return typeof value === "string" ? value : JSON.stringify(value);
+  }
+}
+
+/** Human display of a value; secrets are shown only after a reveal, which the caller decides. */
+export function formatValue(valueType: FieldValueType | undefined, value: unknown, locale = "en-GB"): string {
+  if (value === null || value === undefined || value === "") return "—";
+  switch (valueType) {
+    case "boolean":
+      return value ? "Yes" : "No";
+    case "date":
+      return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? new Intl.DateTimeFormat(locale, { day: "numeric", month: "short", year: "numeric", timeZone: "UTC" }).format(new Date(value)) : String(value);
+    case "datetime":
+      return typeof value === "string" && !Number.isNaN(Date.parse(value)) ? new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeStyle: "short" }).format(new Date(value)) : String(value);
+    case "number":
+      return typeof value === "number" ? new Intl.NumberFormat(locale).format(value) : String(value);
+    case "json":
+      return typeof value === "string" ? value : JSON.stringify(value);
+    default:
+      return typeof value === "string" ? value : JSON.stringify(value);
+  }
+}
+
+/** The first non-secret Field value that can serve as an Entry's title, by preferred names then by order. */
+export function entryTitle(entry: { label?: string; fields: Field[] }, preferredNames: readonly string[] = []): string {
+  if (entry.label) return entry.label;
+  for (const n of preferredNames) {
+    const f = entry.fields.find((x) => x.name === n && !x.secret && x.value !== null && x.value !== undefined && x.value !== "");
+    if (f) return String(f.value);
+  }
+  const f = entry.fields.find((x) => !x.secret && (x.value_type === "text" || x.value_type === "email" || x.value_type === "url") && typeof x.value === "string" && x.value);
+  return f ? String(f.value) : "Untitled";
+}

package/src/enrolment.ts

@@ -0,0 +1,10 @@
+/**
+ * Closing enrolment (ADR-044): whether a Tenant takes new Customers. An
+ * administrator pauses it with a switch, or sets a maximum number of
+ * Customers after which it closes by itself. Existing Customers sign in
+ * either way; only a first sign-in that would enrol a Customer is refused.
+ */
+
+
+/** What `GET /v0/status/:arid` and `GET /v0/portal/presentation` say: no reason and no count. */
+export type EnrolmentState = "open" | "closed";

package/src/fill.ts

@@ -0,0 +1,83 @@
+/**
+ * Fill modes (ADR-046). A Field's value type says what its value is; its fill
+ * mode says where the value comes from: `value` (the Field stores it),
+ * `internal` (the Field stores an ARID) or `external` (the Field stores a
+ * locator for something outside Asturiu, which the Engine never follows).
+ * Shared by the Engine and every client; dependency-free.
+ */
+
+import type { FieldValueType } from "./types.js";
+
+export const FILL_MODES = ["value", "internal", "external"] as const;
+export type FillMode = (typeof FILL_MODES)[number];
+
+/** The Engine's own limit on a locator; a Tenant's `locator.max_length` sits within it. */
+export const LOCATOR_MAX_LENGTH = 2048;
+/** A reference's optional label: as long as a Definition label. */
+export const REFERENCE_LABEL_MAX = 200;
+
+/** A Tenant's rule for the locators of one field. */
+export interface LocatorRule {
+  pattern?: string;
+  max_length?: number;
+}
+
+/** What a write sends in place of `value`: `PUT /v0/fields/{arid}`, and per field in Entry writes. */
+export type FieldRefInput = { arid: string; label?: string | null } | { locator: string; label?: string | null };
+
+/** `ref` on a Field filled by an internal reference. `readable` and `value_type` are left out under `?resolve=false`. */
+export interface InternalFieldRef {
+  arid: string;
+  /** The ARID's type token. */
+  type: string;
+  label: string | null;
+  /** Whether the reader may read the target. `false` also when it does not exist; the two are not told apart. */
+  readable?: boolean;
+  /** For a Field target the reader may read: its value type, which may differ from the referencing Field's. */
+  value_type?: FieldValueType;
+}
+
+/** `ref` on a Field filled by an external reference: the locator exactly as written. */
+export interface ExternalFieldRef {
+  locator: string;
+  label: string | null;
+}
+
+export type FieldRef = InternalFieldRef | ExternalFieldRef;
+
+export function isInternalRef(ref: FieldRef | null | undefined): ref is InternalFieldRef {
+  return !!ref && typeof (ref as InternalFieldRef).arid === "string";
+}
+
+export function isExternalRef(ref: FieldRef | null | undefined): ref is ExternalFieldRef {
+  return !!ref && typeof (ref as ExternalFieldRef).locator === "string";
+}
+
+/**
+ * The modes a field allows: every list given narrows the one before it, and
+ * the order of the narrowest list wins — its first mode is the one a form
+ * preselects. An absent or empty list narrows nothing, so with no lists at all
+ * every mode is allowed.
+ */
+export function effectiveFillModes(...lists: (readonly FillMode[] | null | undefined)[]): FillMode[] {
+  let out: FillMode[] = [...FILL_MODES];
+  for (const list of lists) {
+    if (!list?.length) continue;
+    out = list.filter((m, i) => out.includes(m) && list.indexOf(m) === i);
+  }
+  return out;
+}
+
+/** A Field's fill as a frontend reads it. */
+export type FieldFillView = { mode: "value" } | { mode: "internal"; ref: InternalFieldRef } | { mode: "external"; ref: ExternalFieldRef };
+
+/**
+ * A Field's mode and, for a reference, where it points — from a Field
+ * representation. A representation from before ADR-046 carries no
+ * `filled_by` and reads as filled by value.
+ */
+export function fieldFillOf(field: { filled_by?: FillMode | null; ref?: FieldRef | null }): FieldFillView {
+  if (field.filled_by === "internal" && isInternalRef(field.ref)) return { mode: "internal", ref: field.ref };
+  if (field.filled_by === "external" && isExternalRef(field.ref)) return { mode: "external", ref: field.ref };
+  return { mode: "value" };
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * `@asturiu/v0-sdk`: the Tenant SDK for Asturiu v0 (ADR-074). Everything a
+ * Tenant's application calls, types against or writes files for: the `/v0`
+ * client and its types, the sign-in and the session cookies, the Definition
+ * set, branding and portal files, and the signed Tenant API calls.
+ *
+ * Dependency-free; runs in Node, edge runtimes and browsers. The Tenant API
+ * calls sign only on a server: a Tenant key never reaches a browser. The
+ * command line (`asturiu-v0-tenant`) and `@asturiu/v0-sdk/testing` run in
+ * Node and are never loaded from here.
+ */
+export * from "./version.js";
+export * from "./types.js";
+export * from "./client.js";
+export * from "./oidc.js";
+export * from "./seal.js";
+export * from "./session.js";
+export * from "./signing-in.js";
+export * from "./definitions.js";
+export * from "./urlid.js";
+export * from "./tags.js";
+export * from "./tiers.js";
+export * from "./tickets.js";
+export * from "./changesets.js";
+export * from "./reveal.js";
+export * from "./contacts.js";
+export * from "./portal-options.js";
+export * from "./branding.js";
+export * from "./theme.js";
+export * from "./overlay.js";
+export * from "./definition-set.js";
+export * from "./fill.js";
+export * from "./passes.js";
+export * from "./notifications.js";
+export * from "./enrolment.js";
+export * from "./reads.js";
+export * from "./recovery.js";
+export * from "./tenant-subscription.js";

package/src/notifications.ts

@@ -0,0 +1,55 @@
+/**
+ * Which Notifications a Customer also receives by e-mail (ADR-041 §5). Every
+ * choice is off until the Customer switches it on, per Tenant. Pure and
+ * dependency-free: the Interface API and the Operations API resolve a
+ * Notification's channel with these lists, the Customer Portal and a Tenant's
+ * app draw the switches from them.
+ */
+
+export const NOTIFICATION_EMAIL_CHOICES = ["shares", "transfers", "contacts", "messages", "recovery", "triggers", "updates", "tickets"] as const;
+export type NotificationEmailChoice = (typeof NOTIFICATION_EMAIL_CHOICES)[number];
+
+/** The Notification kinds each choice covers. A kind that is in no list (`delivery_failed`) is in-app only. */
+export const NOTIFICATION_EMAIL_KINDS: Record<NotificationEmailChoice, readonly string[]> = {
+  shares: ["grant", "pass_locked"],
+  transfers: ["transfer"],
+  contacts: ["contact"],
+  messages: ["message"],
+  // An invitation, a new card and the owner's alert are mailed whatever the choice (ADR-050 §7); the rest follow it.
+  recovery: ["recovery_invite", "recovery_card_replaced", "recovery_claim", "recovery_done", "recovery_ended"],
+  triggers: ["trigger_fired", "trigger_warning"],
+  updates: ["definitions_attention"],
+  // A reply on a request of the Customer's, or a move to waiting or resolved (ADR-058 §11).
+  tickets: ["ticket"],
+};
+
+/** The choice a Notification kind falls under, or `null` when the kind never goes by e-mail to a Customer. */
+export function emailChoiceOf(kind: string): NotificationEmailChoice | null {
+  for (const choice of NOTIFICATION_EMAIL_CHOICES) if (NOTIFICATION_EMAIL_KINDS[choice].includes(kind)) return choice;
+  return null;
+}
+
+export function isNotificationEmailChoice(v: unknown): v is NotificationEmailChoice {
+  return typeof v === "string" && (NOTIFICATION_EMAIL_CHOICES as readonly string[]).includes(v);
+}
+
+/** Every choice with its value; what is not listed is off. */
+export function emailChoicesFrom(on: readonly string[] | undefined | null): Record<NotificationEmailChoice, boolean> {
+  return Object.fromEntries(NOTIFICATION_EMAIL_CHOICES.map((c) => [c, !!on?.includes(c)])) as Record<NotificationEmailChoice, boolean>;
+}
+
+/**
+ * `GET /v0/customer/notifications`. `available` is false while the Customer's
+ * sign-in has no verified e-mail address: then no switch can be turned on.
+ */
+export interface NotificationEmailSettings {
+  email: {
+    available: boolean;
+    kinds: Record<NotificationEmailChoice, boolean>;
+  };
+}
+
+/** `PUT /v0/customer/notifications`: name the choices to change; the rest keep their value. */
+export interface NotificationEmailSettingsUpdate {
+  email: { kinds: Partial<Record<NotificationEmailChoice, boolean>> };
+}

package/src/oidc.ts

@@ -0,0 +1,199 @@
+/**
+ * OIDC helpers for the Frontend layer (components/02-customer-ui-web.md §Login
+ * completion; flows/authentication.md). Dependency-free: Web Crypto only, so
+ * the same code runs in a Next.js route handler, an edge runtime or Node.
+ */
+
+/** Authentik OIDC endpoints for an Application slug, relative to a base URL. */
+export function oidcEndpoints(base: string, slug: string) {
+  const b = base.replace(/\/+$/, "");
+  return {
+    issuer: `${b}/application/o/${slug}/`,
+    authorize: `${b}/application/o/authorize/`,
+    token: `${b}/application/o/token/`,
+    userinfo: `${b}/application/o/userinfo/`,
+    jwks: `${b}/application/o/${slug}/jwks/`,
+    endSession: `${b}/application/o/${slug}/end-session/`,
+    /** The Tenant's authentication, enrolment and recovery flows (components/11-authentik.md §One Application per Tenant). */
+    authentication: `${b}/if/flow/${tenantFlowSlug(slug, "authentication")}/`,
+    enrollment: `${b}/if/flow/${tenantFlowSlug(slug, "enrollment")}/`,
+    recovery: `${b}/if/flow/${tenantFlowSlug(slug, "recovery")}/`,
+    /** The step-up flows (ADR-018): confirm the password, or the password and a second factor, on the live Authentik session. */
+    stepUpPassword: `${b}/if/flow/${tenantFlowSlug(slug, "stepup-password")}/`,
+    stepUp2fa: `${b}/if/flow/${tenantFlowSlug(slug, "stepup-2fa")}/`,
+    /** Change the password (ADR-022); ends in a fresh authorization request. */
+    passwordChange: `${b}/if/flow/${tenantFlowSlug(slug, "password-change")}/`,
+    /** Register with the Tenant using an existing shared account: its own sign-in, then a review (ADR-043, ADR-051); `shared` Tenants only. */
+    join: `${b}/if/flow/${tenantFlowSlug(slug, "join")}/`,
+  };
+}
+
+/**
+ * The message of a Tenant sign-in that refuses an account outside the Tenant
+ * (ADR-051): the Operations API's blueprint gives its deny stage this text,
+ * and the Customer Portal recognises it to show its own "register first" step.
+ * Readable as it is, for any page that shows Authentik's own words.
+ */
+export const NOT_REGISTERED_DENIAL = "This account is not registered here yet. Register first, then sign in.";
+
+/**
+ * The message of a sign-up form that refuses an e-mail address another account
+ * has (ADR-053): the Operations API's blueprint gives the enrolment prompt's
+ * validation policy this text, and the Customer Portal recognises it to show
+ * it in the page's language. It says nothing about who has the address.
+ */
+export const EMAIL_NOT_ALLOWED = "This e-mail address is not allowed.";
+
+/** Every flow the Operations API provisions per Tenant, named `<slug>-<kind>` (components/11-authentik.md). */
+export const TENANT_FLOW_KINDS = ["authentication", "enrollment", "recovery", "invalidation", "stepup-password", "stepup-2fa", "password-change", "source-enrollment", "source-authentication", "join"] as const;
+/** The platform's account Application's flows (ADR-022, ADR-032; the step-ups since ADR-022 build note 1). */
+export const ACCOUNT_FLOW_KINDS = ["authentication", "recovery", "invalidation", "password-change", "stepup-password", "stepup-2fa"] as const;
+/** The administrative Application's flows (ADR-032). */
+export const ADMIN_FLOW_KINDS = ["authentication", "invalidation"] as const;
+
+export type TenantFlowKind = (typeof TENANT_FLOW_KINDS)[number];
+
+/** A flow slug: `<slug>-<kind>`, as the Operations API names every flow it provisions. */
+export function tenantFlowSlug(slug: string, kind: TenantFlowKind): string {
+  return `${slug}-${kind}`;
+}
+
+/**
+ * The exact flow slugs an Application owns (ADR-032). A sign-in host runs
+ * these and nothing else; a prefix would not do, because slugs contain
+ * hyphens — `acme-` also matches `acme-labs-…`.
+ */
+export function flowSlugsOf(slug: string, kinds: readonly TenantFlowKind[] = TENANT_FLOW_KINDS): string[] {
+  return kinds.map((k) => tenantFlowSlug(slug, k));
+}
+
+/**
+ * Run a Tenant flow first, then the authorization request: Authentik executes
+ * the flow and, when its last stage is done, continues to `next` — the
+ * authorization request — so the Web UI's callback completes as usual. Used
+ * for enrolment (a session exists once the login stage ran) and for step-up
+ * (the session's login event is fresh, so the token proves what just happened).
+ */
+export function buildFlowUrl(flowEndpoint: string, authorizeUrl: string): string {
+  const url = new URL(flowEndpoint);
+  const authorize = new URL(authorizeUrl);
+  // Authentik accepts `next` as a path on its own host (the form its own redirects use); an absolute URL is not carried through the flow.
+  url.searchParams.set("next", authorize.origin === url.origin ? `${authorize.pathname}${authorize.search}` : authorizeUrl);
+  return url.toString();
+}
+
+/** Start enrolment instead of login (see `buildFlowUrl`). */
+export function buildEnrollmentUrl(enrollmentEndpoint: string, authorizeUrl: string): string {
+  return buildFlowUrl(enrollmentEndpoint, authorizeUrl);
+}
+
+export type OidcEndpoints = ReturnType<typeof oidcEndpoints>;
+
+export const OIDC_SCOPE = "openid email profile";
+
+function b64url(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  const base64 = typeof btoa === "function" ? btoa(s) : Buffer.from(bytes).toString("base64");
+  return base64.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function randomToken(bytes = 32): string {
+  const out = new Uint8Array(bytes);
+  crypto.getRandomValues(out);
+  return b64url(out);
+}
+
+export interface Pkce {
+  verifier: string;
+  challenge: string;
+  method: "S256";
+}
+
+/** A fresh PKCE pair per login attempt (RFC 7636, S256). */
+export async function createPkce(): Promise<Pkce> {
+  const verifier = randomToken(48);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return { verifier, challenge: b64url(new Uint8Array(digest)), method: "S256" };
+}
+
+export interface AuthorizeRequest {
+  authorizeEndpoint: string;
+  clientId: string;
+  redirectUri: string;
+  state: string;
+  codeChallenge: string;
+  scope?: string;
+  /** Passed through to Authentik as-is (`prompt`, `login_hint`, …). */
+  extra?: Record<string, string>;
+}
+
+/** The authorization-code request the Web UI starts; PKCE and `state` are mandatory. */
+export function buildAuthorizeUrl(r: AuthorizeRequest): string {
+  const url = new URL(r.authorizeEndpoint);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("client_id", r.clientId);
+  url.searchParams.set("redirect_uri", r.redirectUri);
+  url.searchParams.set("scope", r.scope ?? OIDC_SCOPE);
+  url.searchParams.set("state", r.state);
+  url.searchParams.set("code_challenge", r.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  for (const [k, v] of Object.entries(r.extra ?? {})) url.searchParams.set(k, v);
+  return url.toString();
+}
+
+export interface TokenResponse {
+  access_token: string;
+  id_token?: string;
+  token_type?: string;
+  expires_in?: number;
+  scope?: string;
+}
+
+export class OidcError extends Error {
+  constructor(
+    readonly code: string,
+    readonly description?: string,
+    readonly status?: number,
+  ) {
+    super(description ? `${code}: ${description}` : code);
+    this.name = "OidcError";
+  }
+}
+
+export interface CodeExchange {
+  tokenEndpoint: string;
+  clientId: string;
+  code: string;
+  redirectUri: string;
+  codeVerifier: string;
+  /** Confidential clients only; Tenant Providers are public clients. */
+  clientSecret?: string;
+  fetch?: typeof fetch;
+  timeoutMs?: number;
+}
+
+/** Back-channel code exchange with the PKCE verifier. The token is exchanged for a session and then discarded. */
+export async function exchangeCode(x: CodeExchange): Promise<TokenResponse> {
+  const form = new URLSearchParams({ grant_type: "authorization_code", client_id: x.clientId, code: x.code, redirect_uri: x.redirectUri, code_verifier: x.codeVerifier });
+  if (x.clientSecret) form.set("client_secret", x.clientSecret);
+  const f: typeof fetch = x.fetch ?? ((input, init) => globalThis.fetch(input, init)); // called on the global, never as a detached method
+  const res = await f(x.tokenEndpoint, { method: "POST", headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" }, body: form, signal: AbortSignal.timeout(x.timeoutMs ?? 15000) });
+  const json = (await res.json().catch(() => ({}))) as Partial<TokenResponse> & { error?: string; error_description?: string };
+  if (!res.ok || !json.access_token) throw new OidcError(json.error ?? `http_${res.status}`, json.error_description, res.status);
+  return json as TokenResponse;
+}
+
+/**
+ * Where to send the browser after the Engine session is gone, so Authentik's
+ * own session ends too. Authentik (2025.10) does not read
+ * `post_logout_redirect_uri`: the Tenant's invalidation flow signs the person
+ * out and redirects to the Tenant's site (`branding.product_url`,
+ * components/11-authentik.md §No portal for customers). The parameter is kept
+ * for a conforming provider.
+ */
+export function buildEndSessionUrl(endSessionEndpoint: string, postLogoutRedirectUri?: string): string {
+  const url = new URL(endSessionEndpoint);
+  if (postLogoutRedirectUri) url.searchParams.set("post_logout_redirect_uri", postLogoutRedirectUri);
+  return url.toString();
+}