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

package/dist/abuse-http.d.ts

@@ -0,0 +1,8 @@
+import type { ExtensionRequest } from '@jimhoyd/urlcode/extensions';
+import type { AuthService } from './auth-core.ts';
+import type { AuthChallenge } from './challenge.ts';
+import { AuthHttp } from './auth-ui.ts';
+import type { UiHost } from './auth-ui.ts';
+import type { PresentationContext } from './presentation.ts';
+/** Entry requests only: callback and code/token redemption keep their own bound proofs. */
+export declare function createAbuseGuard(service: AuthService, http: AuthHttp, mount: string, challenge?: AuthChallenge, ui?: UiHost): (request: ExtensionRequest, presentation?: PresentationContext) => Promise<import("./auth-ui.ts").AuthHttpResponse | undefined>;

package/dist/abuse-http.js

@@ -0,0 +1,74 @@
+import { AuthHttp, AuthHttpError, jsonResponse, screenResponse, wantsJson } from "./auth-ui.js";
+import { isHoneypotFilled } from "./registration.js";
+/** Entry requests only: callback and code/token redemption keep their own bound proofs. */
+export function createAbuseGuard(service, http, mount, challenge, ui) {
+    const policy = service.getAbusePolicy();
+    if (policy?.challengeAfter !== undefined && !challenge)
+        throw new Error('Challenge policy requires an operator verifier');
+    let active = 0;
+    return async (request, presentation) => {
+        const path = request.path.slice(mount.length), signup = path === '/register' || path === '/signup/begin';
+        const entry = ['/login', '/register', '/signup/begin', '/forgot-password', '/send-email-code', '/recover-factor', '/passkeys/login/options'].includes(path) || /^\/providers\/[a-z][a-z0-9-]{0,31}\/start$/.test(path);
+        if (request.method !== 'POST' || !entry)
+            return;
+        if (request.body.byteLength > 16384)
+            throw new AuthHttpError(413, 'Request body too large');
+        let fields = {};
+        const type = request.headers.get('content-type')?.split(';')[0];
+        try {
+            const raw = new TextDecoder('utf-8', { fatal: true }).decode(request.body);
+            if (type === 'application/json') {
+                const value = JSON.parse(raw);
+                if (!value || typeof value !== 'object' || Array.isArray(value))
+                    throw new Error();
+                fields = value;
+            }
+            else if (type === 'application/x-www-form-urlencoded') {
+                const entries = [...new URLSearchParams(raw)];
+                if (new Set(entries.map(([key]) => key)).size !== entries.length)
+                    throw new Error();
+                fields = Object.fromEntries(entries);
+            }
+            else
+                throw new Error();
+        }
+        catch {
+            throw new AuthHttpError(400, 'Invalid authentication request');
+        }
+        if (Object.keys(fields).length > 64 || fields.csrf !== undefined && typeof fields.csrf !== 'string' || fields.challengeToken !== undefined && (typeof fields.challengeToken !== 'string' || fields.challengeToken.length > 2048))
+            throw new AuthHttpError(400, 'Invalid authentication request');
+        http.verify(request, { csrf: typeof fields.csrf === 'string' ? fields.csrf : '' });
+        if (signup && isHoneypotFilled(fields.website))
+            return jsonResponse(202, { message: 'Registration request received.' });
+        if (!policy)
+            return;
+        const admission = await service.admitAuthRequest({ client: request.client, ...(signup ? { signupEmail: typeof fields.email === 'string' ? fields.email : '' } : {}) });
+        if (!admission.challengeRequired)
+            return;
+        let passed = false;
+        if (challenge && typeof fields.challengeToken === 'string' && fields.challengeToken && request.client && active < 32) {
+            active++;
+            const controller = new AbortController();
+            let timer;
+            const verification = Promise.resolve().then(() => challenge.verify({ token: fields.challengeToken, client: request.client, signal: controller.signal }));
+            void verification.finally(() => { active--; }).catch(() => { });
+            try {
+                passed = await Promise.race([verification, new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(false); }, 5000); })]);
+            }
+            catch {
+                passed = false;
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        }
+        if (passed !== true) {
+            const source = 'Challenge required. Return to the form and try again.', message = presentation?.textSource(source) ?? source;
+            if (wantsJson(request))
+                return jsonResponse(403, { error: message, challengeRequired: true });
+            const retry = signup ? '/signup' : path === '/forgot-password' || path === '/recover-factor' ? path : path === '/send-email-code' ? '/email-code' : '/login';
+            return screenResponse('Verification required', { name: 'auth/status', view: { alert: true, message, href: mount + retry, label: presentation?.textSource('Try again') ?? 'Try again' } }, { status: 403, presentation, ui });
+        }
+    };
+}

package/dist/abuse-store.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { AuthAbusePolicy } from './abuse.ts';
+export declare function abuseOperation(operation: string, args: Record<string, unknown>, db: DatabaseSync, policy: AuthAbusePolicy | undefined, fail: (status: number, code: string) => never): {
+    value: unknown;
+} | undefined;

package/dist/abuse-store.js

@@ -0,0 +1,40 @@
+export function abuseOperation(operation, args, db, policy, fail) {
+    if (!operation.startsWith('abuse'))
+        return;
+    const now = Number(args.now), key = String(args.key);
+    const ensure = (count = 1) => { db.prepare('DELETE FROM auth_abuse WHERE key IN (SELECT key FROM auth_abuse WHERE expires<=? LIMIT 1000)').run(now); if (Number(db.prepare('SELECT count(*) AS n FROM auth_abuse').get()?.n) + count > 100000)
+        fail(503, 'auth_capacity_reached'); };
+    if (operation === 'abuseBackoffCheck') {
+        const row = db.prepare('SELECT blocked_until FROM auth_abuse WHERE key=? AND expires>?').get(key, now);
+        return { value: Boolean(row && Number(row.blocked_until) > now) };
+    }
+    if (operation === 'abuseFailure') {
+        const config = policy?.passwordBackoff;
+        if (!config)
+            return { value: undefined };
+        const row = db.prepare('SELECT count FROM auth_abuse WHERE key=? AND expires>?').get(key, now);
+        if (!row)
+            ensure();
+        const count = Math.min(64, Number(row?.count ?? 0) + 1), delay = count < config.threshold ? 0 : Math.min(config.maxDelayMs, config.initialDelayMs * 2 ** Math.min(30, count - config.threshold));
+        db.prepare('INSERT INTO auth_abuse VALUES(?,?,?,?) ON CONFLICT(key) DO UPDATE SET count=excluded.count,expires=excluded.expires,blocked_until=excluded.blocked_until').run(key, count, now + config.resetAfterMs, now + delay);
+        return { value: undefined };
+    }
+    if (operation === 'abuseAdmit') {
+        const limits = args.limits;
+        let challengeRequired = false;
+        const rows = limits.map(item => ({ item, row: db.prepare('SELECT count,expires FROM auth_abuse WHERE key=? AND expires>?').get(item.key, now) }));
+        if (rows.some(({ item, row }) => Number(row?.count ?? 0) >= item.limit))
+            fail(429, 'auth_rate_limited');
+        const added = rows.filter(({ row }) => !row).length;
+        if (added)
+            ensure(added);
+        for (const { item, row } of rows) {
+            const count = Number(row?.count ?? 0) + 1;
+            db.prepare('INSERT INTO auth_abuse VALUES(?,?,?,0) ON CONFLICT(key) DO UPDATE SET count=excluded.count,expires=excluded.expires,blocked_until=0').run(item.key, count, row ? Number(row.expires) : now + item.windowMs);
+            if (item.challengeAfter !== undefined && count > item.challengeAfter)
+                challengeRequired = true;
+        }
+        return { value: { challengeRequired } };
+    }
+    return;
+}

package/dist/abuse.d.ts

@@ -0,0 +1,27 @@
+export interface VelocityLimit {
+    limit: number;
+    windowMs: number;
+}
+export interface AuthAbuseOptions {
+    passwordBackoff?: {
+        threshold?: number;
+        initialDelayMs?: number;
+        maxDelayMs?: number;
+        resetAfterMs?: number;
+    };
+    client?: VelocityLimit;
+    signupClient?: VelocityLimit;
+    signupDomain?: VelocityLimit;
+    challengeAfter?: number;
+}
+export interface AuthAbusePolicy extends Omit<AuthAbuseOptions, 'passwordBackoff'> {
+    passwordBackoff?: {
+        threshold: number;
+        initialDelayMs: number;
+        maxDelayMs: number;
+        resetAfterMs: number;
+    };
+}
+export declare function normalizeAbusePolicy(value: AuthAbuseOptions | undefined): AuthAbusePolicy | undefined;
+/** Pseudonymous, bounded counter keys. No raw address, email or domain is stored. */
+export declare const abuseKey: (scope: string, value: string) => string;

package/dist/abuse.js

@@ -0,0 +1,34 @@
+import { createHash } from 'node:crypto';
+const integer = (value, min, max) => typeof value === 'number' && Number.isSafeInteger(value) && value >= min && value <= max;
+export function normalizeAbusePolicy(value) {
+    if (value === undefined)
+        return;
+    if (!value || typeof value !== 'object' || Array.isArray(value) || Object.keys(value).some(key => !['passwordBackoff', 'client', 'signupClient', 'signupDomain', 'challengeAfter'].includes(key)))
+        throw new Error('Invalid abuse policy');
+    const policy = {};
+    for (const name of ['client', 'signupClient', 'signupDomain']) {
+        const item = value[name];
+        if (item !== undefined) {
+            if (!item || Object.keys(item).some(key => !['limit', 'windowMs'].includes(key)) || !integer(item.limit, 1, 100000) || !integer(item.windowMs, 1000, 86400000))
+                throw new Error('Invalid velocity limit');
+            policy[name] = { limit: item.limit, windowMs: item.windowMs };
+        }
+    }
+    if (value.passwordBackoff !== undefined) {
+        const item = value.passwordBackoff;
+        if (!item || Object.keys(item).some(key => !['threshold', 'initialDelayMs', 'maxDelayMs', 'resetAfterMs'].includes(key)))
+            throw new Error('Invalid backoff policy');
+        const backoff = { threshold: item.threshold ?? 5, initialDelayMs: item.initialDelayMs ?? 1000, maxDelayMs: item.maxDelayMs ?? 900000, resetAfterMs: item.resetAfterMs ?? 86400000 };
+        if (!integer(backoff.threshold, 1, 20) || !integer(backoff.initialDelayMs, 100, 60000) || !integer(backoff.maxDelayMs, backoff.initialDelayMs, 86400000) || !integer(backoff.resetAfterMs, backoff.maxDelayMs, 604800000))
+            throw new Error('Invalid backoff policy');
+        policy.passwordBackoff = backoff;
+    }
+    if (value.challengeAfter !== undefined) {
+        if (!policy.client || !integer(value.challengeAfter, 1, policy.client.limit - 1))
+            throw new Error('Challenge threshold requires a client limit');
+        policy.challengeAfter = value.challengeAfter;
+    }
+    return Object.freeze(policy);
+}
+/** Pseudonymous, bounded counter keys. No raw address, email or domain is stored. */
+export const abuseKey = (scope, value) => createHash('sha256').update('urlcode-auth-abuse:' + scope + '\0' + value).digest('hex');

package/dist/admin-account-operations.d.ts

@@ -0,0 +1,83 @@
+import type { AuthStore } from './auth-store.ts';
+export type AdminAccountAction = 'verify-email' | 'force-password-reset' | 'schedule-deletion' | 'cancel-deletion' | 'remove-passkey' | 'remove-external' | 'request-email-change' | 'assign-roles' | 'resend-verification';
+export type AdminAccountDelivery = {
+    kind: 'token';
+    accountId: string;
+    email: string;
+    locale?: string;
+    purpose: 'verify-email' | 'reset-password' | 'cancel-deletion' | 'verify-email-change' | 'cancel-email-change';
+    token: string;
+} | {
+    kind: 'notice';
+    accountId: string;
+    email: string;
+    locale?: string;
+    action: AdminAccountAction;
+};
+export type AdminAccountRequest = {
+    actorToken: string;
+    accountIds: string[];
+    reason: string;
+} & ({
+    action: 'assign-roles';
+    roles: string[];
+} | {
+    action: 'request-email-change';
+    email: string;
+} | {
+    action: 'remove-passkey';
+    credentialId: string;
+} | {
+    action: 'remove-external';
+    externalId: string;
+} | {
+    action: 'verify-email' | 'force-password-reset' | 'schedule-deletion' | 'cancel-deletion' | 'resend-verification';
+});
+export interface AdminAuthenticationMethods {
+    accountId: string;
+    password: boolean;
+    totp: boolean;
+    passkeys: {
+        id: string;
+        secondFactor: boolean;
+        added?: number;
+        lastUsed?: number;
+    }[];
+    external: {
+        id: string;
+        provider: string;
+        added?: number;
+        lastUsed?: number;
+    }[];
+}
+export interface AdminAccountService {
+    inspectAccountAuthentication(input: {
+        actorToken: string;
+        accountId: string;
+        reason: string;
+    }): Promise<AdminAuthenticationMethods>;
+    stageAccountAdministration(input: AdminAccountRequest): Promise<{
+        operationId: string;
+        deliveries: AdminAccountDelivery[];
+    }>;
+    completeAccountAdministration(input: {
+        actorToken: string;
+        operationId: string;
+    }): Promise<{
+        affected: number;
+    }>;
+    cancelAccountAdministration(input: {
+        actorToken: string;
+        operationId: string;
+    }): Promise<void>;
+}
+interface Dependencies {
+    store: AuthStore;
+    check(): void;
+    now(): number;
+    roles: Record<string, string[]>;
+    permittedEmail(value: string): string;
+}
+/** Operator-side service. Only declared delivery callbacks receive staged tokens. */
+export declare function createAdminAccountOperations(deps: Dependencies): AdminAccountService;
+export {};

package/dist/admin-account-operations.js

@@ -0,0 +1,50 @@
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { AuthError } from "./auth-store.js";
+const hash = (value) => createHash('sha256').update(value).digest('hex');
+const valid = (value, max) => typeof value === 'string' && value.length > 0 && value.length <= max && !/[\u0000-\u001f\u007f]/.test(value);
+/** Operator-side service. Only declared delivery callbacks receive staged tokens. */
+export function createAdminAccountOperations(deps) {
+    const fail = () => { throw new AuthError(400, 'invalid_administration'); };
+    const actor = (value) => { deps.check(); if (!/^[A-Za-z0-9_-]{43}$/.test(value))
+        fail(); return hash(value); };
+    const reason = (value) => { if (!valid(value, 256) || !value.trim())
+        fail(); return value.trim(); };
+    return {
+        async inspectAccountAuthentication(input) { const actorHash = actor(input.actorToken); if (!valid(input.accountId, 256))
+            fail(); return deps.store.call('adminAccountInspect', { hash: actorHash, accountId: input.accountId, reason: reason(input.reason), now: deps.now() }); },
+        async stageAccountAdministration(input) {
+            const actorHash = actor(input.actorToken), why = reason(input.reason);
+            if (!Array.isArray(input.accountIds) || input.accountIds.length < 1 || input.accountIds.length > 50 || new Set(input.accountIds).size !== input.accountIds.length || input.accountIds.some(value => !valid(value, 256)))
+                fail();
+            if (!['verify-email', 'force-password-reset', 'schedule-deletion', 'cancel-deletion', 'remove-passkey', 'remove-external', 'request-email-change', 'assign-roles', 'resend-verification'].includes(input.action))
+                fail();
+            if (input.accountIds.length > 1 && !['assign-roles', 'resend-verification'].includes(input.action))
+                fail();
+            const parameters = {};
+            if (input.action === 'assign-roles') {
+                if (!Array.isArray(input.roles) || input.roles.length < 1 || input.roles.length > 32 || new Set(input.roles).size !== input.roles.length || input.roles.some(value => !Object.hasOwn(deps.roles, value)))
+                    fail();
+                parameters.roles = [...input.roles];
+            }
+            if (input.action === 'request-email-change')
+                parameters.email = deps.permittedEmail(input.email);
+            if (input.action === 'remove-passkey') {
+                if (!valid(input.credentialId, 1024))
+                    fail();
+                parameters.credentialId = input.credentialId;
+            }
+            if (input.action === 'remove-external') {
+                if (!/^[a-f0-9]{64}$/.test(input.externalId))
+                    fail();
+                parameters.externalId = input.externalId;
+            }
+            const raw = new Map(input.accountIds.map(id => [id, { primary: randomBytes(32).toString('base64url'), secondary: randomBytes(32).toString('base64url') }]));
+            const result = await deps.store.call('adminAccountStage', { hash: actorHash, operationId: randomUUID(), accountIds: input.accountIds, action: input.action, reason: why, parameters, tokens: input.accountIds.map(accountId => ({ accountId, primaryHash: hash(raw.get(accountId).primary), secondaryHash: hash(raw.get(accountId).secondary) })), now: deps.now() });
+            return { operationId: result.operationId, deliveries: result.deliveries.map(delivery => delivery.kind === 'notice' ? delivery : { kind: 'token', accountId: delivery.accountId, email: delivery.email, ...(delivery.locale ? { locale: delivery.locale } : {}), purpose: delivery.purpose, token: raw.get(delivery.accountId)[delivery.tokenSlot] }) };
+        },
+        async completeAccountAdministration(input) { const actorHash = actor(input.actorToken); if (!valid(input.operationId, 256))
+            fail(); return deps.store.call('adminAccountComplete', { hash: actorHash, operationId: input.operationId, now: deps.now() }); },
+        async cancelAccountAdministration(input) { const actorHash = actor(input.actorToken); if (!valid(input.operationId, 256))
+            fail(); await deps.store.call('adminAccountCancel', { hash: actorHash, operationId: input.operationId, now: deps.now() }); },
+    };
+}

package/dist/admin-account-store.d.ts

@@ -0,0 +1,22 @@
+import type { DatabaseSync } from 'node:sqlite';
+import type { AuthRecord, SessionRecord } from './auth-store.ts';
+interface Context {
+    db: DatabaseSync;
+    now: number;
+    deletionGraceMs: number;
+    roles: Record<string, string[]>;
+    account(id: string): AuthRecord | null;
+    fresh(hash: string, now: number): {
+        user: AuthRecord;
+        session: SessionRecord;
+    };
+    isRestricted(user: AuthRecord): boolean;
+    save(user: AuthRecord): void;
+    audit(actor: string, action: string, subject: string, now: number, reason?: string): void;
+    fail(status: number, code: string): never;
+}
+/** All calls are inside the existing store revision/active-key checked transaction. */
+export declare function adminAccountOperation(operation: string, args: Record<string, unknown>, context: Context): {
+    value: unknown;
+} | undefined;
+export {};

package/dist/admin-account-store.js

@@ -0,0 +1,185 @@
+import { createHash } from 'node:crypto';
+const externalId = (provider, subject) => createHash('sha256').update(provider + '\0' + subject).digest('hex');
+/** All calls are inside the existing store revision/active-key checked transaction. */
+export function adminAccountOperation(operation, args, context) {
+    if (!operation.startsWith('adminAccount'))
+        return;
+    const { db, now } = context, fail = context.fail;
+    const permissions = (roles) => [...new Set(roles.flatMap(role => context.roles[role] ?? []))];
+    const administrator = (user) => permissions(user.roles).includes('*');
+    const authorize = (actor, target, permission, nextRoles) => {
+        const granted = permissions(actor.roles);
+        if (context.isRestricted(actor) || !granted.includes('*') && !granted.includes(permission))
+            fail(403, 'permission_denied');
+        if (actor.id === target.id)
+            fail(403, 'self_administration_denied');
+        for (const permission of [...permissions(target.roles), ...permissions(nextRoles ?? target.roles)])
+            if (!granted.includes('*') && !granted.includes(permission))
+                fail(403, 'delegation_ceiling_exceeded');
+    };
+    const activity = (kind, id) => { const row = db.prepare('SELECT added,last_used FROM auth_method_activity WHERE kind=? AND method_id=?').get(kind, id); return { ...(typeof row?.added === 'number' ? { added: row.added } : {}), ...(typeof row?.last_used === 'number' ? { lastUsed: row.last_used } : {}) }; };
+    const identities = (id) => db.prepare('SELECT provider,subject FROM auth_external WHERE account_id=? LIMIT 16').all(id).map(row => ({ provider: String(row.provider), subject: String(row.subject), id: externalId(String(row.provider), String(row.subject)) }));
+    const validate = (actor, plan) => {
+        const targets = plan.targets.map(entry => {
+            const user = context.account(entry.id);
+            if (!user)
+                fail(404, 'account_not_found');
+            if (user.version !== entry.version)
+                fail(409, 'account_changed');
+            authorize(actor, user, 'auth.users.manage', plan.parameters.roles);
+            if (plan.action === 'cancel-deletion') {
+                if (user.status !== 'pending-delete' || !user.deleteAfter || user.deleteAfter <= now)
+                    fail(409, 'deletion_unavailable');
+            }
+            else if (user.status === 'pending-delete')
+                fail(409, 'account_pending_deletion');
+            if (['force-password-reset', 'resend-verification', 'request-email-change'].includes(plan.action) && user.status !== 'active')
+                fail(409, 'account_not_active');
+            if (plan.action === 'resend-verification' && user.emailVerified)
+                fail(409, 'email_already_verified');
+            if (plan.action === 'remove-passkey') {
+                if (!db.prepare('SELECT id FROM auth_passkeys WHERE id=? AND account_id=?').get(plan.parameters.credentialId, user.id))
+                    fail(404, 'method_not_found');
+                if (user.mfaPasskeys?.includes(plan.parameters.credentialId))
+                    fail(409, 'factor_reset_case_required');
+                if (!user.passwordHash && identities(user.id).length === 0 && Number(db.prepare('SELECT count(*) AS n FROM auth_passkeys WHERE account_id=?').get(user.id)?.n) <= 1)
+                    fail(409, 'last_sign_in_method');
+            }
+            if (plan.action === 'remove-external') {
+                const methods = identities(user.id);
+                if (!methods.some(method => method.id === plan.parameters.externalId))
+                    fail(404, 'method_not_found');
+                if (!user.passwordHash && methods.length <= 1 && Number(db.prepare('SELECT count(*) AS n FROM auth_passkeys WHERE account_id=?').get(user.id)?.n) === 0)
+                    fail(409, 'last_sign_in_method');
+            }
+            if (['remove-passkey', 'remove-external'].includes(plan.action) && !user.passwordHash && !user.totpSecret && user.mfaPasskeys?.length) {
+                const remainingKeys = db.prepare('SELECT id FROM auth_passkeys WHERE account_id=?').all(user.id).map(row => String(row.id)).filter(id => plan.action !== 'remove-passkey' || id !== plan.parameters.credentialId);
+                const remainingExternal = identities(user.id).filter(method => plan.action !== 'remove-external' || method.id !== plan.parameters.externalId);
+                if (!remainingExternal.length && !remainingKeys.some(primary => user.mfaPasskeys.some(factor => factor !== primary && remainingKeys.includes(factor))))
+                    fail(409, 'last_sign_in_method');
+            }
+            if (plan.action === 'request-email-change') {
+                if (user.email === plan.parameters.email)
+                    fail(400, 'email_unchanged');
+                if (db.prepare('SELECT id FROM auth_accounts WHERE email=?').get(plan.parameters.email))
+                    fail(409, 'email_unavailable');
+                if (db.prepare('SELECT account_id FROM auth_email_changes WHERE account_id=? AND expires>?').get(user.id, now))
+                    fail(409, 'email_change_pending');
+            }
+            return user;
+        });
+        const disabling = (user) => ['schedule-deletion', 'force-password-reset'].includes(plan.action) || plan.action === 'assign-roles' && !permissions(plan.parameters.roles).includes('*');
+        if (targets.some(user => administrator(user) && user.status === 'active' && !context.isRestricted(user) && disabling(user))) {
+            const disabled = new Set(targets.filter(disabling).map(user => user.id));
+            const remaining = db.prepare("SELECT data FROM auth_accounts WHERE administrator=1 AND status='active'").all().some(row => { const user = JSON.parse(String(row.data)); return !disabled.has(user.id) && !context.isRestricted(user); });
+            if (!remaining)
+                fail(409, 'last_administrator_required');
+        }
+        return targets;
+    };
+    const revoke = (id) => { for (const table of ['auth_sessions', 'auth_tokens', '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(id); };
+    if (operation === 'adminAccountInspect') {
+        const actor = context.fresh(String(args.hash), now).user, target = context.account(String(args.accountId));
+        if (!target)
+            fail(404, 'account_not_found');
+        authorize(actor, target, 'auth.users.read');
+        context.audit(actor.id, 'admin.authentication_inspected', target.id, now, String(args.reason));
+        return { value: { accountId: target.id, password: !!target.passwordHash, totp: !!target.totpSecret, passkeys: db.prepare('SELECT id FROM auth_passkeys WHERE account_id=? LIMIT 16').all(target.id).map(row => ({ id: String(row.id), ...activity('passkey', String(row.id)), secondFactor: target.mfaPasskeys?.includes(String(row.id)) ?? false })), external: identities(target.id).map(({ id, provider, subject }) => ({ id, provider, ...activity('oidc', provider + '\0' + subject) })) } };
+    }
+    if (operation === 'adminAccountStage') {
+        const actor = context.fresh(String(args.hash), now).user, targets = args.accountIds.map(id => { const user = context.account(id); if (!user)
+            fail(404, 'account_not_found'); const tokens = args.tokens.find(item => item.accountId === id); return { id, version: user.version, primaryHash: tokens.primaryHash, secondaryHash: tokens.secondaryHash }; });
+        const plan = { actorId: actor.id, actorVersion: actor.version, action: args.action, reason: String(args.reason), parameters: args.parameters, targets };
+        const users = validate(actor, plan);
+        db.prepare('DELETE FROM auth_admin_operations WHERE expires<=?').run(now);
+        if (Number(db.prepare('SELECT count(*) AS n FROM auth_admin_operations').get()?.n) >= 1000)
+            fail(503, 'auth_capacity_reached');
+        db.prepare('INSERT INTO auth_admin_operations(id,data,expires) VALUES(?,?,?)').run(String(args.operationId), JSON.stringify(plan), now + 300000);
+        const deliveries = [];
+        for (const user of users) {
+            const base = { accountId: user.id, email: user.email, ...(user.profile?.locale ? { locale: user.profile.locale } : {}) };
+            if (['remove-passkey', 'remove-external'].includes(plan.action) && !user.passwordHash && !user.totpSecret && user.mfaPasskeys?.length) {
+                const remainingKeys = db.prepare('SELECT id FROM auth_passkeys WHERE account_id=?').all(user.id).map(row => String(row.id)).filter(id => plan.action !== 'remove-passkey' || id !== plan.parameters.credentialId);
+                const remainingExternal = identities(user.id).filter(method => plan.action !== 'remove-external' || method.id !== plan.parameters.externalId);
+                if (!remainingExternal.length && !remainingKeys.some(primary => user.mfaPasskeys.some(factor => factor !== primary && remainingKeys.includes(factor))))
+                    fail(409, 'last_sign_in_method');
+            }
+            if (plan.action === 'request-email-change') {
+                deliveries.push({ ...base, kind: 'token', purpose: 'cancel-email-change', tokenSlot: 'secondary' }, { ...base, email: plan.parameters.email, kind: 'token', purpose: 'verify-email-change', tokenSlot: 'primary' });
+            }
+            else if (['force-password-reset', 'resend-verification', 'schedule-deletion'].includes(plan.action))
+                deliveries.push({ ...base, kind: 'token', purpose: plan.action === 'force-password-reset' ? 'reset-password' : plan.action === 'resend-verification' ? 'verify-email' : 'cancel-deletion', tokenSlot: 'primary' });
+            else
+                deliveries.push({ ...base, kind: 'notice', action: plan.action });
+            context.audit(actor.id, 'admin.' + plan.action + '.staged', user.id, now, plan.reason);
+        }
+        return { value: { operationId: String(args.operationId), deliveries } };
+    }
+    if (operation === 'adminAccountComplete' || operation === 'adminAccountCancel') {
+        const actor = context.fresh(String(args.hash), now).user, row = db.prepare('SELECT data FROM auth_admin_operations WHERE id=? AND expires>?').get(String(args.operationId), now);
+        if (!row)
+            fail(409, 'administration_unavailable');
+        const plan = JSON.parse(String(row.data));
+        if (plan.actorId !== actor.id || plan.actorVersion !== actor.version)
+            fail(409, 'administration_actor_changed');
+        if (operation === 'adminAccountCancel') {
+            db.prepare('DELETE FROM auth_admin_operations WHERE id=?').run(String(args.operationId));
+            for (const target of plan.targets)
+                context.audit(actor.id, 'admin.' + plan.action + '.cancelled', target.id, now, plan.reason);
+            return { value: undefined };
+        }
+        const users = validate(actor, plan);
+        for (const user of users) {
+            const tokens = plan.targets.find(target => target.id === user.id);
+            if (!['resend-verification', 'request-email-change'].includes(plan.action)) {
+                user.version++;
+                revoke(user.id);
+            }
+            switch (plan.action) {
+                case 'verify-email':
+                    user.emailVerified = true;
+                    break;
+                case 'force-password-reset':
+                    user.passwordHash = '';
+                    db.prepare("INSERT INTO auth_tokens VALUES(?,?,'reset-password',?,?)").run(tokens.primaryHash, user.id, now + 1800000, user.version);
+                    break;
+                case 'schedule-deletion':
+                    user.status = 'pending-delete';
+                    user.deleteAfter = now + context.deletionGraceMs;
+                    db.prepare("INSERT INTO auth_tokens VALUES(?,?,'cancel-deletion',?,?)").run(tokens.primaryHash, user.id, user.deleteAfter, user.version);
+                    break;
+                case 'cancel-deletion':
+                    user.status = 'active';
+                    delete user.deleteAfter;
+                    break;
+                case 'remove-passkey':
+                    db.prepare("DELETE FROM auth_method_activity WHERE kind='passkey' AND method_id=? AND account_id=?").run(plan.parameters.credentialId, user.id);
+                    db.prepare('DELETE FROM auth_passkeys WHERE id=? AND account_id=?').run(plan.parameters.credentialId, user.id);
+                    break;
+                case 'remove-external': {
+                    const method = identities(user.id).find(item => item.id === plan.parameters.externalId);
+                    db.prepare('DELETE FROM auth_external WHERE provider=? AND subject=? AND account_id=?').run(method.provider, method.subject, user.id);
+                    db.prepare("DELETE FROM auth_method_activity WHERE kind='oidc' AND method_id=? AND account_id=?").run(method.provider + '\0' + method.subject, user.id);
+                    break;
+                }
+                case 'assign-roles':
+                    user.roles = plan.parameters.roles;
+                    break;
+                case 'resend-verification':
+                    db.prepare("DELETE FROM auth_tokens WHERE account_id=? AND purpose='verify-email'").run(user.id);
+                    db.prepare("INSERT INTO auth_tokens VALUES(?,?,'verify-email',?,?)").run(tokens.primaryHash, user.id, now + 1800000, user.version);
+                    break;
+                case 'request-email-change':
+                    db.prepare('DELETE FROM auth_email_changes WHERE account_id=?').run(user.id);
+                    db.prepare('INSERT INTO auth_email_changes VALUES(?,?,?,?,?,?,?)').run(user.id, plan.parameters.email, tokens.primaryHash, tokens.secondaryHash, now + 86400000, now + 172800000, user.version);
+                    break;
+            }
+            context.save(user);
+            context.audit(actor.id, 'admin.' + plan.action, user.id, now, plan.reason);
+        }
+        db.prepare('DELETE FROM auth_admin_operations WHERE id=?').run(String(args.operationId));
+        return { value: { affected: users.length } };
+    }
+    return;
+}

package/dist/auth-baseline.d.ts

@@ -0,0 +1,30 @@
+import type { AuthService, AuthSecurityPolicy } from './auth-core.ts';
+export interface BaselineCheck {
+    name: string;
+    passed: boolean;
+}
+export interface AuthBaselineResult {
+    passed: boolean;
+    scope: 'offline-synthetic-runtime';
+    checks: BaselineCheck[];
+    liveProviders: 'unverified';
+    limitations: string[];
+}
+/** Fixed synthetic fixtures only; the deadline also bounds broken runtime startup. */
+export declare function runAuthBaseline(options?: {
+    timeoutMs?: number;
+    temporaryDirectory?: string;
+}): Promise<AuthBaselineResult>;
+/** Checks the already-loaded trusted service; no account mutation or migration is requested. */
+export declare function validateAuthService(service: AuthService): Promise<{
+    passed: boolean;
+    checks: BaselineCheck[];
+    revision: string;
+    registration: string;
+    security: AuthSecurityPolicy;
+    roles: {
+        count: number;
+        permissionCount: number;
+    };
+    liveProviders: 'unverified';
+}>;