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

package/IMPLEMENTATION-STATUS.md

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

package/README.md

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

package/SECURITY.md

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

package/THREAT-MODEL.md

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

package/dist/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.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);
@@ -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') {
@@ -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/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,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "type": "module",
   "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
     "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": {