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

package/IMPLEMENTATION-STATUS.md

@@ -1,6 +1,6 @@
 # Auth implementation status
 
-Status: `@jimhoyd/urlcode-auth` 0.1.0-alpha.1 is the first npm release (core issue #78); it requires the published `@jimhoyd/urlcode` 0.4.x and `@jimhoyd/urlcode-ui` 0.1.x alphas. The implemented auth and shared-presentation work is merged to main. The source plan is URLCode PR #54; cross-repository release acceptance is tracked in https://github.com/jimhoyd-com/urlcode/issues/58. The generic core extension contract from PR #59 is merged. Implementation and synthetic acceptance do not establish production readiness.
+Status: `@jimhoyd/urlcode-auth` 0.1.0-alpha.3 is the current npm release. It supersedes 0.1.0-alpha.2, the first working one (core issue #78; 0.1.0-alpha.1 was published from an unbuilt checkout and never worked, see RELEASE-SECURITY.md in urlcode core), and carries the work merged since — the trusted project-level lifecycle hooks (`beforeRegister`, `onSignUp`, `onDelete`), the versioned JSON form-endpoint API contract, and the `ExtensionActivation.root` fixture fixes for core 0.4.0-alpha.2. It requires `@jimhoyd/urlcode` 0.4.0-alpha.2 or newer — `src/auth.ts` resolves project lifecycle hooks through `ExtensionActivation.root`, which does not exist in 0.4.0-alpha.1 — and `@jimhoyd/urlcode-ui` 0.1.x alphas. The implemented auth and shared-presentation work is merged to main. The source plan is URLCode PR #54; cross-repository release acceptance is tracked in https://github.com/jimhoyd-com/urlcode/issues/58. The generic core extension contract from PR #59 is merged. Implementation and synthetic acceptance do not establish production readiness.
 
 Implemented and covered by automated tests: durable SQLite accounts; bounded scrypt and hash migration; email/password and numeric email codes; OIDC with explicit linking; Google/Apple adapters; WebAuthn registration, login and step-up; TOTP/recovery; opaque sessions and revocation; role ceilings; registration modes; terms and scoped metadata; email change cooldown/cancellation; deletion grace; exports; key rotation; backup/restore; operator CLI/scaffolding; SES/development senders; safe themes and locale catalogue; admin service operations including dual-approval cases and bounded impersonation. Device recognition supports notices; separate opt-in, revocable remembered-device authority can exempt ordinary MFA without granting fresh step-up. Explicit passkey second-factor enrollment requires an independent credential. Optional breach checking is an operator-selected external service.
 
@@ -10,6 +10,8 @@ Mandatory verification/TOTP enrollment, operator standard/hardened presets and e
 
 Kit adoption (urlcode-auth issue #9, core plan §7.2) is implemented: every account screen is an `auth/*` kit template with a declared view model and sample view (`authTemplates`, `authUiTemplates`, `authCatalogue`); `authExtension({ ui })` renders through `ui.kit.page` when the host supplies the `ui` extension and through the shared primitives otherwise. The HTTP suites run under both render paths; a doctor-style suite renders every template with its sample and with the view a real request computes, checks escaping of user-controlled values on kit pages and the nonce-bound CSP. A themed browser walkthrough of the account pages remains a manual acceptance step.
 
+Project-level lifecycle hooks (urlcode-auth#35) are implemented: `beforeRegister`, `onSignUp` and `onDelete` in `extensions.auth.config.hooks` (README.md), run trusted and in-process — the same default as any `function`/`middleware` route, no special case. A configured hook's module is resolved and imported eagerly at activation, so a missing module or a broken/missing export fails activation rather than the first request; `sandbox: true` on a hook is refused explicitly at activation (core has no dispatch primitive yet to isolate a hook call, jimhoyd-com/urlcode#151) rather than silently ignored. `beforeRegister` covers the immediate `/register` endpoint and the resumable `/signup/begin` step; `onSignUp` fires after a genuinely new account is created (not an existing-account signup attempt that resolves to sign-in); `onDelete` fires when the account owner schedules their own deletion, not yet from an administrator-initiated deletion or the background purge.
+
 ## Additional implemented acceptance
 
 - Bounded localized email copy, durable progressive password backoff, trusted-client and signup-domain velocity budgets, optional fixed-origin Turnstile verification/widget, and pinned disposable-domain data.

package/README.md

@@ -83,6 +83,62 @@ The external host creates an AuthService and supplies `authExtension({service, c
 
 Registration starts off. Bootstrap the first administrator through `urlcode-auth bootstrap --operator-file /absolute/operator-service.mjs`, supplying `{email,password}` as bounded JSON on stdin. Never place passwords in command arguments or source files. The command returns account metadata, not the session token. A role/default-role configuration change is a reviewed operator change, not an administration-page edit.
 
+## Project-level lifecycle hooks
+
+A project can name its own function per lifecycle point in `extensions.auth.config.hooks`, using the same `{source, export}` shape (or a bare string, defaulting to the module's default export) `function`/`middleware` routes already use — the behavior-layer counterpart to `urlcode-ui`'s presentation layering (urlcode-auth#35, urlcode's docs/EXTENSIONS.md "Project-level lifecycle hooks"):
+
+```yaml
+extensions:
+  auth:
+    version: '1'
+    config:
+      registration: open
+      hooks:
+        beforeRegister: ./hooks/registration-rule.mjs   # bare string: default export
+        onSignUp:
+          source: ./hooks/on-signup.mjs
+          export: provisionWorkspace
+        onDelete: ./hooks/on-delete.mjs
+```
+
+Three lifecycle points are implemented:
+
+- **`beforeRegister(input: {email, profile?})`** runs before an account is
+  created, from the immediate `/register` endpoint and from the resumable
+  `/signup/begin` step, and returns a typed verdict: `{allow: true}` lets the
+  attempt continue, `{allow: false, reason}` rejects it and the `reason` is
+  surfaced to the caller the same way any other registration rejection is (a
+  `403` with that message). This is how "only `@acme.com` may register"
+  becomes portable project code instead of a fork.
+- **`onSignUp(input: {accountId, email})`** is a side-effect hook (no
+  verdict) that fires once, after a *new* account is actually created — from
+  the immediate `/register` endpoint and from `/signup/complete` (an
+  existing-account signup attempt that resolves to sign-in, not a new
+  account, never fires it). Use it for something like provisioning a
+  workspace after sign-up.
+- **`onDelete(input: {accountId, email})`** fires when the account owner
+  schedules their own deletion through the account page's `/delete` endpoint
+  (the deletion grace period still applies and can still be cancelled). It
+  does not yet fire from an administrator-initiated deletion or from the
+  background purge once the grace period elapses.
+
+These hooks are first-party project code, the same trust category as any
+`function`/`middleware` route: **trusted, in-process execution by default**,
+following the runtime's trust model with no special case (urlcode's
+docs/SPIKE-DEFAULT-TRUST-MODEL.md). A missing module, a module that fails to
+import, or a named export that is not a function fails **activation** —
+before this extension serves a single request — never the first request
+that happens to reach the hook.
+
+**`sandbox: true` is not implemented for these hooks and is refused
+explicitly at activation**, naming the hook: `hook <name>: sandbox: true is
+not yet supported for project-level hooks, see jimhoyd-com/urlcode-auth#35`.
+Core's trusted/sandboxed dispatch is wired to route dispatch, not exposed to
+extensions (jimhoyd-com/urlcode#151), so this package has no way to actually
+isolate a hook call yet; accepting the field and running it trusted anyway
+would misrepresent the isolation a project believes it configured. Declare a
+hook without `sandbox` (or with `sandbox: false`) to use it today.
+
 ## Authentication and presentation
 
 `createAuthService` owns a private SQLite database outside the application directory. Its operations enforce authority, fresh authentication, delegation ceilings, replay protection and transaction boundaries. Callers must preserve the distinction between unrestricted operator APIs and actor-token administrative APIs. `authExtension` adds HTTP cookies, same-origin CSRF checks, bounded bodies and trusted pages.

package/SECURITY.md

@@ -4,7 +4,7 @@ This repository is an actively reviewed implementation, not an independent secur
 
 ## Trusted and untrusted components
 
-Operator modules, their dependencies, configuration, database directory, encryption/CSRF keys, identity providers and mail transport are trusted. Project routes and sandboxed guest code do not gain authority to load host modules. Core extension activation requires an explicitly supplied registry and a reviewed exact project revision pin. Never turn revision inspection into automatic approval.
+Operator modules, their dependencies, configuration, database directory, encryption/CSRF keys, identity providers and mail transport are trusted. Project routes are trusted and run in-process with full Node access by default; `sandbox: true` opts a route into the isolated QuickJS/WASM worker pool instead. Neither trusted nor sandboxed project routes gain authority to load auth's own host modules — that boundary is enforced by the host-file/operator-registration mechanism below, independent of a route's own `sandbox` setting. Core extension activation requires an explicitly supplied registry and a reviewed exact project revision pin. Never turn revision inspection into automatic approval.
 
 Auth is Node/SQLite only. It refuses unpatched SQLite versions and requires private database files. Keep the database, WAL/SHM, backups, operator modules and key files outside the application project and inaccessible to guest filesystem access. Do not run the host as a shared hostile operating-system user. Filesystem permission and symlink checks do not defend against an attacker who already controls the operator account or its parent directories.
 

package/THREAT-MODEL.md

@@ -2,8 +2,10 @@
 
 ## Scope and assets
 
-This package is a trusted Node host service. Application server code remains
-untrusted WASM under the core runtime's capability model. The auth service protects
+This package is a trusted Node host service. Under the core runtime's current
+capability model, application `function`/`middleware` routes run trusted and
+in-process with full Node access by default; a route opts into isolated
+QuickJS/WASM execution only by declaring `sandbox: true`. The auth service protects
 account ownership, verified identifiers, credential material, sessions, factor and
 recovery proofs, operator role grants, audit history and private profile data.
 SQLite files and backups contain sensitive account data: file permissions are a

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 {};