@jimhoyd/urlcode-auth 0.4.1 → 0.4.2

package/IMPLEMENTATION-STATUS.md

@@ -22,7 +22,7 @@ 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 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 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.
+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. Core's extension-hook primitive resolves and imports them eagerly, exposes their typed contracts through extension inspection, and rejects `sandbox: true` under the trusted-only v1 hook contract. `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
 

package/README.md

@@ -137,14 +137,10 @@ 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. 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.
+Core's extension-hook primitive loads these hooks and publishes their contracts
+through `get_extensions`. Contract v1 is trusted-only: `sandbox: true` is
+refused explicitly at activation. Declare a hook without `sandbox` (or with
+`sandbox: false`) to use it.
 
 ## Authentication and presentation
 

package/dist/auth.js

@@ -7,7 +7,7 @@ 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, readFields, screenResponse, wantsJson, passkeyScript, secondFactorButton } from "./auth-ui.js";
-import { hooksConfigSchema, loadLifecycleHooks } from "./lifecycle-hooks.js";
+import { authHookContracts, hooksConfigSchema, loadLifecycleHooks } from "./lifecycle-hooks.js";
 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 } };
@@ -16,7 +16,7 @@ const actionIcons = { identify: 'arrow-right', login: 'arrow-right', 'step-up':
 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'],
+    return { name: 'auth', version: '1', projectSha256: options.projectSha256, targets: ['node'], schema, policySchema, hooks: authHookContracts, credentialHeaders: ['cookie', 'authorization', 'x-csrf-token'],
         async activate(config, context) {
             if (context.mounts.length !== 1)
                 throw new Error('Auth requires exactly one mount');

package/dist/lifecycle-hooks.d.ts

@@ -1,9 +1,5 @@
-export interface HookReference {
-    source: string;
-    export?: string;
-    sandbox?: boolean;
-}
-export type HookConfig = string | HookReference;
+import type { ExtensionHookConfig } from '@jimhoyd/urlcode/extensions';
+export type HookConfig = ExtensionHookConfig;
 export interface LifecycleHooksConfig {
     beforeRegister?: HookConfig;
     onSignUp?: HookConfig;
@@ -30,42 +26,72 @@ export interface LifecycleHooks {
     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;
-            })[];
+export declare const authHookContracts: readonly [{
+    readonly name: "beforeRegister";
+    readonly kind: "filter";
+    readonly description: "Runs before account creation and may return an allow/deny verdict.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["email"];
+        readonly properties: {
+            readonly email: {
+                readonly type: "string";
+            };
+            readonly profile: {
+                readonly type: "object";
+            };
+        };
+    };
+    readonly outputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["allow"];
+        readonly properties: {
+            readonly allow: {
+                readonly type: "boolean";
+            };
+            readonly reason: {
+                readonly type: "string";
+            };
+        };
+    };
+}, {
+    readonly name: "onSignUp";
+    readonly kind: "action";
+    readonly description: "Runs after a new account is created.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["accountId", "email"];
+        readonly properties: {
+            readonly accountId: {
+                readonly type: "string";
+            };
+            readonly email: {
+                readonly type: "string";
+            };
+        };
+    };
+}, {
+    readonly name: "onDelete";
+    readonly kind: "action";
+    readonly description: "Runs after an account owner schedules deletion.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly additionalProperties: false;
+        readonly required: readonly ["accountId", "email"];
+        readonly properties: {
+            readonly accountId: {
+                readonly type: "string";
+            };
+            readonly email: {
+                readonly type: "string";
+            };
         };
     };
-};
+}];
+export declare const hooksConfigSchema: object;
 /**
  * Resolves and eagerly imports every declared hook, so a missing module, a
  * syntax error or a missing export fails activation (fail-fast), never the

package/dist/lifecycle-hooks.js

@@ -1,11 +1,3 @@
-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`
@@ -14,14 +6,9 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // (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 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.
+// Core's shared extension-hook primitive owns resolution, import and
+// discovery. Contract v1 is trusted-only; `sandbox: true` is rejected at
+// activation and never silently run trusted.
 //
 // Each activation re-imports the hook's ENTRY module under a fresh
 // cache-busting query, mirroring core's trusted route activation
@@ -32,58 +19,13 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // 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';
-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;
-}
+import { extensionHooksSchema, loadExtensionHooks } from '@jimhoyd/urlcode/extensions';
+export const authHookContracts = [
+    { name: 'beforeRegister', kind: 'filter', description: 'Runs before account creation and may return an allow/deny verdict.', inputSchema: { type: 'object', additionalProperties: false, required: ['email'], properties: { email: { type: 'string' }, profile: { type: 'object' } } }, outputSchema: { type: 'object', additionalProperties: false, required: ['allow'], properties: { allow: { type: 'boolean' }, reason: { type: 'string' } } } },
+    { name: 'onSignUp', kind: 'action', description: 'Runs after a new account is created.', inputSchema: { type: 'object', additionalProperties: false, required: ['accountId', 'email'], properties: { accountId: { type: 'string' }, email: { type: 'string' } } } },
+    { name: 'onDelete', kind: 'action', description: 'Runs after an account owner schedules deletion.', inputSchema: { type: 'object', additionalProperties: false, required: ['accountId', 'email'], properties: { accountId: { type: 'string' }, email: { type: 'string' } } } },
+];
+export const hooksConfigSchema = extensionHooksSchema(authHookContracts);
 /**
  * Resolves and eagerly imports every declared hook, so a missing module, a
  * syntax error or a missing export fails activation (fail-fast), never the
@@ -92,32 +34,5 @@ async function projectFile(root, file, hookName) {
  * trusted.
  */
 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; 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 + '?urlcode-hook-epoch=' + epoch)));
-        }
-        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;
+    return await loadExtensionHooks(config, authHookContracts, { root });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "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.1 <0.5.0",
-    "@jimhoyd/urlcode-ui": ">=0.4.1 <0.5.0"
+    "@jimhoyd/urlcode": ">=0.4.2 <0.5.0",
+    "@jimhoyd/urlcode-ui": ">=0.4.2 <0.5.0"
   },
   "bin": {
     "urlcode-auth": "./dist/cli.js"