@jimhoyd/urlcode-auth 0.4.2 → 0.4.6

package/README.md

@@ -8,7 +8,12 @@ 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 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.
+The npm `latest` tag identifies auth's stable package version; `alpha` is the
+separate prerelease channel. Install the three packages together and pin the
+resolved versions. The peer ranges for `@jimhoyd/urlcode` and
+`@jimhoyd/urlcode-ui` are declared in `package.json`, while each release created
+by the current publisher shows the exact stack tested together and attaches its
+signed `train.json` receipt.
 
 ```sh
 npm install @jimhoyd/urlcode @jimhoyd/urlcode-ui @jimhoyd/urlcode-auth
@@ -17,7 +22,12 @@ npx urlcode init my-site --with ui,auth
 
 `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.
+Stable publication does not establish production readiness: independent
+security review, accessibility assessment, broader browser/device WebAuthn
+coverage and deployment/soak/recovery exercises remain pending (see
+[IMPLEMENTATION-STATUS.md](IMPLEMENTATION-STATUS.md)). Prerelease versions may
+change public exports, configuration keys and the SQLite schema without a
+migration path; do not run the `alpha` channel 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.
 
@@ -156,7 +166,22 @@ An operator can configure `checkPassword: createPasswordBreachChecker()` on `cre
 
 ## Email and local development
 
-`createSesSender({region, from, origin, authMount, credentials?})` returns a callable token sender with `sendEmailCode`, `notify` and `close`. Wire callbacks explicitly into the auth/admin factories. Production credentials come from operator configuration or the SDK credential chain; never put them in YAML. Delivery is bounded and cancellable; services cannot guarantee that an email reaches an inbox.
+SES is optional so an auth installation that uses another delivery adapter does
+not install the AWS SDK and its provider chain. Install it explicitly before
+using the built-in sender:
+
+```sh
+npm install --save-exact @aws-sdk/client-sesv2@3.1135.0
+```
+
+`createSesSender({region, from, origin, authMount, credentials?})` then returns a
+callable token sender with `sendEmailCode`, `notify` and `close`. Without the
+optional SDK it fails immediately with an installation instruction. Wire
+callbacks explicitly into the auth/admin factories. Production credentials
+come from operator configuration or the SDK credential chain; never put them
+in YAML. Delivery is bounded and cancellable; services cannot guarantee that
+an email reaches an inbox. A test-only `transport` injection does not load the
+SDK.
 
 `createDevelopmentSender` requires `allowDevelopment: true` and either a private output directory outside the project plus its `projectRoot`, or `allowConsoleTokens: true`. File notices use exclusive `0600` files and a bounded count. Console mode deliberately exposes development tokens and must never feed shared production logs. Sender helpers do not infer safety from `NODE_ENV`.
 
@@ -210,6 +235,14 @@ Migration preserves accounts, enrolled credentials and history, while revoking s
 
 ## Presentation
 
+Auth is one part of the product, while this package retains ownership of
+identity, sessions, CSRF, validation and recovery behavior. Its extension
+registration publishes a machine-readable `authoring` contract through
+`urlcode extensions --host-file ... --json` and MCP `get_extensions`. Follow
+those configuration, copy, template and lifecycle-hook surfaces before copying
+an auth screen or flow into the project. The contract also lists focused checks
+for the edit loop; full project tests remain the handoff evidence.
+
 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` 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.

package/dist/auth-store.d.ts

@@ -85,7 +85,7 @@ export interface AuthStore {
  * 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;
+export declare function startupPhase(onlineMs: number | undefined, elapsedMs: number, stage?: string): 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

package/dist/auth-store.js

@@ -24,10 +24,10 @@ const startupCodes = ['auth_configuration_changed', 'configuration_approval_mism
  * diagnosable from the failure alone. `onlineMs` is undefined when the worker
  * thread never began executing JavaScript.
  */
-export function startupPhase(onlineMs, elapsedMs) {
+export function startupPhase(onlineMs, elapsedMs, stage) {
     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`;
+        : `worker thread began executing after ${onlineMs}ms, then did not report readiness for a further ${elapsedMs - onlineMs}ms${stage ? ` (last startup stage reached: ${stage})` : ' (no startup stage reached: the database open itself had not returned)'}`;
 }
 /**
  * Resolves once the worker reports readiness, and otherwise rejects with what it
@@ -37,12 +37,17 @@ export function startupPhase(onlineMs, elapsedMs) {
  */
 export function awaitStoreStartup(worker, boundMs) {
     const started = performance.now(), elapsed = () => Math.round(performance.now() - started);
-    let onlineMs;
+    let onlineMs, stage;
     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) => {
+        const timer = setTimeout(() => { worker.removeAllListeners('message'); reject(unavailable(startupPhase(onlineMs, elapsed(), stage))); }, boundMs);
+        worker.on('message', function report(message) {
+            if (message.stage) {
+                stage = message.stage;
+                return;
+            }
+            worker.off('message', report);
             clearTimeout(timer);
             if (message.ready)
                 accept();
@@ -288,12 +293,14 @@ if (!isMainThread && workerData?.authStore) {
     };
     try {
         db = new DatabaseSync(options.database, { allowExtension: false });
+        port.postMessage({ stage: 'database opened' });
         db.exec('PRAGMA busy_timeout=1000; PRAGMA foreign_keys=ON; PRAGMA trusted_schema=OFF;');
         const version = db.prepare('PRAGMA user_version').get()?.user_version, application = db.prepare('PRAGMA application_id').get()?.application_id;
         const empty = db.prepare("SELECT count(*) AS n FROM sqlite_master WHERE type='table'").get()?.n === 0;
         if (!(version === 1 && application === 1430345032) && !(version === 0 && application === 0 && empty))
             error(503, 'unsupported_auth_database');
         db.exec('PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;');
+        port.postMessage({ stage: 'journal mode set' });
         if (empty)
             transaction(() => {
                 db.exec(`CREATE TABLE auth_meta(key TEXT PRIMARY KEY,value TEXT NOT NULL);

package/dist/auth-templates.js

@@ -13,8 +13,8 @@ const declare = (name, body) => `{{!-- viewModel: auth/${name}@1 --}}${body}`;
 const link = '<a href="{{href href}}">{{label}}</a>';
 const screens = {
     'sign-in': {
-        body: `{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}{{form}}{{passkey}}{{providers}}<nav class="ui-link-list" aria-label="{{linksLabel}}">{{#each links}}${link}{{/each}}</nav>`,
-        sample: { intro: '', form: m('<form method="post"></form>'), passkey: m(''), providers: m(''), linksLabel: 'Sign-in methods', links: [{ href: '/account/register', label: 'Create account' }] },
+        body: `{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}<div class="ui-auth-primary">{{form}}</div>{{#if passkey}}<div class="ui-field-separator" data-slot="field-separator"><span>{{alternativeLabel}}</span></div>{{else}}{{#if providers}}<div class="ui-field-separator" data-slot="field-separator"><span>{{alternativeLabel}}</span></div>{{/if}}{{/if}}<div class="ui-auth-alternatives">{{passkey}}{{providers}}</div><nav class="ui-link-list" aria-label="{{linksLabel}}">{{#each links}}${link}{{/each}}</nav>`,
+        sample: { intro: 'Enter your email to continue to your account.', form: m('<form method="post"></form>'), alternativeLabel: 'Or continue with', passkey: m(''), providers: m('<form method="post"><button type="submit">Continue with Example</button></form>'), linksLabel: 'Sign-in methods', links: [{ href: '/account/register', label: 'Create account' }] },
     },
     password: {
         body: `{{#if failed}}<p class="error" role="alert">{{failed}}</p>{{/if}}{{#if intro}}<p class="ui-intro">{{intro}}</p>{{/if}}<div class="ui-selected-identity"><span class="ui-identifier">{{email}}</span><a href="{{href changeHref}}">{{changeLabel}}</a></div>{{form}}`,

package/dist/auth.d.ts

@@ -45,5 +45,34 @@ export interface AuthExtensionOptions {
     }) => Promise<void>;
 }
 export declare function hasPermission(principal: AuthPrincipal, permission: string): boolean;
+export declare const authAuthoring: Readonly<{
+    description: "Auth is part of the application, while this package keeps ownership of identity, session, CSRF and recovery behavior. Customize its project configuration and UI surfaces before replacing package behavior.";
+    surfaces: readonly ({
+        kind: "configuration";
+        name: string;
+        description: string;
+        path: string;
+        command?: never;
+    } | {
+        kind: "copy";
+        name: string;
+        description: string;
+        path: string;
+        command?: never;
+    } | {
+        kind: "template";
+        name: string;
+        description: string;
+        path: string;
+        command: string;
+    } | {
+        kind: "hook";
+        name: string;
+        description: string;
+        path: string;
+        command?: never;
+    })[];
+    fastChecks: readonly string[];
+}>;
 export declare function authExtension(options: AuthExtensionOptions): RuntimeExtension;
 export type { AuthUser };

package/dist/auth.js

@@ -13,10 +13,20 @@ export function hasPermission(principal, permission) { return !enrollmentRequire
 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' };
+export const authAuthoring = Object.freeze({
+    description: 'Auth is part of the application, while this package keeps ownership of identity, session, CSRF and recovery behavior. Customize its project configuration and UI surfaces before replacing package behavior.',
+    surfaces: Object.freeze([
+        { kind: 'configuration', name: 'registration', description: 'Select the supported registration mode in extensions.auth.config.registration.', path: 'urlcode.yaml#extensions.auth.config.registration' },
+        { kind: 'copy', name: 'account copy', description: 'Change account-screen wording through the UI catalogue.', path: 'ui/copy/<locale>.json' },
+        { kind: 'template', name: 'account screens', description: 'Override one auth/* screen when its structure must change; keep form actions and security behavior package-owned.', path: 'ui/templates/auth/<screen>.html', command: 'urlcode-ui list --project . --extensions @jimhoyd/urlcode-auth' },
+        { kind: 'hook', name: 'registration lifecycle', description: 'Use the declared beforeRegister, onSignUp and onDelete hooks for application behavior at supported lifecycle points.', path: 'extensions.auth.config.hooks' },
+    ]),
+    fastChecks: Object.freeze(['urlcode-ui doctor --project . --extensions @jimhoyd/urlcode-auth --copy ui/copy --templates ui/templates --stylesheet ui/extra.css', 'urlcode validate --local', 'urlcode test']),
+});
 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, hooks: authHookContracts, credentialHeaders: ['cookie', 'authorization', 'x-csrf-token'],
+    return { name: 'auth', version: '1', projectSha256: options.projectSha256, targets: ['node'], schema, policySchema, hooks: authHookContracts, authoring: authAuthoring, credentialHeaders: ['cookie', 'authorization', 'x-csrf-token'],
         async activate(config, context) {
             if (context.mounts.length !== 1)
                 throw new Error('Auth requires exactly one mount');
@@ -234,7 +244,7 @@ export function authExtension(options) {
                             if (path === '/csrf')
                                 return jsonResponse(200, { csrf }, headers);
                             if (path === '/' || path === '/login')
-                                return screen('Sign in', 'sign-in', { intro: '', form: m(form(mount + '/identify', csrf, formField('email', 'Email address', 'email', 'username'), 'Continue')), passkey: m(passkeyLogin(csrf)), providers: m(flows.buttons(csrf, false, text, presentation.locale, presentation)), linksLabel: text('Sign-in methods'), links: [...(registrationMode !== 'off' ? [{ href: mount + '/register', label: presentation.text('action.register') }] : []), ...(factorRecovery.enabled() ? [{ href: mount + '/recover-factor', label: presentation.text('recovery.lost') }] : []), ...(options.sendToken ? [{ href: mount + '/forgot-password', label: presentation.text('nav.forgotPassword') }] : []), ...(options.sendEmailCode ? [{ href: mount + '/email-code', label: presentation.text('copy.emailSignIn') }] : [])] }, 200, headers, options.passkeys ? mount + '/assets/passkeys.js' : undefined);
+                                return screen('Sign in', 'sign-in', { intro: presentation.text('ux.signInIntro'), form: m(form(mount + '/identify', csrf, formField('email', 'Email address', 'email', 'username'), 'Continue')), alternativeLabel: presentation.text('ux.orContinueWith'), passkey: m(passkeyLogin(csrf)), providers: m(flows.buttons(csrf, false, text, presentation.locale, presentation)), linksLabel: text('Sign-in methods'), links: [...(registrationMode !== 'off' ? [{ href: mount + '/register', label: presentation.text('action.register') }] : []), ...(factorRecovery.enabled() ? [{ href: mount + '/recover-factor', label: presentation.text('recovery.lost') }] : []), ...(options.sendToken ? [{ href: mount + '/forgot-password', label: presentation.text('nav.forgotPassword') }] : []), ...(options.sendEmailCode ? [{ href: mount + '/email-code', label: presentation.text('copy.emailSignIn') }] : [])] }, 200, headers, options.passkeys ? mount + '/assets/passkeys.js' : undefined);
                             if (path === '/register') {
                                 const invitations = request.query.getAll('token');
                                 if (invitations.length > 1 || invitations.some(token => token.length > 512))

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { createAuthService, AuthError } from './auth-core.ts';
 export type { AuthService, AuthPrincipal, AuthUser } from './auth-core.ts';
-export { authExtension, hasPermission } from './auth.ts';
+export { authExtension, authAuthoring, 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, readFields, screenResponse, wantsJson } from './auth-ui.ts';
@@ -22,7 +22,7 @@ export type { BackupOptions, BackupResult, RestoreOptions } from './backup.ts';
 export type { AuthOptions, AuthSessionResult, AuthSession, AuthAuditEvent, AuthCase } from './auth-core.ts';
 export { initAuthentication, scaffold } from './scaffold.ts';
 export type { AuthenticationScaffold, ScaffoldRequest, ScaffoldResult, ScaffoldFile } from './scaffold.ts';
-export type { EmailSender, TokenSender, TokenMessage, EmailCodeMessage, FactorRecoveryMessage, SignupCodeMessage, SecurityNotice, SesSenderOptions, DevelopmentSenderOptions } from './senders.ts';
+export type { EmailSender, TokenSender, TokenMessage, EmailCodeMessage, FactorRecoveryMessage, SignupCodeMessage, SecurityNotice, SesSenderOptions, SesCredentials, SesEmailInput, SesEmailCommand, DevelopmentSenderOptions } from './senders.ts';
 export { createPasswordBreachChecker } from './password-policy.ts';
 export type { PasswordBreachOptions } from './password-policy.ts';
 export type { AuthDailyMetric, AuthHookStats, AuthLifecycleEvent, AuthCredentials, AuthSecondFactor, AuthDevice, AuthPasskey, AuthProof, ExternalAuthProof, PasskeyAuthProof, SignupBinding, SignupState, SignupStart } from './auth-core.ts';

package/dist/index.js

@@ -1,5 +1,5 @@
 export { createAuthService, AuthError } from "./auth-core.js";
-export { authExtension, hasPermission } from "./auth.js";
+export { authExtension, authAuthoring, hasPermission } from "./auth.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";

package/dist/presentation.js

@@ -415,6 +415,8 @@ export const englishCatalogue = Object.freeze({
     "ux.twoStepHelp": "If your account uses two-step verification, enter an authenticator code or a recovery code. Otherwise, leave this section closed.",
     "ux.change": "Change",
     "ux.passwordIntro": "Enter the password for this account.",
+    "ux.signInIntro": "Enter your email to continue to your account.",
+    "ux.orContinueWith": "Or continue with",
     "ux.resetIntro": "Enter your account email. If it is eligible, we will send a password reset link.",
     "ux.resetSent": "If this account is eligible, a reset message will be sent. Check your inbox and spam folder, then follow the link to choose a new password.",
     "ux.backSignIn": "Back to sign in",

package/dist/scaffold.d.ts

@@ -26,6 +26,11 @@ export interface ScaffoldFile {
 }
 export interface ScaffoldResult {
     name: string;
+    /** Composition contract: capabilities offered, extensions or capabilities required (and ordered before), ordered-after-if-present, and refused together. */
+    provides?: string[];
+    requires?: string[];
+    after?: string[];
+    conflicts?: string[];
     extensions: Record<string, unknown>;
     routes: Record<string, unknown>;
     hostImports: string[];

package/dist/scaffold.js

@@ -83,18 +83,18 @@ 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.
+    // Every account screen renders through the kit. Core orders the host and urlcode.yaml from `requires` below, so
+    // the spelling of --with does not matter, but the ui extension has to be part of the set.
     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');
+        throw new Error('auth requires the ui extension, which is not part of this composition; add ui to --with');
     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);
     const operator = shellReference(directory, join(directory, OPERATOR_FILE)), projectPath = shellReference(directory, project), host = shellReference(directory, hostFile);
     return {
         name: 'auth',
+        requires: ['ui.kit'],
+        provides: ['auth.service'],
         extensions: { auth: { version: '1', config: { registration: 'off' } } },
         routes: {
             '/account/*': { extension: 'auth', methods: ['GET', 'HEAD', 'POST'] },
@@ -205,9 +205,13 @@ export async function dependencySpecifiers() {
     const dependencies = { [manifest.name]: manifest.version };
     const unpinned = [];
     const peers = manifest.peerDependencies && typeof manifest.peerDependencies === 'object' ? manifest.peerDependencies : {};
+    const meta = manifest.peerDependenciesMeta && typeof manifest.peerDependenciesMeta === 'object' ? manifest.peerDependenciesMeta : {};
     for (const [name, range] of Object.entries(peers)) {
         if (typeof range !== 'string')
             continue;
+        const detail = meta[name];
+        if (detail && typeof detail === 'object' && detail.optional === true)
+            continue;
         const version = await installedVersion(name, dirname(own));
         if (version)
             dependencies[name] = version;
@@ -227,7 +231,7 @@ export async function initAuthentication(directory) {
     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.
+    // ui first in both the YAML and the host (auth declares requires: ui.kit): auth refuses to activate before the kit is active.
     const result = {
         ...auth,
         extensions: { ...kit.extensions, ...auth.extensions },

package/dist/senders.d.ts

@@ -1,8 +1,6 @@
 import type { AdminAccountDelivery } from './admin-account-operations.ts';
 import type { EmailCopy } from './email-copy.ts';
 import type { ManualRecoveryDelivery } from './manual-recovery.ts';
-import { SendEmailCommand } from '@aws-sdk/client-sesv2';
-import type { SESv2ClientConfig } from '@aws-sdk/client-sesv2';
 export interface TokenMessage {
     email: string;
     token: string;
@@ -60,12 +58,40 @@ interface SenderLocation {
 export interface SesSenderOptions extends SenderLocation {
     region: string;
     from: string;
-    credentials?: SESv2ClientConfig['credentials'];
+    credentials?: SesCredentials | (() => Promise<SesCredentials>);
     /** Trusted injection for tests; production uses the AWS SDK with bounded retries. */
-    transport?: (command: SendEmailCommand, options: {
+    transport?: (command: SesEmailCommand, options: {
         abortSignal: AbortSignal;
     }) => Promise<unknown>;
 }
+export interface SesCredentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SesEmailInput {
+    FromEmailAddress: string;
+    Destination: {
+        ToAddresses: string[];
+    };
+    Content: {
+        Simple: {
+            Subject: {
+                Data: string;
+                Charset: 'UTF-8';
+            };
+            Body: {
+                Text: {
+                    Data: string;
+                    Charset: 'UTF-8';
+                };
+            };
+        };
+    };
+}
+export interface SesEmailCommand {
+    input: SesEmailInput;
+}
 export declare function createSesSender(options: SesSenderOptions): EmailSender;
 export type DevelopmentSenderOptions = SenderLocation & {
     allowDevelopment: true;

package/dist/senders.js

@@ -1,5 +1,5 @@
 import { createEmailCopy } from "./email-copy.js";
-import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';
+import { createRequire } from 'node:module';
 import { randomUUID } from 'node:crypto';
 import { open, realpath, stat, readdir } from 'node:fs/promises';
 import { join, relative, isAbsolute } from 'node:path';
@@ -96,12 +96,25 @@ function sender(where, deliver, cleanup = () => { }) {
     });
     return result;
 }
+function loadSes() {
+    try {
+        return createRequire(import.meta.url)('@aws-sdk/client-sesv2');
+    }
+    catch {
+        throw new Error('SES delivery requires the optional @aws-sdk/client-sesv2 package');
+    }
+}
 export function createSesSender(options) {
     const where = location(options), from = normalizeEmail(options.from);
     if (!/^[a-z]{2}(?:-[a-z]+)+-\d$/.test(options.region))
         throw new Error('Invalid SES region');
-    const client = options.transport ? undefined : new SESv2Client({ region: options.region, maxAttempts: 2, ...(options.credentials ? { credentials: options.credentials } : {}) });
-    return sender(where, async (message, signal) => { await (options.transport ?? ((command, init) => client.send(command, init)))(new SendEmailCommand({ FromEmailAddress: from, Destination: { ToAddresses: [message.email] }, Content: { Simple: { Subject: { Data: message.subject, Charset: 'UTF-8' }, Body: { Text: { Data: message.text, Charset: 'UTF-8' } } } } }), { abortSignal: signal }); }, () => client?.destroy());
+    const sdk = options.transport ? undefined : loadSes();
+    const client = sdk ? new sdk.SESv2Client({ region: options.region, maxAttempts: 2, ...(options.credentials ? { credentials: options.credentials } : {}) }) : undefined;
+    return sender(where, async (message, signal) => {
+        const input = { FromEmailAddress: from, Destination: { ToAddresses: [message.email] }, Content: { Simple: { Subject: { Data: message.subject, Charset: 'UTF-8' }, Body: { Text: { Data: message.text, Charset: 'UTF-8' } } } } };
+        const command = sdk ? new sdk.SendEmailCommand(input) : { input };
+        await (options.transport ?? ((value, init) => client.send(value, init)))(command, { abortSignal: signal });
+    }, () => client?.destroy());
 }
 /** Development only. File output uses exclusive 0600 notices in an existing private directory outside the project. */
 export async function createDevelopmentSender(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.4.2",
+  "version": "0.4.6",
   "type": "module",
   "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
   "license": "Apache-2.0",
@@ -24,7 +24,6 @@
   },
   "exports": {
     ".": {
-      "development": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     }
@@ -34,17 +33,15 @@
     "README.md",
     "LICENSE",
     "SECURITY.md",
-    "IMPLEMENTATION-STATUS.md",
-    "THIRD_PARTY_NOTICES.md",
-    "THREAT-MODEL.md"
+    "THIRD_PARTY_NOTICES.md"
   ],
   "devDependencies": {
     "@jimhoyd/urlcode": "file:../..",
+    "@aws-sdk/client-sesv2": "3.1135.0",
     "@types/node": "26.5.1",
     "typescript": "6.0.3"
   },
   "dependencies": {
-    "@aws-sdk/client-sesv2": "3.1135.0",
     "@simplewebauthn/server": "14.0.2",
     "bcryptjs": "3.0.3",
     "jose": "6.2.12",
@@ -52,8 +49,14 @@
     "otpauth": "9.5.2"
   },
   "peerDependencies": {
-    "@jimhoyd/urlcode": ">=0.4.2 <0.5.0",
-    "@jimhoyd/urlcode-ui": ">=0.4.2 <0.5.0"
+    "@jimhoyd/urlcode": ">=0.4.6 <0.5.0",
+    "@jimhoyd/urlcode-ui": ">=0.4.6 <0.5.0",
+    "@aws-sdk/client-sesv2": ">=3.1135.0 <4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-sesv2": {
+      "optional": true
+    }
   },
   "bin": {
     "urlcode-auth": "./dist/cli.js"

package/IMPLEMENTATION-STATUS.md

@@ -1,51 +0,0 @@
-# Auth implementation status
-
-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.
-
-Resumable verification-first password/passkey signup (including waitlist approval) and opt-in email-mediated factor recovery with a 24-hour cancellation window and recovery-session-only reenrollment are implemented.
-
-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 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. 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
-
-- 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.
-- Integrated maker/checker manual recovery, staged administrative account actions and audited identifier reveal/notes. Manual recovery is an operator process; public lost-everything intake and recovery contacts remain later scope.
-- Offline `auth-baseline` runs 17 synthetic checks on a passing run (extra failure-only markers are recorded when a probe, deadline or cleanup fails); anonymous `verify-deployment` inspects headers/cookies without claiming provider readiness.
-- Local browser walkthrough exercised identifier-first password login, account page, admin dashboard, filtered directory and masked detail. It found and corrected the no-referrer/Origin form failure. This is not a complete WCAG 2.2 AA assessment.
-
-- The source-only [synthetic recovery drill](RECOVERY-DRILL.md) exercises online backup, isolated reopen, configuration/key refusal and explicit session revocation after snapshot restore. Its 18 checks do not establish production disaster recovery or RTO/RPO.
-
-## Remaining first-release acceptance
-
-- Complete accessibility assessment, browser/device WebAuthn coverage, deployment/soak/backup-recovery exercises and independent security review.
-- Operator wiring of sender monitoring and lifecycle delivery policy. Hooks and security notices are best-effort after commit, without a durable retry queue (signed webhooks/retries are later scope).
-- Refresh the recorded package and CI evidence whenever code or dependency pins change; the merged implementation baseline is recorded in ACCEPTANCE.md.
-
-Live Google/Apple/SES testing is explicitly deferred by the project owner and is not a blocker for local implementation. It remains unverified. Synthetic signed protocol tests do not establish vendor configuration or delivery readiness.
-
-## Agreed architecture corrections
-
-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](ACCEPTANCE.md) for exact merged revisions, automated coverage,
-clean-install evidence and the remaining operational validation boundary.

package/THREAT-MODEL.md

@@ -1,70 +0,0 @@
-# Auth threat model
-
-## Scope and assets
-
-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
-boundary, not whole-database encryption. TOTP secrets and protocol state are sealed;
-passwords are hashed, and reusable browser capabilities are stored as hashes.
-
-## Entry points and trust boundaries
-
-| Entry point | Untrusted input | Authority boundary |
-| --- | --- | --- |
-| Mounted auth HTTP routes | Query, form/JSON, cookies, origin, provider responses | Bounded parsing, browser binding, CSRF, maintained protocol verification, final SQLite transaction |
-| Public signup | Identifier, credential, profile and consent | Verification-first state machine; unique identifiers and reviewed default role; no metadata grants |
-| OIDC/WebAuthn completion | State, claims, signed assertions | Issuer/subject binding or RP/origin/UV checks; current account and credential versions rechecked at issuance |
-| Self-service security changes | Password/factor proof and session | Fresh non-impersonated authority; current version; atomic proof use and session revocation |
-| Email/manual recovery | Mailbox capabilities or reviewed case evidence | Explicit operator opt-in; cancellation/cooldown or two current administrators; restricted reenrollment |
-| Operator modules and CLI | Configuration, keys, import data, callbacks | Trusted operator installation outside the project; bounded imports; explicit configuration migration |
-| Auth service API called by admin | Actor token, target and reason | Worker rechecks current permissions, delegation ceiling, freshness and target state |
-
-A same-origin frontend can exercise browser authority even without reading an
-HttpOnly cookie. Do not host adversarial frontend scripts on this origin. A hostile
-host process, operator module, dependency or OS user able to read the key material
-is outside the boundary this extension protects: that boundary is the
-operator/host-file boundary, not a sandbox. The QuickJS/WASM sandbox is not an
-ambient boundary — it exists only for routes that declare `sandbox: true`. This release does not claim hostile multi-tenant
-readiness or independent assessment.
-
-## Required invariants
-
-- Project declarations cannot register host modules, and the runtime does not
-  inject session, provider or recovery secrets into application handlers.
-  Trusted Node code still has the host process's ambient authority; host-file
-  registration and header filtering do not confine it. Keep hostile code out of
-  that process. `sandbox: true` retains the guest isolation boundary and grants.
-- Required signup verification precedes stored credentials. Existing accounts are
-  never overwritten by a duplicate signup, linked by email alone, or upgraded from
-  untrusted metadata.
-- Proof verification and authority issuance must share account/credential version
-  checks; retries, parallel workers and A→B→A configuration changes cannot revive
-  consumed or stale authority.
-- A passkey cannot serve as both primary and second factor in the same sign-in.
-  Remembered-device authority never grants fresh admin/credential authority.
-- Recovery replacement-factor enrollment belongs to the restoration session.
-  Another party possessing an old password cannot win an enrollment race.
-- Administrative restoration is a human evidence procedure. Software enforces
-  two-person approval and delivery gates; it does not establish legal identity.
-- Limits fail closed, cleanup is bounded, and expiry is checked during use rather
-  than relying on a sweep. Network callbacks cannot authorize incomplete state.
-- Diagnostic output, public responses, browser JavaScript, tests and repository
-  artifacts must not contain real passwords, reusable credentials or customer data.
-
-## Review and evidence
-
-For an auth change, trace the final transaction, not just the form or preflight.
-Check replay, concurrency, expiry, browser/account binding, privilege changes,
-configuration migration, fallback methods, last usable access and secret handling.
-Run `npm run verify`; for exports/build/CLI changes also exercise the installed
-local tarballs across core/auth/admin. Protocol fixtures must use synthetic keys.
-
-Tests cover these mechanisms but are not a penetration test, real-provider setup,
-load/soak result or disaster-recovery exercise. Live Google/Apple/SES verification
-is separately deferred. Operator callbacks and policy data require their own
-review, monitoring, incident handling and periodically tested backups.