@asturiu/v0-sdk 0.0.0-stage → 1.0.0

package/dist/oidc.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 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 declare function oidcEndpoints(base: string, slug: string): {
+    issuer: string;
+    authorize: string;
+    token: string;
+    userinfo: string;
+    jwks: string;
+    endSession: string;
+    /** The Tenant's authentication, enrolment and recovery flows (components/11-authentik.md §One Application per Tenant). */
+    authentication: string;
+    enrollment: string;
+    recovery: string;
+    /** The step-up flows (ADR-018): confirm the password, or the password and a second factor, on the live Authentik session. */
+    stepUpPassword: string;
+    stepUp2fa: string;
+    /** Change the password (ADR-022); ends in a fresh authorization request. */
+    passwordChange: string;
+    /** Register with the Tenant using an existing shared account: its own sign-in, then a review (ADR-043, ADR-051); `shared` Tenants only. */
+    join: string;
+};
+/**
+ * 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 declare 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 declare 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 declare const TENANT_FLOW_KINDS: readonly ["authentication", "enrollment", "recovery", "invalidation", "stepup-password", "stepup-2fa", "password-change", "source-enrollment", "source-authentication", "join"];
+/** The platform's account Application's flows (ADR-022, ADR-032; the step-ups since ADR-022 build note 1). */
+export declare const ACCOUNT_FLOW_KINDS: readonly ["authentication", "recovery", "invalidation", "password-change", "stepup-password", "stepup-2fa"];
+/** The administrative Application's flows (ADR-032). */
+export declare const ADMIN_FLOW_KINDS: readonly ["authentication", "invalidation"];
+export type TenantFlowKind = (typeof TENANT_FLOW_KINDS)[number];
+/** A flow slug: `<slug>-<kind>`, as the Operations API names every flow it provisions. */
+export declare function tenantFlowSlug(slug: string, kind: TenantFlowKind): string;
+/**
+ * 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 declare function flowSlugsOf(slug: string, kinds?: readonly TenantFlowKind[]): string[];
+/**
+ * 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 declare function buildFlowUrl(flowEndpoint: string, authorizeUrl: string): string;
+/** Start enrolment instead of login (see `buildFlowUrl`). */
+export declare function buildEnrollmentUrl(enrollmentEndpoint: string, authorizeUrl: string): string;
+export type OidcEndpoints = ReturnType<typeof oidcEndpoints>;
+export declare const OIDC_SCOPE = "openid email profile";
+export declare function randomToken(bytes?: number): string;
+export interface Pkce {
+    verifier: string;
+    challenge: string;
+    method: "S256";
+}
+/** A fresh PKCE pair per login attempt (RFC 7636, S256). */
+export declare function createPkce(): Promise<Pkce>;
+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 declare function buildAuthorizeUrl(r: AuthorizeRequest): string;
+export interface TokenResponse {
+    access_token: string;
+    id_token?: string;
+    token_type?: string;
+    expires_in?: number;
+    scope?: string;
+}
+export declare class OidcError extends Error {
+    readonly code: string;
+    readonly description?: string | undefined;
+    readonly status?: number | undefined;
+    constructor(code: string, description?: string | undefined, status?: number | undefined);
+}
+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 declare function exchangeCode(x: CodeExchange): Promise<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 declare function buildEndSessionUrl(endSessionEndpoint: string, postLogoutRedirectUri?: string): string;
+//# sourceMappingURL=oidc.d.ts.map

package/dist/oidc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.d.ts","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"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"}

package/dist/oidc.js

@@ -0,0 +1,150 @@
+/**
+ * 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, slug) {
+    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"];
+/** 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"];
+/** The administrative Application's flows (ADR-032). */
+export const ADMIN_FLOW_KINDS = ["authentication", "invalidation"];
+/** A flow slug: `<slug>-<kind>`, as the Operations API names every flow it provisions. */
+export function tenantFlowSlug(slug, kind) {
+    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, kinds = TENANT_FLOW_KINDS) {
+    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, authorizeUrl) {
+    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, authorizeUrl) {
+    return buildFlowUrl(enrollmentEndpoint, authorizeUrl);
+}
+export const OIDC_SCOPE = "openid email profile";
+function b64url(bytes) {
+    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) {
+    const out = new Uint8Array(bytes);
+    crypto.getRandomValues(out);
+    return b64url(out);
+}
+/** A fresh PKCE pair per login attempt (RFC 7636, S256). */
+export async function createPkce() {
+    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" };
+}
+/** The authorization-code request the Web UI starts; PKCE and `state` are mandatory. */
+export function buildAuthorizeUrl(r) {
+    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 class OidcError extends Error {
+    code;
+    description;
+    status;
+    constructor(code, description, status) {
+        super(description ? `${code}: ${description}` : code);
+        this.code = code;
+        this.description = description;
+        this.status = status;
+        this.name = "OidcError";
+    }
+}
+/** Back-channel code exchange with the PKCE verifier. The token is exchanged for a session and then discarded. */
+export async function exchangeCode(x) {
+    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 = 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(() => ({})));
+    if (!res.ok || !json.access_token)
+        throw new OidcError(json.error ?? `http_${res.status}`, json.error_description, res.status);
+    return json;
+}
+/**
+ * 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, postLogoutRedirectUri) {
+    const url = new URL(endSessionEndpoint);
+    if (postLogoutRedirectUri)
+        url.searchParams.set("post_logout_redirect_uri", postLogoutRedirectUri);
+    return url.toString();
+}
+//# sourceMappingURL=oidc.js.map

package/dist/oidc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oidc.js","sourceRoot":"","sources":["../src/oidc.ts"],"names":[],"mappings":"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"}

package/dist/overlay.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Wallet overlays (ADR-028): a Customer's renames, layout and custom fields
+ * for one Wallet. Shared by the Engine (validation, the reveal gate) and every
+ * frontend (forms, labels): pure and dependency-free so the Frontend kit can
+ * carry it.
+ */
+import { type RevealLevel } from "./reveal.js";
+import type { EntryDefinitionDetail, EntryDefinitionField, FieldValueType } from "./types.js";
+import type { FillMode, LocatorRule } from "./fill.js";
+/** The key of a custom field: `x_` and a ULID, generated by the Engine. */
+export declare const CUSTOM_FIELD_ID: RegExp;
+export declare function isCustomFieldId(value: unknown): value is string;
+/** How strict a reveal level is: a higher rank asks more of the person. `null` (a plain field) ranks lowest. */
+export declare function revealRank(level: RevealLevel | null | undefined): number;
+/** One custom field of a Wallet overlay. */
+export interface CustomFieldSpec {
+    id: string;
+    /** The Entry type it applies to (`edf` ARID). */
+    entry_definition: string;
+    label: string;
+    description?: string;
+    value_type: FieldValueType;
+    validation?: {
+        pattern?: string;
+        min?: number;
+        max?: number;
+        min_length?: number;
+        max_length?: number;
+        enum?: (string | number | boolean)[];
+    };
+    /** Required on Entries created after it was added, and wherever it holds a value. */
+    required: boolean;
+    secret: boolean;
+    /** Only with `secret`; `click` when absent. Never below the Entry type's `secret_reveal_min`. */
+    reveal?: RevealLevel;
+    searchable: boolean;
+    /** ADR-046, as on a FieldDefinition: the modes allowed (absent: what the Entry type's `custom_filled_by` allows), what an internal reference may point at, the locator rule. */
+    filled_by?: FillMode[];
+    targets?: string[];
+    target_definitions?: string[];
+    locator?: LocatorRule;
+}
+/** Order and hidden Tenant fields for one Entry type. `order` lists field keys: `fdf` ARIDs and `x_` ids. */
+export interface OverlayLayout {
+    order?: string[];
+    hidden?: string[];
+}
+/** The document `PUT /v0/wallets/{arid}/overlay` takes. A new custom field omits `id`. */
+export interface WalletOverlayInput {
+    renames?: Record<string, string>;
+    layout?: Record<string, OverlayLayout>;
+    fields?: (Omit<CustomFieldSpec, "id" | "required" | "secret" | "searchable"> & {
+        id?: string;
+        required?: boolean;
+        secret?: boolean;
+        searchable?: boolean;
+    })[];
+}
+/** What the Wallet owner's subscription level allows, and what the overlay uses of it. */
+export interface OverlayAllowance {
+    level: string;
+    rename: boolean;
+    arrange: boolean;
+    secret_fields: boolean;
+    extra_fields: {
+        max: number;
+        used: number;
+    };
+    searchable_fields: {
+        max: number;
+        used: number;
+    };
+}
+/** `GET /v0/wallets/{arid}/overlay`. `arid` and `version` are `null` until the Wallet is first customised. */
+export interface WalletOverlay {
+    wallet: string;
+    arid: string | null;
+    version: number | null;
+    renames: Record<string, string>;
+    layout: Record<string, OverlayLayout>;
+    fields: CustomFieldSpec[];
+    allowance: OverlayAllowance;
+}
+/** One field of a form or a view, Tenant or custom, as the overlay presents it. */
+export interface FormField {
+    /** `fdf` ARID for a Tenant field, `x_` id for a custom one. */
+    key: string;
+    custom: boolean;
+    label: string;
+    description?: string;
+    value_type?: FieldValueType;
+    secret: boolean;
+    reveal?: RevealLevel;
+    searchable: boolean;
+    required: boolean;
+    hidden: boolean;
+    /** The Tenant's declaration, for a Tenant field. */
+    definition?: EntryDefinitionField;
+    /** The overlay's spec, for a custom field. */
+    spec?: CustomFieldSpec;
+}
+/**
+ * The fields of an Entry type in the order and with the names this Wallet's
+ * overlay gives them: the overlay's `order` first, then the remaining Tenant
+ * fields in the Tenant's order, then the remaining custom fields. Hidden
+ * fields are included and marked; leaving them out is the frontend's choice.
+ */
+export declare function orderedFormFields(def: Pick<EntryDefinitionDetail, "arid" | "fields">, overlay: Pick<WalletOverlay, "renames" | "layout" | "fields"> | null | undefined): FormField[];
+//# sourceMappingURL=overlay.d.ts.map

package/dist/overlay.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}

package/dist/overlay.js

@@ -0,0 +1,58 @@
+/**
+ * Wallet overlays (ADR-028): a Customer's renames, layout and custom fields
+ * for one Wallet. Shared by the Engine (validation, the reveal gate) and every
+ * frontend (forms, labels): pure and dependency-free so the Frontend kit can
+ * carry it.
+ */
+import { REVEAL_LEVELS } from "./reveal.js";
+/** The key of a custom field: `x_` and a ULID, generated by the Engine. */
+export const CUSTOM_FIELD_ID = /^x_[0-9A-HJKMNP-TV-Z]{26}$/;
+export function isCustomFieldId(value) {
+    return typeof value === "string" && CUSTOM_FIELD_ID.test(value);
+}
+/** How strict a reveal level is: a higher rank asks more of the person. `null` (a plain field) ranks lowest. */
+export function revealRank(level) {
+    return level ? REVEAL_LEVELS.indexOf(level) : -1;
+}
+/**
+ * The fields of an Entry type in the order and with the names this Wallet's
+ * overlay gives them: the overlay's `order` first, then the remaining Tenant
+ * fields in the Tenant's order, then the remaining custom fields. Hidden
+ * fields are included and marked; leaving them out is the frontend's choice.
+ */
+export function orderedFormFields(def, overlay) {
+    const tenant = 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(({ f }) => ({
+        key: f.definition.arid,
+        custom: false,
+        label: overlay?.renames?.[f.definition.arid] ?? f.label ?? f.name ?? f.definition.arid,
+        value_type: f.value_type,
+        secret: !!f.secret,
+        reveal: f.reveal,
+        searchable: !!f.searchable,
+        required: f.required,
+        hidden: false,
+        definition: f,
+    }));
+    const custom = (overlay?.fields ?? [])
+        .filter((s) => s.entry_definition === def.arid)
+        .map((s) => ({ key: s.id, custom: true, label: s.label, description: s.description, value_type: s.value_type, secret: s.secret, reveal: s.secret ? s.reveal ?? "click" : undefined, searchable: s.searchable, required: s.required, hidden: false, spec: s }));
+    const layout = overlay?.layout?.[def.arid];
+    const hidden = new Set(layout?.hidden ?? []);
+    const byKey = new Map([...tenant, ...custom].map((f) => [f.key, f]));
+    const out = [];
+    for (const k of layout?.order ?? []) {
+        const f = byKey.get(k);
+        if (f) {
+            out.push(f);
+            byKey.delete(k);
+        }
+    }
+    for (const f of [...tenant, ...custom])
+        if (byKey.has(f.key))
+            out.push(f);
+    return out.map((f) => ({ ...f, hidden: !f.custom && !f.required && hidden.has(f.key) }));
+}
+//# sourceMappingURL=overlay.js.map

package/dist/overlay.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay.js","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,aAAa,EAAoB,MAAM,aAAa,CAAC;AAI9D,2EAA2E;AAC3E,MAAM,CAAC,MAAM,eAAe,GAAG,4BAA4B,CAAC;AAE5D,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,eAAe,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;AAClE,CAAC;AAED,gHAAgH;AAChH,MAAM,UAAU,UAAU,CAAC,KAAqC;IAC9D,OAAO,KAAK,CAAC,CAAC,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC;AA6ED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAmD,EAAE,OAAgF;IACrK,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM;SACtB,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;SACzB,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;SACpE,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,EAAa,EAAE,CAAC,CAAC;QAC1B,GAAG,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI;QACtB,MAAM,EAAE,KAAK;QACb,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,UAAU,CAAC,IAAI;QACtF,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM;QAClB,MAAM,EAAE,CAAC,CAAC,MAAM;QAChB,UAAU,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU;QAC1B,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,MAAM,EAAE,KAAK;QACb,UAAU,EAAE,CAAC;KACd,CAAC,CAAC,CAAC;IACN,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,CAAC;SACnC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,gBAAgB,KAAK,GAAG,CAAC,IAAI,CAAC;SAC9C,GAAG,CAAC,CAAC,CAAC,EAAa,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,SAAS,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;IAC5Q,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACrE,MAAM,GAAG,GAAgB,EAAE,CAAC;IAC5B,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,KAAK,IAAI,EAAE,EAAE,CAAC;QACpC,MAAM,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACvB,IAAI,CAAC,EAAE,CAAC;YACN,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YACZ,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,MAAM,EAAE,GAAG,MAAM,CAAC;QAAE,IAAI,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC1E,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;AAC3F,CAAC"}

package/dist/passes.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Guest passes (ADR-040): the kinds and states of a pass, the code a person
+ * types, and what a Tenant switches on for its customers' passes. Pure and
+ * dependency-free: the Engine validates with these lists, the Customer
+ * Portal, the Admin UI and a Tenant's app read with them.
+ */
+/** `bearer`: a link for anyone, the token in the link. `email`: a code sent to one address, typed on the pass page. */
+export declare const PASS_KINDS: readonly ["bearer", "email"];
+export type PassKind = (typeof PASS_KINDS)[number];
+/** What is stored; `ended`, `expired` and `exhausted` are derived when read (`passState`). */
+export declare const PASS_STORED_STATES: readonly ["active", "locked", "revoked"];
+export type PassStoredState = (typeof PASS_STORED_STATES)[number];
+export declare const PASS_STATES: readonly ["active", "locked", "revoked", "ended", "expired", "exhausted"];
+export type PassState = (typeof PASS_STATES)[number];
+/** A link for anyone opens at once or behind a captcha; an e-mail pass always asks for its code. */
+export declare const PASS_GATES: readonly ["none", "captcha", "code"];
+export type PassGate = (typeof PASS_GATES)[number];
+/** Where an e-mail pass is opened: the Customer Portal's pass page, or the Tenant's own app. */
+export declare const PASS_PAGES: readonly ["portal", "app"];
+export type PassPage = (typeof PASS_PAGES)[number];
+export declare const PASS_LIMITS: {
+    readonly label: 120;
+    readonly message: 1000;
+    readonly appUrl: 2000;
+    readonly codeFailuresMin: 3;
+    readonly codeFailuresMax: 20;
+    readonly sessionsMax: 50;
+    readonly lifetimeDaysMax: 3650;
+    readonly passesPerLevelMax: 1000;
+    readonly opensMax: 100000;
+};
+/**
+ * The derived state of a pass. Terminal states come first, so a pass that is
+ * both expired and locked reads `expired`: only an `active` pass opens.
+ */
+export declare function passState(p: {
+    stored: PassStoredState;
+    not_after?: string | Date | null;
+    opens: number;
+    max_opens?: number | null;
+    bound?: boolean;
+}, now?: number): PassState;
+/** 32 capital letters and digits without 0, 1, I and O, so a code read aloud or typed again is not mistaken. */
+export declare const PASS_CODE_ALPHABET = "ABCDEFGHJKLMNPQRSTUVWXYZ23456789";
+/** 8 characters from 32: 40 bits, safe only behind the attempt limit (ADR-040 §6). */
+export declare const PASS_CODE_LENGTH = 8;
+/** What a person typed, as the Engine compares it: capitals, with spaces, dashes and dots dropped. */
+export declare function normalizePassCode(input: string): string;
+export declare function isPassCode(value: string): boolean;
+/** `ABCDEFGH` → `ABCD-EFGH`, the way the code is shown in the e-mail. */
+export declare function formatPassCode(code: string): string;
+/** `Tenant.passes` (ADR-040 §10), every key filled. */
+export interface TenantPassOptions {
+    bearer: boolean;
+    email: boolean;
+    page: PassPage;
+    /** The Tenant app's pass page: links for anyone, the handover, and `page: app`. */
+    app_url: string | null;
+    /** The latest end date a pass may have, in days; `null` also allows passes without an end date. */
+    max_lifetime_days: number | null;
+    code_failure_limit: number;
+    /** The ceiling for live guest sessions per pass. */
+    max_sessions: number;
+}
+export declare function defaultPassOptions(): TenantPassOptions;
+/** An http(s) URL without credentials, as a pass may point to; null otherwise. */
+export declare function passAppUrl(v: unknown): string | null;
+/**
+ * The rules a set of pass options must keep beyond its shape: an app address
+ * while either kind is on. One entry per problem, with
+ * its path under `passes`; the Engine's Tenant schema reports them as `422`.
+ */
+export declare function passOptionProblems(raw: unknown): {
+    path: (string | number)[];
+    message: string;
+}[];
+/**
+ * Stored or presented options as every reader takes them: anything missing or
+ * odd back to its default, so an older record or Interface API never breaks a
+ * page. Passes stay off unless a kind is on and the app address is good.
+ */
+export declare function resolvePassOptions(raw: unknown): TenantPassOptions;
+/** What the portal needs from `Tenant.passes`, on the public presentation. */
+export interface PassPresentation {
+    email: boolean;
+    page: PassPage;
+    app_url: string | null;
+}
+/** The latest end date a new pass may have, or `null` when passes without an end date are allowed. */
+export declare function passLatestEnd(options: TenantPassOptions, now?: number): Date | null;
+/** The address a link for anyone carries: the app's pass page with the token in the fragment, never sent to a server. */
+export declare function bearerPassUrl(appUrl: string, token: string): string;
+/** The app's pass page with one query parameter added (`handover`, or `pass` for a handle). */
+export declare function passAppTarget(appUrl: string, key: "handover" | "pass", value: string): string;
+//# sourceMappingURL=passes.d.ts.map

package/dist/passes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"passes.d.ts","sourceRoot":"","sources":["../src/passes.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,uHAAuH;AACvH,eAAO,MAAM,UAAU,8BAA+B,CAAC;AACvD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,8FAA8F;AAC9F,eAAO,MAAM,kBAAkB,0CAA2C,CAAC;AAC3E,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,eAAO,MAAM,WAAW,2EAA4E,CAAC;AACrG,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,oGAAoG;AACpG,eAAO,MAAM,UAAU,sCAAuC,CAAC;AAC/D,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,gGAAgG;AAChG,eAAO,MAAM,UAAU,4BAA6B,CAAC;AACrD,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC;AAEnD,eAAO,MAAM,WAAW;;;;;;;;;;CAUd,CAAC;AAEX;;;GAGG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,GAAG,GAAE,MAAmB,GAAG,SAAS,CAO1L;AAID,gHAAgH;AAChH,eAAO,MAAM,kBAAkB,qCAAqC,CAAC;AACrE,sFAAsF;AACtF,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAElC,sGAAsG;AACtG,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAIjD;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAGnD;AAID,uDAAuD;AACvD,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,mFAAmF;IACnF,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,mGAAmG;IACnG,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oDAAoD;IACpD,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,wBAAgB,kBAAkB,IAAI,iBAAiB,CAEtD;AAED,kFAAkF;AAClF,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAQpD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAAE,CAQjG;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAalE;AAED,8EAA8E;AAC9E,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,IAAI,EAAE,QAAQ,CAAC;IACf,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED,sGAAsG;AACtG,wBAAgB,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,GAAG,GAAE,MAAmB,GAAG,IAAI,GAAG,IAAI,CAE/F;AAED,yHAAyH;AACzH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,+FAA+F;AAC/F,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,UAAU,GAAG,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI7F"}