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

package/IMPLEMENTATION-STATUS.md

@@ -1,6 +1,18 @@
 # Auth implementation status
 
-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.
+Status: `@jimhoyd/urlcode-auth` is published to npm as an alpha. The current
+version and the peer ranges it supports are in `package.json`; read them there
+rather than from this page, and see [package and channel
+alignment](../../docs/VERSION-ALIGNMENT.md) for how versions, channels and tags
+relate. Core, ui, auth and admin are workspace packages in one repository, so a
+single commit identifies all of them and development resolves peers through the
+workspace links rather than published versions. `src/auth.ts` resolves project
+lifecycle hooks through `ExtensionActivation.root`, which is the oldest core API
+this package needs. The implemented auth and shared-presentation work is merged
+to main. The source plan is URLCode PR #54; release acceptance is tracked in
+[issue 58](https://github.com/jimhoyd-com/urlcode/issues/58), and 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.
 
@@ -8,9 +20,9 @@ Resumable verification-first password/passkey signup (including waitlist approva
 
 Mandatory verification/TOTP enrollment, operator standard/hardened presets and explicit pinned configuration migration are implemented; hardened requires email and breach-screening adapters.
 
-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.
+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 every screen through `ui.kit.page`. The `ui` extension is required: activation refuses when it is absent, or when the runtime has not activated it because `extensions.ui` is missing from `urlcode.yaml` or declared after `extensions.auth`. The shared-primitive fallback that earlier releases used without the kit has been removed, along with its compile-on-demand template cache and the `pageResponse` document helper that served it (no longer exported). The HTTP suites run once, on the kit path; a doctor-style suite renders every template with its sample and with the view a real request computes, checks escaping of user-controlled values and the nonce-bound CSP, and a separate test covers the activation refusal. 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.
+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 rather than silently ignored — core exports the `SandboxPool` primitive (`@jimhoyd/urlcode/sandbox`), but this package does not route a hook invocation through it yet, so the opt-in it would imply does not exist here. `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
 
@@ -31,9 +43,9 @@ Live Google/Apple/SES testing is explicitly deferred by the project owner and is
 
 ## Agreed architecture corrections
 
-Auth/admin live in independent repositories. The core owns generic revision-pinned extension contracts and never depends on auth. SQLite and privileged transactions belong to the trusted operator service. Project YAML cannot select host modules or credentials. Safe package renderers replace arbitrary project templates. The initial auth target is Node with operator-owned durable storage; runtime adapter availability does not make this SQLite service portable to every deployment target.
+Auth and admin are separate packages with their own contracts; core owns the generic extension contract and never depends on auth. SQLite and privileged transactions belong to the trusted operator service. Project YAML cannot select host modules or credentials. Safe package renderers replace arbitrary project templates. The initial auth target is Node with operator-owned durable storage; runtime adapter availability does not make this SQLite service portable to every deployment target.
 
 ## Recorded acceptance
 
-See [ACCEPTANCE.md](https://github.com/jimhoyd-com/urlcode-auth/blob/main/ACCEPTANCE.md) for exact merged revisions, automated coverage,
+See [ACCEPTANCE.md](ACCEPTANCE.md) for exact merged revisions, automated coverage,
 clean-install evidence and the remaining operational validation boundary.

package/README.md

@@ -8,20 +8,20 @@ The implementation is under active review. Local tests and builds are evidence o
 
 ## Install
 
-`@jimhoyd/urlcode-auth` is published to npm as an alpha alongside its peers. Install the three packages together; the peer ranges in `package.json` require `@jimhoyd/urlcode` 0.4.0-alpha.1 or a later 0.4.x and `@jimhoyd/urlcode-ui` 0.1.0-alpha.1 or a later 0.1.x, and the release workflow builds and tests against exactly those registry versions.
+`@jimhoyd/urlcode-auth` is published to npm as an alpha alongside its peers. Install the three packages together; the peer ranges for `@jimhoyd/urlcode` and `@jimhoyd/urlcode-ui` are declared in `package.json` — read them there rather than from this page — and the release workflow builds and tests against exactly those registry versions.
 
 ```sh
 npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth
-npx urlcode init my-site --with auth
+npx urlcode init my-site --with ui,auth
 ```
 
-`urlcode init --with auth` is core's layered scaffold; `npx urlcode-auth init --directory /absolute/new-account-site` scaffolds an auth-only project. Either writes `app/urlcode.yaml`, external `host.mjs` and `operator-service.mjs`, a private `data/` directory and independent encryption/CSRF keys, and refuses an existing destination. Its README gives the exact next steps.
+`urlcode init --with ui,auth` is core's layered scaffold (auth renders through the ui kit, so `ui` must be named first: the runtime activates extensions in the order the project declares them, and auth's scaffold refuses any other order); `npx urlcode-auth init --directory /absolute/new-account-site` scaffolds an auth-only project. Either writes `app/urlcode.yaml`, external `host.mjs` and `operator-service.mjs`, a private `data/` directory and independent encryption/CSRF keys, and refuses an existing destination. Its README gives the exact next steps.
 
 Alpha caveat: the source is complete for the first release and its automated checks pass, but independent security review, accessibility assessment, browser/device WebAuthn coverage and deployment/soak/recovery exercises are still pending (see [IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md)). Alpha versions may change public exports, configuration keys and the SQLite schema between releases without a migration path. Do not run an alpha on production accounts.
 
 Use a current supported Node release with a patched SQLite build. The actual runtime requirement is a Node build whose bundled SQLite (`process.versions.sqlite`) is 3.51.3 or newer, or a patched 3.50.7+ / 3.44.6+ branch release; `engines.node` alone does not encode this, and the service (`src/auth-store.ts`) refuses other builds with `patched_sqlite_required` even when the package's minimum Node version is satisfied.
 
-Every release tarball is attested from the tagged commit: `gh attestation verify jimhoyd-urlcode-auth-<version>.tgz --repo jimhoyd-com/urlcode-auth`. `npm view @jimhoyd/urlcode-auth` shows the published provenance.
+Every release tarball is attested from the tagged commit: `gh attestation verify jimhoyd-urlcode-auth-<version>.tgz --repo jimhoyd-com/urlcode`. `npm view @jimhoyd/urlcode-auth` shows the published provenance.
 
 ## Install from reviewed source
 
@@ -42,7 +42,7 @@ 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.
+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` for each workspace package; 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:
 
@@ -55,7 +55,7 @@ Tarball names and versions must match the generated manifest. Install the same r
 
 ## Programmatic scaffold
 
-`scaffold({directory, project, hostFile, names})` returns the auth pieces of a layered project (YAML fragments, host imports and entries, private files with in-memory key material, a README section and next steps) without writing anything; `initAuthentication` is assembled from it. Core's `urlcode init --with auth` calls this export and merges it with other extensions.
+`scaffold({directory, project, hostFile, names})` returns the auth pieces of a layered project (YAML fragments, host imports and entries, private files with in-memory key material, a README section and next steps) without writing anything; `initAuthentication` is assembled from it. Core's `urlcode init --with ui,auth` calls this export and merges it with other extensions; it refuses a request whose `names` omit `ui` or place it after `auth`.
 Exported types: `ScaffoldRequest`, `ScaffoldResult`, `ScaffoldFile`.
 
 ## Operator activation
@@ -131,14 +131,20 @@ 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.
 
+Each activation re-reads the hook's **entry** module from disk, so editing a
+hook file and re-activating (a dev reload) takes effect without restarting
+the process. Only the entry module is refreshed: modules the hook itself
+imports stay on Node's module cache for the life of the process, so a change
+to a hook's own dependency still needs a restart.
+
 **`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.
+explicitly at activation**, naming the hook. Core exports the isolate itself —
+`SandboxPool` from `@jimhoyd/urlcode/sandbox`, the same engine a sandboxed
+route uses ([extensions](../../docs/EXTENSIONS.md)) — but this package does not
+route a hook invocation through it, so the opt-in does not exist here 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
 
@@ -208,9 +214,9 @@ Migration preserves accounts, enrolled credentials and history, while revoking s
 
 ## Presentation
 
-Every account screen is an `auth/*` template in the urlcode-ui kit language with a declared view model (`authTemplates`, each with a sample view; `authUiTemplates` is the block the `ui` extension takes). The extension computes the view and the template only places it: a template cannot change which steps a flow has, what a form validates, what is escaped, or the CSRF field and headers a page sends. Forms, fields and buttons arrive in the view as renderer-produced markup built by the shared primitives.
+Every account screen is an `auth/*` template in the urlcode-ui kit language with a declared view model (`authTemplates`, each with a sample view; `authUiTemplates` is the block the `ui` extension takes). The extension computes the view and the template only places it: a template cannot change which steps a flow has, what a form validates, what is escaped, or the CSRF field and headers a page sends. Forms, fields and buttons arrive in the view as renderer-produced markup built by the kit's shared form primitives (`field`, `postForm` and friends from `@jimhoyd/urlcode-ui`).
 
-`authExtension` takes an optional `ui`, the object `createUiExtension` returns. Declare `ui` first in the host file so the runtime activates it before auth; auth reads `ui.kit` per request and never captures it at activation.
+`authExtension` requires `ui`, the object `createUiExtension` returns: the kit is the only render path. Declare `ui` before `auth` in `urlcode.yaml` and list `ui.registration` before `authExtension` in the host — the runtime activates extensions in the order `urlcode.yaml` declares them, and auth refuses activation when `ui` is missing or not yet activated. Auth reads `ui.kit` per request and never captures it at activation. `@jimhoyd/urlcode-ui` is already a required peer dependency, so this adds nothing to install.
 
 ```js
 import { createUiExtension } from '@jimhoyd/urlcode-ui/host';
@@ -222,13 +228,15 @@ export default { extensions: [ui.registration, authExtension({ service, csrfKey,
 ```yaml
 extensions:
   ui: { version: "1", config: { theme: { name: Acme }, templates: ui/templates } }
+  auth: { version: "1", config: { registration: "off" } }
 routes:
   /assets/ui/*: { extension: ui, methods: [GET, HEAD] }
+  /account/*: { extension: auth, methods: [GET, HEAD, POST] }
 ```
 
-With `ui`, screens render through `ui.kit.page`: the project's theme, layout, hashed stylesheet and copy apply, a project file `ui/templates/auth/<screen>.html` shadows the shipped template, and `urlcode-ui doctor` reports every `auth/*` template behind its view model. Copy then resolves through the kit's presentation, which carries the kit catalogue, the auth catalogue and the project's `extensions.ui` copy; omit `presentation` in that case. If both are given, `presentation` wins and must register the kit catalogue for the layout's own keys.
+Screens render through `ui.kit.page`: the project's theme, layout, hashed stylesheet and copy apply, a project file `ui/templates/auth/<screen>.html` shadows the shipped template, and `urlcode-ui doctor --extensions @jimhoyd/urlcode-auth` reports every `auth/*` template behind its view model (the CLI loads the namespace, copy and samples from this package's `authUiTemplates` export; without the flag it sees the kit alone). Copy then resolves through the kit's presentation, which carries the kit catalogue, the auth catalogue and the project's `extensions.ui` copy; omit `presentation` in that case. If both are given, `presentation` wins and must register the kit catalogue for the layout's own keys.
 
-Without `ui`, nothing changes: screens render the same templates through the shared primitives with `presentation` (or the bundled English catalogue). The `presentation` option remains the fallback; core plans to retire it one minor version after the kit path ships. The auth passkey script and the optional challenge widget are nonce-bound on both paths and the page CSP admits only that nonce (plus the challenge origin when configured).
+There is no fallback render path: earlier releases rendered the same templates through the shared primitives when `ui` was absent, and that branch has been removed. The auth passkey script and the optional challenge widget are nonce-bound to the kit's page nonce and the page CSP admits only that nonce (plus the challenge origin when configured).
 
 Changing `configurationTag` deliberately advances the approved configuration revision for provider/callback/profile-policy deployments that cannot be fingerprinted as simple data. The service does not automatically fingerprint executable callbacks. Session idle and absolute limits do participate in the declared configuration fingerprint.
 

package/dist/abuse-http.d.ts

@@ -5,4 +5,4 @@ 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>;
+export declare function createAbuseGuard(service: AuthService, http: AuthHttp, mount: string, challenge: AuthChallenge | undefined, ui: UiHost): (request: ExtensionRequest, presentation?: PresentationContext) => Promise<import("./auth-ui.ts").AuthHttpResponse | undefined>;

package/dist/auth-baseline.js

@@ -66,11 +66,14 @@ async function probe(root) {
     let runtime, service;
     try {
         const { createRuntime } = await import('@jimhoyd/urlcode'), { inspectExtensionRevision } = await import('@jimhoyd/urlcode/extensions'), { createAuthService } = await import("./auth-core.js"), { authExtension } = await import("./auth.js");
+        // Account screens render only through the kit, so the synthetic project declares and registers `ui` exactly as a real host must.
+        const { createUiExtension } = await import('@jimhoyd/urlcode-ui/host'), { authUiTemplates } = await import("./auth-templates.js"), { englishCatalogue } = await import("./presentation.js");
         const project = join(root, 'project'), operator = join(root, 'operator'), origin = 'https://baseline.invalid';
         await mkdir(project, { mode: 0o700 });
         await mkdir(operator, { mode: 0o700 });
-        await writeFile(join(project, 'urlcode.yaml'), JSON.stringify({ version: '1', extensions: { auth: { version: '1', config: { registration: 'open' } } }, routes: {
+        await writeFile(join(project, 'urlcode.yaml'), JSON.stringify({ version: '1', extensions: { ui: { version: '1', config: {} }, auth: { version: '1', config: { registration: 'open' } } }, routes: {
                 '/account/*': { extension: 'auth', methods: ['GET', 'HEAD', 'POST'] },
+                '/assets/ui/*': { extension: 'ui', methods: ['GET', 'HEAD'] },
                 '/protected': { respond: { json: { authorized: true } }, methods: ['GET', 'POST'], policies: { extensions: { auth: { permission: 'baseline.read' } } } },
                 '/public-guest': { parameters: [{ name: 'cookie', in: 'header', schema: { type: 'string', default: 'untrusted-default' } }, { name: 'authorization', in: 'header', schema: { type: 'string' } }], function: { source: 'guest.mjs' } },
             } }), { mode: 0o600 });
@@ -78,7 +81,8 @@ async function probe(root) {
         const revision = await inspectExtensionRevision(project), csrfKey = randomBytes(32), encryptionKey = randomBytes(32), password = 'synthetic-baseline-' + randomBytes(16).toString('hex');
         service = await createAuthService({ database: join(operator, 'ordinary.sqlite'), encryptionKey, roles: { member: ['baseline.read'], admin: ['*'] }, defaultRole: 'member' });
         const account = await service.register({ email: 'synthetic-baseline@example.test', password });
-        const startRuntime = () => createRuntime(project, { origin, environment: {}, workers: 1, timeoutMs: 1000, extensions: [authExtension({ service: service, csrfKey, projectSha256: revision })], log: () => { } });
+        const ui = createUiExtension({ projectSha256: revision, projectRoot: project, sources: [englishCatalogue], extensions: [authUiTemplates] });
+        const startRuntime = () => createRuntime(project, { origin, environment: {}, workers: 1, timeoutMs: 1000, extensions: [ui.registration, authExtension({ service: service, csrfKey, projectSha256: revision, ui })], log: () => { } });
         runtime = await startRuntime();
         const text = (response) => typeof response.body === 'string' ? response.body : response.body ? Buffer.from(response.body).toString('utf8') : '';
         const cookies = new Map();

package/dist/auth-flows.d.ts

@@ -10,7 +10,7 @@ import type { AuthHttpResponse, UiHost } from './auth-ui.ts';
 export interface AuthFlowOptions {
     service: AuthService;
     presentation?: Presentation;
-    ui?: UiHost;
+    ui: UiHost;
     onSession?: (request: ExtensionRequest, result: AuthSessionResult) => Promise<[
         string,
         string

package/dist/auth-store.d.ts

@@ -1,9 +1,10 @@
 import type { AuthAbusePolicy } from './abuse.ts';
 import type { RegistrationProfile } from './registration.ts';
+import type { EventEmitter } from 'node:events';
 export declare class AuthError extends Error {
     readonly status: number;
     readonly code: string;
-    constructor(status: number, code: string);
+    constructor(status: number, code: string, cause?: unknown);
 }
 export interface AuthRecord {
     mfaPasskeys?: string[];
@@ -77,5 +78,20 @@ export interface AuthStore {
     call<T = unknown>(operation: string, args?: Record<string, unknown>): Promise<T>;
     close(): Promise<void>;
 }
+/**
+ * Describes the phase a worker was still in when its startup bound elapsed.
+ * Thread scheduling and database initialization fail for unrelated reasons, and a
+ * bare timeout cannot tell them apart; naming the phase makes the next occurrence
+ * diagnosable from the failure alone. `onlineMs` is undefined when the worker
+ * thread never began executing JavaScript.
+ */
+export declare function startupPhase(onlineMs: number | undefined, elapsedMs: number): string;
+/**
+ * Resolves once the worker reports readiness, and otherwise rejects with what it
+ * reached. A worker that fails or exits before reporting is rejected at once
+ * rather than waiting out `boundMs`, whose expiry is reported with its phase and
+ * timings. Separated from Worker construction so every branch is testable.
+ */
+export declare function awaitStoreStartup(worker: EventEmitter, boundMs: number): Promise<void>;
 export declare function patched(version: string): boolean;
 export declare function openAuthStore(options: StoreOptions): Promise<AuthStore>;

package/dist/auth-store.js

@@ -11,7 +11,49 @@ import { resolve, dirname, basename, join } from 'node:path';
 export class AuthError extends Error {
     status;
     code;
-    constructor(status, code) { super(code); this.status = status; this.code = code; }
+    // `cause` carries operator diagnostics only. Responses are built from `status`
+    // and `code`, so nothing recorded here reaches a client.
+    constructor(status, code, cause) { super(code, cause === undefined ? undefined : { cause }); this.status = status; this.code = code; }
+}
+/** Startup codes the worker reports for itself; anything else is an unavailable store. */
+const startupCodes = ['auth_configuration_changed', 'configuration_approval_mismatch', 'configuration_roles_invalid', 'configuration_admin_required'];
+/**
+ * Describes the phase a worker was still in when its startup bound elapsed.
+ * Thread scheduling and database initialization fail for unrelated reasons, and a
+ * bare timeout cannot tell them apart; naming the phase makes the next occurrence
+ * diagnosable from the failure alone. `onlineMs` is undefined when the worker
+ * thread never began executing JavaScript.
+ */
+export function startupPhase(onlineMs, elapsedMs) {
+    return onlineMs === undefined
+        ? `worker thread did not begin executing within ${elapsedMs}ms`
+        : `worker thread began executing after ${onlineMs}ms, then did not report readiness for a further ${elapsedMs - onlineMs}ms`;
+}
+/**
+ * Resolves once the worker reports readiness, and otherwise rejects with what it
+ * reached. A worker that fails or exits before reporting is rejected at once
+ * rather than waiting out `boundMs`, whose expiry is reported with its phase and
+ * timings. Separated from Worker construction so every branch is testable.
+ */
+export function awaitStoreStartup(worker, boundMs) {
+    const started = performance.now(), elapsed = () => Math.round(performance.now() - started);
+    let onlineMs;
+    worker.once('online', () => { onlineMs = elapsed(); });
+    return new Promise((accept, reject) => {
+        const unavailable = (detail) => new AuthError(503, 'auth_store_unavailable', new Error(detail));
+        const timer = setTimeout(() => { reject(unavailable(startupPhase(onlineMs, elapsed()))); }, boundMs);
+        worker.once('message', (message) => {
+            clearTimeout(timer);
+            if (message.ready)
+                accept();
+            else if (startupCodes.includes(message.error ?? ''))
+                reject(new AuthError(503, message.error));
+            else
+                reject(unavailable(`worker reported ${message.error ?? 'no readiness'} after ${elapsed()}ms`));
+        });
+        worker.once('error', (error) => { clearTimeout(timer); reject(unavailable(`worker failed after ${elapsed()}ms: ${error instanceof Error ? error.message : String(error)}`)); });
+        worker.once('exit', (code) => { clearTimeout(timer); reject(unavailable(`worker exited with code ${code} after ${elapsed()}ms without reporting readiness`)); });
+    });
 }
 export function patched(version) { const [a = 0, b = 0, c = 0] = version.split('.').map(Number); return a > 3 || a === 3 && (b > 51 || b === 51 && c >= 3 || b === 50 && c >= 7 || b === 44 && c >= 6); }
 export async function openAuthStore(options) {
@@ -47,18 +89,7 @@ export async function openAuthStore(options) {
     worker.on('error', fail);
     worker.on('exit', fail);
     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')); });
-        });
+        await awaitStoreStartup(worker, 15000);
     }
     catch (error) {
         // A rejected open must release SQLite handles before its caller can

package/dist/auth-templates.d.ts

@@ -1,4 +1,4 @@
-import type { ViewModel } from '@jimhoyd/urlcode-ui';
+import type { ExtensionTemplates, ViewModel } from '@jimhoyd/urlcode-ui';
 export interface AuthTemplate {
     readonly source: string;
     readonly sample: ViewModel;
@@ -6,8 +6,13 @@ export interface AuthTemplate {
 /** Template sources with their view model samples, keyed by full template name. */
 export declare const authTemplates: Readonly<Record<string, AuthTemplate>>;
 export declare const authTemplateNames: readonly string[];
-/** What the host hands to `createUiExtension({ extensions: [authUiTemplates] })`. */
-export declare const authUiTemplates: {
+/**
+ * What the host hands to `createUiExtension({ extensions: [authUiTemplates] })`. It also carries the
+ * catalogue the host registers in `sources` and the view model samples, so `urlcode-ui --extensions
+ * @jimhoyd/urlcode-auth` lists, ejects, previews and drift-checks these screens from this one export.
+ */
+export declare const authUiTemplates: ExtensionTemplates & {
     readonly name: 'auth';
     readonly templates: Readonly<Record<string, string>>;
+    readonly samples: Readonly<Record<string, ViewModel>>;
 };

package/dist/auth-templates.js

@@ -7,6 +7,7 @@
  * validates, what is escaped or what a page sends in headers.
  */
 import { Markup } from '@jimhoyd/urlcode-ui';
+import { englishCatalogue } from "./presentation.js";
 const m = (html) => new Markup(html);
 const declare = (name, body) => `{{!-- viewModel: auth/${name}@1 --}}${body}`;
 const link = '<a href="{{href href}}">{{label}}</a>';
@@ -70,5 +71,14 @@ const screens = {
 /** Template sources with their view model samples, keyed by full template name. */
 export const authTemplates = Object.freeze(Object.fromEntries(Object.entries(screens).map(([name, screen]) => [`auth/${name}`, Object.freeze({ source: declare(name, screen.body), sample: screen.sample })])));
 export const authTemplateNames = Object.freeze(Object.keys(authTemplates));
-/** What the host hands to `createUiExtension({ extensions: [authUiTemplates] })`. */
-export const authUiTemplates = Object.freeze({ name: 'auth', templates: Object.freeze(Object.fromEntries(Object.entries(authTemplates).map(([name, template]) => [name, template.source]))) });
+/**
+ * What the host hands to `createUiExtension({ extensions: [authUiTemplates] })`. It also carries the
+ * catalogue the host registers in `sources` and the view model samples, so `urlcode-ui --extensions
+ * @jimhoyd/urlcode-auth` lists, ejects, previews and drift-checks these screens from this one export.
+ */
+export const authUiTemplates = Object.freeze({
+    name: 'auth',
+    templates: Object.freeze(Object.fromEntries(Object.entries(authTemplates).map(([name, template]) => [name, template.source]))),
+    catalogue: englishCatalogue,
+    samples: Object.freeze(Object.fromEntries(Object.entries(authTemplates).map(([name, template]) => [name, template.sample]))),
+});

package/dist/auth-ui.d.ts

@@ -1,4 +1,4 @@
-import type { ViewModel, Kit, Presentation } from '@jimhoyd/urlcode-ui';
+import type { ViewModel, Kit } from '@jimhoyd/urlcode-ui';
 export { escapeHtml } from '@jimhoyd/urlcode-ui';
 import type { TurnstileWidget } from './challenge-ui.ts';
 import type { PresentationContext } from './presentation.ts';
@@ -32,27 +32,20 @@ export interface Screen {
 export interface ScreenOptions {
     status?: number | undefined;
     headers?: [string, string][] | undefined;
-    /** A same-origin script the screen needs (the passkey glue); it is nonce-bound on both render paths. */
+    /** A same-origin script the screen needs (the passkey glue); it is nonce-bound to the kit's page nonce. */
     scriptPath?: string | undefined;
     presentation?: PresentationContext | undefined;
     turnstile?: TurnstileWidget | undefined;
     layout?: 'default' | 'compact' | 'application' | undefined;
-    /** When present and active, the screen renders through the kit; otherwise through the primitives. */
-    ui?: UiHost | undefined;
+    /** The kit every account screen renders through; `authExtension` refuses activation without it. */
+    ui: UiHost;
 }
-/** Test hook: sees every screen before it renders, with the path that renders it. */
+/** Test hook: sees every screen before it renders. */
 export declare const screenObserver: {
-    current?: ((screen: Screen, path: 'primitives' | 'kit') => void) | undefined;
+    current?: ((screen: Screen) => void) | undefined;
 };
-/** Renders a screen: through `ui.kit` when the host supplied the ui extension and it is active, otherwise through the shared primitives. */
-export declare function screenResponse(title: string, screen: Screen, options?: ScreenOptions): AuthHttpResponse;
-/** The presentation auth resolves copy through: the host's, else the kit's once `ui` is active, else the bundled English catalogue. */
-export declare function presentationSource(presentation: Presentation | undefined, ui: UiHost | undefined, fallback: Presentation): Presentation;
-/** Only trusted package code constructs markup. Project/user values must pass escapeHtml. */
-export declare function pageResponse(title: string, markup: string, status?: number, headers?: [
-    string,
-    string
-][], scriptPath?: string, presentation?: PresentationContext, turnstile?: TurnstileWidget, layout?: 'default' | 'compact' | 'application'): AuthHttpResponse;
+/** Renders a screen through `ui.kit`, the only render path; activation already refused a missing or inactive `ui`. */
+export declare function screenResponse(title: string, screen: Screen, options: ScreenOptions): AuthHttpResponse;
 export declare function formField(name: string, label: string, type?: string, autocomplete?: string, required?: boolean): string;
 export declare function csrfField(token: string): string;
 export declare function wantsJson(request: ExtensionRequest): boolean;
@@ -96,10 +89,10 @@ export declare class AuthHttp {
         string
     ][];
 }
-export declare function httpFailure(error: unknown, request: ExtensionRequest, presentation?: PresentationContext, recovery?: {
+export declare function httpFailure(error: unknown, request: ExtensionRequest, presentation: PresentationContext | undefined, recovery: {
     href: string;
     label: string;
-}, ui?: UiHost): AuthHttpResponse;
+} | undefined, ui: UiHost): AuthHttpResponse;
 /** Proof token stays in the submitting form and is consumed once with the primary proof. */
 export declare function secondFactorButton(base: string, text?: (source: string) => string): string;
 /** Browser glue for maintained server-side WebAuthn verification. No guest scripts. */

package/dist/auth-ui.js

@@ -1,9 +1,8 @@
-import { renderDocument, field, escapeHtml, compileTemplate, Markup } from '@jimhoyd/urlcode-ui';
+import { field, escapeHtml, Markup } from '@jimhoyd/urlcode-ui';
 export { escapeHtml } from '@jimhoyd/urlcode-ui';
 import { authTemplates } from "./auth-templates.js";
 import { addTurnstileWidgets, turnstileOrigin, turnstileScript } from "./challenge-ui.js";
 import { englishCatalogue } from "./presentation.js";
-import { createPresentation } from "./presentation.js";
 import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
 export class AuthHttpError extends Error {
     status;
@@ -12,33 +11,18 @@ export class AuthHttpError extends Error {
 const encoder = new TextEncoder();
 const securityHeaders = [['cache-control', 'no-store'], ['content-security-policy', "default-src 'none'; style-src 'unsafe-inline'; form-action 'self'; base-uri 'none'; frame-ancestors 'none'"], ['referrer-policy', 'strict-origin'], ['x-content-type-options', 'nosniff']];
 export function jsonResponse(status, value, headers = []) { return { status, headers: [...securityHeaders, ['content-type', 'application/json; charset=utf-8'], ...headers], body: encoder.encode(JSON.stringify(value)) }; }
-/** Test hook: sees every screen before it renders, with the path that renders it. */
+/** Test hook: sees every screen before it renders. */
 export const screenObserver = {};
-let defaultContext;
-const localTemplates = new Map();
-function localTemplate(name) {
-    let template = localTemplates.get(name);
-    if (!template && Object.hasOwn(authTemplates, name)) {
-        template = compileTemplate(name, authTemplates[name].source);
-        localTemplates.set(name, template);
-    }
-    return template;
-}
 function pageTitle(title, presentation) {
     const titleKey = Object.entries(englishCatalogue).find(([key, value]) => key.startsWith('page.') && value === title)?.[0];
     return presentation ? (titleKey ? presentation.text(titleKey) : presentation.textSource(title)) : title;
 }
-/** Renders a screen: through `ui.kit` when the host supplied the ui extension and it is active, otherwise through the shared primitives. */
-export function screenResponse(title, screen, options = {}) {
+/** Renders a screen through `ui.kit`, the only render path; activation already refused a missing or inactive `ui`. */
+export function screenResponse(title, screen, options) {
     if (!Object.hasOwn(authTemplates, screen.name))
         throw new Error(`Unknown auth screen: ${screen.name.slice(0, 64)}`);
-    const kit = options.ui?.active ? options.ui.kit : undefined;
-    screenObserver.current?.(screen, kit ? 'kit' : 'primitives');
-    if (!kit) {
-        const context = options.presentation ?? (defaultContext ??= createPresentation().resolve());
-        const markup = localTemplate(screen.name).render(screen.view, context, localTemplate).html;
-        return pageResponse(title, markup, options.status, options.headers, options.scriptPath, options.presentation, options.turnstile, options.layout);
-    }
+    const kit = options.ui.kit;
+    screenObserver.current?.(screen);
     const context = options.presentation ?? kit.resolveContext();
     const challenge = addTurnstileWidgets(kit.render(screen.name, screen.view, context).html, options.turnstile);
     const page = kit.wrap(new Markup(challenge.markup), { title: pageTitle(title, context), context, ...(options.layout ? { layout: options.layout } : {}), ...(options.status !== undefined ? { status: options.status } : {}), ...(options.headers ? { headers: options.headers } : {}), ...(challenge.enabled ? { csp: { script: [turnstileOrigin], frame: [turnstileOrigin], connect: [turnstileOrigin] } } : {}) });
@@ -53,20 +37,6 @@ export function screenResponse(title, screen, options = {}) {
     html = html.slice(0, -'</body></html>'.length) + scripts.map(script => `<script nonce="${nonce}" src="${escapeHtml(script.src)}"${script.async ? ' async' : ' defer'}></script>`).join('') + '</body></html>';
     return { status: page.status, headers: page.headers, body: encoder.encode(html) };
 }
-/** The presentation auth resolves copy through: the host's, else the kit's once `ui` is active, else the bundled English catalogue. */
-export function presentationSource(presentation, ui, fallback) {
-    return presentation ?? (ui?.active ? ui.kit.presentation : fallback);
-}
-/** Only trusted package code constructs markup. Project/user values must pass escapeHtml. */
-export function pageResponse(title, markup, status = 200, headers = [], scriptPath, presentation, turnstile, layout = 'default') {
-    title = pageTitle(title, presentation);
-    const challenge = addTurnstileWidgets(markup, turnstile);
-    markup = challenge.markup;
-    const nonce = randomBytes(18).toString('base64');
-    const scripts = [...(scriptPath ? [{ src: scriptPath, nonce: nonce }] : []), ...(challenge.enabled ? [{ src: turnstileScript, nonce: nonce, async: true }] : [])];
-    const html = renderDocument({ title, trustedContent: markup, layout, theme: { nonce }, ...(presentation ? { presentation } : {}), scripts });
-    return { status, headers: [...securityHeaders.map(([name, value]) => [name, name === 'content-security-policy' ? value + (presentation?.logo || presentation?.favicon ? "; img-src 'self'" : '') + (nonce ? `; script-src 'nonce-${nonce}'${challenge.enabled ? ' ' + turnstileOrigin : ''}` : '') + (challenge.enabled ? `; frame-src ${turnstileOrigin}; connect-src 'self' ${turnstileOrigin}` : '') : value]), ['content-type', 'text/html; charset=utf-8'], ...headers], body: encoder.encode(html) };
-}
 export function formField(name, label, type = 'text', autocomplete = 'off', required = true) { return field({ name, label, type, autocomplete, required }); }
 export function csrfField(token) { return `<input type="hidden" name="csrf" value="${escapeHtml(token)}">`; }
 export function wantsJson(request) { return (request.headers.get('accept') || '').split(',').some(value => value.trim().split(';')[0] === 'application/json') || request.headers.get('content-type')?.split(';')[0]?.trim() === 'application/json'; }

package/dist/auth.d.ts

@@ -10,8 +10,8 @@ export interface AuthExtensionOptions {
     challenge?: AuthChallenge;
     sendFactorRecovery?: (message: FactorRecoveryMessage) => Promise<void>;
     presentation?: Presentation;
-    /** The `ui` extension from `createUiExtension`, declared before auth in the host file. Screens then render through its kit. */
-    ui?: UiHost;
+    /** The `ui` extension from `createUiExtension`, declared before auth in the host file. Every account screen renders through its kit; activation refuses without it. */
+    ui: UiHost;
     service: AuthService;
     csrfKey: Uint8Array;
     projectSha256: string;

package/dist/auth.js

@@ -2,14 +2,12 @@ import { icon, hiddenField, postForm, Markup } from '@jimhoyd/urlcode-ui';
 import { createAbuseGuard } from "./abuse-http.js";
 import { createManualRecoveryFlows } from "./manual-recovery.js";
 import { createFactorRecoveryFlows } from "./factor-recovery.js";
-import { createPresentation } from "./presentation.js";
 import { isHoneypotFilled } from "./registration.js";
 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 { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField as baseField, httpFailure, jsonResponse, 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'] }, hooks: hooksConfigSchema } };
@@ -22,14 +20,20 @@ export function authExtension(options) {
         async activate(config, context) {
             if (context.mounts.length !== 1)
                 throw new Error('Auth requires exactly one mount');
+            // Account screens render only through the kit, so a missing or unactivated `ui`
+            // is refused here rather than per request in production.
+            if (!options.ui)
+                throw new Error('Auth requires the ui extension: pass the object createUiExtension() returns as authExtension({ui, ...}). Every account screen renders through its kit; there is no shared-primitive fallback.');
+            if (!options.ui.active)
+                throw new Error('Auth requires an activated ui extension: declare `ui` in urlcode.yaml before `auth`, with its asset route (for example /assets/ui/*), and list ui.registration before authExtension in the host. The runtime activates extensions in the order urlcode.yaml declares them.');
             // 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);
+            // The runtime activated `ui` before auth, but its kit is read per request, never captured at activation.
+            const source = () => options.presentation ?? options.ui.kit.presentation;
             const lazyPresentation = { get locales() { return source().locales; }, get defaultLocale() { return source().defaultLocale; }, get english() { return source().english; }, resolve: preferences => source().resolve(preferences), coverage: locale => source().coverage(locale) };
             if (registrationMode !== service.getRegistrationMode())
                 throw new Error('Project registration mode must match operator auth service mode');
@@ -136,7 +140,7 @@ export function authExtension(options) {
                     let presentation = source().resolve({ ...(request.query.get('lang') ? { queryLocale: request.query.get('lang') } : {}), ...(request.headers.get('accept-language') ? { acceptLanguage: request.headers.get('accept-language') } : {}) });
                     try {
                         const token = http.session(request), user = token ? await service.authenticate(token) : null;
-                        const locale = user && localized ? (await service.getUser(user.id))?.profile?.locale : undefined;
+                        const locale = user ? (await service.getUser(user.id))?.profile?.locale : undefined;
                         if (locale)
                             presentation = source().resolve({ accountLocale: locale });
                         const allowed = user && !enrollmentRequired(user) && (!requirement.role || user.roles.includes(String(requirement.role))) && (!requirement.permission || hasPermission(user, String(requirement.permission))) && (!requirement.verified || user.emailVerified) && (!requirement.freshWithinSeconds || Date.now() - user.authenticatedAt <= Number(requirement.freshWithinSeconds) * 1000);
@@ -155,13 +159,11 @@ export function authExtension(options) {
                 },
                 async handle(request) {
                     let accountLocale;
-                    if (localized) {
-                        try {
-                            const session = http.session(request), actor = session ? await service.authenticate(session) : null;
-                            accountLocale = actor ? (await service.getUser(actor.id))?.profile?.locale : undefined;
-                        }
-                        catch { /* An unreadable session only means no account locale to prefer; fall back to the request locale. */ }
+                    try {
+                        const session = http.session(request), actor = session ? await service.authenticate(session) : null;
+                        accountLocale = actor ? (await service.getUser(actor.id))?.profile?.locale : undefined;
                     }
+                    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));
                     const text = (value) => presentation?.textSource(value) ?? value;

package/dist/factor-recovery.d.ts

@@ -37,7 +37,7 @@ export interface FactorRecoveryOptions {
     challenge?: AuthChallenge;
     service: FactorRecoveryService;
     sendFactorRecovery?: (message: FactorRecoveryMessage) => Promise<void>;
-    ui?: UiHost;
+    ui: UiHost;
 }
 /** Opt-in email fallback lowers factor assurance; it never creates an unrestricted session. */
 export declare function createFactorRecoveryFlows(options: FactorRecoveryOptions, http: AuthHttp, mount: string): {

package/dist/index.d.ts

@@ -3,7 +3,7 @@ export type { AuthService, AuthPrincipal, AuthUser } from './auth-core.ts';
 export { authExtension, hasPermission } from './auth.ts';
 export type { AuthExtensionOptions } from './auth.ts';
 export type { AuthHttpOptions, AuthHttpResponse } from './auth-ui.ts';
-export { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, httpFailure, jsonResponse, pageResponse, readFields, screenResponse, wantsJson } from './auth-ui.ts';
+export { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, httpFailure, jsonResponse, readFields, screenResponse, wantsJson } from './auth-ui.ts';
 export type { Screen, ScreenOptions, UiHost } from './auth-ui.ts';
 export { authTemplates, authTemplateNames, authUiTemplates } from './auth-templates.ts';
 export type { AuthTemplate } from './auth-templates.ts';

package/dist/index.js

@@ -1,6 +1,6 @@
 export { createAuthService, AuthError } from "./auth-core.js";
 export { authExtension, hasPermission } from "./auth.js";
-export { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, httpFailure, jsonResponse, pageResponse, readFields, screenResponse, wantsJson } from "./auth-ui.js";
+export { AuthHttp, AuthHttpError, csrfField, escapeHtml, formField, httpFailure, jsonResponse, readFields, screenResponse, wantsJson } from "./auth-ui.js";
 export { authTemplates, authTemplateNames, authUiTemplates } from "./auth-templates.js";
 export { createOidcProvider } from "./oidc.js";
 export { createPasskeyProvider } from "./passkeys.js";

package/dist/lifecycle-hooks.js

@@ -15,11 +15,24 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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.
+// ignored. Core now exports the isolate itself -- `SandboxPool` from
+// `@jimhoyd/urlcode/sandbox`, the same QuickJS/worker engine a sandboxed
+// route uses -- so the missing piece is no longer a core primitive but this
+// package's own wiring: a hook invocation is a plain in-process call and
+// nothing here routes it through a pool. Until that exists, accepting
+// `sandbox: true` and running it trusted anyway would misrepresent the
+// isolation the project believes it configured, so it is refused instead.
+//
+// Each activation re-imports the hook's ENTRY module under a fresh
+// cache-busting query, mirroring core's trusted route activation
+// (src/trusted-functions.ts, `urlcode-trusted-epoch`): Node's ESM loader
+// caches a resolved module forever by URL, so without this an edited hook
+// file kept returning its previous decision for the life of the process
+// (jimhoyd-com/urlcode#198). Only the entry module is refreshed — modules the
+// hook itself imports stay on Node's module cache, the same already-documented
+// core limitation the trusted route path has; a change to a hook's own
+// dependency still needs a process restart.
+import { randomUUID } from 'node:crypto';
 import { isAbsolute, relative, resolve } from 'node:path';
 import { realpath, stat } from 'node:fs/promises';
 import { pathToFileURL } from 'node:url';
@@ -82,17 +95,21 @@ export async function loadLifecycleHooks(config, root) {
     const hooks = {};
     if (!config)
         return hooks;
+    // One epoch per activation, not per hook: two hooks naming the same entry
+    // module still share a single instance within this activation, exactly as
+    // core's per-runtime-instance epoch does.
+    const epoch = randomUUID();
     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`);
+            throw new Error(`hook ${name}: sandbox: true is not yet supported for project-level hooks; this extension does not route a hook invocation through core's SandboxPool yet. See docs/EXTENSIONS.md "Project-level lifecycle hooks".`);
         const file = await projectFile(root, definition.source, name);
         let mod;
         try {
-            mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href)));
+            mod = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href + '?urlcode-hook-epoch=' + epoch)));
         }
         catch {
             throw new Error(`hook ${name}: failed to load module "${definition.source}"`);

package/dist/manual-recovery.d.ts

@@ -82,6 +82,6 @@ export interface ManualRecoveryService {
 }
 export declare function validateRecoveryEvidence(input: ManualRecoveryEvidence): ManualRecoveryEvidence;
 /** Redemption is POST-only and creates an enrollment session, never normal access. */
-export declare function createManualRecoveryFlows(service: ManualRecoveryService, http: AuthHttp, mount: string, ui?: UiHost): {
+export declare function createManualRecoveryFlows(service: ManualRecoveryService, http: AuthHttp, mount: string, ui: UiHost): {
     handle(request: ExtensionRequest, presentation?: PresentationContext): Promise<AuthHttpResponse | undefined>;
 };

package/dist/scaffold.d.ts

@@ -3,6 +3,10 @@ export interface AuthenticationScaffold {
     project: string;
     hostFile: string;
     operatorFile: string;
+    /** Exact versions recorded in the generated package.json. */
+    dependencies: Record<string, string>;
+    /** Peers whose installed version could not be read, recorded as their declared range instead of a pin. */
+    unpinnedDependencies: string[];
 }
 /** Shared scaffold contract (core `urlcode init --with`): what the caller is assembling. */
 export interface ScaffoldRequest {
@@ -40,5 +44,17 @@ export interface ScaffoldResult {
 export declare function scaffold(request: ScaffoldRequest): Promise<ScaffoldResult>;
 /** Deterministic YAML for scaffold fragments: block mappings, flow lists of scalars, {} for empty maps. */
 export declare function renderYaml(value: Record<string, unknown>, indent?: string): string;
+export interface DependencySpecifiers {
+    dependencies: Record<string, string>;
+    unpinned: string[];
+}
+/**
+ * What a generated auth site depends on: this package at its exact version, plus each declared peer at the exact
+ * version installed beside it. A peer whose installation cannot be found is recorded as its declared range and
+ * reported, because a manifest with no dependencies at all -- what this initializer wrote before #212 -- tells the
+ * generated site nothing about the versions it was generated against. Nothing is installed here; running a package
+ * manager to produce a lockfile stays the operator's own explicit step.
+ */
+export declare function dependencySpecifiers(): Promise<DependencySpecifiers>;
 /** Creates a new private directory only; never merges or overwrites an existing project. */
 export declare function initAuthentication(directory: string): Promise<AuthenticationScaffold>;

package/dist/scaffold.js

@@ -1,6 +1,8 @@
 import { randomBytes } from 'node:crypto';
-import { mkdir, open, realpath, rm } from 'node:fs/promises';
+import { scaffold as uiScaffold } from '@jimhoyd/urlcode-ui/host';
+import { mkdir, open, readFile, realpath, rm } from 'node:fs/promises';
 import { resolve, dirname, basename, join, relative, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
 const OPERATOR_FILE = 'operator-service.mjs', ENCRYPTION_KEY = 'data/encryption.key', CSRF_KEY = 'data/csrf.key';
 function moduleReference(from, to) {
     const path = relative(from, to).split(sep).join('/');
@@ -35,7 +37,9 @@ function readmeSection(request, admin) {
 
 ## Install
 
-Use a supported patched Node release. From this directory, install the separately built repositories until packages are released:
+Use a supported patched Node release. The generated \`package.json\` pins the runtime and extensions to the exact versions that were installed when this directory was created; review it, then run \`npm install\` here to install exactly those and write \`package-lock.json\`. Nothing installs them for you, and there is no upgrade command: changing a pinned version today means editing \`package.json\` and re-running the install yourself.
+
+To develop against separately built source repositories instead, replace those pins with the local paths (an install from a path is not reproducible anywhere that path does not exist):
 
 \`\`\`sh
 # First run npm ci && npm run build in each source repository.
@@ -79,6 +83,12 @@ export async function scaffold(request) {
     }
     if (!Array.isArray(request.names) || request.names.some(name => typeof name !== 'string'))
         throw new Error('Scaffold names must be strings');
+    // Every account screen renders through the kit, and the runtime activates extensions in urlcode.yaml order,
+    // which core writes in --with order. So ui must be named, and named first.
+    if (!request.names.includes('ui'))
+        throw new Error('Auth scaffold requires the ui extension: urlcode init --with ui,auth');
+    if (request.names.indexOf('ui') > request.names.indexOf('auth'))
+        throw new Error('Auth scaffold requires ui before auth so the kit activates first: urlcode init --with ui,auth');
     const directory = resolve(request.directory), project = resolve(directory, request.project), hostFile = resolve(directory, request.hostFile);
     const normalized = { directory, project, hostFile, names: request.names };
     const admin = request.names.includes('admin'), hostDirectory = dirname(hostFile);
@@ -104,7 +114,7 @@ export async function scaffold(request) {
             "  if (csrfKey.length !== 32) throw new Error('Invalid CSRF key');",
             '} catch (error) { await service.close(); throw error; }',
         ],
-        hostEntries: ['authExtension({service, csrfKey, projectSha256})'],
+        hostEntries: ['authExtension({service, csrfKey, projectSha256, ui})'],
         hostClose: ['csrfKey.fill(0);', 'await service.close();'],
         files: [
             { path: OPERATOR_FILE, content: serviceModule(directory), mode: 0o600 },
@@ -159,13 +169,78 @@ function hostModule(result) {
         '};',
     ].join('\n') + '\n';
 }
+async function readManifest(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Node's own `node_modules` lookup, reading manifests rather than loading anything. */
+async function installedVersion(name, from) {
+    let directory = resolve(from);
+    for (;;) {
+        const manifest = await readManifest(join(directory, 'node_modules', ...name.split('/'), 'package.json'));
+        if (manifest && manifest.name === name && typeof manifest.version === 'string')
+            return manifest.version;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return null;
+        directory = parent;
+    }
+}
+/**
+ * What a generated auth site depends on: this package at its exact version, plus each declared peer at the exact
+ * version installed beside it. A peer whose installation cannot be found is recorded as its declared range and
+ * reported, because a manifest with no dependencies at all -- what this initializer wrote before #212 -- tells the
+ * generated site nothing about the versions it was generated against. Nothing is installed here; running a package
+ * manager to produce a lockfile stays the operator's own explicit step.
+ */
+export async function dependencySpecifiers() {
+    const own = fileURLToPath(new URL('../package.json', import.meta.url));
+    const manifest = await readManifest(own);
+    if (!manifest || typeof manifest.name !== 'string' || typeof manifest.version !== 'string')
+        throw new Error(`Could not read this package's manifest at ${own}`);
+    const dependencies = { [manifest.name]: manifest.version };
+    const unpinned = [];
+    const peers = manifest.peerDependencies && typeof manifest.peerDependencies === 'object' ? manifest.peerDependencies : {};
+    for (const [name, range] of Object.entries(peers)) {
+        if (typeof range !== 'string')
+            continue;
+        const version = await installedVersion(name, dirname(own));
+        if (version)
+            dependencies[name] = version;
+        else {
+            dependencies[name] = range;
+            unpinned.push(name);
+        }
+    }
+    return { dependencies: Object.fromEntries(Object.entries(dependencies).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)), unpinned };
+}
 /** Creates a new private directory only; never merges or overwrites an existing project. */
 export async function initAuthentication(directory) {
     if (typeof directory !== 'string' || !directory || directory.includes('\0'))
         throw new Error('An output directory is required');
     const requested = resolve(directory), parent = await realpath(dirname(requested)), root = join(parent, basename(requested));
     const project = join(root, 'app'), hostFile = join(root, 'host.mjs');
-    const result = await scaffold({ directory: root, project, hostFile, names: ['auth'] });
+    const names = ['ui', 'auth'];
+    const kit = await uiScaffold({ directory: root, project, hostFile, names });
+    const auth = await scaffold({ directory: root, project, hostFile, names });
+    // ui first in both the YAML and the host: auth refuses to activate before the kit is active.
+    const result = {
+        ...auth,
+        extensions: { ...kit.extensions, ...auth.extensions },
+        routes: { ...kit.routes, ...auth.routes },
+        hostImports: [...kit.hostImports, ...auth.hostImports],
+        hostSetup: [...kit.hostSetup, ...auth.hostSetup],
+        hostEntries: [...kit.hostEntries, ...auth.hostEntries],
+        files: [...kit.files, ...auth.files],
+    };
+    // Resolved before the directory exists, so a manifest failure leaves nothing
+    // behind. `@jimhoyd/urlcode-ui` is a declared peer, so the kit this scaffold
+    // now emits is pinned by the same pass that pins auth itself.
+    const pins = await dependencySpecifiers();
     try {
         await mkdir(root, { mode: 0o700 });
     }
@@ -191,14 +266,16 @@ export async function initAuthentication(directory) {
         await write('app/urlcode.yaml', renderYaml({ version: '1', extensions: result.extensions, routes: result.routes }));
         await write('host.mjs', hostModule(result));
         await write('README.md', `# Auth project and operator host\n\n${result.readme}`);
-        await write('package.json', JSON.stringify({ name: 'urlcode-auth-site', private: true, type: 'module' }, null, 2) + '\n');
+        await write('package.json', JSON.stringify({ name: 'urlcode-auth-site', private: true, version: '0.0.0', type: 'module', dependencies: pins.dependencies }, null, 2) + '\n');
         await write('.gitignore', 'node_modules/\ndata/\n.env\n.env.*\n');
         for (const file of result.files) {
             if (file.path.includes('\0') || resolve(root, file.path) !== join(root, file.path) || relative(root, resolve(root, file.path)).startsWith('..'))
                 throw new Error('Invalid scaffold file path');
+            // Composed scaffolds contribute nested paths of their own (the kit's ui/copy and ui/templates).
+            await mkdir(dirname(join(root, file.path)), { recursive: true, mode: 0o700 });
             await write(file.path, file.content, file.mode);
         }
-        return { directory: root, project, hostFile, operatorFile: join(root, OPERATOR_FILE) };
+        return { directory: root, project, hostFile, operatorFile: join(root, OPERATOR_FILE), dependencies: pins.dependencies, unpinnedDependencies: pins.unpinned };
     }
     catch (error) {
         await rm(root, { recursive: true, force: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.1.0-alpha.6",
+  "version": "0.4.1",
   "type": "module",
   "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
   "license": "Apache-2.0",
@@ -52,8 +52,8 @@
     "otpauth": "9.5.2"
   },
   "peerDependencies": {
-    "@jimhoyd/urlcode": ">=0.4.0-alpha.2 <0.5.0",
-    "@jimhoyd/urlcode-ui": ">=0.1.0-alpha.1 <0.2.0"
+    "@jimhoyd/urlcode": ">=0.4.1 <0.5.0",
+    "@jimhoyd/urlcode-ui": ">=0.4.1 <0.5.0"
   },
   "bin": {
     "urlcode-auth": "./dist/cli.js"