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

package/IMPLEMENTATION-STATUS.md

@@ -1,6 +1,6 @@
 # Admin implementation status
 
-Status: `0.1.0-alpha.1`, the first npm alpha, published through the tag-driven release workflow after core `0.4.0-alpha.1`, ui `0.1.0-alpha.1` and auth `0.1.0-alpha.1` (core issue #78). The implemented admin workflows and reviewed shared-presentation work are merged to main. Production release validation remains separate. Cross-repository acceptance: https://github.com/jimhoyd-com/urlcode/issues/58. Core extension integration PR #59 is merged. Auth owns identities, sessions and transactional authority checks; this package owns the trusted administration interface.
+Status: `0.1.0-alpha.3`, published through the tag-driven release workflow after core `0.4.0-alpha.2`, ui `0.1.0-alpha.5` and auth `0.1.0-alpha.3`. It requires `@jimhoyd/urlcode` 0.4.0-alpha.2 or newer (`src/admin.ts` loads project hooks through `ExtensionActivation.root`) and `@jimhoyd/urlcode-ui` 0.1.0-alpha.5 or newer (whose hand-copied `ExtensionActivation` first carries `root`). It supersedes `0.1.0-alpha.2`, the first working npm alpha (`0.1.0-alpha.1` was blocked by npm's registry after an earlier out-of-band publish attempt and could never be used), and carries the work merged since — the trusted project-level lifecycle hooks and the `ExtensionActivation.root` fixture fixes for core 0.4.0-alpha.2 (core issue #78). The implemented admin workflows and reviewed shared-presentation work are merged to main. Production release validation remains separate. Cross-repository acceptance: https://github.com/jimhoyd-com/urlcode/issues/58. Core extension integration PR #59 is merged. Auth owns identities, sessions and transactional authority checks; this package owns the trusted administration interface.
 
 Implemented: scoped internal authorization; no impersonated admin access; fresh, reasoned mutations; account search, compound filters, sorting, stable live pagination, details, setup invitation and bounded export; audited full-email reveal; lock/unlock/role assignment; global and individual session revocation; role definitions; audit pagination; registration approval; dual-approval security cases with notes/closure; opt-in short-lived impersonation with required notice; shared safe presentation; auth/admin initialization with private operator storage.
 

package/README.md

@@ -13,7 +13,7 @@ npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth @jimhoyd/
 npx urlcode init my-site --with auth,admin
 ```
 
-`@jimhoyd/urlcode-admin` is published to npm as an alpha (`0.1.0-alpha.1`). Alpha releases can change exported names, the console's routes and the scaffold output between versions without a deprecation period; pin exact versions in an operator directory and read the release notes before upgrading. The package declares its peers by version range (`@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0`, `@jimhoyd/urlcode-ui` and `@jimhoyd/urlcode-auth >=0.1.0-alpha.1 <0.2.0`), so install all four together; npm resolves them from the registry. Every release is built by the tag-driven [release workflow](.github/workflows/release.yml), signed with a GitHub attestation and published through npm trusted publishing, so `gh attestation verify jimhoyd-urlcode-admin-<version>.tgz --repo jimhoyd-com/urlcode-admin` and `npm audit signatures` can check what you downloaded. Publishing is still not a security review, real-provider deployment evidence or an accessibility certification.
+`@jimhoyd/urlcode-admin` is published to npm as an alpha (`0.1.0-alpha.3`). Alpha releases can change exported names, the console's routes and the scaffold output between versions without a deprecation period; pin exact versions in an operator directory and read the release notes before upgrading. The package declares its peers by version range (`@jimhoyd/urlcode >=0.4.0-alpha.1 <0.5.0`, `@jimhoyd/urlcode-ui >=0.1.0-alpha.1 <0.2.0` and `@jimhoyd/urlcode-auth >=0.1.0-alpha.2 <0.2.0`), so install all four together; npm resolves them from the registry. Every release is built by the tag-driven [release workflow](.github/workflows/release.yml), signed with a GitHub attestation and published through npm trusted publishing, so `gh attestation verify jimhoyd-urlcode-admin-<version>.tgz --repo jimhoyd-com/urlcode-admin` and `npm audit signatures` can check what you downloaded. Publishing is still not a security review, real-provider deployment evidence or an accessibility certification.
 
 ## Build from reviewed local repositories
 
@@ -67,6 +67,34 @@ The snippet is an integration fragment; use the auth scaffold's private key/serv
 
 Administrative actions authenticate internally even without an extra route policy. Missing sessions or administrative permissions receive 404 at the console gate. Use operator role declarations with the actual permissions exported by this implementation: `auth.users.read`, `auth.users.reveal`, `auth.users.export`, `auth.users.manage`, `auth.users.create`, `auth.sessions.manage`, `auth.roles.read`, `auth.audit.read`, `auth.cases.read`, `auth.cases.manage`, and `auth.users.impersonate`. `*` grants full operator-defined administrator permissions. Do not copy the proposal's separate `admin.*` permission names and expect them to work automatically.
 
+## Project-level lifecycle hooks
+
+A project can name its own function to run at three admin lifecycle points, using the same `hooks` shape core documents for extensions generally (`docs/EXTENSIONS.md`, "Project-level lifecycle hooks", in [`urlcode`](https://github.com/jimhoyd-com/urlcode)) — a bare source path (default export), or an explicit `{source, export}`, resolved relative to the project root:
+
+```yaml
+extensions:
+  admin:
+    version: '1'
+    config:
+      hooks:
+        beforeRoleChange:
+          source: ./hooks/role-change.mjs
+        onRegistrationApproved:
+          source: ./hooks/registration-approved.mjs
+          export: onApproved
+        onAccountStatusChanged: ./hooks/account-status.mjs
+```
+
+| Hook | Fires | Input | Verdict |
+|---|---|---|---|
+| `beforeRoleChange` | Before an administrator's role change is applied (`/users/roles`) | `{accountId, currentRoles, requestedRoles, actorId, reason}` | `{allow: boolean, reason?: string}` — `allow: false` blocks the change before it reaches the auth service, and the request fails with 403 |
+| `onRegistrationApproved` | After a waitlisted registration request is approved (`/registrations/approve`) | `{requestId, accountId, email, actorId, reason}` | none (side effect only) |
+| `onAccountStatusChanged` | After an account is locked or unlocked (`/users/status`) | `{accountId, status: 'active' \| 'locked', actorId, reason}` | none (side effect only) |
+
+**Trust model: no special case.** These hooks are first-party project code and run trusted, in-process, exactly like the general trusted-by-default rule for `function`/`middleware` routes (`docs/SPIKE-DEFAULT-TRUST-MODEL.md` in `urlcode`). This package does not implement sandboxed hook execution yet — that needs a core dispatch primitive extensions do not have ([jimhoyd-com/urlcode#151](https://github.com/jimhoyd-com/urlcode/issues/151)). A hook that declares `sandbox: true` is rejected explicitly, during activation, with an error naming the hook — never silently run trusted and never ignored.
+
+A missing hook module, or a named export that is not a function, also fails activation (not the first request that would have used it). Registration approval, role assignment and lock/unlock cover the lifecycle points with existing, unambiguous admin actions today; registration rejection, session revocation, impersonation start/end and bulk actions have no hook yet and are tracked as follow-up work in [jimhoyd-com/urlcode-admin#32](https://github.com/jimhoyd-com/urlcode-admin/issues/32).
+
 ## Operating the console
 
 Bootstrap the first administrator through auth's operator CLI using JSON stdin. Writes require recent authentication and a reason; role/status/session changes run through the auth service's transactional authority checks. Roles themselves remain operator configuration. Masked lists, pagination, permission-filtered navigation and audit records help limit routine exposure.

package/dist/admin-hooks.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Project-level lifecycle hooks: the shape documented in core's
+ * docs/EXTENSIONS.md ("Project-level lifecycle hooks") — a `hooks` block in
+ * the extension's own `config` naming a project function per lifecycle
+ * point, using the same source shape `function`/`middleware` routes already
+ * use (a bare string, or `{source, export}`), resolved relative to
+ * `ExtensionActivation.root`.
+ *
+ * Trust model: these hooks are first-party project code and run trusted,
+ * in-process, exactly like the general trusted-by-default rule for
+ * `function`/`middleware` routes (docs/SPIKE-DEFAULT-TRUST-MODEL.md). This
+ * package does not implement sandboxed hook execution yet — that requires a
+ * core dispatch primitive extensions do not have (jimhoyd-com/urlcode#151).
+ * A hook that declares `sandbox: true` is rejected explicitly at activation
+ * time (see `loadAdminHooks` below); it is never silently run trusted.
+ */
+/** A hook reference: a bare source path (default export), or an explicit `{source, export}`. */
+export interface HookDefinition {
+    source: string;
+    export?: string;
+    sandbox?: boolean;
+}
+export type HookConfig = string | HookDefinition;
+export interface AdminHooksConfig {
+    /**
+     * Pre-action, veto-capable: called before an administrator's role change
+     * is applied. Returning `{allow: false}` blocks the change; the
+     * operation never reaches the auth service.
+     */
+    beforeRoleChange?: HookConfig;
+    /** Post-action, side-effect only: called after a registration request is approved. */
+    onRegistrationApproved?: HookConfig;
+    /** Post-action, side-effect only: called after an account is locked or unlocked. */
+    onAccountStatusChanged?: HookConfig;
+}
+export declare const adminHooksSchema: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly beforeRoleChange: {
+            readonly oneOf: readonly [{
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly source: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 1024;
+                    };
+                    readonly export: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                    };
+                    readonly sandbox: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly required: readonly ["source"];
+            }];
+        };
+        readonly onRegistrationApproved: {
+            readonly oneOf: readonly [{
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly source: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 1024;
+                    };
+                    readonly export: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                    };
+                    readonly sandbox: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly required: readonly ["source"];
+            }];
+        };
+        readonly onAccountStatusChanged: {
+            readonly oneOf: readonly [{
+                readonly type: "string";
+                readonly minLength: 1;
+                readonly maxLength: 1024;
+            }, {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly properties: {
+                    readonly source: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                        readonly maxLength: 1024;
+                    };
+                    readonly export: {
+                        readonly type: "string";
+                        readonly pattern: "^[A-Za-z_][A-Za-z0-9_]*$";
+                    };
+                    readonly sandbox: {
+                        readonly type: "boolean";
+                    };
+                };
+                readonly required: readonly ["source"];
+            }];
+        };
+    };
+};
+/** Typed verdict for a pre-action hook that can veto. */
+export interface HookVerdict {
+    allow: boolean;
+    reason?: string;
+}
+export interface RoleChangeInput {
+    accountId: string;
+    currentRoles: readonly string[];
+    requestedRoles: readonly string[];
+    actorId: string;
+    reason: string;
+}
+export interface RegistrationApprovedInput {
+    requestId: string;
+    accountId: string;
+    email: string;
+    actorId: string;
+    reason: string;
+}
+export interface AccountStatusChangedInput {
+    accountId: string;
+    status: 'active' | 'locked';
+    actorId: string;
+    reason: string;
+}
+export interface LoadedAdminHooks {
+    beforeRoleChange?: (input: RoleChangeInput) => HookVerdict | Promise<HookVerdict>;
+    onRegistrationApproved?: (input: RegistrationApprovedInput) => void | Promise<void>;
+    onAccountStatusChanged?: (input: AccountStatusChangedInput) => void | Promise<void>;
+}
+/**
+ * Resolves and imports every declared hook module against `root`
+ * (`ExtensionActivation.root`), trusted and in-process. Fails fast: a
+ * missing module, a missing/non-function export, or `sandbox: true` throws
+ * here, during activation, so a broken or unsupported hook never reaches a
+ * live request.
+ */
+export declare function loadAdminHooks(config: Readonly<Record<string, unknown>>, root: string): Promise<LoadedAdminHooks>;

package/dist/admin-hooks.js

@@ -0,0 +1,69 @@
+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;
+};
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** JSON Schema fragment for the `hooks` block, merged into the extension's own config schema. */
+const hookDefinitionSchema = {
+    oneOf: [
+        { type: 'string', minLength: 1, maxLength: 1024 },
+        {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+                source: { type: 'string', minLength: 1, maxLength: 1024 },
+                export: { type: 'string', pattern: '^[A-Za-z_][A-Za-z0-9_]*$' },
+                sandbox: { type: 'boolean' },
+            },
+            required: ['source'],
+        },
+    ],
+};
+export const adminHooksSchema = {
+    type: 'object',
+    additionalProperties: false,
+    properties: {
+        beforeRoleChange: hookDefinitionSchema,
+        onRegistrationApproved: hookDefinitionSchema,
+        onAccountStatusChanged: hookDefinitionSchema,
+    },
+};
+const HOOK_NAMES = ['beforeRoleChange', 'onRegistrationApproved', 'onAccountStatusChanged'];
+/**
+ * Resolves and imports every declared hook module against `root`
+ * (`ExtensionActivation.root`), trusted and in-process. Fails fast: a
+ * missing module, a missing/non-function export, or `sandbox: true` throws
+ * here, during activation, so a broken or unsupported hook never reaches a
+ * live request.
+ */
+export async function loadAdminHooks(config, root) {
+    const hooks = (config.hooks ?? {});
+    const loaded = {};
+    for (const name of HOOK_NAMES) {
+        const raw = hooks[name];
+        if (raw === undefined)
+            continue;
+        const definition = typeof raw === 'string' ? { source: raw } : raw;
+        if (definition.sandbox === true)
+            throw new Error(`hook ${name}: sandbox: true is not yet supported for project-level hooks, see jimhoyd-com/urlcode-admin#32`);
+        const exportName = definition.export || 'default';
+        const modulePath = resolve(root, definition.source);
+        let mod;
+        try {
+            mod = await import(__rewriteRelativeImportExtension(pathToFileURL(modulePath).href));
+        }
+        catch (error) {
+            throw new Error(`hook ${name}: failed to load module "${definition.source}": ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const fn = mod[exportName];
+        if (typeof fn !== 'function')
+            throw new Error(`hook ${name}: export "${exportName}" of "${definition.source}" is not a function`);
+        loaded[name] = fn;
+    }
+    return loaded;
+}

package/dist/admin.js

@@ -12,17 +12,21 @@ import { exportAuditRange } from "./admin-audit-export.js";
 import { createHealthReader } from "./admin-health.js";
 import { maskEmail, sessionFilters, userFilters, userFilterKeys, auditFilters, selectedNames, selectedAccounts, usersCsv } from "./admin-reporting.js";
 import { AuthHttp, AuthHttpError, formField as baseField, jsonResponse, readFields, wantsJson, hasPermission } from '@jimhoyd/urlcode-auth';
+import { adminHooksSchema, loadAdminHooks } from "./admin-hooks.js";
 const defaultPresentation = createAdminPresentation();
-const schema = { type: 'object', additionalProperties: false, properties: {} };
+const schema = { type: 'object', additionalProperties: false, properties: { hooks: adminHooksSchema } };
 const permissions = ['auth.users.reveal', 'auth.audit.export', 'auth.health.read', 'auth.cases.read', 'auth.cases.manage', 'auth.users.impersonate', 'auth.users.export', 'auth.users.create', 'auth.users.read', 'auth.users.manage', 'auth.audit.read', 'auth.sessions.manage', 'auth.roles.read'];
 export function adminExtension(options) {
     const authMount = options.authMount || '/account';
     if (!/^\/[A-Za-z0-9/_-]*$/.test(authMount) || authMount.includes('//'))
         throw new Error('Invalid auth mount');
     return { name: 'admin', version: '1', projectSha256: options.projectSha256, targets: ['node'], schema, credentialHeaders: ['cookie', 'authorization', 'x-csrf-token'],
-        activate(_config, context) {
+        async activate(config, context) {
             if (context.mounts.length !== 1)
                 throw new Error('Admin requires exactly one mount');
+            // Fails fast during activation: a missing/broken hook module or an
+            // unsupported `sandbox: true` throws here, never on first request.
+            const hooks = await loadAdminHooks(config, context.root);
             const readHealth = options.health ? createHealthReader(options.health) : undefined;
             const mount = context.mounts[0], http = new AuthHttp({ origin: context.origin, csrfKey: options.csrfKey }), service = options.service;
             const accounts = createAdminAccount({ service, ...(options.sendAccountAdministration ? { sendAccountAdministration: options.sendAccountAdministration } : {}) }, http, mount);
@@ -268,7 +272,9 @@ export function adminExtension(options) {
                         }
                         else if (path === '/registrations/approve') {
                             requirePermission(principal, 'auth.users.manage');
-                            await service.approveRegistration({ actorToken: token, requestId: fields.requestId || '', reason: fields.reason });
+                            const approved = await service.approveRegistration({ actorToken: token, requestId: fields.requestId || '', reason: fields.reason });
+                            if (hooks.onRegistrationApproved)
+                                await hooks.onRegistrationApproved({ requestId: fields.requestId || '', accountId: approved.id, email: approved.email, actorId: principal.id, reason: fields.reason || '' });
                         }
                         else if (path === '/invitations') {
                             requirePermission(principal, 'auth.users.create');
@@ -280,13 +286,22 @@ export function adminExtension(options) {
                         else if (path === '/users/roles') {
                             requirePermission(principal, 'auth.users.manage');
                             const roles = (fields.roles || '').split(',').map(role => role.trim()).filter(Boolean);
-                            await service.adminSetRoles({ actorToken: token, accountId: fields.accountId || '', roles, reason: fields.reason });
+                            const accountId = fields.accountId || '';
+                            if (hooks.beforeRoleChange) {
+                                const current = await service.getUser(accountId);
+                                const verdict = await hooks.beforeRoleChange({ accountId, currentRoles: current?.roles ?? [], requestedRoles: roles, actorId: principal.id, reason: fields.reason || '' });
+                                if (!verdict?.allow)
+                                    throw new AuthHttpError(403, verdict?.reason || 'Role change rejected by project hook');
+                            }
+                            await service.adminSetRoles({ actorToken: token, accountId, roles, reason: fields.reason });
                         }
                         else if (path === '/users/status') {
                             requirePermission(principal, 'auth.users.manage');
                             if (fields.status !== 'active' && fields.status !== 'locked')
                                 throw new AuthHttpError(400, 'Invalid status');
                             await service.adminSetStatus({ actorToken: token, accountId: fields.accountId || '', status: fields.status, reason: fields.reason });
+                            if (hooks.onAccountStatusChanged)
+                                await hooks.onAccountStatusChanged({ accountId: fields.accountId || '', status: fields.status, actorId: principal.id, reason: fields.reason || '' });
                         }
                         else if (path === '/sessions/revoke') {
                             requirePermission(principal, 'auth.sessions.manage');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode-admin",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.3",
   "type": "module",
   "description": "Administration console extension for URLCode, on top of the auth extension",
   "repository": {
@@ -42,9 +42,9 @@
     "typescript": "6.0.3"
   },
   "peerDependencies": {
-    "@jimhoyd/urlcode": ">=0.4.0-alpha.1 <0.5.0",
+    "@jimhoyd/urlcode": ">=0.4.0-alpha.2 <0.5.0",
     "@jimhoyd/urlcode-auth": ">=0.1.0-alpha.2 <0.2.0",
-    "@jimhoyd/urlcode-ui": ">=0.1.0-alpha.1 <0.2.0"
+    "@jimhoyd/urlcode-ui": ">=0.1.0-alpha.5 <0.2.0"
   },
   "bin": {
     "urlcode-admin": "./dist/cli.js"