@jimhoyd/urlcode-auth 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/auth-templates.d.ts

@@ -0,0 +1,13 @@
+import type { ViewModel } from '@jimhoyd/urlcode-ui';
+export interface AuthTemplate {
+    readonly source: string;
+    readonly sample: ViewModel;
+}
+/** Template sources with their view model samples, keyed by full template name. */
+export declare const authTemplates: Readonly<Record<string, AuthTemplate>>;
+export declare const authTemplateNames: readonly string[];
+/** What the host hands to `createUiExtension({ extensions: [authUiTemplates] })`. */
+export declare const authUiTemplates: {
+    readonly name: 'auth';
+    readonly templates: Readonly<Record<string, string>>;
+};

package/dist/auth-templates.js

@@ -0,0 +1,74 @@
+/**
+ * The account screens as kit templates, under the `auth` namespace. A
+ * template only places a view model the extension computes: every value is
+ * escaped by the renderer, and the `Markup` slots (forms with their CSRF
+ * field, fields, buttons) are built by trusted package code. A project may
+ * shadow any of these by name; it cannot change a flow, what a form
+ * validates, what is escaped or what a page sends in headers.
+ */
+import { Markup } from '@jimhoyd/urlcode-ui';
+const m = (html) => new Markup(html);
+const declare = (name, body) => `{{!-- viewModel: auth/${name}@1 --}}${body}`;
+const link = '<a href="{{href href}}">{{label}}</a>';
+const screens = {
+    'sign-in': {
+        body: `{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}{{form}}{{passkey}}{{providers}}<nav class="ui-link-list" aria-label="{{linksLabel}}">{{#each links}}${link}{{/each}}</nav>`,
+        sample: { intro: '', form: m('<form method="post"></form>'), passkey: m(''), providers: m(''), linksLabel: 'Sign-in methods', links: [{ href: '/account/register', label: 'Create account' }] },
+    },
+    password: {
+        body: `{{#if failed}}<p class="error" role="alert">{{failed}}</p>{{/if}}{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}<div class="ui-selected-identity"><span class="ui-identifier">{{email}}</span><a href="{{href changeHref}}">{{changeLabel}}</a></div>{{form}}`,
+        sample: { failed: null, intro: '', email: 'ada@example.test', changeHref: '/account/login', changeLabel: 'Change', form: m('<form method="post"></form>') },
+    },
+    register: { body: `{{form}}`, sample: { form: m('<form method="post"></form>') } },
+    'forgot-password': { body: `{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}{{form}}`, sample: { intro: 'We will send a reset link.', form: m('<form method="post"></form>') } },
+    'email-code': { body: `{{form}}`, sample: { form: m('<form method="post"></form>') } },
+    'confirm-token': { body: `{{form}}`, sample: { form: m('<form method="post"></form>') } },
+    enrollment: {
+        body: `<p role="status">{{status}}</p><p>{{email}}</p><h2>{{heading}}</h2>{{#if form}}{{form}}{{else}}<p>{{unavailable}}</p>{{/if}}{{#if passkeyHref}}<p><a href="{{href passkeyHref}}">{{passkeyLabel}}</a></p>{{/if}}<p><a href="{{href stepUpHref}}">{{stepUpLabel}}</a> {{stepUpHelp}}</p>{{signOut}}`,
+        sample: { status: 'Application access remains blocked until enrollment is complete.', email: 'ada@example.test', heading: 'Verify your email first', form: m('<form method="post"></form>'), unavailable: null, passkeyHref: null, passkeyLabel: null, stepUpHref: '/account/step-up', stepUpLabel: 'Confirm your identity', stepUpHelp: 'if your recent sign-in has expired.', signOut: m('<form method="post"></form>') },
+    },
+    impersonation: { body: `{{navigation}}<p role="alert">{{alert}}</p>{{form}}`, sample: { navigation: m('<nav></nav>'), alert: 'You are viewing this account as a support administrator.', form: m('<form method="post"></form>') } },
+    account: {
+        body: `{{navigation}}<section class="ui-card ui-section"><div class="ui-toolbar"><div><p class="ui-identifier">{{email}}</p></div>{{signOut}}</div><p>{{state}}</p>{{verification}}</section><div class="ui-settings-grid">{{#each sections}}<section class="ui-card ui-section{{#if danger}} ui-danger-zone{{/if}}"><h2>{{heading}}</h2>{{content}}</section>{{/each}}</div>`,
+        sample: { navigation: m('<nav></nav>'), overviewLabel: 'Your account', email: 'ada@example.test', signOut: m('<form method="post"></form>'), state: 'Email verified. Authenticator disabled.', verification: m(''), sections: [{ heading: 'Profile', content: m('<form method="post"></form>'), danger: false }] },
+    },
+    'second-factors': {
+        body: `{{navigation}}{{csrf}}<p>{{intro}}</p>{{register}}{{#each passkeys}}<section class="ui-card ui-section"><h2>{{id}}</h2><p>{{state}}</p>{{form}}</section>{{/each}}`,
+        sample: { navigation: m('<nav></nav>'), csrf: m('<input type="hidden" name="csrf" value="token">'), intro: 'A second-factor passkey must be different from the sign-in passkey.', register: m('<button type="button">Add a passkey</button>'), passkeys: [{ id: 'credential', state: 'Enabled', form: m('<form method="post"></form>') }] },
+    },
+    'trusted-devices': {
+        body: `{{navigation}}<p>{{intro}}</p>{{form}}{{#each devices}}<section class="ui-card ui-section"><h2>{{label}}</h2><p>{{expires}}</p>{{form}}</section>{{/each}}`,
+        sample: { navigation: m('<nav></nav>'), intro: 'Remembering a device requires a real second factor.', form: m('<form method="post"></form>'), devices: [{ label: 'Laptop', expires: '2030-01-01T00:00:00.000Z', form: m('<form method="post"></form>') }] },
+    },
+    sessions: {
+        body: `{{navigation}}<ul class="ui-card-list">{{#each sessions}}<li class="ui-card ui-section">{{summary}}{{form}}</li>{{/each}}</ul>{{form}}`,
+        sample: { navigation: m('<nav></nav>'), sessions: [{ summary: 'Session started 2030-01-01T00:00:00.000Z', form: m('<form method="post"></form>') }], form: m('<form method="post"></form>') },
+    },
+    methods: {
+        body: `{{navigation}}<h2>{{passkeysHeading}}</h2>{{#each passkeys}}{{form}}{{/each}}<h2>{{providersHeading}}</h2>{{#each identities}}{{form}}{{/each}}<p>{{note}}</p>`,
+        sample: { navigation: m('<nav></nav>'), passkeysHeading: 'Passkeys', passkeys: [{ form: m('<form method="post"></form>') }], providersHeading: 'Linked providers', identities: [], note: 'The last sign-in method cannot be removed.' },
+    },
+    'step-up': { body: `{{navigation}}{{form}}{{passkey}}`, sample: { navigation: m('<nav></nav>'), form: m('<form method="post"></form>'), passkey: m('') } },
+    status: {
+        body: `<p role="{{#if alert}}alert{{else}}status{{/if}}"{{#if alert}} class="error"{{/if}}>{{message}}</p>{{#if href}}<p><a class="ui-button" href="{{href href}}">{{label}}</a></p>{{/if}}`,
+        sample: { alert: false, message: 'Your email address has been verified.', href: '/account', label: 'Continue to your account' },
+    },
+    'totp-setup': { body: `<p>{{intro}} <code>{{secret}}</code></p>{{form}}`, sample: { intro: 'Add this key to your authenticator:', secret: 'JBSWY3DPEHPK3PXP', form: m('<form method="post"></form>') } },
+    'recovery-codes': {
+        body: `<p>{{intro}}</p><ul>{{#each codes}}<li><code>{{this}}</code></li>{{/each}}</ul><a href="{{href href}}">{{label}}</a>`,
+        sample: { intro: 'Store these codes securely. Each can be used once.', codes: ['abcd-efgh', 'ijkl-mnop'], href: '/account', label: 'Continue to your account' },
+    },
+    signup: {
+        body: `<p class="ui-progress">{{progressLabel}}</p>{{#if email}}<div class="ui-selected-identity"><span class="ui-identifier">{{email}}</span></div>{{/if}}{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}{{#if identifier}}<p class="ui-identifier">{{identifier}}</p>{{/if}}{{form}}{{passkey}}{{#if restart}}<details class="ui-disclosure"><summary>{{changeLabel}}</summary><p>{{restart.help}}</p>{{restart.form}}</details>{{/if}}<p class="ui-link-list">{{signInPrompt}} <a href="{{href signInHref}}">{{signInLabel}}</a></p>`,
+        sample: { progressLabel: 'Step 1 of 3', stepsLabel: 'Account setup progress', steps: [{ number: 1, label: 'Email address', current: true }, { number: 2, label: 'Secure your account', current: false }], email: null, changeLabel: 'Change', intro: '', identifier: null, form: m('<form method="post"></form>'), passkey: m(''), restart: null, signInPrompt: 'Already have an account?', signInHref: '/account/login', signInLabel: 'Sign in' },
+    },
+    'recover-factor': { body: `{{#if intro}}<p>{{intro}}</p>{{/if}}{{form}}`, sample: { intro: 'We will send recovery instructions.', form: m('<form method="post"></form>') } },
+    'restore-access': { body: `<p>{{intro}}</p>{{form}}`, sample: { intro: 'Choose a new password, then enroll a second factor.', form: m('<form method="post"></form>') } },
+    'provider-enroll': { body: `{{form}}`, sample: { form: m('<form method="post"></form>') } },
+    'provider-second-factor': { body: `{{form}}`, sample: { form: m('<form method="post"></form>') } },
+};
+/** Template sources with their view model samples, keyed by full template name. */
+export const authTemplates = Object.freeze(Object.fromEntries(Object.entries(screens).map(([name, screen]) => [`auth/${name}`, Object.freeze({ source: declare(name, screen.body), sample: screen.sample })])));
+export const authTemplateNames = Object.freeze(Object.keys(authTemplates));
+/** What the host hands to `createUiExtension({ extensions: [authUiTemplates] })`. */
+export const authUiTemplates = Object.freeze({ name: 'auth', templates: Object.freeze(Object.fromEntries(Object.entries(authTemplates).map(([name, template]) => [name, template.source]))) });

package/dist/auth-ui.d.ts

@@ -0,0 +1,106 @@
+import type { ViewModel, Kit, Presentation } from '@jimhoyd/urlcode-ui';
+export { escapeHtml } from '@jimhoyd/urlcode-ui';
+import type { TurnstileWidget } from './challenge-ui.ts';
+import type { PresentationContext } from './presentation.ts';
+import type { ExtensionRequest } from '@jimhoyd/urlcode/extensions';
+export interface AuthHttpResponse {
+    status: number;
+    headers: [
+        string,
+        string
+    ][];
+    body: Uint8Array;
+}
+export declare class AuthHttpError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function jsonResponse(status: number, value: unknown, headers?: [
+    string,
+    string
+][]): AuthHttpResponse;
+/** The object `createUiExtension` returns, structurally: the kit once the runtime has activated the `ui` extension. */
+export interface UiHost {
+    readonly kit: Kit;
+    readonly active: boolean;
+}
+/** One account screen: an `auth/*` template name and the view model the extension computed for it. */
+export interface Screen {
+    name: string;
+    view: ViewModel;
+}
+export interface ScreenOptions {
+    status?: number | undefined;
+    headers?: [string, string][] | undefined;
+    /** A same-origin script the screen needs (the passkey glue); it is nonce-bound on both render paths. */
+    scriptPath?: string | undefined;
+    presentation?: PresentationContext | undefined;
+    turnstile?: TurnstileWidget | undefined;
+    layout?: 'default' | 'compact' | 'application' | undefined;
+    /** When present and active, the screen renders through the kit; otherwise through the primitives. */
+    ui?: UiHost | undefined;
+}
+/** Test hook: sees every screen before it renders, with the path that renders it. */
+export declare const screenObserver: {
+    current?: ((screen: Screen, path: 'primitives' | 'kit') => void) | undefined;
+};
+/** Renders a screen: through `ui.kit` when the host supplied the ui extension and it is active, otherwise through the shared primitives. */
+export declare function screenResponse(title: string, screen: Screen, options?: ScreenOptions): AuthHttpResponse;
+/** The presentation auth resolves copy through: the host's, else the kit's once `ui` is active, else the bundled English catalogue. */
+export declare function presentationSource(presentation: Presentation | undefined, ui: UiHost | undefined, fallback: Presentation): Presentation;
+/** Only trusted package code constructs markup. Project/user values must pass escapeHtml. */
+export declare function pageResponse(title: string, markup: string, status?: number, headers?: [
+    string,
+    string
+][], scriptPath?: string, presentation?: PresentationContext, turnstile?: TurnstileWidget, layout?: 'default' | 'compact' | 'application'): AuthHttpResponse;
+export declare function formField(name: string, label: string, type?: string, autocomplete?: string, required?: boolean): string;
+export declare function csrfField(token: string): string;
+export declare function wantsJson(request: ExtensionRequest): boolean;
+export declare function readFields(request: ExtensionRequest, allowed: string[]): Record<string, string>;
+export interface AuthHttpOptions {
+    csrfKey: Uint8Array;
+    origin: string;
+}
+export declare class AuthHttp {
+    #private;
+    readonly origin: string;
+    readonly sessionCookie = "__Host-urlcode-session";
+    readonly flowCookie = "__Host-urlcode-flow";
+    constructor(options: AuthHttpOptions);
+    cookie(request: ExtensionRequest, name: string): string | undefined;
+    device(request: ExtensionRequest): {
+        id: string;
+        label: string;
+        headers: [
+            string,
+            string
+        ][];
+    };
+    session(request: ExtensionRequest): string | undefined;
+    token(binding: string): string;
+    prepare(request: ExtensionRequest): {
+        csrf: string;
+        headers: [
+            string,
+            string
+        ][];
+    };
+    verify(request: ExtensionRequest, fields: Record<string, string>): void;
+    setCookie(name: string, value: string, maxAge?: number): string;
+    sessionHeaders(token: string): [
+        string,
+        string
+    ][];
+    clearSession(): [
+        string,
+        string
+    ][];
+}
+export declare function httpFailure(error: unknown, request: ExtensionRequest, presentation?: PresentationContext, recovery?: {
+    href: string;
+    label: string;
+}, ui?: UiHost): AuthHttpResponse;
+/** Proof token stays in the submitting form and is consumed once with the primary proof. */
+export declare function secondFactorButton(base: string, text?: (source: string) => string): string;
+/** Browser glue for maintained server-side WebAuthn verification. No guest scripts. */
+export declare const passkeyScript: string;

package/dist/auth-ui.js

@@ -0,0 +1,205 @@
+import { renderDocument, field, escapeHtml, compileTemplate, Markup } from '@jimhoyd/urlcode-ui';
+export { escapeHtml } from '@jimhoyd/urlcode-ui';
+import { authTemplates } from "./auth-templates.js";
+import { addTurnstileWidgets, turnstileOrigin, turnstileScript } from "./challenge-ui.js";
+import { englishCatalogue } from "./presentation.js";
+import { createPresentation } from "./presentation.js";
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+export class AuthHttpError extends Error {
+    status;
+    constructor(status, message) { super(message); this.status = status; }
+}
+const encoder = new TextEncoder();
+const securityHeaders = [['cache-control', 'no-store'], ['content-security-policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'"], ['referrer-policy', 'strict-origin'], ['x-content-type-options', 'nosniff']];
+export function jsonResponse(status, value, headers = []) { return { status, headers: [...securityHeaders, ['content-type', 'application/json; charset=utf-8'], ...headers], body: encoder.encode(JSON.stringify(value)) }; }
+/** Test hook: sees every screen before it renders, with the path that renders it. */
+export const screenObserver = {};
+let defaultContext;
+const localTemplates = new Map();
+function localTemplate(name) {
+    let template = localTemplates.get(name);
+    if (!template && Object.hasOwn(authTemplates, name)) {
+        template = compileTemplate(name, authTemplates[name].source);
+        localTemplates.set(name, template);
+    }
+    return template;
+}
+function pageTitle(title, presentation) {
+    const titleKey = Object.entries(englishCatalogue).find(([key, value]) => key.startsWith('page.') && value === title)?.[0];
+    return presentation ? (titleKey ? presentation.text(titleKey) : presentation.textSource(title)) : title;
+}
+/** Renders a screen: through `ui.kit` when the host supplied the ui extension and it is active, otherwise through the shared primitives. */
+export function screenResponse(title, screen, options = {}) {
+    if (!Object.hasOwn(authTemplates, screen.name))
+        throw new Error(`Unknown auth screen: ${screen.name.slice(0, 64)}`);
+    const kit = options.ui?.active ? options.ui.kit : undefined;
+    screenObserver.current?.(screen, kit ? 'kit' : 'primitives');
+    if (!kit) {
+        const context = options.presentation ?? (defaultContext ??= createPresentation().resolve());
+        const markup = localTemplate(screen.name).render(screen.view, context, localTemplate).html;
+        return pageResponse(title, markup, options.status, options.headers, options.scriptPath, options.presentation, options.turnstile, options.layout);
+    }
+    const context = options.presentation ?? kit.resolveContext();
+    const challenge = addTurnstileWidgets(kit.render(screen.name, screen.view, context).html, options.turnstile);
+    const page = kit.wrap(new Markup(challenge.markup), { title: pageTitle(title, context), context, ...(options.layout ? { layout: options.layout } : {}), ...(options.status !== undefined ? { status: options.status } : {}), ...(options.headers ? { headers: options.headers } : {}), ...(challenge.enabled ? { csp: { script: [turnstileOrigin], frame: [turnstileOrigin], connect: [turnstileOrigin] } } : {}) });
+    const scripts = [...(options.scriptPath ? [{ src: options.scriptPath, async: false }] : []), ...(challenge.enabled ? [{ src: turnstileScript, async: true }] : [])];
+    if (!scripts.length)
+        return page;
+    // The kit binds one nonce per page (its style tag carries it); the extension's own scripts share it, so the page CSP admits them.
+    let html = new TextDecoder().decode(page.body);
+    const nonce = /<style nonce="([A-Za-z0-9+/=]+)">/.exec(html)?.[1];
+    if (!nonce || !html.endsWith('</body></html>'))
+        throw new Error('Kit layout lacks the nonce-bound style tag or body end the auth scripts need');
+    html = html.slice(0, -'</body></html>'.length) + scripts.map(script => `<script nonce="${nonce}" src="${escapeHtml(script.src)}"${script.async ? ' async' : ' defer'}></script>`).join('') + '</body></html>';
+    return { status: page.status, headers: page.headers, body: encoder.encode(html) };
+}
+/** The presentation auth resolves copy through: the host's, else the kit's once `ui` is active, else the bundled English catalogue. */
+export function presentationSource(presentation, ui, fallback) {
+    return presentation ?? (ui?.active ? ui.kit.presentation : fallback);
+}
+/** Only trusted package code constructs markup. Project/user values must pass escapeHtml. */
+export function pageResponse(title, markup, status = 200, headers = [], scriptPath, presentation, turnstile, layout = 'default') {
+    title = pageTitle(title, presentation);
+    const challenge = addTurnstileWidgets(markup, turnstile);
+    markup = challenge.markup;
+    const nonce = randomBytes(18).toString('base64');
+    const scripts = [...(scriptPath ? [{ src: scriptPath, nonce: nonce }] : []), ...(challenge.enabled ? [{ src: turnstileScript, nonce: nonce, async: true }] : [])];
+    const html = renderDocument({ title, trustedContent: markup, layout, theme: { nonce }, ...(presentation ? { presentation } : {}), scripts });
+    return { status, headers: [...securityHeaders.map(([name, value]) => [name, name === 'content-security-policy' ? value + (presentation?.logo || presentation?.favicon ? "; img-src 'self'" : '') + (nonce ? `; script-src 'nonce-${nonce}'${challenge.enabled ? ' ' + turnstileOrigin : ''}` : '') + (challenge.enabled ? `; frame-src ${turnstileOrigin}; connect-src 'self' ${turnstileOrigin}` : '') : value]), ['content-type', 'text/html; charset=utf-8'], ...headers], body: encoder.encode(html) };
+}
+export function formField(name, label, type = 'text', autocomplete = 'off', required = true) { return field({ name, label, type, autocomplete, required }); }
+export function csrfField(token) { return `<input type="hidden" name="csrf" value="${escapeHtml(token)}">`; }
+export function wantsJson(request) { return (request.headers.get('accept') || '').split(',').some(value => value.trim().split(';')[0] === 'application/json') || request.headers.get('content-type')?.split(';')[0]?.trim() === 'application/json'; }
+export function readFields(request, allowed) {
+    if (request.body.byteLength > 16384)
+        throw new AuthHttpError(413, 'Request body too large');
+    let source;
+    try {
+        source = new TextDecoder('utf-8', { fatal: true }).decode(request.body);
+    }
+    catch {
+        throw new AuthHttpError(400, 'Invalid request encoding');
+    }
+    const type = request.headers.get('content-type')?.split(';')[0]?.trim(), result = Object.create(null);
+    let entries;
+    if (type === 'application/json') {
+        let data;
+        try {
+            data = JSON.parse(source);
+        }
+        catch {
+            throw new AuthHttpError(400, 'Invalid JSON body');
+        }
+        if (!data || typeof data !== 'object' || Array.isArray(data))
+            throw new AuthHttpError(400, 'Expected an object');
+        entries = Object.entries(data);
+    }
+    else if (type === 'application/x-www-form-urlencoded')
+        entries = [...new URLSearchParams(source)];
+    else
+        throw new AuthHttpError(415, 'Use JSON or form data');
+    if (entries.length > 64)
+        throw new AuthHttpError(400, 'Too many fields');
+    for (const [key, value] of entries) {
+        if (![...allowed, 'csrf', 'challengeToken'].includes(key) || Object.hasOwn(result, key) || typeof value !== 'string' || value.length > (key === 'challengeToken' ? 2048 : 4096))
+            throw new AuthHttpError(400, 'Invalid request field');
+        result[key] = value;
+    }
+    return result;
+}
+export class AuthHttp {
+    origin;
+    #key;
+    #devices = new WeakMap();
+    sessionCookie = '__Host-urlcode-session';
+    flowCookie = '__Host-urlcode-flow';
+    constructor(options) {
+        const origin = new URL(options.origin);
+        if (origin.origin !== options.origin || origin.username || origin.password || !(origin.protocol === 'https:' || (origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname))))
+            throw new Error('Auth requires a canonical HTTPS origin (loopback HTTP development only)');
+        if (options.csrfKey.byteLength < 32)
+            throw new Error('Auth CSRF key requires at least 32 bytes');
+        this.origin = options.origin;
+        this.#key = Buffer.from(options.csrfKey);
+    }
+    cookie(request, name) {
+        const raw = request.headers.get('cookie') || '';
+        if (raw.length > 8192 || (request.headerCounts['cookie'] || 0) > 1)
+            throw new AuthHttpError(400, 'Invalid cookies');
+        const values = raw.split(';').map(value => value.trim()).filter(value => value.startsWith(name + '='));
+        if (values.length > 1)
+            throw new AuthHttpError(400, 'Duplicate session cookie');
+        const value = values[0]?.slice(name.length + 1);
+        if (value !== undefined && !/^[A-Za-z0-9_-]{20,256}$/.test(value))
+            throw new AuthHttpError(400, 'Invalid session cookie');
+        return value;
+    }
+    device(request) {
+        const cached = this.#devices.get(request);
+        if (cached)
+            return cached;
+        const existing = this.cookie(request, '__Host-urlcode-device');
+        const value = { id: existing || randomBytes(32).toString('base64url'), label: (request.headers.get('user-agent') || 'Browser').replace(/[\x00-\x1f\x7f]/g, '').slice(0, 160), headers: [] };
+        if (!existing)
+            value.headers.push(['set-cookie', this.setCookie('__Host-urlcode-device', value.id, 31536000)]);
+        this.#devices.set(request, value);
+        return value;
+    }
+    session(request) { return this.cookie(request, this.sessionCookie); }
+    token(binding) { return createHmac('sha256', this.#key).update('urlcode-csrf\0' + this.origin + '\0' + binding).digest('hex'); }
+    prepare(request) {
+        const session = this.session(request), flow = this.cookie(request, this.flowCookie), binding = session || flow || randomBytes(32).toString('base64url');
+        return { csrf: this.token(binding), headers: [...(session || flow ? [] : [['set-cookie', this.setCookie(this.flowCookie, binding, 900)]]), ...this.device(request).headers] };
+    }
+    verify(request, fields) {
+        if (request.origin !== this.origin || request.headers.get('origin') !== this.origin || request.headers.get('sec-fetch-site') === 'cross-site')
+            throw new AuthHttpError(403, 'Same-origin request required');
+        if ((request.headerCounts['origin'] || 0) > 1 || (request.headerCounts['x-csrf-token'] || 0) > 1)
+            throw new AuthHttpError(403, 'Invalid CSRF token');
+        const binding = this.session(request) || this.cookie(request, this.flowCookie), provided = request.headers.get('x-csrf-token') || fields.csrf;
+        if (!binding || !provided || !/^[a-f0-9]{64}$/.test(provided) || !timingSafeEqual(Buffer.from(this.token(binding), 'hex'), Buffer.from(provided, 'hex')))
+            throw new AuthHttpError(403, 'Invalid CSRF token');
+    }
+    setCookie(name, value, maxAge) { return `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=Strict${maxAge === undefined ? '' : `; Max-Age=${maxAge}`}`; }
+    sessionHeaders(token) { return [['set-cookie', this.setCookie(this.sessionCookie, token)], ['set-cookie', this.setCookie(this.flowCookie, '', 0)]]; }
+    clearSession() { return [['set-cookie', this.setCookie(this.sessionCookie, '', 0)]]; }
+}
+export function httpFailure(error, request, presentation, recovery, ui) {
+    const known = error instanceof AuthHttpError || (error instanceof Error && 'status' in error && typeof error.status === 'number' && error.status >= 400 && error.status < 500);
+    const status = known ? error.status : 500;
+    const source = error instanceof AuthHttpError ? error.message : status >= 500 ? 'Service unavailable' : 'Request could not be completed';
+    const message = presentation?.textSource(source) ?? source;
+    return wantsJson(request) ? jsonResponse(status, { error: message }) : screenResponse('Request could not be completed', { name: 'auth/status', view: { alert: true, message: presentation?.textSource(message) ?? message, href: recovery?.href ?? null, label: recovery?.label ?? null } }, { status, presentation, layout: 'compact', ui });
+}
+/** Proof token stays in the submitting form and is consumed once with the primary proof. */
+export function secondFactorButton(base, text = value => value) {
+    return `<button type="button" data-passkey="second-factor" data-base="${escapeHtml(base)}" data-unavailable="${escapeHtml(text('Passkeys are unavailable in this browser. Use another sign-in method.'))}" data-failed="${escapeHtml(text('Passkey request failed'))}" data-cancelled="${escapeHtml(text('Passkey ceremony cancelled'))}" data-confirmed="${escapeHtml(text('Passkey confirmed. Continue signing in.'))}">${escapeHtml(text('Use a passkey as your second factor'))}</button><input type="hidden" name="secondFactorToken" value=""><p role="status" aria-live="polite" data-passkey-status></p>`;
+}
+/** Browser glue for maintained server-side WebAuthn verification. No guest scripts. */
+export const passkeyScript = String.raw `(() => {
+ const decode=value=>Uint8Array.from(atob(value.replace(/-/g,'+').replace(/_/g,'/')),c=>c.charCodeAt(0));
+ const encode=value=>{let text='';for(const byte of new Uint8Array(value))text+=String.fromCharCode(byte);return btoa(text).replace(/\+/g,'-').replace(/\//g,'_').replace(/=+$/,'');};
+ for(const button of document.querySelectorAll('[data-passkey]'))button.addEventListener('click',async()=>{
+  const form=button.closest('form'),status=form?.querySelector('[data-passkey-status]')||document.querySelector('[data-passkey-status]');button.disabled=true;
+  try{
+   if(!window.PublicKeyCredential||!navigator.credentials)throw new Error(button.dataset.unavailable);
+   const base=button.dataset.base,kind=button.dataset.passkey,csrf=(form||document).querySelector('input[name="csrf"]').value;
+   const post=async(path,data)=>{const response=await fetch(base+path,{method:'POST',headers:{'content-type':'application/json','x-csrf-token':csrf,accept:'application/json'},body:JSON.stringify(data)});const result=await response.json();if(!response.ok)throw new Error(button.dataset.failed);return result;};
+   const prefix=kind==='signup'?'/signup/passkeys':kind==='second-factor'?'/second-factor':'/passkeys/'+kind;
+   const challengeToken=kind==='login'?form?.querySelector('input[name="challengeToken"]')?.value:undefined;
+   const started=await post(prefix+'/options',challengeToken?{challengeToken}:{}),options=started.options;options.challenge=decode(options.challenge);
+   if(options.user)options.user.id=decode(options.user.id);
+   for(const item of options.excludeCredentials||options.allowCredentials||[])item.id=decode(item.id);
+   const credential=(kind==='register'||kind==='signup')?await navigator.credentials.create({publicKey:options}):await navigator.credentials.get({publicKey:options});
+   if(!credential)throw new Error(button.dataset.cancelled);
+   const response={id:credential.id,rawId:encode(credential.rawId),type:credential.type,clientExtensionResults:credential.getClientExtensionResults(),response:{clientDataJSON:encode(credential.response.clientDataJSON)}};
+   if(credential.authenticatorAttachment)response.authenticatorAttachment=credential.authenticatorAttachment;
+   if(kind==='register'||kind==='signup'){response.response.attestationObject=encode(credential.response.attestationObject);response.response.transports=credential.response.getTransports?.()||[];}
+   else {response.response.authenticatorData=encode(credential.response.authenticatorData);response.response.signature=encode(credential.response.signature);response.response.userHandle=credential.response.userHandle?encode(credential.response.userHandle):null;}
+   const scope=form||document,totp=scope.querySelector('input[name="totp"]')?.value,recoveryCode=scope.querySelector('input[name="recoveryCode"]')?.value,secondFactorToken=scope.querySelector('input[name="secondFactorToken"]')?.value;
+   const verified=await post(prefix+'/verify',{...(started.flowId?{flowId:started.flowId}:{}),response,...(kind!=='second-factor'&&totp?{totp}:{}),...(kind!=='second-factor'&&recoveryCode?{recoveryCode}:{}),...(kind!=='second-factor'&&secondFactorToken?{secondFactorToken}:{})});
+   if(kind==='second-factor'){if(!form)throw new Error(button.dataset.failed);form.querySelector('input[name="secondFactorToken"]').value=verified.secondFactorToken;status.textContent=button.dataset.confirmed;return;}
+   location.assign(base+(kind==='signup'?'/signup':'/account'));
+  }catch(error){status.textContent=error instanceof Error&&[button.dataset.unavailable,button.dataset.failed,button.dataset.cancelled].includes(error.message)?error.message:button.dataset.failed;}finally{button.disabled=false;}
+ });
+})();`;

package/dist/auth.d.ts

@@ -0,0 +1,49 @@
+import type { AuthChallenge } from './challenge.ts';
+import type { FactorRecoveryMessage } from './factor-recovery.ts';
+import type { Presentation } from './presentation.ts';
+import type { OidcProvider } from './oidc.ts';
+import type { PasskeyProvider } from './passkeys.ts';
+import type { RuntimeExtension } from '@jimhoyd/urlcode/extensions';
+import type { AuthService, AuthPrincipal, AuthUser } from './auth-core.ts';
+import type { UiHost } from './auth-ui.ts';
+export interface AuthExtensionOptions {
+    challenge?: AuthChallenge;
+    sendFactorRecovery?: (message: FactorRecoveryMessage) => Promise<void>;
+    presentation?: Presentation;
+    /** The `ui` extension from `createUiExtension`, declared before auth in the host file. Screens then render through its kit. */
+    ui?: UiHost;
+    service: AuthService;
+    csrfKey: Uint8Array;
+    projectSha256: string;
+    providers?: Record<string, OidcProvider>;
+    passkeys?: PasskeyProvider;
+    sendSignupCode?: (message: {
+        email: string;
+        code: string;
+        locale?: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+    sendEmailCode?: (message: {
+        email: string;
+        flowId: string;
+        code: string;
+        locale?: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+    sendNotice?: (message: {
+        email: string;
+        event: 'password-changed' | 'new-device' | 'registration-attempt' | 'email-changed';
+        locale?: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+    sendToken?: (message: {
+        email: string;
+        token: string;
+        purpose: 'verify-email' | 'reset-password' | 'cancel-deletion' | 'verify-email-change' | 'cancel-email-change';
+        locale?: string;
+        signal: AbortSignal;
+    }) => Promise<void>;
+}
+export declare function hasPermission(principal: AuthPrincipal, permission: string): boolean;
+export declare function authExtension(options: AuthExtensionOptions): RuntimeExtension;
+export type { AuthUser };