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

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

@@ -2,7 +2,7 @@
 
 An optional, operator-installed authentication extension for URLCode. This repository contains the Node/SQLite implementation: password and passkey authentication, OpenID Connect, email codes, TOTP, recovery codes, versioned registration profiles, account lifecycle operations, administrative service operations and trusted HTML pages.
 
-[![Verify](https://github.com/jimhoyd-com/urlcode-auth/actions/workflows/verify.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode-auth/actions/workflows/verify.yml)
+[![CI](https://github.com/jimhoyd-com/urlcode/actions/workflows/ci.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode/actions/workflows/ci.yml)
 
 The implementation is under active review. Local tests and builds are evidence of those checks, not an independent security assessment, production deployment, provider certification or recovery/soak result. See [SECURITY.md](SECURITY.md) for the trust boundary and [the first-release coverage review](docs/SPIKE-AUTH.md) for the proposal; the proposal is not a list of completed features.
 
@@ -27,20 +27,21 @@ Every release tarball is attested from the tagged commit: `gh attestation verify
 
 Operators who pin exact reviewed commits rather than registry versions can build the same packages locally. A registry version alone does not establish that a revision was reviewed: this implementation requires the core extension contract introduced by [core PR #59](https://github.com/jimhoyd-com/urlcode/pull/59). Use its reviewed implementation or a reviewed successor containing it, pinned to an exact commit. Do not infer approval from the current branch name.
 
-This package also depends on the shared `@jimhoyd/urlcode-ui` peer, which owns document layout, semantic fields, escaping, themes and the locale engine; authentication/administration behavior remains here. Core can use UI without auth/admin. Source CI (`verify.yml`) checks the peers out at the commits in [`peers.json`](peers.json) and needs the narrow `URLCODE_UI_READ_TOKEN`; the release workflow resolves them from the registry instead.
+This package also depends on the shared `@jimhoyd/urlcode-ui` peer, which owns document layout, semantic fields, escaping, themes and the locale engine; authentication/administration behavior remains here. Core can use UI without auth/admin. Both peers are siblings in this repository, so CI builds them from the same commit — there is no peer checkout, no `peers.json` and no read token; the release workflow resolves the published versions from the registry instead, to prove the declared ranges are satisfiable.
 
-Each repository has a lockfile. The source packaging helper installs dependencies with lifecycle scripts disabled, builds the reviewed packages (core, then UI, then their consumers), installs local peer tarballs in dependency order and writes package integrity/revision metadata. It does not publish. All source trees must be committed and clean. `--core`, `--auth`, `--ui`, `--core-revision` and `--out` are required. Replace these illustrative paths with your reviewed locations. `--core-revision` defaults to the `urlcode` entry in [`peers.json`](peers.json), the single source of verified peer revisions; pass it explicitly only to override:
+One lockfile governs the workspace. The source packaging helper installs dependencies with lifecycle scripts disabled, builds the reviewed packages in dependency order (core, then UI, then their consumers) and writes package integrity metadata. It does not publish. The tree must be committed and clean, and it re-checks that after every build and pack. `--revision` and `--out` are required; `--revision` is exact and has no default, because the reviewed commit is the thing being asserted:
 
 ```sh
 node scripts/pack-sources.mjs \
-  --core /absolute/source/urlcode \
-  --ui /absolute/source/urlcode-ui \
-  --auth /absolute/source/urlcode-auth \
-  --admin /absolute/source/urlcode-admin \
-  --core-revision REVIEWED_40_CHARACTER_COMMIT_SHA \
+  --revision REVIEWED_40_CHARACTER_COMMIT_SHA \
   --out /absolute/new-private-package-directory
 ```
 
+One commit identifies every package: core, ui, auth and admin are built from
+the same reviewed revision of this repository. The script refuses to run if the
+checkout is not at that exact commit or has uncommitted changes, and re-checks
+both after each build and pack.
+
 Omit `--admin` for auth only. `--offline` forbids network package resolution and requires a populated dependency cache. `--skip-install` reuses installed third-party dependencies; local peer tarballs are still installed. The script does not alter dependency manifests or lockfiles. Run `npm run verify` in each repository separately; source packaging runs typecheck/build, not the HTTP suite.
 
 Install all required local tarballs together (core, UI and auth; admin if built) in an operator-owned directory with a private `package.json`. For example, after checking the manifest:
@@ -83,6 +84,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.
@@ -127,7 +184,7 @@ Run `urlcode-auth --help` for the current CLI. Operator commands have full datab
 
 `--operator-file` is an absolute path to a module that default-exports an `AuthService`.
 
-Backup/restore accepts JSON paths on stdin. `createBackup({database,destination,projectRoot})` uses SQLite's online backup API, including committed WAL pages, with a bounded worker and integrity checks. `restoreBackup({backup,destination,projectRoot})` restores to a **new** path. Both require private operator paths outside the project and refuse overwrite. Never copy only a live `.sqlite` file and assume its WAL is included.
+Backup/restore accepts JSON paths on stdin. `createBackup({database,destination,projectRoot})` uses SQLite's online backup API, including committed WAL pages, with a bounded worker and integrity checks. `restoreBackup({backup,destination,projectRoot})` restores to a **new** path. Both require private operator paths outside the project and refuse overwrite. Never copy only a live `.sqlite` file and assume its WAL is included. See [backup and restore platform guarantees](../../docs/AUTH-BACKUP.md), including Windows ACL and directory durability limits.
 
 Back up encryption keys, CSRF keys and reviewed static configuration separately. Database snapshots contain sensitive account/audit data and password hashes, but do not export key files. Restoring historical data also restores historical sessions/tokens and revocation state: plan revocation and recovery before reopening traffic. Rotate keys by adding a new active key, retaining decryption keys while bounded migration reports remaining records, then remove old keys only after completion and backup verification. Old writers fail closed after activation switches. Keep a tested isolated restore procedure.
 

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. Project YAML cannot register auth's host modules: activation requires the explicit host-file/operator-registration mechanism. This is not a confinement boundary for trusted Node code, which can independently import accessible modules and read process environment/files with the host user's authority. Only an explicitly sandboxed route has the guest isolation boundary. 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
@@ -25,12 +27,18 @@ passwords are hashed, and reusable browser capabilities are stored as hashes.
 A same-origin frontend can exercise browser authority even without reading an
 HttpOnly cookie. Do not host adversarial frontend scripts on this origin. A hostile
 host process, operator module, dependency or OS user able to read the key material
-is outside the WASM boundary. This release does not claim hostile multi-tenant
+is outside the boundary this extension protects: that boundary is the
+operator/host-file boundary, not a sandbox. The QuickJS/WASM sandbox is not an
+ambient boundary — it exists only for routes that declare `sandbox: true`. This release does not claim hostile multi-tenant
 readiness or independent assessment.
 
 ## Required invariants
 
-- Guests cannot select host modules or receive session, provider or recovery secrets.
+- Project declarations cannot register host modules, and the runtime does not
+  inject session, provider or recovery secrets into application handlers.
+  Trusted Node code still has the host process's ambient authority; host-file
+  registration and header filtering do not confine it. Keep hostile code out of
+  that process. `sandbox: true` retains the guest isolation boundary and grants.
 - Required signup verification precedes stored credentials. Existing accounts are
   never overwritten by a duplicate signup, linked by email alone, or upgraded from
   untrusted metadata.

package/dist/admin-account-store.js

@@ -68,7 +68,7 @@ export function adminAccountOperation(operation, args, context) {
             }
             return user;
         });
-        const disabling = (user) => ['schedule-deletion', 'force-password-reset'].includes(plan.action) || plan.action === 'assign-roles' && !permissions(plan.parameters.roles).includes('*');
+        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); });

package/dist/auth-core.js

@@ -27,7 +27,7 @@ export function normalizeEmail(value) {
     if (parts.length !== 2)
         fail(400, 'invalid_email');
     const local = parts[0].toLowerCase(), domain = domainToASCII(parts[1]).toLowerCase();
-    if (!local || local.length > 64 || /[\s\x00-\x1f\x7f"(),:;<>\[\]\\]/.test(local) || !domain || domain.length > 253 || domain.split('.').some(label => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) || local.length + domain.length + 1 > 254)
+    if (!local || local.length > 64 || /[\s\x00-\x1f\x7f"(),:;<>[\]\\]/.test(local) || !domain || domain.length > 253 || domain.split('.').some(label => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) || local.length + domain.length + 1 > 254)
         fail(400, 'invalid_email');
     return local + '@' + domain;
 }

package/dist/auth-flows.d.ts

@@ -25,6 +25,6 @@ export interface AuthFlowOptions {
     };
 }
 export declare function createAuthFlows(options: AuthFlowOptions, http: AuthHttp, mount: string, registration: boolean): {
-    buttons(csrf: string, link?: boolean, text?: (value: string) => string, locale?: string, presentation?: PresentationContext): string;
+    buttons(csrf: string, link?: boolean, _text?: (value: string) => string, locale?: string, presentation?: PresentationContext): string;
     handle(request: ExtensionRequest): Promise<AuthHttpResponse | undefined>;
 };

package/dist/auth-flows.js

@@ -42,7 +42,7 @@ export function createAuthFlows(options, http, mount, registration) {
     const cookie = (value, maxAge = 600) => ['set-cookie', `${flowCookie}=${value}; Path=/; Secure; HttpOnly; SameSite=None; Max-Age=${maxAge}`];
     const finish = async (request, result) => { const headers = options.onSession ? await options.onSession(request, result) : []; return wantsJson(request) ? jsonResponse(200, { user: result.user, csrf: http.token(result.token), ...(result.principal.restrictions ? { restrictions: result.principal.restrictions } : {}) }, [...http.sessionHeaders(result.token), cookie('', 0), ...headers]) : jsonResponse(303, { redirect: mount + '/account' }, [['location', mount + '/account'], ...http.sessionHeaders(result.token), cookie('', 0), ...headers]); };
     return {
-        buttons(csrf, link = false, text = value => value, locale, presentation) { return Object.keys(providers).map(name => `<form method="post" action="${escapeHtml(mount + '/providers/' + name + (link ? '/link' : '/start') + (locale ? '?lang=' + encodeURIComponent(locale) : ''))}">${csrfField(csrf)}<button type="submit">${escapeHtml((presentation ?? defaultPresentation.resolve()).text(link ? 'provider.link' : 'provider.signIn', { provider: name }))}</button></form>`).join(''); },
+        buttons(csrf, link = false, _text = value => value, locale, presentation) { return Object.keys(providers).map(name => `<form method="post" action="${escapeHtml(mount + '/providers/' + name + (link ? '/link' : '/start') + (locale ? '?lang=' + encodeURIComponent(locale) : ''))}">${csrfField(csrf)}<button type="submit">${escapeHtml((presentation ?? defaultPresentation.resolve()).text(link ? 'provider.link' : 'provider.signIn', { provider: name }))}</button></form>`).join(''); },
         async handle(request) {
             let presentation = (options.presentation ?? defaultPresentation).resolve({ ...(request.query.get('lang') ? { queryLocale: request.query.get('lang') } : {}), ...(request.headers.get('accept-language') ? { acceptLanguage: request.headers.get('accept-language') } : {}) });
             const tr = (key, values) => escapeHtml(presentation.text(key, values));

package/dist/auth-signup.d.ts

@@ -3,9 +3,10 @@ import type { AuthExtensionOptions } from './auth.ts';
 import type { PresentationContext } from './presentation.ts';
 import type { RegistrationInput } from './registration.ts';
 import { AuthHttp } from './auth-ui.ts';
+import type { LifecycleHooks } from './lifecycle-hooks.ts';
 /** Operator-owned signup orchestration. Only opaque browser-bound state is held in cookies. */
 export declare function createSignup(options: AuthExtensionOptions, http: AuthHttp, mount: string, profile: {
     fields(p: PresentationContext): string;
     read(fields: Record<string, string>): RegistrationInput;
     names: string[];
-}): (request: ExtensionRequest, presentation: PresentationContext) => Promise<import("./auth-ui.ts").AuthHttpResponse | undefined>;
+}, hooks?: LifecycleHooks): (request: ExtensionRequest, presentation: PresentationContext) => Promise<import("./auth-ui.ts").AuthHttpResponse | undefined>;

package/dist/auth-signup.js

@@ -3,7 +3,7 @@ import { createHash, randomBytes } from 'node:crypto';
 import { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, jsonResponse, readFields, screenResponse, wantsJson } from "./auth-ui.js";
 import { Markup } from '@jimhoyd/urlcode-ui';
 /** Operator-owned signup orchestration. Only opaque browser-bound state is held in cookies. */
-export function createSignup(options, http, mount, profile) {
+export function createSignup(options, http, mount, profile, hooks = {}) {
     const service = options.service, browserCookie = '__Host-urlcode-signup-browser', flowCookie = '__Host-urlcode-signup';
     const clear = () => [['set-cookie', http.setCookie(flowCookie, '', 0)]];
     async function delivery(message, locale) {
@@ -107,6 +107,11 @@ export function createSignup(options, http, mount, profile) {
         if (path === '/signup/begin') {
             if (service.getSecurityPolicy().requireEmailVerification && !options.sendSignupCode)
                 throw new AuthHttpError(503, 'Email delivery is not configured');
+            if (hooks.beforeRegister) {
+                const verdict = await hooks.beforeRegister({ email: fields.email || '' });
+                if (!verdict || verdict.allow !== true)
+                    throw new AuthHttpError(403, verdict?.reason || 'Registration not permitted');
+            }
             const started = await service.beginSignup({ email: fields.email || '', browserHash, ...(fields.invitationToken ? { invitationToken: fields.invitationToken } : {}) });
             if (started.delivery)
                 await delivery(started.delivery, presentation.locale);
@@ -134,6 +139,10 @@ export function createSignup(options, http, mount, profile) {
             const resultHeaders = [...headers, ...clear(), ...(result ? http.sessionHeaders(result.token) : [])];
             if (result?.newDevice)
                 await delivery({ kind: 'new-device', email: result.user.email }, options.presentation?.resolve({ ...(result.user.profile?.locale ? { accountLocale: result.user.profile.locale } : {}), queryLocale: presentation.locale }).locale ?? presentation.locale);
+            // Existing-account attempts complete at sign-in (`result` is null), never a
+            // fresh account, so onSignUp fires only for a genuinely new account.
+            if (result && hooks.onSignUp)
+                await hooks.onSignUp({ accountId: result.user.id, email: result.user.email });
             // Existing-account attempts finish at sign-in; no existing credentials are replaced.
             const target = mount + (result ? '/account' : service.getRegistrationMode() === 'waitlist' ? '/signup/pending' : '/login');
             return wantsJson(request) ? jsonResponse(200, { complete: true, redirect: target, ...(result ? { csrf: http.token(result.token) } : {}) }, resultHeaders) : jsonResponse(303, { redirect: target }, [['location', target], ...resultHeaders]);

package/dist/auth-store.js

@@ -46,19 +46,26 @@ export async function openAuthStore(options) {
     };
     worker.on('error', fail);
     worker.on('exit', fail);
-    await new Promise((accept, reject) => {
-        const timer = setTimeout(() => { void worker.terminate(); reject(new AuthError(503, 'auth_store_unavailable')); }, 15000);
-        worker.once('message', (message) => {
-            clearTimeout(timer);
-            if (message.ready)
-                accept();
-            else {
-                void worker.terminate();
-                reject(new AuthError(503, ['auth_configuration_changed', 'configuration_approval_mismatch', 'configuration_roles_invalid', 'configuration_admin_required'].includes(message.error ?? '') ? message.error : 'auth_store_unavailable'));
-            }
+    try {
+        await new Promise((accept, reject) => {
+            const timer = setTimeout(() => { reject(new AuthError(503, 'auth_store_unavailable')); }, 15000);
+            worker.once('message', (message) => {
+                clearTimeout(timer);
+                if (message.ready)
+                    accept();
+                else {
+                    reject(new AuthError(503, ['auth_configuration_changed', 'configuration_approval_mismatch', 'configuration_roles_invalid', 'configuration_admin_required'].includes(message.error ?? '') ? message.error : 'auth_store_unavailable'));
+                }
+            });
+            worker.once('error', () => { clearTimeout(timer); reject(new AuthError(503, 'auth_store_unavailable')); });
         });
-        worker.once('error', () => { clearTimeout(timer); reject(new AuthError(503, 'auth_store_unavailable')); });
-    });
+    }
+    catch (error) {
+        // A rejected open must release SQLite handles before its caller can
+        // retry, restore or remove the database (Windows cannot unlink them).
+        await worker.terminate();
+        throw error;
+    }
     worker.on('message', (message) => {
         const p = pending.get(message.id);
         if (!p)

package/dist/auth.js

@@ -8,19 +8,25 @@ import { createSecondFactorFlows } from "./second-factor-flows.js";
 import { createSignup } from "./auth-signup.js";
 import { createAuthFlows } from "./auth-flows.js";
 import { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField as baseField, httpFailure, jsonResponse, presentationSource, readFields, screenResponse, wantsJson, passkeyScript, secondFactorButton } from "./auth-ui.js";
+import { hooksConfigSchema, loadLifecycleHooks } from "./lifecycle-hooks.js";
 const defaultPresentation = createPresentation();
 function enrollmentRequired(principal) { return Boolean(principal.restrictions?.length); }
 export function hasPermission(principal, permission) { return !enrollmentRequired(principal) && (principal.permissions.includes('*') || principal.permissions.includes(permission)); }
-const schema = { type: 'object', additionalProperties: false, properties: { registration: { enum: ['open', 'invite-only', 'waitlist', 'off'] } } };
+const schema = { type: 'object', additionalProperties: false, properties: { registration: { enum: ['open', 'invite-only', 'waitlist', 'off'] }, hooks: hooksConfigSchema } };
 const policySchema = { type: 'object', additionalProperties: false, properties: { role: { type: 'string', minLength: 1, maxLength: 64 }, permission: { type: 'string', minLength: 1, maxLength: 128 }, verified: { type: 'boolean' }, freshWithinSeconds: { type: 'integer', minimum: 1, maximum: 3600 }, onDeny: { enum: [401, 403, 404, 'sign-in'] } }, minProperties: 0 };
 const actionIcons = { identify: 'arrow-right', login: 'arrow-right', 'step-up': 'shield', logout: 'log-out', export: 'download' };
 const hidden = hiddenField;
 const m = (html) => new Markup(html);
 export function authExtension(options) {
     return { name: 'auth', version: '1', projectSha256: options.projectSha256, targets: ['node'], schema, policySchema, credentialHeaders: ['cookie', 'authorization', 'x-csrf-token'],
-        activate(config, context) {
+        async activate(config, context) {
             if (context.mounts.length !== 1)
                 throw new Error('Auth requires exactly one mount');
+            // Fail-fast: a configured hook whose module fails to load or whose
+            // named export is missing fails activation here, never the first
+            // request that happens to reach it. `sandbox: true` is rejected
+            // inside loadLifecycleHooks, explicitly, not silently ignored.
+            const hooks = await loadLifecycleHooks(config.hooks, context.root);
             const mount = context.mounts[0], http = new AuthHttp({ origin: context.origin, csrfKey: options.csrfKey }), service = options.service, registrationMode = String(config.registration || 'off'), registration = registrationMode === 'open';
             // The runtime activates `ui` before auth, but its kit is read per request, never captured at activation.
             const source = () => presentationSource(options.presentation, options.ui, defaultPresentation), localized = Boolean(options.presentation || options.ui);
@@ -63,7 +69,18 @@ export function authExtension(options) {
                 }, enrollment: { required: !!registrationSchema.termsVersion || metadataFields.some(([, field]) => field.required), fields: (presentation) => profileMarkup((name, label, ...rest) => baseField(name, presentation?.textSource(label) ?? label, ...rest), presentation), read: profileInput, names: ['displayName', 'locale', 'termsAccepted', ...metadataFields.map(([name]) => 'meta.' + name)] } }, http, mount, registration);
             const factorRecovery = createFactorRecoveryFlows(options, http, mount);
             const manualRecovery = createManualRecoveryFlows(service, http, mount, options.ui);
-            const signup = createSignup({ ...options, presentation: lazyPresentation }, http, mount, { fields: p => profileMarkup((name, label, ...rest) => baseField(name, p.textSource(label), ...rest), p), read: profileInput, names: ['displayName', 'locale', 'termsAccepted', ...metadataFields.map(([name]) => 'meta.' + name)] });
+            const signup = createSignup({ ...options, presentation: lazyPresentation }, http, mount, { fields: p => profileMarkup((name, label, ...rest) => baseField(name, p.textSource(label), ...rest), p), read: profileInput, names: ['displayName', 'locale', 'termsAccepted', ...metadataFields.map(([name]) => 'meta.' + name)] }, hooks);
+            // `beforeRegister` is project governance over the project's own signup flow
+            // (docs/SPIKE-AUTH.md): a missing verdict or `allow: false` rejects the
+            // attempt with the hook's own reason, surfaced the same way any other
+            // registration rejection is (AuthHttpError -> httpFailure).
+            async function checkBeforeRegister(email, profile) {
+                if (!hooks.beforeRegister)
+                    return;
+                const verdict = await hooks.beforeRegister({ email, ...(profile ? { profile } : {}) });
+                if (!verdict || verdict.allow !== true)
+                    throw new AuthHttpError(403, verdict?.reason || 'Registration not permitted');
+            }
             const passkeyButton = (kind, text = value => value) => options.passkeys ? `<button type="button" data-passkey="${kind}" data-base="${escapeHtml(mount)}" data-unavailable="${escapeHtml(text('Passkeys are unavailable in this browser. Use another sign-in method.'))}" data-failed="${escapeHtml(text('Passkey request failed'))}" data-cancelled="${escapeHtml(text('Passkey ceremony cancelled'))}">${escapeHtml(text(kind === 'register' ? 'Add a passkey' : kind === 'step-up' ? 'Confirm identity with a passkey' : 'Sign in with a passkey'))}</button><p role="status" aria-live="polite" data-passkey-status></p>` : '';
             async function principal(request) {
                 const token = http.session(request);
@@ -108,7 +125,7 @@ export function authExtension(options) {
                 try {
                     await Promise.race([options.sendNotice({ email, event, ...(locale ? { locale } : {}), signal: controller.signal }), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('timeout')); }, 5000); })]);
                 }
-                catch { }
+                catch { /* Notification delivery is best-effort: a failed or timed-out notice must not fail the operation that triggered it. */ }
                 finally {
                     if (timer)
                         clearTimeout(timer);
@@ -143,7 +160,7 @@ export function authExtension(options) {
                             const session = http.session(request), actor = session ? await service.authenticate(session) : null;
                             accountLocale = actor ? (await service.getUser(actor.id))?.profile?.locale : undefined;
                         }
-                        catch { }
+                        catch { /* An unreadable session only means no account locale to prefer; fall back to the request locale. */ }
                     }
                     const presentation = source().resolve({ ...(accountLocale ? { accountLocale } : {}), ...(request.query.get('lang') ? { queryLocale: request.query.get('lang') } : {}), ...(request.headers.get('accept-language') ? { acceptLanguage: request.headers.get('accept-language') } : {}) });
                     const tr = (key, values) => escapeHtml(presentation.text(key, values));
@@ -327,6 +344,10 @@ export function authExtension(options) {
                                 return jsonResponse(202, { message: presentation.textSource('Registration request received.') });
                             if (path === '/register' && registrationMode === 'off')
                                 throw new AuthHttpError(404, 'Not found');
+                            if (path === '/register') {
+                                const registerProfile = profileInput(fields);
+                                await checkBeforeRegister(fields.email || '', registerProfile);
+                            }
                             if (path === '/register' && registrationMode === 'waitlist') {
                                 await service.requestRegistration({ email: fields.email || '', password: fields.password || '', profile: profileInput(fields) });
                                 return jsonResponse(202, { message: presentation.textSource('Registration request received.') });
@@ -335,6 +356,8 @@ export function authExtension(options) {
                             const result = path === '/register' ? await service.register({ email: fields.email || '', password: fields.password || '', device: { id: device.id, label: device.label }, profile: profileInput(fields), ...(fields.invitationToken ? { invitationToken: fields.invitationToken } : {}) }) : await service.login({ ...trusted(request), email: fields.email || '', password: fields.password || '', device: { id: device.id, label: device.label }, ...(fields.totp ? { totp: fields.totp } : {}), ...(fields.recoveryCode ? { recoveryCode: fields.recoveryCode } : {}), ...secondFactor });
                             if (result.newDevice)
                                 await notice(result.user.email, 'new-device', noticeLocale(request, result.user));
+                            if (path === '/register' && hooks.onSignUp)
+                                await hooks.onSignUp({ accountId: result.user.id, email: result.user.email });
                             return wantsJson(request) ? jsonResponse(path === '/register' ? 201 : 200, { user: result.user, csrf: http.token(result.token), ...(result.principal.restrictions ? { restrictions: result.principal.restrictions } : {}) }, [...http.sessionHeaders(result.token), ...device.headers]) : redirect(mount + '/account', [...http.sessionHeaders(result.token), ...device.headers]);
                         }
                         if (path === '/send-email-code') {
@@ -347,7 +370,7 @@ export function authExtension(options) {
                                 try {
                                     await Promise.race([options.sendEmailCode({ email, flowId: issued.flowId, code: issued.code, locale: presentation.locale, signal: controller.signal }), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('timeout')); }, 5000); })]);
                                 }
-                                catch { }
+                                catch { /* Delivery is best-effort here too: the code is already issued, and the flow continues on the verification step. */ }
                                 finally {
                                     if (timer)
                                         clearTimeout(timer);
@@ -454,6 +477,12 @@ export function authExtension(options) {
                             if (fields.confirmation !== 'DELETE')
                                 throw new AuthHttpError(400, 'Deletion confirmation required');
                             const result = await service.deleteAccount({ token: current.token, ...(fields.password ? { password: fields.password } : {}), ...(fields.totp ? { totp: fields.totp } : {}), ...(fields.recoveryCode ? { recoveryCode: fields.recoveryCode } : {}), ...secondFactor });
+                            // Fires when the account owner schedules their own deletion (the
+                            // grace period still applies and can be cancelled); it does not
+                            // yet fire from an administrator-initiated deletion or from the
+                            // background purge once the grace period elapses.
+                            if (hooks.onDelete)
+                                await hooks.onDelete({ accountId: current.principal.id, email: current.principal.email });
                             await deliver(current.principal.email, result.cancelToken, 'cancel-deletion', false, presentation.locale);
                             return completed({ deletionScheduled: true, deleteAfter: result.deleteAfter, cancellationDays: service.getSecurityPolicy().deletionGraceMs / 86400000 }, 'Account deletion scheduled', 'Your account deletion is scheduled. Check your email for cancellation instructions if you change your mind.', http.clearSession(), '/login');
                         }

package/dist/backup.js

@@ -61,7 +61,8 @@ async function snapshot(sourceInput, destinationInput, projectRoot) {
         const copied = await lstat(file);
         if (!copied.isFile() || copied.size > 1073741824)
             throw new Error('Backup exceeds size limit');
-        const handle = await open(file, 'r');
+        // Windows FlushFileBuffers requires a writable handle.
+        const handle = await open(file, 'r+');
         try {
             await handle.sync();
         }
@@ -71,12 +72,16 @@ async function snapshot(sourceInput, destinationInput, projectRoot) {
         // Linking is atomic and refuses any existing destination, including a raced-in symlink.
         await link(file, destination);
         await rm(file);
-        const directory = await open(parent, 'r');
-        try {
-            await directory.sync();
-        }
-        finally {
-            await directory.close();
+        // Node cannot open/flush directory handles this way on Windows.
+        // File bytes were flushed above; POSIX also flushes the new directory entry.
+        if (process.platform !== 'win32') {
+            const directory = await open(parent, 'r');
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
         }
         return { format: 'urlcode-auth-sqlite-v1', bytes: copied.size };
     }

package/dist/challenge.js

@@ -10,7 +10,7 @@ export function createTurnstileChallenge(options) {
         throw new Error('Invalid Turnstile hostname');
     }
     const timeout = options.timeoutMs ?? 5000;
-    if (!key(options.secret) || !key(options.siteKey) || hostname !== options.hostname || !hostname || /[\/:@?#]/.test(hostname) || !Number.isInteger(timeout) || timeout < 10 || timeout > 5000)
+    if (!key(options.secret) || !key(options.siteKey) || hostname !== options.hostname || !hostname || /[/:@?#]/.test(hostname) || !Number.isInteger(timeout) || timeout < 10 || timeout > 5000)
         throw new Error('Invalid Turnstile configuration');
     let active = 0;
     return Object.freeze({ widget: Object.freeze({ siteKey: options.siteKey, action: 'auth' }), async verify(input) {

package/dist/lifecycle-hooks.d.ts

@@ -0,0 +1,76 @@
+export interface HookReference {
+    source: string;
+    export?: string;
+    sandbox?: boolean;
+}
+export type HookConfig = string | HookReference;
+export interface LifecycleHooksConfig {
+    beforeRegister?: HookConfig;
+    onSignUp?: HookConfig;
+    onDelete?: HookConfig;
+}
+export interface BeforeRegisterInput {
+    email: string;
+    profile?: Record<string, unknown>;
+}
+export interface BeforeRegisterVerdict {
+    allow: boolean;
+    reason?: string;
+}
+export interface OnSignUpInput {
+    accountId: string;
+    email: string;
+}
+export interface OnDeleteInput {
+    accountId: string;
+    email: string;
+}
+export interface LifecycleHooks {
+    beforeRegister?(input: BeforeRegisterInput): BeforeRegisterVerdict | Promise<BeforeRegisterVerdict>;
+    onSignUp?(input: OnSignUpInput): void | Promise<void>;
+    onDelete?(input: OnDeleteInput): void | Promise<void>;
+}
+export declare const hooksConfigSchema: {
+    type: string;
+    additionalProperties: boolean;
+    properties: {
+        [k: string]: {
+            oneOf: ({
+                type: string;
+                minLength: number;
+                maxLength: number;
+                additionalProperties?: never;
+                required?: never;
+                properties?: never;
+            } | {
+                type: string;
+                additionalProperties: boolean;
+                required: string[];
+                properties: {
+                    source: {
+                        type: string;
+                        minLength: number;
+                        maxLength: number;
+                    };
+                    export: {
+                        type: string;
+                        pattern: string;
+                    };
+                    sandbox: {
+                        type: string;
+                    };
+                };
+                minLength?: never;
+                maxLength?: never;
+            })[];
+        };
+    };
+};
+/**
+ * Resolves and eagerly imports every declared hook, so a missing module, a
+ * syntax error or a missing export fails activation (fail-fast), never the
+ * first request that happens to reach the hook. `sandbox: true` is rejected
+ * here, immediately and explicitly, rather than accepted and silently run
+ * trusted.
+ */
+export declare function loadLifecycleHooks(config: LifecycleHooksConfig | undefined, root: string): Promise<LifecycleHooks>;

package/dist/lifecycle-hooks.js

@@ -0,0 +1,106 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+// Project-level lifecycle hooks (docs/SPIKE-AUTH.md, urlcode-auth#35). A
+// project names its own function per lifecycle point in `extensions.auth.config.hooks`,
+// using the same `{source, export}` (or bare string) shape `function`/`middleware`
+// routes already use. These hooks are first-party project code and run
+// trusted, in-process, exactly like any other route's `function`/`middleware`
+// (docs/SPIKE-DEFAULT-TRUST-MODEL.md, urlcode's docs/EXTENSIONS.md "Project-level
+// lifecycle hooks"): no special case, no hardwired sandbox.
+//
+// `sandbox: true` is explicitly rejected at activation, never silently
+// ignored: core's trusted/sandboxed dispatch (TrustedFunctions/FunctionPool)
+// is wired to route dispatch, not exposed to extensions, so this package has
+// no way to actually isolate a hook call yet (tracked in
+// jimhoyd-com/urlcode#151). Accepting `sandbox: true` and running it trusted
+// anyway would misrepresent the isolation the project believes it configured.
+import { isAbsolute, relative, resolve } from 'node:path';
+import { realpath, stat } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+const hookNames = ['beforeRegister', 'onSignUp', 'onDelete'];
+export const hooksConfigSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: Object.fromEntries(hookNames.map(name => [name, {
+            oneOf: [
+                { type: 'string', minLength: 1, maxLength: 1024 },
+                {
+                    type: 'object',
+                    additionalProperties: false,
+                    required: ['source'],
+                    properties: {
+                        source: { type: 'string', minLength: 1, maxLength: 1024 },
+                        export: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+                        sandbox: { type: 'boolean' },
+                    },
+                },
+            ],
+        }])),
+};
+function normalize(ref) {
+    return typeof ref === 'string'
+        ? { source: ref, export: 'default', sandbox: false }
+        : { source: ref.source, export: ref.export ?? 'default', sandbox: ref.sandbox === true };
+}
+// Same project-relative-file discipline core's own `safeFile` applies to a
+// route's `function.source`: resolved against the project root, refused if
+// it escapes it. Not a security boundary against the module's own code
+// (trusted hooks get full Node access like any other project code), just the
+// same "the YAML cannot point outside the project" hygiene.
+async function projectFile(root, file, hookName) {
+    if (isAbsolute(file))
+        throw new Error(`hook ${hookName}: source must be a project-relative path`);
+    const base = await realpath(root);
+    let actual;
+    try {
+        actual = await realpath(resolve(base, file));
+    }
+    catch {
+        throw new Error(`hook ${hookName}: source module "${file}" was not found`);
+    }
+    const rel = relative(base, actual);
+    if (!rel || rel === '..' || rel.startsWith('..' + (process.platform === 'win32' ? '\\' : '/')) || isAbsolute(rel))
+        throw new Error(`hook ${hookName}: source escapes the project`);
+    if (!(await stat(actual)).isFile())
+        throw new Error(`hook ${hookName}: source must be a file`);
+    return actual;
+}
+/**
+ * Resolves and eagerly imports every declared hook, so a missing module, a
+ * syntax error or a missing export fails activation (fail-fast), never the
+ * first request that happens to reach the hook. `sandbox: true` is rejected
+ * here, immediately and explicitly, rather than accepted and silently run
+ * trusted.
+ */
+export async function loadLifecycleHooks(config, root) {
+    const hooks = {};
+    if (!config)
+        return hooks;
+    for (const name of hookNames) {
+        const ref = config[name];
+        if (ref === undefined)
+            continue;
+        const definition = normalize(ref);
+        if (definition.sandbox)
+            throw new Error(`hook ${name}: sandbox: true is not yet supported for project-level hooks, see jimhoyd-com/urlcode-auth#35`);
+        const file = await projectFile(root, definition.source, name);
+        let mod;
+        try {
+            mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+        }
+        catch {
+            throw new Error(`hook ${name}: failed to load module "${definition.source}"`);
+        }
+        const fn = mod[definition.export];
+        if (typeof fn !== 'function')
+            throw new Error(`hook ${name}: export "${definition.export}" in "${definition.source}" is not a function`);
+        hooks[name] = fn;
+    }
+    return hooks;
+}

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.6",
   "type": "module",
   "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jimhoyd-com/urlcode-auth.git"
+    "url": "git+https://github.com/jimhoyd-com/urlcode.git",
+    "directory": "packages/auth"
   },
   "publishConfig": {
     "access": "public"
@@ -18,7 +19,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "pretest": "node scripts/check-sqlite.mjs",
-    "test": "node --conditions=development --test test/*.test.ts",
+    "test": "node --conditions=development --test --test-timeout=300000 test/*.test.ts",
     "verify": "npm run typecheck && npm run build && npm test"
   },
   "exports": {
@@ -38,6 +39,7 @@
     "THREAT-MODEL.md"
   ],
   "devDependencies": {
+    "@jimhoyd/urlcode": "file:../..",
     "@types/node": "26.5.1",
     "typescript": "6.0.3"
   },
@@ -50,14 +52,14 @@
     "otpauth": "9.5.2"
   },
   "peerDependencies": {
-    "@jimhoyd/urlcode": ">=0.4.0-alpha.1 <0.5.0",
+    "@jimhoyd/urlcode": ">=0.4.0-alpha.2 <0.5.0",
     "@jimhoyd/urlcode-ui": ">=0.1.0-alpha.1 <0.2.0"
   },
   "bin": {
     "urlcode-auth": "./dist/cli.js"
   },
-  "homepage": "https://github.com/jimhoyd-com/urlcode-auth#readme",
+  "homepage": "https://github.com/jimhoyd-com/urlcode/tree/main/packages/auth#readme",
   "bugs": {
-    "url": "https://github.com/jimhoyd-com/urlcode-auth/issues"
+    "url": "https://github.com/jimhoyd-com/urlcode/issues"
   }
 }