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

package/dist/disposable-domains.d.ts

@@ -0,0 +1,3 @@
+export declare const disposableDomainsRevision = "be0dd1affed11ea9b1ffcd14da81319f9a080609";
+/** Exact domain or dot-delimited subdomain match, never substring matching. No DNS/network lookup. */
+export declare function isDisposableEmailDomain(value: string): boolean;

package/dist/disposable-domains.js

@@ -0,0 +1,17 @@
+import { domainToASCII } from 'node:url';
+import { disposableDomainData } from "./disposable-domain-data.js";
+export const disposableDomainsRevision = 'be0dd1affed11ea9b1ffcd14da81319f9a080609';
+const blocked = new Set(disposableDomainData);
+/** Exact domain or dot-delimited subdomain match, never substring matching. No DNS/network lookup. */
+export function isDisposableEmailDomain(value) {
+    if (typeof value !== 'string' || value.length > 253 || value.endsWith('.') || /[\s/@\\:]/.test(value))
+        throw new Error('Invalid email domain');
+    const domain = domainToASCII(value.toLowerCase());
+    if (!domain || domain.length > 253 || domain.split('.').some(label => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)))
+        throw new Error('Invalid email domain');
+    const labels = domain.split('.');
+    for (let index = 0; index < labels.length - 1; index++)
+        if (blocked.has(labels.slice(index).join('.')))
+            return true;
+    return false;
+}

package/dist/email-copy.d.ts

@@ -0,0 +1,114 @@
+export declare const englishEmailCatalogue: Readonly<{
+    'admin-verify-email': {
+        subject: string;
+        text: string;
+    };
+    'admin-force-password-reset': {
+        subject: string;
+        text: string;
+    };
+    'admin-schedule-deletion': {
+        subject: string;
+        text: string;
+    };
+    'admin-cancel-deletion': {
+        subject: string;
+        text: string;
+    };
+    'admin-remove-passkey': {
+        subject: string;
+        text: string;
+    };
+    'admin-remove-external': {
+        subject: string;
+        text: string;
+    };
+    'admin-request-email-change': {
+        subject: string;
+        text: string;
+    };
+    'admin-assign-roles': {
+        subject: string;
+        text: string;
+    };
+    'admin-resend-verification': {
+        subject: string;
+        text: string;
+    };
+    'verify-email': {
+        subject: string;
+        text: string;
+    };
+    'reset-password': {
+        subject: string;
+        text: string;
+    };
+    'cancel-deletion': {
+        subject: string;
+        text: string;
+    };
+    invitation: {
+        subject: string;
+        text: string;
+    };
+    'verify-email-change': {
+        subject: string;
+        text: string;
+    };
+    'cancel-email-change': {
+        subject: string;
+        text: string;
+    };
+    'sign-in-code': {
+        subject: string;
+        text: string;
+    };
+    'signup-code': {
+        subject: string;
+        text: string;
+    };
+    'factor-recovery': {
+        subject: string;
+        text: string;
+    };
+    'manual-recovery-warning': {
+        subject: string;
+        text: string;
+    };
+    'manual-recovery': {
+        subject: string;
+        text: string;
+    };
+    'new-device': {
+        subject: string;
+        text: string;
+    };
+    'password-changed': {
+        subject: string;
+        text: string;
+    };
+    'email-changed': {
+        subject: string;
+        text: string;
+    };
+    'registration-attempt': {
+        subject: string;
+        text: string;
+    };
+}>;
+export type EmailTemplateKey = keyof typeof englishEmailCatalogue;
+export interface EmailCopyOptions {
+    defaultLocale?: string;
+    catalogues?: Record<string, Partial<Record<EmailTemplateKey, {
+        subject: string;
+        text: string;
+    }>>>;
+}
+export interface EmailCopy {
+    render(key: EmailTemplateKey, values: Readonly<Record<string, string>>, locale?: string): {
+        subject: string;
+        text: string;
+    };
+}
+/** Plain-text notices only. Translations must preserve every required capability placeholder. */
+export declare function createEmailCopy(options?: EmailCopyOptions): EmailCopy;

package/dist/email-copy.js

@@ -0,0 +1,58 @@
+export const englishEmailCatalogue = Object.freeze({
+    'admin-verify-email': { subject: 'Account administration requested', text: 'An administrator requested to verify your account email. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-force-password-reset': { subject: 'Account administration requested', text: 'An administrator requested to require a new account password. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-schedule-deletion': { subject: 'Account administration requested', text: 'An administrator requested to schedule account deletion. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-cancel-deletion': { subject: 'Account administration requested', text: 'An administrator requested to cancel account deletion. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-remove-passkey': { subject: 'Account administration requested', text: 'An administrator requested to remove an account passkey. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-remove-external': { subject: 'Account administration requested', text: 'An administrator requested to remove an external sign-in method. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-request-email-change': { subject: 'Account administration requested', text: 'An administrator requested to change your account email. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-assign-roles': { subject: 'Account administration requested', text: 'An administrator requested to change your account role assignments. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'admin-resend-verification': { subject: 'Account administration requested', text: 'An administrator requested to send account email verification. This notice does not confirm completion.\n\nReview your account at {link}. If you did not expect this, contact the account operator.' },
+    'verify-email': { subject: 'Verify your email address', text: 'Verify your email address by opening this link:\n\n{link}\n\nIf you did not request this, ignore this email. Never share this link.' },
+    'reset-password': { subject: 'Reset your password', text: 'Reset your password by opening this link:\n\n{link}\n\nIf you did not request this, ignore this email. Never share this link.' },
+    'cancel-deletion': { subject: 'Cancel account deletion', text: 'Cancel account deletion by opening this link:\n\n{link}\n\nAccount deletion was requested. If you did not request this, use this link to cancel the deletion before the grace period ends. Never share this link.' },
+    invitation: { subject: 'Create your invited account', text: 'Create your invited account by opening this link:\n\n{link}\n\nIf you did not request this, ignore this email. Never share this link.' },
+    'verify-email-change': { subject: 'Verify your new email address', text: 'Verify your new email address by opening this link:\n\n{link}\n\nVerification confirms the new address. The change only activates after the 24-hour cooldown. Never share this link.' },
+    'cancel-email-change': { subject: 'Cancel an email address change', text: 'Cancel an email address change by opening this link:\n\n{link}\n\nA change to your account email was requested. Use this cancellation link before completion if this was not you. Never share this link.' },
+    'sign-in-code': { subject: 'Your sign-in code', text: 'Your sign-in code is: {code}\n\nEnter it at {link}\n\nIf you did not request this, ignore this email. Never share this code.' },
+    'signup-code': { subject: 'Verify your email address', text: 'Your signup code is: {code}\n\nEnter it in the browser where you started signing up at {link}\n\nIf you did not request this, ignore this email. Never share this code.' },
+    'factor-recovery': { subject: 'Second-factor recovery requested', text: 'Someone requested recovery of your account second factor. Confirm in the browser where you started recovery:\n\n{link}\n\nConfirmation starts a 24-hour waiting period. After that period, return to the confirmation link to finish recovery and enroll a new second factor. Existing sessions will be revoked when recovery completes.\n\nIf this was not you, cancel the request before it completes:\n\n{cancelLink}\n\nNever share these links.' },
+    'manual-recovery-warning': { subject: 'Manual account recovery approved', text: 'Two administrators approved a manual recovery request for your account. Completing recovery will replace your sign-in methods and revoke existing sessions. If you did not request this, contact the account operator immediately.' },
+    'manual-recovery': { subject: 'Restore account access', text: 'Two administrators approved your account recovery. Choose a new password and enroll a second factor at:\n\n{link}\n\nThis link expires in 30 minutes. Your existing sign-in methods and sessions will be revoked when recovery completes. Never share this link.' },
+    'new-device': { subject: 'Account security notification', text: 'A new device signed in to your account.\n\nReview your account at {link}. If this was not you, contact the account operator.' },
+    'password-changed': { subject: 'Account security notification', text: 'Your account password changed.\n\nReview your account at {link}. If this was not you, contact the account operator.' },
+    'email-changed': { subject: 'Account security notification', text: 'Your account email address changed.\n\nReview your account at {link}. If this was not you, contact the account operator.' },
+    'registration-attempt': { subject: 'Account security notification', text: 'Someone tried to create an account with your email address. Your existing account was not changed.\n\nReview your account at {link}. If this was not you, contact the account operator.' },
+});
+for (const template of Object.values(englishEmailCatalogue))
+    Object.freeze(template);
+const slots = (text) => [...new Set([...text.matchAll(/\{([A-Za-z]+)\}/g)].map(match => match[1]))].sort();
+function canonical(value) { if (typeof value !== 'string' || value.length > 64)
+    throw new Error('Invalid email locale'); return Intl.getCanonicalLocales(value)[0]; }
+/** Plain-text notices only. Translations must preserve every required capability placeholder. */
+export function createEmailCopy(options = {}) {
+    const defaultLocale = canonical(options.defaultLocale ?? 'en'), catalogues = new Map();
+    const entries = Object.entries(options.catalogues ?? {});
+    if (entries.length > 32)
+        throw new Error('Too many email locales');
+    for (const [raw, source] of entries) {
+        const locale = canonical(raw);
+        if (catalogues.has(locale) || !source || typeof source !== 'object' || Array.isArray(source))
+            throw new Error('Invalid email catalogue');
+        const copy = {};
+        let total = 0;
+        for (const [key, value] of Object.entries(source)) {
+            if (!Object.hasOwn(englishEmailCatalogue, key) || !value || typeof value.subject !== 'string' || typeof value.text !== 'string' || !value.subject || value.subject.length > 160 || /[\r\n\x00-\x1f\x7f]/.test(value.subject) || value.text.length > 16384 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value.text) || slots(value.subject).length || JSON.stringify(slots(value.text)) !== JSON.stringify(slots(englishEmailCatalogue[key].text)))
+                throw new Error('Invalid email template');
+            total += value.subject.length + value.text.length;
+            if (total > 65536)
+                throw new Error('Email catalogue too large');
+            copy[key] = Object.freeze({ subject: value.subject, text: value.text });
+        }
+        catalogues.set(locale, Object.freeze(copy));
+    }
+    return Object.freeze({ render(key, values, locale) { if (!Object.hasOwn(englishEmailCatalogue, key))
+            throw new Error('Unknown email template'); const language = canonical(locale ?? defaultLocale), template = catalogues.get(language)?.[key] ?? catalogues.get(language.split('-')[0])?.[key] ?? catalogues.get(defaultLocale)?.[key] ?? englishEmailCatalogue[key]; const text = template.text.replace(/\{([A-Za-z]+)\}/g, (_match, name) => { const value = values[name]; if (typeof value !== 'string' || value.length > 4096)
+            throw new Error('Missing email value'); return value; }); if (text.length > 16384)
+            throw new Error('Rendered email too large'); return { subject: template.subject, text }; } });
+}

package/dist/factor-recovery.d.ts

@@ -0,0 +1,46 @@
+import type { AuthChallenge } from './challenge.ts';
+import type { PresentationContext } from './presentation.ts';
+import type { ExtensionRequest } from '@jimhoyd/urlcode/extensions';
+import type { AuthSessionResult } from './auth-core.ts';
+import { AuthHttp } from './auth-ui.ts';
+import type { AuthHttpResponse, UiHost } from './auth-ui.ts';
+export interface FactorRecoveryService {
+    getFactorRecoveryEnabled(): boolean;
+    beginFactorRecovery(input: {
+        email: string;
+        browserToken: string;
+    }): Promise<{
+        verificationToken: string | null;
+        cancelToken: string | null;
+    }>;
+    confirmFactorRecovery(input: {
+        token: string;
+        browserToken: string;
+    }): Promise<{
+        completeAfter: number;
+        expires: number;
+    }>;
+    cancelFactorRecovery(token: string): Promise<void>;
+    completeFactorRecovery(input: {
+        token: string;
+        browserToken: string;
+    }): Promise<AuthSessionResult>;
+}
+export interface FactorRecoveryMessage {
+    email: string;
+    verificationToken: string;
+    cancelToken: string;
+    locale?: string;
+    signal: AbortSignal;
+}
+export interface FactorRecoveryOptions {
+    challenge?: AuthChallenge;
+    service: FactorRecoveryService;
+    sendFactorRecovery?: (message: FactorRecoveryMessage) => Promise<void>;
+    ui?: UiHost;
+}
+/** Opt-in email fallback lowers factor assurance; it never creates an unrestricted session. */
+export declare function createFactorRecoveryFlows(options: FactorRecoveryOptions, http: AuthHttp, mount: string): {
+    enabled: () => boolean;
+    handle(request: ExtensionRequest, presentation?: PresentationContext): Promise<AuthHttpResponse | undefined>;
+};

package/dist/factor-recovery.js

@@ -0,0 +1,71 @@
+import { createPresentation } from "./presentation.js";
+import { randomBytes } from 'node:crypto';
+import { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, jsonResponse, readFields, screenResponse, wantsJson } from "./auth-ui.js";
+import { hiddenField, Markup } from '@jimhoyd/urlcode-ui';
+/** Opt-in email fallback lowers factor assurance; it never creates an unrestricted session. */
+export function createFactorRecoveryFlows(options, http, mount) {
+    const browserCookie = '__Host-urlcode-factor-recovery';
+    const enabled = () => options.service.getFactorRecoveryEnabled() && Boolean(options.sendFactorRecovery);
+    const hidden = (token) => hiddenField('token', token);
+    return { enabled, async handle(request, presentation = createPresentation().resolve()) {
+            const tr = (key, values) => presentation.text(key, values);
+            const form = (path, csrf, markup, label) => `<form method="post" action="${escapeHtml(mount + path + '?lang=' + encodeURIComponent(presentation.locale))}">${csrfField(csrf)}${markup}<button type="submit">${escapeHtml(label)}</button></form>`;
+            const page = (title, view, status = 200, headers = []) => screenResponse(title, { name: 'auth/recover-factor', view: { intro: view.intro, form: new Markup(view.form) } }, { status, headers, presentation, turnstile: request.path === mount + '/recover-factor' && request.method !== 'POST' ? options.challenge?.widget : undefined, layout: 'compact', ui: options.ui });
+            const status = (title, message, headers = []) => screenResponse(title, { name: 'auth/status', view: { alert: false, message, href: mount + '/login', label: presentation.textSource('Back to sign in') } }, { status: 200, headers, presentation, layout: 'compact', ui: options.ui });
+            const path = request.path.slice(mount.length);
+            if (!['/recover-factor', '/recover-factor/confirm', '/recover-factor/cancel', '/recover-factor/complete'].includes(path))
+                return;
+            if (!enabled())
+                throw new AuthHttpError(404, 'Not found');
+            if (!['GET', 'HEAD', 'POST'].includes(request.method))
+                throw new AuthHttpError(405, 'GET, HEAD or POST required');
+            if (request.method !== 'POST') {
+                const prepared = http.prepare(request);
+                if (path === '/recover-factor')
+                    return page(tr('recovery.title'), { intro: tr('recovery.intro'), form: form(path, prepared.csrf, formField('email', presentation.textSource('Email address'), 'email', 'username'), tr('recovery.send')) }, 200, prepared.headers);
+                const tokens = request.query.getAll('token');
+                if (tokens.length !== 1 || !/^[A-Za-z0-9_-]{43}$/.test(tokens[0]))
+                    throw new AuthHttpError(400, 'A single recovery token is required');
+                if (path === '/recover-factor/cancel')
+                    return page(tr('recovery.cancelTitle'), { intro: null, form: form(path, prepared.csrf, hidden(tokens[0]), tr('recovery.cancel')) }, 200, prepared.headers);
+                return page(tr('recovery.confirmTitle'), { intro: tr('recovery.confirmInfo'), form: form('/recover-factor/confirm', prepared.csrf, hidden(tokens[0]), tr('recovery.confirm')) + form('/recover-factor/complete', prepared.csrf, hidden(tokens[0]), tr('recovery.complete')) }, 200, prepared.headers);
+            }
+            const fields = readFields(request, ['email', 'token']);
+            http.verify(request, fields);
+            if (path === '/recover-factor') {
+                const browserToken = http.cookie(request, browserCookie) || randomBytes(32).toString('base64url');
+                const issued = await options.service.beginFactorRecovery({ email: fields.email || '', browserToken });
+                if (issued.verificationToken && issued.cancelToken) {
+                    const controller = new AbortController();
+                    let timer;
+                    try {
+                        await Promise.race([options.sendFactorRecovery({ email: fields.email || '', verificationToken: issued.verificationToken, cancelToken: issued.cancelToken, locale: presentation.locale, signal: controller.signal }), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('Delivery timeout')); }, 5000); })]);
+                    }
+                    catch {
+                        await options.service.cancelFactorRecovery(issued.cancelToken).catch(() => { });
+                    }
+                    finally {
+                        if (timer)
+                            clearTimeout(timer);
+                    }
+                }
+                const responseHeaders = [['set-cookie', http.setCookie(browserCookie, browserToken, 5 * 86400)]];
+                return wantsJson(request) ? jsonResponse(200, { message: 'If this account is eligible, recovery instructions will be sent. Continue in this browser.' }, responseHeaders) : status(presentation.textSource('Check your email'), presentation.textSource('If this account is eligible, recovery instructions will be sent. Continue in this browser.'), responseHeaders);
+            }
+            if (path === '/recover-factor/cancel') {
+                await options.service.cancelFactorRecovery(fields.token || '');
+                return wantsJson(request) ? jsonResponse(200, { cancelled: true }) : status(presentation.textSource('Recovery cancelled'), presentation.textSource('This recovery request has been cancelled. Your existing sign-in methods are unchanged.'));
+            }
+            const browserToken = http.cookie(request, browserCookie);
+            if (!browserToken)
+                throw new AuthHttpError(403, 'Use the browser that requested recovery');
+            if (path === '/recover-factor/confirm') {
+                const result = await options.service.confirmFactorRecovery({ token: fields.token || '', browserToken });
+                return wantsJson(request) ? jsonResponse(200, result) : page(tr('recovery.waitTitle'), { intro: tr('recovery.waitInfo', { time: new Date(result.completeAfter).toISOString() }), form: form('/recover-factor/complete', http.token(http.session(request) || http.cookie(request, http.flowCookie) || ''), hidden(fields.token || ''), tr('recovery.complete')) });
+            }
+            const result = await options.service.completeFactorRecovery({ token: fields.token || '', browserToken });
+            const headers = http.sessionHeaders(result.token);
+            headers.push(['set-cookie', http.setCookie(browserCookie, '', 0)]);
+            return wantsJson(request) ? jsonResponse(200, { enrollmentRequired: true, user: result.user, csrf: http.token(result.token) }, headers) : jsonResponse(303, { enrollmentRequired: true }, [['location', mount + '/account'], ...headers]);
+        } };
+}

package/dist/index.d.ts

@@ -0,0 +1,42 @@
+export { createAuthService, AuthError } from './auth-core.ts';
+export type { AuthService, AuthPrincipal, AuthUser } from './auth-core.ts';
+export { authExtension, hasPermission } from './auth.ts';
+export type { AuthExtensionOptions } from './auth.ts';
+export type { AuthHttpOptions, AuthHttpResponse } from './auth-ui.ts';
+export { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, httpFailure, jsonResponse, pageResponse, readFields, screenResponse, wantsJson } from './auth-ui.ts';
+export type { Screen, ScreenOptions, UiHost } from './auth-ui.ts';
+export { authTemplates, authTemplateNames, authUiTemplates } from './auth-templates.ts';
+export type { AuthTemplate } from './auth-templates.ts';
+export { createOidcProvider } from './oidc.ts';
+export type { OidcProvider, OidcFlow, OidcIdentity, OidcProviderOptions } from './oidc.ts';
+export { createPasskeyProvider } from './passkeys.ts';
+export type { PasskeyProvider, StoredPasskey, PasskeyProviderOptions } from './passkeys.ts';
+export { createSesSender, createDevelopmentSender } from './senders.ts';
+export { createPresentation, englishCatalogue, englishCatalogue as authCatalogue } from './presentation.ts';
+export type { Presentation, PresentationOptions, PresentationContext, Catalogue, ThemeVariables } from './presentation.ts';
+export * from './registration.ts';
+export { createGoogleProvider, createAppleProvider } from './providers.ts';
+export type { GoogleProviderOptions, AppleProviderOptions } from './providers.ts';
+export { createBackup, restoreBackup } from './backup.ts';
+export type { BackupOptions, BackupResult, RestoreOptions } from './backup.ts';
+export type { AuthOptions, AuthSessionResult, AuthSession, AuthAuditEvent, AuthCase } from './auth-core.ts';
+export { initAuthentication, scaffold } from './scaffold.ts';
+export type { AuthenticationScaffold, ScaffoldRequest, ScaffoldResult, ScaffoldFile } from './scaffold.ts';
+export type { EmailSender, TokenSender, TokenMessage, EmailCodeMessage, FactorRecoveryMessage, SignupCodeMessage, SecurityNotice, SesSenderOptions, DevelopmentSenderOptions } from './senders.ts';
+export { createPasswordBreachChecker } from './password-policy.ts';
+export type { PasswordBreachOptions } from './password-policy.ts';
+export type { AuthDailyMetric, AuthHookStats, AuthLifecycleEvent, AuthCredentials, AuthSecondFactor, AuthDevice, AuthPasskey, AuthProof, ExternalAuthProof, PasskeyAuthProof, SignupBinding, SignupState, SignupStart } from './auth-core.ts';
+export { createAuthPreset } from './presets.ts';
+export type { AuthPreset, AuthPresetOptions } from './presets.ts';
+export type { AuthRestriction, AuthSecurityPolicy } from './auth-core.ts';
+export { verifyDeployment } from './deployment-check.ts';
+export type { DeploymentCheckOptions, DeploymentCheckResult } from './deployment-check.ts';
+export type { ManualRecoveryService, ManualRecoveryCase, ManualRecoveryDelivery, ManualRecoveryEvidence } from './manual-recovery.ts';
+export type { UserQuery, ValidatedUserQuery } from './user-query.ts';
+export { validateUserQuery } from './user-query.ts';
+export { createEmailCopy, englishEmailCatalogue } from './email-copy.ts';
+export type { EmailCopy, EmailCopyOptions, EmailTemplateKey } from './email-copy.ts';
+export type { AdminAccountAction, AdminAccountDelivery, AdminAccountRequest, AdminAuthenticationMethods, AdminAccountService } from './admin-account-operations.ts';
+export type { TurnstileWidget } from './challenge-ui.ts';
+export { createTurnstileChallenge } from './challenge.ts';
+export type { AuthChallenge, AuthChallengeInput, TurnstileChallengeOptions } from './challenge.ts';

package/dist/index.js

@@ -0,0 +1,18 @@
+export { createAuthService, AuthError } from "./auth-core.js";
+export { authExtension, hasPermission } from "./auth.js";
+export { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, httpFailure, jsonResponse, pageResponse, readFields, screenResponse, wantsJson } from "./auth-ui.js";
+export { authTemplates, authTemplateNames, authUiTemplates } from "./auth-templates.js";
+export { createOidcProvider } from "./oidc.js";
+export { createPasskeyProvider } from "./passkeys.js";
+export { createSesSender, createDevelopmentSender } from "./senders.js";
+export { createPresentation, englishCatalogue, englishCatalogue as authCatalogue } from "./presentation.js";
+export * from "./registration.js";
+export { createGoogleProvider, createAppleProvider } from "./providers.js";
+export { createBackup, restoreBackup } from "./backup.js";
+export { initAuthentication, scaffold } from "./scaffold.js";
+export { createPasswordBreachChecker } from "./password-policy.js";
+export { createAuthPreset } from "./presets.js";
+export { verifyDeployment } from "./deployment-check.js";
+export { validateUserQuery } from "./user-query.js";
+export { createEmailCopy, englishEmailCatalogue } from "./email-copy.js";
+export { createTurnstileChallenge } from "./challenge.js";

package/dist/manual-recovery-store.d.ts

@@ -0,0 +1,25 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { AuthRecord, SessionRecord } from './auth-store.ts';
+interface Context {
+    db: DatabaseSync;
+    enabled: boolean;
+    now: number;
+    account(id: string): AuthRecord | null;
+    active(id: string): AuthRecord;
+    fresh(hash: string, now: number): {
+        user: AuthRecord;
+        session: SessionRecord;
+    };
+    authorizeCase(actor: AuthRecord, target: AuthRecord): void;
+    save(user: AuthRecord): void;
+    addSession(session: SessionRecord): void;
+    audit(actor: string, action: string, subject: string, now: number, reason?: string): void;
+    isAdministrator(user: AuthRecord): boolean;
+    isRestricted(user: AuthRecord): boolean;
+    fail(status: number, code: string): never;
+}
+/** Called only inside the store's revision-checked BEGIN IMMEDIATE dispatch. */
+export declare function manualRecoveryOperation(operation: string, args: Record<string, unknown>, context: Context): {
+    value: unknown;
+} | undefined;
+export {};

package/dist/manual-recovery-store.js

@@ -0,0 +1,129 @@
+/** Called only inside the store's revision-checked BEGIN IMMEDIATE dispatch. */
+export function manualRecoveryOperation(operation, args, context) {
+    if (!operation.startsWith('manualRecovery'))
+        return;
+    const { db, now } = context;
+    const fail = context.fail;
+    if (!context.enabled)
+        fail(403, 'manual_recovery_disabled');
+    const rowCase = (id) => { const row = db.prepare('SELECT data FROM auth_cases WHERE id=?').get(id); if (!row)
+        fail(404, 'case_not_found'); const item = JSON.parse(String(row.data)); if (item.action !== 'restore-access')
+        fail(400, 'invalid_recovery_case'); return item; };
+    const saveCase = (item) => db.prepare('UPDATE auth_cases SET data=? WHERE id=?').run(JSON.stringify(item), item.id);
+    const availableEmail = (email, accountId) => { const row = db.prepare('SELECT id FROM auth_accounts WHERE email=?').get(email); if (row && row.id !== accountId)
+        fail(409, 'email_unavailable'); };
+    const targetFor = (item) => { const target = context.account(item.accountId); if (!target || target.version !== item.targetVersion)
+        fail(409, 'case_target_changed'); return target; };
+    const authorize = (item, target) => { context.authorizeCase(context.active(item.makerId), target); if (item.approverId)
+        context.authorizeCase(context.active(item.approverId), target); };
+    switch (operation) {
+        case 'manualRecoveryCreate': {
+            const maker = context.fresh(String(args.hash), now).user, target = context.account(String(args.accountId));
+            if (!target)
+                fail(404, 'account_not_found');
+            context.authorizeCase(maker, target);
+            availableEmail(String(args.email), target.id);
+            if (Number(db.prepare('SELECT count(*) AS n FROM auth_cases').get()?.n) >= 10000)
+                fail(503, 'auth_capacity_reached');
+            const item = { id: String(args.id), accountId: target.id, action: 'restore-access', reason: String(args.reason), makerId: maker.id, status: 'pending', created: now, expires: now + 86400000, targetVersion: target.version, recovery: { email: String(args.email), evidence: args.evidence, state: 'review' } };
+            db.prepare('INSERT INTO auth_cases(id,data) VALUES(?,?)').run(item.id, JSON.stringify(item));
+            context.audit(maker.id, 'recovery.case_created', target.id, now, item.reason);
+            return { value: item };
+        }
+        case 'manualRecoveryList': return { value: db.prepare("SELECT data FROM auth_cases WHERE id>? AND json_extract(data,'$.action')='restore-access' ORDER BY id LIMIT ?").all(String(args.after), Number(args.limit)).map(row => JSON.parse(String(row.data))) };
+        case 'manualRecoveryCheck': {
+            const credential = db.prepare('SELECT * FROM auth_manual_recovery WHERE hash=? AND active=1 AND expires>?').get(String(args.tokenHash), now);
+            if (!credential)
+                fail(401, 'invalid_recovery');
+            const item = rowCase(String(credential.case_id)), target = targetFor(item);
+            authorize(item, target);
+            return { value: undefined };
+        }
+        case 'manualRecoveryApprove': {
+            const checker = context.fresh(String(args.hash), now).user, item = rowCase(String(args.id));
+            if (item.status !== 'pending' || item.expires <= now)
+                fail(409, 'case_unavailable');
+            if (item.makerId === checker.id)
+                fail(403, 'distinct_approver_required');
+            const target = targetFor(item);
+            authorize(item, target);
+            context.authorizeCase(checker, target);
+            availableEmail(item.recovery.email, target.id);
+            db.prepare('INSERT INTO auth_manual_recovery(hash,case_id,account_id,version,approver_id,maker_version,approver_version,active,expires) VALUES(?,?,?,?,?,?,?,0,?)').run(String(args.tokenHash), item.id, target.id, target.version, checker.id, context.active(item.makerId).version, checker.version, now + 1800000);
+            item.status = 'applied';
+            item.approverId = checker.id;
+            item.recovery.state = 'delivery';
+            saveCase(item);
+            context.audit(checker.id, 'recovery.case_approved', target.id, now, String(args.reason));
+            return { value: { case: item, email: item.recovery.email, oldEmail: target.email } };
+        }
+        case 'manualRecoveryActivate':
+        case 'manualRecoveryCancel': {
+            const checker = context.fresh(String(args.hash), now).user, item = rowCase(String(args.id)), credential = db.prepare('SELECT * FROM auth_manual_recovery WHERE hash=? AND case_id=?').get(String(args.tokenHash), item.id);
+            if (!credential || credential.approver_id !== checker.id || item.approverId !== checker.id)
+                fail(409, 'recovery_unavailable');
+            if (operation === 'manualRecoveryCancel') {
+                db.prepare('DELETE FROM auth_manual_recovery WHERE case_id=?').run(item.id);
+                item.recovery.state = 'cancelled';
+                item.status = 'closed';
+                saveCase(item);
+                context.audit(checker.id, 'recovery.delivery_cancelled', item.accountId, now);
+                return { value: undefined };
+            }
+            if (Number(credential.expires) <= now || credential.active !== 0 || item.recovery.state !== 'delivery')
+                fail(409, 'recovery_unavailable');
+            const target = targetFor(item);
+            authorize(item, target);
+            if (context.active(item.makerId).version !== credential.maker_version || checker.version !== credential.approver_version)
+                fail(409, 'recovery_approval_changed');
+            availableEmail(item.recovery.email, target.id);
+            db.prepare('UPDATE auth_manual_recovery SET active=1 WHERE hash=?').run(String(args.tokenHash));
+            item.recovery.state = 'ready';
+            saveCase(item);
+            context.audit(checker.id, 'recovery.delivery_confirmed', item.accountId, now);
+            return { value: undefined };
+        }
+        case 'manualRecoveryRedeem': {
+            const credential = db.prepare('SELECT * FROM auth_manual_recovery WHERE hash=? AND active=1 AND expires>?').get(String(args.tokenHash), now);
+            if (!credential)
+                fail(401, 'invalid_recovery');
+            const item = rowCase(String(credential.case_id));
+            if (item.recovery.state !== 'ready')
+                fail(401, 'invalid_recovery');
+            const target = targetFor(item);
+            authorize(item, target);
+            if (context.active(item.makerId).version !== credential.maker_version || context.active(item.approverId).version !== credential.approver_version)
+                fail(409, 'recovery_approval_changed');
+            availableEmail(item.recovery.email, target.id);
+            if (context.isAdministrator(target) && !db.prepare("SELECT data FROM auth_accounts WHERE administrator=1 AND status='active' AND id<>?").all(target.id).some(row => !context.isRestricted(JSON.parse(String(row.data)))))
+                fail(409, 'last_administrator_required');
+            target.email = item.recovery.email;
+            target.emailVerified = true;
+            target.passwordHash = String(args.passwordHash);
+            target.status = 'active';
+            target.mfaRecoveryRequired = true;
+            target.version++;
+            delete target.totpSecret;
+            delete target.totpPending;
+            delete target.totpPendingUntil;
+            delete target.mfaPasskeys;
+            target.totpCounter = -1;
+            db.prepare('UPDATE auth_accounts SET email=? WHERE id=?').run(target.email, target.id);
+            context.save(target);
+            for (const table of ['auth_sessions', 'auth_tokens', 'auth_recovery', 'auth_method_activity', 'auth_passkeys', 'auth_external', 'auth_email_codes', 'auth_email_changes', 'auth_factor_recovery', 'auth_second_factor_proofs', 'auth_trusted_devices', 'auth_manual_recovery'])
+                db.prepare(`DELETE FROM ${table} WHERE account_id=?`).run(target.id);
+            const session = args.session;
+            session.accountId = target.id;
+            session.recoveryEnrollment = 1;
+            session.primaryMethod = 'recovery';
+            session.mfaAuthenticatedAt = 0;
+            session.mfaVersion = 0;
+            context.addSession(session);
+            item.recovery.state = 'redeemed';
+            saveCase(item);
+            context.audit(target.id, 'recovery.access_restored', target.id, now, item.id);
+            return { value: target };
+        }
+        default: return;
+    }
+}

package/dist/manual-recovery.d.ts

@@ -0,0 +1,87 @@
+import type { ExtensionRequest } from '@jimhoyd/urlcode/extensions';
+import type { AuthSessionResult } from './auth-core.ts';
+import type { PresentationContext } from './presentation.ts';
+import { AuthHttp } from './auth-ui.ts';
+import type { UiHost } from './auth-ui.ts';
+import type { AuthHttpResponse } from './auth-ui.ts';
+/** Evidence is an internal human assessment, never an automatic identity assertion. */
+export interface ManualRecoveryEvidence {
+    summary: string;
+    reference?: string;
+}
+export interface ManualRecoveryCase {
+    id: string;
+    accountId: string;
+    action: 'restore-access';
+    reason: string;
+    makerId: string;
+    approverId?: string;
+    status: 'pending' | 'applied' | 'closed';
+    created: number;
+    expires: number;
+    targetVersion: number;
+    recovery: {
+        email: string;
+        evidence: ManualRecoveryEvidence;
+        state: 'review' | 'delivery' | 'ready' | 'redeemed' | 'cancelled';
+    };
+    notes?: {
+        actorId: string;
+        note: string;
+        created: number;
+    }[];
+}
+/** Delivery must send the approved address its link AND warn the old address before resolving. */
+export interface ManualRecoveryDelivery {
+    email: string;
+    oldEmail: string;
+    token: string;
+    caseId: string;
+    signal: AbortSignal;
+}
+export interface ManualRecoveryService {
+    getManualRecoveryEnabled(): boolean;
+    createRecoveryCase(input: {
+        actorToken: string;
+        accountId: string;
+        email: string;
+        evidence: ManualRecoveryEvidence;
+        reason: string;
+    }): Promise<ManualRecoveryCase>;
+    listRecoveryCases(options?: {
+        limit?: number;
+        after?: string;
+    }): Promise<{
+        cases: ManualRecoveryCase[];
+        next?: string;
+    }>;
+    approveRecoveryCase(input: {
+        actorToken: string;
+        caseId: string;
+        reason: string;
+    }): Promise<{
+        case: ManualRecoveryCase;
+        token: string;
+        email: string;
+        oldEmail: string;
+    }>;
+    activateRecoveryCase(input: {
+        actorToken: string;
+        caseId: string;
+        token: string;
+    }): Promise<void>;
+    cancelRecoveryCredential(input: {
+        actorToken: string;
+        caseId: string;
+        token: string;
+    }): Promise<void>;
+    redeemRecoveryCase(input: {
+        token: string;
+        password: string;
+    }): Promise<AuthSessionResult>;
+}
+export declare function validateRecoveryEvidence(input: ManualRecoveryEvidence): ManualRecoveryEvidence;
+/** Redemption is POST-only and creates an enrollment session, never normal access. */
+export declare function createManualRecoveryFlows(service: ManualRecoveryService, http: AuthHttp, mount: string, ui?: UiHost): {
+    handle(request: ExtensionRequest, presentation?: PresentationContext): Promise<AuthHttpResponse | undefined>;
+};