@oatscenter/trellis 0.100.0-rc.1

package/auth/browser/flow_types.js

@@ -0,0 +1,70 @@
+import { Type } from "typebox";
+const OpenObjectSchema = Type.Object({}, { additionalProperties: true });
+const AppSchema = Type.Object({
+    displayName: Type.String({ minLength: 1 }),
+}, { additionalProperties: true });
+const ApprovalSchema = Type.Object({
+    contractId: Type.String({ minLength: 1 }),
+    contractDigest: Type.String({ minLength: 1 }),
+    displayName: Type.String({ minLength: 1 }),
+    description: Type.String(),
+    capabilities: Type.Record(Type.String(), Type.Object({
+        displayName: Type.String({ minLength: 1 }),
+        description: Type.String(),
+    })),
+});
+const UserSchema = Type.Object({
+    origin: Type.String({ minLength: 1 }),
+    id: Type.String({ minLength: 1 }),
+    name: Type.Optional(Type.String({ minLength: 1 })),
+    email: Type.Optional(Type.String({ minLength: 1 })),
+    image: Type.Optional(Type.String({ minLength: 1 })),
+});
+export const PortalFlowStateSchema = Type.Union([
+    Type.Object({
+        status: Type.Literal("choose_provider"),
+        flowId: Type.String({ minLength: 1 }),
+        providers: Type.Array(Type.Object({
+            id: Type.String({ minLength: 1 }),
+            displayName: Type.String({ minLength: 1 }),
+        })),
+        app: AppSchema,
+        portal: Type.Optional(OpenObjectSchema),
+        registration: Type.Optional(OpenObjectSchema),
+    }),
+    Type.Object({
+        status: Type.Literal("processing"),
+        flowId: Type.String({ minLength: 1 }),
+    }),
+    Type.Object({
+        status: Type.Literal("approval_required"),
+        flowId: Type.String({ minLength: 1 }),
+        consentViewDigest: Type.String({ minLength: 1 }),
+        optionalBundles: Type.Array(OpenObjectSchema),
+        user: UserSchema,
+        approval: ApprovalSchema,
+    }),
+    Type.Object({
+        status: Type.Literal("approval_denied"),
+        flowId: Type.String({ minLength: 1 }),
+        approval: ApprovalSchema,
+        returnLocation: Type.Optional(Type.String({ minLength: 1 })),
+    }),
+    Type.Object({
+        status: Type.Literal("insufficient_capabilities"),
+        flowId: Type.String({ minLength: 1 }),
+        user: Type.Optional(UserSchema),
+        approval: ApprovalSchema,
+        missingCapabilities: Type.Array(Type.String()),
+        userCapabilities: Type.Array(Type.String()),
+        returnLocation: Type.Optional(Type.String({ minLength: 1 })),
+    }),
+    Type.Object({
+        status: Type.Literal("redirect"),
+        location: Type.String({ minLength: 1 }),
+    }),
+    Type.Object({
+        status: Type.Literal("expired"),
+        returnLocation: Type.Optional(Type.String({ minLength: 1 })),
+    }),
+]);

package/auth/browser/portal.d.ts

@@ -0,0 +1,21 @@
+import { type PortalFlowState } from "./flow_types.ts";
+export type { PortalFlowState } from "./flow_types.ts";
+export type ApprovalDecision = "approved" | "denied";
+export type AuthConfig = {
+    authUrl: string;
+    /** Explicit portal origin for non-browser automation; browsers supply Origin. */
+    portalOrigin?: string;
+};
+export type PortalBinding = {
+    secret: string;
+    digest: string;
+};
+/** Returns the portal browser's per-flow verifier, creating it when absent. */
+export declare function createPortalBinding(): Promise<PortalBinding>;
+/** Returns the portal browser's per-flow verifier, creating it when absent. */
+export declare function getOrCreatePortalBinding(flowId: string, storage: Storage): Promise<PortalBinding>;
+export declare function portalFlowIdFromUrl(url: URL): string | null;
+export declare function fetchPortalFlowState(config: AuthConfig, flowId: string, binding: PortalBinding): Promise<PortalFlowState>;
+export declare function portalProviderLoginUrl(config: AuthConfig, providerId: string, flowId: string, binding: PortalBinding): string;
+export declare function submitPortalApproval(config: AuthConfig, flowId: string, binding: PortalBinding, decision: ApprovalDecision): Promise<PortalFlowState>;
+export declare function portalRedirectLocation(state: PortalFlowState | null): string | null;

package/auth/browser/portal.js

@@ -0,0 +1,307 @@
+import { decodeTrellisHttpError } from "../http_error.js";
+import { PortalFlowStateSchema } from "./flow_types.js";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+const PORTAL_BINDING_HEADER = "trellis-portal-binding";
+const PORTAL_BINDING_KEY_PREFIX = "trellis.portal-binding.v1:";
+function base64Url(bytes) {
+    let binary = "";
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+function decodeBase64Url(value) {
+    try {
+        const base64 = value.replaceAll("-", "+").replaceAll("_", "/");
+        const binary = atob(base64.padEnd(Math.ceil(base64.length / 4) * 4, "="));
+        return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    }
+    catch {
+        return null;
+    }
+}
+/** Returns the portal browser's per-flow verifier, creating it when absent. */
+export async function createPortalBinding() {
+    const bytes = crypto.getRandomValues(new Uint8Array(32));
+    return {
+        secret: base64Url(bytes),
+        digest: base64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes)))),
+    };
+}
+/** Returns the portal browser's per-flow verifier, creating it when absent. */
+export async function getOrCreatePortalBinding(flowId, storage) {
+    const key = `${PORTAL_BINDING_KEY_PREFIX}${flowId}`;
+    const stored = storage.getItem(key);
+    const storedBytes = stored ? decodeBase64Url(stored) : null;
+    let bytes;
+    let secret;
+    if (stored && storedBytes?.length === 32) {
+        bytes = storedBytes;
+        secret = stored;
+    }
+    else {
+        const created = await createPortalBinding();
+        const decoded = decodeBase64Url(created.secret);
+        if (!decoded)
+            throw new Error("generated portal binding is invalid");
+        bytes = decoded;
+        secret = created.secret;
+    }
+    if (secret !== stored)
+        storage.setItem(key, secret);
+    return {
+        secret,
+        digest: base64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", Uint8Array.from(bytes)))),
+    };
+}
+function authBaseUrl(config) {
+    return config.authUrl.replace(/\/$/, "");
+}
+const BrowserFlowWireProperties = {
+    flowId: Type.String({ minLength: 1 }),
+    expiresAt: Type.Integer(),
+    state: Type.Union([
+        Type.Literal("choose_provider"),
+        Type.Literal("authenticated"),
+        Type.Literal("approval_required"),
+        Type.Literal("approval_denied"),
+        Type.Literal("approved"),
+        Type.Literal("consumed"),
+        Type.Literal("expired"),
+    ]),
+    providers: Type.Array(Type.String({ minLength: 1 })),
+    registrationEnabled: Type.Boolean(),
+    federatedRegistrationEnabled: Type.Boolean(),
+    consentView: Type.Object({
+        participantId: Type.String({ minLength: 1 }),
+        packageDigest: Type.String({ minLength: 1 }),
+        installedRevision: Type.Integer({ minimum: 1 }),
+        expectedGrantRevision: Type.Integer({ minimum: 0 }),
+        capabilities: Type.Array(Type.Object({
+            id: Type.String({ minLength: 1 }),
+            title: Type.String(),
+            description: Type.String(),
+            consequence: Type.String(),
+            consentDigest: Type.String({ minLength: 1 }),
+            required: Type.Boolean(),
+            eligible: Type.Boolean(),
+            alreadyApproved: Type.Boolean(),
+        })),
+        resources: Type.Array(Type.Object({
+            kind: Type.Union([
+                Type.Literal("kv"),
+                Type.Literal("state"),
+                Type.Literal("store"),
+            ]),
+            name: Type.String({ minLength: 1 }),
+            title: Type.String(),
+            description: Type.String(),
+            required: Type.Boolean(),
+            requestedCommitment: Type.Record(Type.String(), Type.Unknown()),
+            actual: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+            change: Type.Union([
+                Type.Literal("new"),
+                Type.Literal("unchanged"),
+                Type.Literal("reduced"),
+                Type.Literal("expanded"),
+                Type.Literal("incompatible"),
+                Type.Literal("detached"),
+            ]),
+            eligible: Type.Boolean(),
+            alreadyApproved: Type.Boolean(),
+        })),
+        companion: Type.Optional(Type.Unknown()),
+        decisionDigest: Type.String({ minLength: 1 }),
+    }),
+    redirectTarget: Type.Optional(Type.Union([
+        Type.Null(),
+        Type.String({ minLength: 1 }),
+    ])),
+};
+const BrowserFlowWireSchema = Type.Object(BrowserFlowWireProperties);
+const PortalFlowWireSchema = Type.Object({
+    ...BrowserFlowWireProperties,
+    decisionDigest: Type.String({ minLength: 1 }),
+    user: Type.Object({
+        origin: Type.String({ minLength: 1 }),
+        id: Type.String({ minLength: 1 }),
+        name: Type.Optional(Type.String({ minLength: 1 })),
+        email: Type.Optional(Type.String({ minLength: 1 })),
+        image: Type.Optional(Type.String({ minLength: 1 })),
+    }),
+});
+function approval(wire) {
+    const capabilities = {};
+    for (const capability of wire.consentView.capabilities) {
+        capabilities[`capability:${capability.id}`] = {
+            displayName: capability.title || capability.id,
+            description: capability.description,
+        };
+    }
+    for (const resource of wire.consentView.resources) {
+        capabilities[`resource:${resource.kind}:${resource.name}`] = {
+            displayName: resource.title || resource.name,
+            description: resource.description,
+        };
+    }
+    return {
+        contractId: wire.consentView.participantId,
+        contractDigest: wire.consentView.packageDigest,
+        displayName: wire.consentView.participantId,
+        description: "",
+        capabilities,
+    };
+}
+function portalState(wire) {
+    const evidence = approval(wire);
+    let state;
+    if (wire.state === "choose_provider") {
+        const federatedProviders = wire.providers.filter((id) => id !== "local")
+            .map((id) => ({ id, displayName: id }));
+        state = {
+            status: "choose_provider",
+            flowId: wire.flowId,
+            providers: wire.providers.map((id) => ({ id, displayName: id })),
+            app: {
+                contractId: evidence.contractId,
+                contractDigest: evidence.contractDigest,
+                displayName: evidence.displayName,
+                description: evidence.description,
+            },
+            registration: {
+                localIdentity: { available: wire.registrationEnabled },
+                federatedIdentity: {
+                    available: wire.federatedRegistrationEnabled,
+                    providers: federatedProviders,
+                },
+            },
+        };
+    }
+    else if (wire.state === "authenticated") {
+        state = { status: "processing", flowId: wire.flowId };
+    }
+    else if (wire.state === "approval_required") {
+        if (!("user" in wire) || !("decisionDigest" in wire)) {
+            throw new Error("Authenticated portal flow requires portal binding");
+        }
+        state = {
+            status: "approval_required",
+            flowId: wire.flowId,
+            consentViewDigest: wire.decisionDigest,
+            optionalBundles: [],
+            user: wire.user,
+            approval: evidence,
+        };
+    }
+    else if (wire.state === "approval_denied") {
+        state = {
+            status: "approval_denied",
+            flowId: wire.flowId,
+            approval: evidence,
+            ...(wire.redirectTarget ? { returnLocation: wire.redirectTarget } : {}),
+        };
+    }
+    else if (wire.state === "approved" || wire.state === "consumed") {
+        if (!wire.redirectTarget) {
+            throw new Error("Completed portal flow has no redirect target");
+        }
+        const location = new URL(wire.redirectTarget);
+        location.searchParams.set("flowId", wire.flowId);
+        state = { status: "redirect", location: location.toString() };
+    }
+    else if (wire.state === "expired") {
+        state = {
+            status: "expired",
+            ...(wire.redirectTarget ? { returnLocation: wire.redirectTarget } : {}),
+        };
+    }
+    return Value.Parse(PortalFlowStateSchema, state);
+}
+async function fetchBrowserFlowWire(config, flowId) {
+    const response = await fetch(`${authBaseUrl(config)}/auth/flow/${encodeURIComponent(flowId)}`);
+    if (!response.ok) {
+        throw await decodeTrellisHttpError(response);
+    }
+    return Value.Parse(BrowserFlowWireSchema, await response.json());
+}
+async function fetchBoundPortalFlowWire(config, flowId, binding) {
+    const response = await fetch(`${authBaseUrl(config)}/auth/flow/${encodeURIComponent(flowId)}/portal`, {
+        method: "POST",
+        headers: {
+            ...(config.portalOrigin ? { origin: config.portalOrigin } : {}),
+            [PORTAL_BINDING_HEADER]: binding.secret,
+        },
+    });
+    if (!response.ok)
+        throw await decodeTrellisHttpError(response);
+    return Value.Parse(PortalFlowWireSchema, await response.json());
+}
+export function portalFlowIdFromUrl(url) {
+    return url.searchParams.get("flowId");
+}
+export async function fetchPortalFlowState(config, flowId, binding) {
+    const flow = await fetchBrowserFlowWire(config, flowId);
+    if (flow.state !== "authenticated" && flow.state !== "approval_required") {
+        return portalState(flow);
+    }
+    return portalState(await fetchBoundPortalFlowWire(config, flowId, binding));
+}
+export function portalProviderLoginUrl(config, providerId, flowId, binding) {
+    const base = `${authBaseUrl(config)}/auth/login/${encodeURIComponent(providerId)}`;
+    const query = new URLSearchParams({
+        flowId,
+        portalBindingDigest: binding.digest,
+    });
+    return `${base}?${query}`;
+}
+export async function submitPortalApproval(config, flowId, binding, decision) {
+    const flow = await fetchBrowserFlowWire(config, flowId);
+    const wire = flow.state === "authenticated" || flow.state === "approval_required"
+        ? await fetchBoundPortalFlowWire(config, flowId, binding)
+        : null;
+    if (wire?.state !== "approval_required") {
+        throw new Error("Portal flow is not awaiting approval");
+    }
+    const response = await fetch(`${authBaseUrl(config)}/auth/flow/${encodeURIComponent(flowId)}/approval`, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            ...(config.portalOrigin ? { origin: config.portalOrigin } : {}),
+            [PORTAL_BINDING_HEADER]: binding.secret,
+        },
+        body: JSON.stringify({
+            decision: decision === "approved" ? "approve" : "reject",
+            approval: decision === "approved"
+                ? {
+                    mode: "capabilities",
+                    installedRevision: wire.consentView.installedRevision,
+                    expectedGrantRevision: wire.consentView.expectedGrantRevision,
+                    decisionDigest: wire.consentView.decisionDigest,
+                    approvedCapabilities: wire.consentView.capabilities.filter((item) => item.required && item.eligible).map((item) => ({
+                        id: item.id,
+                        consentDigest: item.consentDigest,
+                    })),
+                    approvedResources: wire.consentView.resources.filter((item) => item.required && item.eligible).map((item) => ({
+                        kind: item.kind,
+                        name: item.name,
+                        commitment: item.requestedCommitment,
+                    })),
+                    companionApproved: wire.consentView.companion != null,
+                }
+                : undefined,
+        }),
+    });
+    if (!response.ok) {
+        throw await decodeTrellisHttpError(response);
+    }
+    return portalState(Value.Parse(PortalFlowWireSchema, await response.json()));
+}
+export function portalRedirectLocation(state) {
+    if (state?.status === "redirect")
+        return state.location;
+    if (state?.status === "approval_denied")
+        return state.returnLocation ?? null;
+    if (state?.status === "expired")
+        return state.returnLocation ?? null;
+    return null;
+}

package/auth/browser/storage.d.ts

@@ -0,0 +1,26 @@
+/** Browser-owned installation credential and optional remembered login. */
+export type BrowserSessionCredential = Readonly<{
+    generation: number;
+    seed: Uint8Array;
+    sessionKey: string;
+    loginSessionId?: string;
+    expiresAt?: number | null;
+    pendingFlowId?: string;
+}>;
+/** Canonical identity for one participant installation at one Trellis origin. */
+export declare function browserInstallationScope(trellisUrl: string, participantId: string): string;
+/** Persists only a browser installation key and nullable login metadata. */
+export declare class BrowserSessionStore {
+    #private;
+    constructor(scope: string, persistence?: "remembered" | "temporary");
+    getOrCreateCredential(now?: number): Promise<BrowserSessionCredential>;
+    readLogin(now?: number): Promise<BrowserSessionCredential | undefined>;
+    rememberFlow(expected: Pick<BrowserSessionCredential, "generation" | "sessionKey">, flowId: string): Promise<boolean>;
+    completeBind(expected: Pick<BrowserSessionCredential, "generation" | "sessionKey" | "pendingFlowId">, login: {
+        loginSessionId: string;
+        expiresAt: number | null;
+    }): Promise<boolean>;
+    clearLogin(expected: Pick<BrowserSessionCredential, "generation" | "sessionKey"> & {
+        loginSessionId?: string;
+    }): Promise<boolean>;
+}

package/auth/browser/storage.js

@@ -0,0 +1,224 @@
+import { publicKeyBase64urlFromSeed } from "../keys.js";
+const DB_NAME = "trellis-auth";
+const DB_VERSION = 3;
+const STORE_NAME = "installations";
+const temporaryInstallations = new Map();
+function openDB() {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(DB_NAME, DB_VERSION);
+        request.onerror = () => reject(request.error);
+        request.onsuccess = () => resolve(request.result);
+        request.onupgradeneeded = () => {
+            const db = request.result;
+            if (!db.objectStoreNames.contains(STORE_NAME)) {
+                db.createObjectStore(STORE_NAME, { keyPath: "id" });
+            }
+        };
+    });
+}
+function validGeneration(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0;
+}
+function credential(record) {
+    if (!record || !validGeneration(record.generation) ||
+        !(record.seed instanceof Uint8Array) || !record.sessionKey)
+        return undefined;
+    return {
+        generation: record.generation,
+        seed: record.seed.slice(),
+        sessionKey: record.sessionKey,
+        ...(record.loginSessionId === undefined
+            ? {}
+            : { loginSessionId: record.loginSessionId }),
+        ...(record.expiresAt === undefined ? {} : { expiresAt: record.expiresAt }),
+        ...(record.pendingFlowId === undefined
+            ? {}
+            : { pendingFlowId: record.pendingFlowId }),
+    };
+}
+function expired(record, now) {
+    return record.loginSessionId !== undefined && record.expiresAt !== null &&
+        record.expiresAt !== undefined && record.expiresAt <= now;
+}
+function tombstone(record) {
+    return {
+        id: record.id,
+        generation: validGeneration(record.generation) ? record.generation + 1 : 0,
+    };
+}
+/** Canonical identity for one participant installation at one Trellis origin. */
+export function browserInstallationScope(trellisUrl, participantId) {
+    return JSON.stringify([
+        "trellis.browser-installation.v2",
+        new URL(trellisUrl).origin,
+        participantId,
+    ]);
+}
+/** Persists only a browser installation key and nullable login metadata. */
+export class BrowserSessionStore {
+    #id;
+    #temporary;
+    constructor(scope, persistence = "remembered") {
+        if (!scope.trim() || scope.length > 4_096) {
+            throw new Error("browser installation scope is invalid");
+        }
+        this.#id = scope;
+        this.#temporary = persistence === "temporary";
+    }
+    async getOrCreateCredential(now = Date.now()) {
+        const candidateSeed = crypto.getRandomValues(new Uint8Array(32));
+        const candidateSessionKey = publicKeyBase64urlFromSeed(candidateSeed);
+        if (this.#temporary) {
+            let current = temporaryInstallations.get(this.#id);
+            if (current && expired(current, now)) {
+                current = tombstone(current);
+                temporaryInstallations.set(this.#id, current);
+            }
+            const existing = credential(current);
+            if (existing)
+                return existing;
+            const created = {
+                id: this.#id,
+                generation: validGeneration(current?.generation)
+                    ? current.generation
+                    : 0,
+                seed: candidateSeed,
+                sessionKey: candidateSessionKey,
+            };
+            temporaryInstallations.set(this.#id, created);
+            return credential(created);
+        }
+        const db = await openDB();
+        return await new Promise((resolve, reject) => {
+            let result;
+            const tx = db.transaction(STORE_NAME, "readwrite");
+            const store = tx.objectStore(STORE_NAME);
+            const request = store.get(this.#id);
+            request.onerror = () => reject(request.error);
+            request.onsuccess = () => {
+                let current = request.result;
+                if (current && expired(current, now))
+                    current = tombstone(current);
+                const existing = credential(current);
+                if (existing) {
+                    result = existing;
+                    if (current !== request.result)
+                        store.put(current);
+                    return;
+                }
+                const created = {
+                    id: this.#id,
+                    generation: validGeneration(current?.generation)
+                        ? current.generation
+                        : 0,
+                    seed: candidateSeed,
+                    sessionKey: candidateSessionKey,
+                };
+                store.put(created);
+                result = credential(created);
+            };
+            tx.oncomplete = () => {
+                db.close();
+                resolve(result);
+            };
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    async readLogin(now = Date.now()) {
+        if (this.#temporary) {
+            const current = temporaryInstallations.get(this.#id);
+            if (!current)
+                return undefined;
+            if (expired(current, now)) {
+                temporaryInstallations.set(this.#id, tombstone(current));
+                return undefined;
+            }
+            return credential(current);
+        }
+        const db = await openDB();
+        return await new Promise((resolve, reject) => {
+            let result;
+            const tx = db.transaction(STORE_NAME, "readwrite");
+            const store = tx.objectStore(STORE_NAME);
+            const request = store.get(this.#id);
+            request.onerror = () => reject(request.error);
+            request.onsuccess = () => {
+                const current = request.result;
+                if (current && expired(current, now)) {
+                    store.put(tombstone(current));
+                    return;
+                }
+                result = credential(current);
+            };
+            tx.oncomplete = () => {
+                db.close();
+                resolve(result);
+            };
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+    rememberFlow(expected, flowId) {
+        return this.#update((current) => {
+            if (current.generation !== expected.generation ||
+                current.sessionKey !== expected.sessionKey)
+                return undefined;
+            return { ...current, pendingFlowId: flowId };
+        });
+    }
+    completeBind(expected, login) {
+        return this.#update((current) => {
+            if (current.generation !== expected.generation ||
+                current.sessionKey !== expected.sessionKey ||
+                !expected.pendingFlowId ||
+                current.pendingFlowId !== expected.pendingFlowId)
+                return undefined;
+            const { pendingFlowId: _, ...retained } = current;
+            return { ...retained, ...login };
+        });
+    }
+    clearLogin(expected) {
+        return this.#update((current) => {
+            if (current.generation !== expected.generation ||
+                current.sessionKey !== expected.sessionKey ||
+                (expected.loginSessionId !== undefined &&
+                    current.loginSessionId !== expected.loginSessionId))
+                return undefined;
+            return tombstone(current);
+        });
+    }
+    async #update(update) {
+        if (this.#temporary) {
+            const current = temporaryInstallations.get(this.#id);
+            if (!current)
+                return false;
+            const next = update(current);
+            if (!next)
+                return false;
+            temporaryInstallations.set(this.#id, next);
+            return true;
+        }
+        const db = await openDB();
+        return await new Promise((resolve, reject) => {
+            let changed = false;
+            const tx = db.transaction(STORE_NAME, "readwrite");
+            const store = tx.objectStore(STORE_NAME);
+            const request = store.get(this.#id);
+            request.onerror = () => reject(request.error);
+            request.onsuccess = () => {
+                const current = request.result;
+                if (!current)
+                    return;
+                const next = update(current);
+                if (!next)
+                    return;
+                store.put(next);
+                changed = true;
+            };
+            tx.oncomplete = () => {
+                db.close();
+                resolve(changed);
+            };
+            tx.onerror = () => reject(tx.error);
+        });
+    }
+}

package/auth/browser.d.ts

@@ -0,0 +1,11 @@
+/**
+ * @module
+ * Browser-based authentication utilities for session-key based authentication.
+ * Uses WebCrypto API and IndexedDB for secure key storage.
+ */
+export { type ApprovalDecision, createPortalBinding, fetchPortalFlowState, getOrCreatePortalBinding, type PortalBinding, portalFlowIdFromUrl, type PortalFlowState, type PortalFlowState as BrowserPortalFlowState, portalProviderLoginUrl, portalRedirectLocation, submitPortalApproval, } from "./browser/portal.ts";
+export { BrowserSessionStore } from "./browser/storage.ts";
+export { classifyBrowserAuthError, isRecoverableBrowserAuthError, } from "./browser_recovery.ts";
+export type { BrowserAuthRecoveryClassification, BrowserAuthRecoveryKind, } from "./browser_recovery.ts";
+export { decodeTrellisHttpError, TrellisHttpError } from "./http_error.ts";
+export { base64urlDecode, base64urlEncode, sha256, toArrayBuffer, utf8, } from "./utils.ts";

package/auth/browser.js

@@ -0,0 +1,10 @@
+/**
+ * @module
+ * Browser-based authentication utilities for session-key based authentication.
+ * Uses WebCrypto API and IndexedDB for secure key storage.
+ */
+export { createPortalBinding, fetchPortalFlowState, getOrCreatePortalBinding, portalFlowIdFromUrl, portalProviderLoginUrl, portalRedirectLocation, submitPortalApproval, } from "./browser/portal.js";
+export { BrowserSessionStore } from "./browser/storage.js";
+export { classifyBrowserAuthError, isRecoverableBrowserAuthError, } from "./browser_recovery.js";
+export { decodeTrellisHttpError, TrellisHttpError } from "./http_error.js";
+export { base64urlDecode, base64urlEncode, sha256, toArrayBuffer, utf8, } from "./utils.js";

package/auth/browser_recovery.d.ts

@@ -0,0 +1,13 @@
+/** Stable browser-auth recovery categories for app-owned recovery flows. */
+export type BrowserAuthRecoveryKind = "recoverable_stale_session" | "recoverable_expired_flow" | "recoverable_auth_required" | "policy_denied" | "insufficient_capabilities" | "runtime_unavailable" | "unknown";
+/** Classification result for a browser-auth related failure. */
+export type BrowserAuthRecoveryClassification = {
+    kind: BrowserAuthRecoveryKind;
+    recoverable: boolean;
+    reason?: string;
+    code?: string;
+};
+/** Classifies an exact auth machine error code. */
+export declare function classifyBrowserAuthError(error: unknown): BrowserAuthRecoveryClassification;
+/** Returns whether a browser auth error can silently restart sign-in. */
+export declare function isRecoverableBrowserAuthError(error: unknown): boolean;