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

package/dist/registration.js

@@ -0,0 +1,130 @@
+const forbidden = new Set(['__proto__', 'prototype', 'constructor', 'role', 'roles', 'permission', 'permissions', 'session', 'sessions', 'sessionid', 'token', 'password', 'passwordhash', 'secret', 'secrets', 'emailverified', 'status', 'administrator', 'id', 'userid', 'accountid', 'authenticatedat', 'totp', 'totpsecret', 'recoverycodes', 'claims', 'auth', 'security']);
+function object(value) { return Boolean(value && typeof value === 'object' && !Array.isArray(value) && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)); }
+function locale(value) {
+    if (typeof value !== 'string' || value.length > 64 || !/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(value))
+        throw new Error('Invalid profile locale');
+    try {
+        return Intl.getCanonicalLocales(value)[0];
+    }
+    catch {
+        throw new Error('Invalid profile locale');
+    }
+}
+function validValue(value, field) {
+    if (typeof value !== field.type)
+        return false;
+    if (typeof value === 'string' && (value.length > (field.maxLength ?? 1024) || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)))
+        return false;
+    if (typeof value === 'number' && (!Number.isFinite(value) || Math.abs(value) > 1e12 || field.minimum !== undefined && value < field.minimum || field.maximum !== undefined && value > field.maximum))
+        return false;
+    return !field.enum || field.enum.includes(value);
+}
+export function createRegistrationPolicy(options = {}) {
+    if (!object(options) || Object.keys(options).some(key => !['termsVersion', 'metadata', 'locales'].includes(key)))
+        throw new Error('Unknown registration option');
+    const terms = options.termsVersion;
+    if (terms !== undefined && (typeof terms !== 'string' || !terms || terms.length > 128 || /[\x00-\x1f\x7f]/.test(terms)))
+        throw new Error('Invalid terms version');
+    if (options.locales !== undefined && (!Array.isArray(options.locales) || !options.locales.length || options.locales.length > 32))
+        throw new Error('Invalid profile locales');
+    const locales = options.locales?.map(locale);
+    if (locales && new Set(locales).size !== locales.length)
+        throw new Error('Duplicate profile locale');
+    const source = options.metadata ?? {};
+    if (!object(source) || Object.keys(source).length > 32)
+        throw new Error('Invalid metadata schema');
+    const fields = Object.create(null);
+    for (const [name, input] of Object.entries(source)) {
+        if (!/^[a-zA-Z][a-zA-Z0-9_]{0,63}$/.test(name) || forbidden.has(name.replaceAll('_', '').toLowerCase()))
+            throw new Error('Reserved or invalid metadata field');
+        if (!object(input) || Object.keys(input).some(key => !['type', 'scope', 'required', 'default', 'enum', 'maxLength', 'minimum', 'maximum'].includes(key)) || !['string', 'number', 'boolean'].includes(String(input.type)) || !['public', 'private', 'unsafe'].includes(String(input.scope)))
+            throw new Error('Invalid metadata field schema');
+        const field = structuredClone(input);
+        if (field.required !== undefined && typeof field.required !== 'boolean')
+            throw new Error('Invalid required flag');
+        if (field.maxLength !== undefined && (field.type !== 'string' || !Number.isInteger(field.maxLength) || field.maxLength < 1 || field.maxLength > 4096))
+            throw new Error('Invalid string bound');
+        for (const bound of [field.minimum, field.maximum])
+            if (bound !== undefined && (field.type !== 'number' || !Number.isFinite(bound) || Math.abs(bound) > 1e12))
+                throw new Error('Invalid numeric bound');
+        if (field.minimum !== undefined && field.maximum !== undefined && field.minimum > field.maximum)
+            throw new Error('Inverted numeric bounds');
+        if (field.enum !== undefined && (!Array.isArray(field.enum) || !field.enum.length || field.enum.length > 64 || field.enum.some(value => !validValue(value, { type: field.type, scope: field.scope, ...(field.maxLength !== undefined ? { maxLength: field.maxLength } : {}), ...(field.minimum !== undefined ? { minimum: field.minimum } : {}), ...(field.maximum !== undefined ? { maximum: field.maximum } : {}) }))))
+            throw new Error('Invalid metadata enum');
+        if (Object.hasOwn(field, 'default') && !validValue(field.default, field))
+            throw new Error('Invalid metadata default');
+        if (field.enum)
+            Object.freeze(field.enum);
+        fields[name] = Object.freeze(field);
+    }
+    Object.freeze(fields);
+    const validate = (input, context) => {
+        if (!object(input) || Object.keys(input).some(key => !['displayName', 'locale', 'metadata', 'termsAccepted'].includes(key)))
+            throw new Error('Unknown profile field');
+        if (!Number.isSafeInteger(context.now) || context.now < 0)
+            throw new Error('Invalid acceptance time');
+        const existing = context.existing;
+        const result = { metadata: Object.create(null) };
+        const name = input.displayName ?? existing?.displayName;
+        if (name !== undefined) {
+            if (typeof name !== 'string' || [...name].length > 100 || /[\x00-\x1f\x7f]/.test(name))
+                throw new Error('Invalid display name');
+            result.displayName = name;
+        }
+        const language = input.locale ?? existing?.locale;
+        if (language !== undefined) {
+            const normalized = locale(language);
+            if (locales && !locales.includes(normalized))
+                throw new Error('Profile locale is not enabled');
+            result.locale = normalized;
+        }
+        if (input.metadata !== undefined && !object(input.metadata))
+            throw new Error('Invalid metadata values');
+        for (const [name, value] of Object.entries(existing?.metadata ?? {})) {
+            const field = fields[name];
+            if (!field || !validValue(value, field))
+                throw new Error('Stored metadata does not match schema');
+            result.metadata[name] = value;
+        }
+        for (const [name, value] of Object.entries(input.metadata ?? {})) {
+            const field = fields[name];
+            if (!field)
+                throw new Error('Unknown metadata field');
+            if (field.scope === 'private' && context.operator !== true)
+                throw new Error('Private metadata requires operator authority');
+            if (!validValue(value, field))
+                throw new Error('Invalid metadata value');
+            result.metadata[name] = value;
+        }
+        for (const [name, field] of Object.entries(fields)) {
+            if (!Object.hasOwn(result.metadata, name) && Object.hasOwn(field, 'default'))
+                result.metadata[name] = field.default;
+            if (field.required && !Object.hasOwn(result.metadata, name))
+                throw new Error('Required metadata is missing');
+        }
+        if (JSON.stringify(result.metadata).length > 16384)
+            throw new Error('Metadata exceeds total bound');
+        if (input.termsAccepted !== undefined && typeof input.termsAccepted !== 'boolean')
+            throw new Error('Invalid terms acceptance');
+        if (existing?.terms)
+            result.terms = { ...existing.terms };
+        if (terms) {
+            if (input.termsAccepted === true)
+                result.terms = { version: terms, acceptedAt: context.now };
+            else if (existing?.terms?.version !== terms)
+                throw new Error('Current terms acceptance required');
+        }
+        return result;
+    };
+    return Object.freeze({ validate, publicSchema() { return structuredClone({ ...(terms ? { termsVersion: terms } : {}), ...(locales ? { locales } : {}), metadata: Object.fromEntries(Object.entries(fields).filter(([, field]) => field.scope !== 'private')) }); }, publicProfile(profile) {
+            const result = { metadata: Object.create(null), ...(profile.displayName !== undefined ? { displayName: profile.displayName } : {}), ...(profile.locale !== undefined ? { locale: profile.locale } : {}), ...(profile.terms ? { terms: { ...profile.terms } } : {}) };
+            for (const [name, value] of Object.entries(profile.metadata)) {
+                const field = fields[name];
+                if (field && field.scope !== 'private' && validValue(value, field))
+                    result.metadata[name] = value;
+            }
+            return result;
+        } });
+}
+/** Quiet refusal is an HTTP integration decision; this helper never creates a fake account or session. */
+export function isHoneypotFilled(value) { return value !== undefined && value !== ''; }

package/dist/scaffold.d.ts

@@ -0,0 +1,44 @@
+export interface AuthenticationScaffold {
+    directory: string;
+    project: string;
+    hostFile: string;
+    operatorFile: string;
+}
+/** Shared scaffold contract (core `urlcode init --with`): what the caller is assembling. */
+export interface ScaffoldRequest {
+    /** Root of the generated site; file paths in the result are relative to it. */
+    directory: string;
+    /** Project directory holding urlcode.yaml. */
+    project: string;
+    /** Path of the combined host module the caller writes. */
+    hostFile: string;
+    /** Every extension name being scaffolded together, including this one. */
+    names: readonly string[];
+}
+export interface ScaffoldFile {
+    path: string;
+    content: string | Uint8Array;
+    mode?: number;
+}
+export interface ScaffoldResult {
+    name: string;
+    extensions: Record<string, unknown>;
+    routes: Record<string, unknown>;
+    hostImports: string[];
+    hostSetup: string[];
+    hostEntries: string[];
+    hostClose?: string[];
+    files: ScaffoldFile[];
+    readme: string;
+    nextSteps: string[];
+    env?: Record<string, string>;
+}
+/**
+ * Generates the auth pieces of a layered project without touching the filesystem.
+ * Key material is created in memory and returned as files; the caller writes them with private modes.
+ */
+export declare function scaffold(request: ScaffoldRequest): Promise<ScaffoldResult>;
+/** Deterministic YAML for scaffold fragments: block mappings, flow lists of scalars, {} for empty maps. */
+export declare function renderYaml(value: Record<string, unknown>, indent?: string): string;
+/** Creates a new private directory only; never merges or overwrites an existing project. */
+export declare function initAuthentication(directory: string): Promise<AuthenticationScaffold>;

package/dist/scaffold.js

@@ -0,0 +1,212 @@
+import { randomBytes } from 'node:crypto';
+import { mkdir, open, realpath, rm } from 'node:fs/promises';
+import { resolve, dirname, basename, join, relative, sep } from 'node:path';
+const OPERATOR_FILE = 'operator-service.mjs', ENCRYPTION_KEY = 'data/encryption.key', CSRF_KEY = 'data/csrf.key';
+function moduleReference(from, to) {
+    const path = relative(from, to).split(sep).join('/');
+    return path.startsWith('.') ? path : './' + path;
+}
+function shellReference(from, to) {
+    return relative(from, to).split(sep).join('/');
+}
+function serviceModule(directory) {
+    const here = dirname(join(directory, OPERATOR_FILE));
+    return `import {readFile} from 'node:fs/promises';
+import {fileURLToPath} from 'node:url';
+import {createAuthService} from '@jimhoyd/urlcode-auth';
+const key = await readFile(new URL('${moduleReference(here, join(directory, ENCRYPTION_KEY))}', import.meta.url));
+let service;
+try {
+  service = await createAuthService({
+    database: fileURLToPath(new URL('${moduleReference(here, join(directory, 'data/auth.sqlite'))}', import.meta.url)),
+    encryptionKey: key,
+    roles: {member: [], admin: ['*']},
+    defaultRole: 'member',
+    registrationMode: 'off',
+    ...(process.env.AUTH_CONFIG_FROM ? {approveConfigurationChangeFrom: process.env.AUTH_CONFIG_FROM} : {}),
+  });
+} finally { key.fill(0); }
+export default service;
+`;
+}
+function readmeSection(request, admin) {
+    const operator = shellReference(request.directory, join(request.directory, OPERATOR_FILE)), project = shellReference(request.directory, request.project), host = shellReference(request.directory, request.hostFile);
+    return `This directory separates untrusted route files in ${project}/ from trusted operator modules and private data/. Registration is off. No credentials appear in generated source or command output. Keep the whole data/ directory and operator environment private.${admin ? ' This starter includes auth and admin; the admin console is described in its own section.' : ' This starter includes auth only.'}
+
+## Install
+
+Use a supported patched Node release. From this directory, install the separately built repositories until packages are released:
+
+\`\`\`sh
+# First run npm ci && npm run build in each source repository.
+npm install /absolute/path/to/urlcode /absolute/path/to/urlcode-auth${admin ? ' /absolute/path/to/urlcode-admin' : ''}
+\`\`\`
+
+Review the operator modules and ${project}/urlcode.yaml before activation. Set an HTTPS origin served by your TLS proxy. The runtime listener itself can remain on loopback behind that proxy.
+
+\`\`\`sh
+export AUTH_ORIGIN='https://accounts.example.com'
+# Inspect only; this command does not grant or load operator code.
+node --input-type=module -e 'import {inspectExtensionRevision} from "@jimhoyd/urlcode/extensions"; console.log(await inspectExtensionRevision("./${project}"))'
+# Paste the reviewed hash explicitly. Re-review after any project change.
+export PROJECT_SHA256='paste-reviewed-64-character-sha256'
+\`\`\`
+
+Bootstrap the first administrator using the operator service. Pass JSON on stdin from your secret manager or a private terminal; never put the password in argv or commit it. The JSON shape is {"email":"owner@example.com","password":"a unique password of at least 15 characters"}. The command prints account metadata, never the password or session token.
+
+\`\`\`sh
+npx urlcode-auth bootstrap --operator-file "$PWD/${operator}"
+# Paste the JSON on stdin, then end input (Ctrl-D in a terminal).
+npx urlcode serve --project "$PWD/${project}" --host-file "$PWD/${host}" --origin "$AUTH_ORIGIN"
+\`\`\`
+
+Sign in at /account/login; /private requires a valid session${admin ? ' and /admin requires the admin role' : ''}. Opening registration requires a reviewed operator configuration migration as well as changing the YAML and setting a new explicit project revision pin. Inspect the current database configuration with the configuration CLI command, then supply its exact hash as AUTH_CONFIG_FROM for the first startup with the new operator settings. This revokes old sessions and pending sign-ins. Stop/restart all service instances; old workers refuse requests after migration. Remove the approval environment variable after the migration. Email recovery is unavailable until an operator sender is configured. Do not serve hostile frontend scripts on this origin: browser JavaScript shares ambient session authority even though guest server code cannot read session headers.
+
+Back up the SQLite database through the auth backup API, not by copying a live WAL database. Preserve encryption.key and csrf.key separately in your secret backup system, together with the exact operator configuration. Database backup does not include those key files. A restored snapshot can restore historical sessions and tokens: use a planned revocation and recovery procedure. Generated files and key material are local, not published.
+`;
+}
+/**
+ * Generates the auth pieces of a layered project without touching the filesystem.
+ * Key material is created in memory and returned as files; the caller writes them with private modes.
+ */
+export async function scaffold(request) {
+    if (!request || typeof request !== 'object')
+        throw new Error('A scaffold request is required');
+    for (const key of ['directory', 'project', 'hostFile']) {
+        const value = request[key];
+        if (typeof value !== 'string' || !value || value.includes('\0'))
+            throw new Error(`Scaffold ${key} is required`);
+    }
+    if (!Array.isArray(request.names) || request.names.some(name => typeof name !== 'string'))
+        throw new Error('Scaffold names must be strings');
+    const directory = resolve(request.directory), project = resolve(directory, request.project), hostFile = resolve(directory, request.hostFile);
+    const normalized = { directory, project, hostFile, names: request.names };
+    const admin = request.names.includes('admin'), hostDirectory = dirname(hostFile);
+    const operator = shellReference(directory, join(directory, OPERATOR_FILE)), projectPath = shellReference(directory, project), host = shellReference(directory, hostFile);
+    return {
+        name: 'auth',
+        extensions: { auth: { version: '1', config: { registration: 'off' } } },
+        routes: {
+            '/account/*': { extension: 'auth', methods: ['GET', 'HEAD', 'POST'] },
+            '/private': { respond: { text: 'Signed in' }, policies: { extensions: { auth: {} } } },
+        },
+        hostImports: ["import {readFile} from 'node:fs/promises';", "import {authExtension} from '@jimhoyd/urlcode-auth';"],
+        hostSetup: [
+            '// Explicit operator approval, not computed from the project at activation.',
+            'const projectSha256 = process.env.PROJECT_SHA256;',
+            "if (!projectSha256 || !/^[a-f0-9]{64}$/.test(projectSha256)) throw new Error('Set the reviewed PROJECT_SHA256 revision');",
+            "const origin = new URL(process.env.AUTH_ORIGIN || '');",
+            "if (origin.protocol !== 'https:' || origin.origin !== process.env.AUTH_ORIGIN || origin.username || origin.password) throw new Error('Set a canonical HTTPS AUTH_ORIGIN');",
+            `const {default: service} = await import('${moduleReference(hostDirectory, join(directory, OPERATOR_FILE))}');`,
+            'let csrfKey;',
+            'try {',
+            `  csrfKey = await readFile(new URL('${moduleReference(hostDirectory, join(directory, CSRF_KEY))}', import.meta.url));`,
+            "  if (csrfKey.length !== 32) throw new Error('Invalid CSRF key');",
+            '} catch (error) { await service.close(); throw error; }',
+        ],
+        hostEntries: ['authExtension({service, csrfKey, projectSha256})'],
+        hostClose: ['csrfKey.fill(0);', 'await service.close();'],
+        files: [
+            { path: OPERATOR_FILE, content: serviceModule(directory), mode: 0o600 },
+            { path: ENCRYPTION_KEY, content: randomBytes(32), mode: 0o600 },
+            { path: CSRF_KEY, content: randomBytes(32), mode: 0o600 },
+        ],
+        readme: readmeSection(normalized, admin),
+        nextSteps: [
+            "export AUTH_ORIGIN='https://accounts.example.com'",
+            "export PROJECT_SHA256='paste-reviewed-64-character-sha256'",
+            `npx urlcode-auth bootstrap --operator-file "$PWD/${operator}"`,
+            `npx urlcode serve --project "$PWD/${projectPath}" --host-file "$PWD/${host}" --origin "$AUTH_ORIGIN"`,
+        ],
+        env: {
+            AUTH_ORIGIN: 'Canonical HTTPS origin of the site, as served by the TLS proxy.',
+            PROJECT_SHA256: 'Reviewed project revision from inspectExtensionRevision; re-review after any project change.',
+            AUTH_CONFIG_FROM: 'Optional: current configuration revision hash approving an operator configuration migration.',
+        },
+    };
+}
+const PLAIN = /^[A-Za-z_/][A-Za-z0-9_ ./*-]*$/, RESERVED = /^(true|false|yes|no|on|off|null|~)$/i;
+function scalar(value) {
+    if (typeof value === 'string')
+        return PLAIN.test(value) && !RESERVED.test(value) && !value.endsWith(' ') ? value : `'${value.replace(/'/g, "''")}'`;
+    if (typeof value === 'number' || typeof value === 'boolean')
+        return String(value);
+    throw new Error('Unsupported YAML scalar');
+}
+/** Deterministic YAML for scaffold fragments: block mappings, flow lists of scalars, {} for empty maps. */
+export function renderYaml(value, indent = '') {
+    let out = '';
+    for (const [key, entry] of Object.entries(value)) {
+        const name = scalar(key);
+        if (Array.isArray(entry))
+            out += `${indent}${name}: [${entry.map(scalar).join(', ')}]\n`;
+        else if (entry && typeof entry === 'object') {
+            const nested = entry;
+            out += Object.keys(nested).length ? `${indent}${name}:\n${renderYaml(nested, indent + '  ')}` : `${indent}${name}: {}\n`;
+        }
+        else
+            out += `${indent}${name}: ${scalar(entry)}\n`;
+    }
+    return out;
+}
+function hostModule(result) {
+    return [
+        ...result.hostImports,
+        ...result.hostSetup,
+        'export default {',
+        `  extensions: [${result.hostEntries.join(', ')}],`,
+        `  async close() { ${(result.hostClose ?? []).join(' ')} },`,
+        '};',
+    ].join('\n') + '\n';
+}
+/** Creates a new private directory only; never merges or overwrites an existing project. */
+export async function initAuthentication(directory) {
+    if (typeof directory !== 'string' || !directory || directory.includes('\0'))
+        throw new Error('An output directory is required');
+    const requested = resolve(directory), parent = await realpath(dirname(requested)), root = join(parent, basename(requested));
+    const project = join(root, 'app'), hostFile = join(root, 'host.mjs');
+    const result = await scaffold({ directory: root, project, hostFile, names: ['auth'] });
+    try {
+        await mkdir(root, { mode: 0o700 });
+    }
+    catch (error) {
+        for (const file of result.files)
+            if (file.content instanceof Uint8Array)
+                file.content.fill(0);
+        throw error;
+    }
+    async function write(path, value, mode = 0o600) {
+        const file = await open(join(root, path), 'wx', mode);
+        try {
+            await file.writeFile(value);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+    }
+    try {
+        await mkdir(project, { mode: 0o700 });
+        await mkdir(join(root, 'data'), { mode: 0o700 });
+        await write('app/urlcode.yaml', renderYaml({ version: '1', extensions: result.extensions, routes: result.routes }));
+        await write('host.mjs', hostModule(result));
+        await write('README.md', `# Auth project and operator host\n\n${result.readme}`);
+        await write('package.json', JSON.stringify({ name: 'urlcode-auth-site', private: true, type: 'module' }, null, 2) + '\n');
+        await write('.gitignore', 'node_modules/\ndata/\n.env\n.env.*\n');
+        for (const file of result.files) {
+            if (file.path.includes('\0') || resolve(root, file.path) !== join(root, file.path) || relative(root, resolve(root, file.path)).startsWith('..'))
+                throw new Error('Invalid scaffold file path');
+            await write(file.path, file.content, file.mode);
+        }
+        return { directory: root, project, hostFile, operatorFile: join(root, OPERATOR_FILE) };
+    }
+    catch (error) {
+        await rm(root, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        for (const file of result.files)
+            if (file.content instanceof Uint8Array)
+                file.content.fill(0);
+    }
+}

package/dist/second-factor-flows.d.ts

@@ -0,0 +1,28 @@
+import type { ExtensionRequest } from '@jimhoyd/urlcode/extensions';
+import type { AuthService, PasskeyAuthProof } from './auth-core.ts';
+import type { PasskeyProvider } from './passkeys.ts';
+import { AuthHttp } from './auth-ui.ts';
+import type { AuthHttpResponse } from './auth-ui.ts';
+export interface SecondFactorInput {
+    token: string;
+    browserHash: string;
+}
+export interface SecondFactorFlowService extends Pick<AuthService, 'putFlow' | 'consumeFlow' | 'getPasskey'> {
+    getSecurityPolicy(): {
+        allowPasskeySecondFactor?: boolean;
+    };
+    createSecondFactorProof(input: {
+        browserHash: string;
+        proof: PasskeyAuthProof;
+    }): Promise<string>;
+}
+/** Obtains UV evidence only. The domain consumes the resulting opaque proof together
+ * with the independent primary proof and counter update in the final transaction. */
+export declare function createSecondFactorFlows(options: {
+    service: SecondFactorFlowService;
+    passkeys?: PasskeyProvider;
+    now?: () => number;
+}, http: AuthHttp, mount: string): {
+    proof(request: ExtensionRequest, token: string): SecondFactorInput;
+    handle(request: ExtensionRequest): Promise<AuthHttpResponse | undefined>;
+};

package/dist/second-factor-flows.js

@@ -0,0 +1,76 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { AuthHttp, AuthHttpError, jsonResponse } from "./auth-ui.js";
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const opaque = (value) => typeof value === 'string' && /^[A-Za-z0-9_-]{43}$/.test(value);
+function record(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new AuthHttpError(400, 'Invalid second-factor payload');
+    return value;
+}
+function payload(request) {
+    if (request.body.byteLength > 16384)
+        throw new AuthHttpError(413, 'Request body too large');
+    if (request.headers.get('content-type')?.split(';')[0] !== 'application/json')
+        throw new AuthHttpError(415, 'JSON required');
+    try {
+        return record(JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(request.body)));
+    }
+    catch {
+        throw new AuthHttpError(400, 'Invalid second-factor payload');
+    }
+}
+/** Obtains UV evidence only. The domain consumes the resulting opaque proof together
+ * with the independent primary proof and counter update in the final transaction. */
+export function createSecondFactorFlows(options, http, mount) {
+    const { service, passkeys } = options, now = options.now ?? Date.now;
+    const enabled = () => Boolean(passkeys && service.getSecurityPolicy().allowPasskeySecondFactor);
+    const browserHash = (request) => {
+        const browser = http.session(request) || http.cookie(request, http.flowCookie);
+        if (!browser)
+            throw new AuthHttpError(403, 'Authentication browser binding required');
+        return hash(browser);
+    };
+    return {
+        proof(request, token) {
+            if (!enabled() || !opaque(token))
+                throw new AuthHttpError(400, 'Invalid second-factor proof');
+            return { token, browserHash: browserHash(request) };
+        },
+        async handle(request) {
+            if (!enabled() || ![mount + '/second-factor/options', mount + '/second-factor/verify'].includes(request.path))
+                return undefined;
+            if (request.method !== 'POST')
+                throw new AuthHttpError(405, 'POST required');
+            const body = payload(request), begin = request.path.endsWith('/options');
+            if (Object.keys(body).some(key => !(begin ? ['csrf'] : ['csrf', 'flowId', 'response']).includes(key)) || body.csrf !== undefined && typeof body.csrf !== 'string')
+                throw new AuthHttpError(400, 'Invalid second-factor payload');
+            http.verify(request, { csrf: typeof body.csrf === 'string' ? body.csrf : '' });
+            const binding = browserHash(request);
+            if (begin) {
+                const authentication = await passkeys.beginAuthentication(), flowId = randomBytes(32).toString('base64url');
+                await service.putFlow({ id: flowId, kind: 'passkey-second-factor', expires: now() + 300000, data: { challenge: authentication.challenge, browserHash: binding, expires: now() + 300000 } });
+                return jsonResponse(200, { flowId, options: authentication });
+            }
+            if (!opaque(body.flowId))
+                throw new AuthHttpError(400, 'Invalid second-factor flow');
+            const flow = record(await service.consumeFlow(body.flowId, 'passkey-second-factor'));
+            if (flow.browserHash !== binding || typeof flow.challenge !== 'string' || typeof flow.expires !== 'number' || flow.expires <= now())
+                throw new AuthHttpError(403, 'Invalid second-factor flow');
+            const response = record(body.response);
+            if (typeof response.id !== 'string' || response.id.length > 2048)
+                throw new AuthHttpError(400, 'Invalid second-factor assertion');
+            const stored = await service.getPasskey(response.id);
+            if (!stored)
+                throw new AuthHttpError(400, 'Invalid second-factor assertion');
+            let counter;
+            try {
+                ({ counter } = await passkeys.verifyAuthentication(response, flow.challenge, stored.credential));
+            }
+            catch {
+                throw new AuthHttpError(400, 'Invalid second-factor assertion');
+            }
+            const secondFactorToken = await service.createSecondFactorProof({ browserHash: binding, proof: { ...stored.proof, newCounter: counter } });
+            return jsonResponse(200, { secondFactorToken });
+        },
+    };
+}

package/dist/senders.d.ts

@@ -0,0 +1,86 @@
+import type { AdminAccountDelivery } from './admin-account-operations.ts';
+import type { EmailCopy } from './email-copy.ts';
+import type { ManualRecoveryDelivery } from './manual-recovery.ts';
+import { SendEmailCommand } from '@aws-sdk/client-sesv2';
+import type { SESv2ClientConfig } from '@aws-sdk/client-sesv2';
+export interface TokenMessage {
+    email: string;
+    token: string;
+    purpose: 'verify-email' | 'reset-password' | 'cancel-deletion' | 'invitation' | 'verify-email-change' | 'cancel-email-change';
+    signal: AbortSignal;
+    locale?: string;
+}
+export interface EmailCodeMessage {
+    email: string;
+    flowId: string;
+    code: string;
+    signal: AbortSignal;
+    locale?: string;
+}
+export interface SignupCodeMessage {
+    email: string;
+    code: string;
+    signal: AbortSignal;
+    locale?: string;
+}
+export interface FactorRecoveryMessage {
+    email: string;
+    verificationToken: string;
+    cancelToken: string;
+    signal: AbortSignal;
+    locale?: string;
+}
+export type TokenSender = (message: TokenMessage) => Promise<void>;
+export interface SecurityNotice {
+    email: string;
+    event: 'new-device' | 'password-changed' | 'email-changed' | 'registration-attempt';
+    signal: AbortSignal;
+    locale?: string;
+}
+/** A callable sendToken adapter; notify carries no credential or arbitrary markup. */
+export interface EmailSender extends TokenSender {
+    sendEmailCode(message: EmailCodeMessage): Promise<void>;
+    sendSignupCode(message: SignupCodeMessage): Promise<void>;
+    sendFactorRecovery(message: FactorRecoveryMessage): Promise<void>;
+    sendManualRecovery(message: ManualRecoveryDelivery & {
+        locale?: string;
+    }): Promise<void>;
+    notify(message: SecurityNotice): Promise<void>;
+    sendAccountAdministration(message: AdminAccountDelivery & {
+        signal: AbortSignal;
+        locale?: string;
+    }): Promise<void>;
+    close(): void;
+}
+interface SenderLocation {
+    origin: string;
+    authMount: string;
+    emailCopy?: EmailCopy;
+}
+export interface SesSenderOptions extends SenderLocation {
+    region: string;
+    from: string;
+    credentials?: SESv2ClientConfig['credentials'];
+    /** Trusted injection for tests; production uses the AWS SDK with bounded retries. */
+    transport?: (command: SendEmailCommand, options: {
+        abortSignal: AbortSignal;
+    }) => Promise<unknown>;
+}
+export declare function createSesSender(options: SesSenderOptions): EmailSender;
+export type DevelopmentSenderOptions = SenderLocation & {
+    allowDevelopment: true;
+    maxMessages?: number;
+} & ({
+    directory: string;
+    projectRoot: string;
+    allowConsoleTokens?: never;
+    write?: never;
+} | {
+    allowConsoleTokens: true;
+    write?: (message: string) => void;
+    directory?: never;
+    projectRoot?: never;
+});
+/** Development only. File output uses exclusive 0600 notices in an existing private directory outside the project. */
+export declare function createDevelopmentSender(options: DevelopmentSenderOptions): Promise<EmailSender>;
+export {};