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

package/README.md

@@ -2,7 +2,7 @@
 
 An optional, operator-installed authentication extension for URLCode. This repository contains the Node/SQLite implementation: password and passkey authentication, OpenID Connect, email codes, TOTP, recovery codes, versioned registration profiles, account lifecycle operations, administrative service operations and trusted HTML pages.
 
-[![Verify](https://github.com/jimhoyd-com/urlcode-auth/actions/workflows/verify.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode-auth/actions/workflows/verify.yml)
+[![CI](https://github.com/jimhoyd-com/urlcode/actions/workflows/ci.yml/badge.svg)](https://github.com/jimhoyd-com/urlcode/actions/workflows/ci.yml)
 
 The implementation is under active review. Local tests and builds are evidence of those checks, not an independent security assessment, production deployment, provider certification or recovery/soak result. See [SECURITY.md](SECURITY.md) for the trust boundary and [the first-release coverage review](docs/SPIKE-AUTH.md) for the proposal; the proposal is not a list of completed features.
 
@@ -27,20 +27,21 @@ Every release tarball is attested from the tagged commit: `gh attestation verify
 
 Operators who pin exact reviewed commits rather than registry versions can build the same packages locally. A registry version alone does not establish that a revision was reviewed: this implementation requires the core extension contract introduced by [core PR #59](https://github.com/jimhoyd-com/urlcode/pull/59). Use its reviewed implementation or a reviewed successor containing it, pinned to an exact commit. Do not infer approval from the current branch name.
 
-This package also depends on the shared `@jimhoyd/urlcode-ui` peer, which owns document layout, semantic fields, escaping, themes and the locale engine; authentication/administration behavior remains here. Core can use UI without auth/admin. Source CI (`verify.yml`) checks the peers out at the commits in [`peers.json`](peers.json) and needs the narrow `URLCODE_UI_READ_TOKEN`; the release workflow resolves them from the registry instead.
+This package also depends on the shared `@jimhoyd/urlcode-ui` peer, which owns document layout, semantic fields, escaping, themes and the locale engine; authentication/administration behavior remains here. Core can use UI without auth/admin. Both peers are siblings in this repository, so CI builds them from the same commit — there is no peer checkout, no `peers.json` and no read token; the release workflow resolves the published versions from the registry instead, to prove the declared ranges are satisfiable.
 
-Each repository has a lockfile. The source packaging helper installs dependencies with lifecycle scripts disabled, builds the reviewed packages (core, then UI, then their consumers), installs local peer tarballs in dependency order and writes package integrity/revision metadata. It does not publish. All source trees must be committed and clean. `--core`, `--auth`, `--ui`, `--core-revision` and `--out` are required. Replace these illustrative paths with your reviewed locations. `--core-revision` defaults to the `urlcode` entry in [`peers.json`](peers.json), the single source of verified peer revisions; pass it explicitly only to override:
+One lockfile governs the workspace. The source packaging helper installs dependencies with lifecycle scripts disabled, builds the reviewed packages in dependency order (core, then UI, then their consumers) and writes package integrity metadata. It does not publish. The tree must be committed and clean, and it re-checks that after every build and pack. `--revision` and `--out` are required; `--revision` is exact and has no default, because the reviewed commit is the thing being asserted:
 
 ```sh
 node scripts/pack-sources.mjs \
-  --core /absolute/source/urlcode \
-  --ui /absolute/source/urlcode-ui \
-  --auth /absolute/source/urlcode-auth \
-  --admin /absolute/source/urlcode-admin \
-  --core-revision REVIEWED_40_CHARACTER_COMMIT_SHA \
+  --revision REVIEWED_40_CHARACTER_COMMIT_SHA \
   --out /absolute/new-private-package-directory
 ```
 
+One commit identifies every package: core, ui, auth and admin are built from
+the same reviewed revision of this repository. The script refuses to run if the
+checkout is not at that exact commit or has uncommitted changes, and re-checks
+both after each build and pack.
+
 Omit `--admin` for auth only. `--offline` forbids network package resolution and requires a populated dependency cache. `--skip-install` reuses installed third-party dependencies; local peer tarballs are still installed. The script does not alter dependency manifests or lockfiles. Run `npm run verify` in each repository separately; source packaging runs typecheck/build, not the HTTP suite.
 
 Install all required local tarballs together (core, UI and auth; admin if built) in an operator-owned directory with a private `package.json`. For example, after checking the manifest:
@@ -183,7 +184,7 @@ Run `urlcode-auth --help` for the current CLI. Operator commands have full datab
 
 `--operator-file` is an absolute path to a module that default-exports an `AuthService`.
 
-Backup/restore accepts JSON paths on stdin. `createBackup({database,destination,projectRoot})` uses SQLite's online backup API, including committed WAL pages, with a bounded worker and integrity checks. `restoreBackup({backup,destination,projectRoot})` restores to a **new** path. Both require private operator paths outside the project and refuse overwrite. Never copy only a live `.sqlite` file and assume its WAL is included.
+Backup/restore accepts JSON paths on stdin. `createBackup({database,destination,projectRoot})` uses SQLite's online backup API, including committed WAL pages, with a bounded worker and integrity checks. `restoreBackup({backup,destination,projectRoot})` restores to a **new** path. Both require private operator paths outside the project and refuse overwrite. Never copy only a live `.sqlite` file and assume its WAL is included. See [backup and restore platform guarantees](../../docs/AUTH-BACKUP.md), including Windows ACL and directory durability limits.
 
 Back up encryption keys, CSRF keys and reviewed static configuration separately. Database snapshots contain sensitive account/audit data and password hashes, but do not export key files. Restoring historical data also restores historical sessions/tokens and revocation state: plan revocation and recovery before reopening traffic. Rotate keys by adding a new active key, retaining decryption keys while bounded migration reports remaining records, then remove old keys only after completion and backup verification. Old writers fail closed after activation switches. Keep a tested isolated restore procedure.
 

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 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.
+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. Project YAML cannot register auth's host modules: activation requires the explicit host-file/operator-registration mechanism. This is not a confinement boundary for trusted Node code, which can independently import accessible modules and read process environment/files with the host user's authority. Only an explicitly sandboxed route has the guest isolation boundary. 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

@@ -27,12 +27,18 @@ passwords are hashed, and reusable browser capabilities are stored as hashes.
 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 WASM boundary. This release does not claim hostile multi-tenant
+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
 
-- Guests cannot select host modules or receive session, provider or recovery secrets.
+- 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.

package/dist/admin-account-store.js

@@ -68,7 +68,7 @@ export function adminAccountOperation(operation, args, context) {
             }
             return user;
         });
-        const disabling = (user) => ['schedule-deletion', 'force-password-reset'].includes(plan.action) || plan.action === 'assign-roles' && !permissions(plan.parameters.roles).includes('*');
+        const disabling = (_user) => ['schedule-deletion', 'force-password-reset'].includes(plan.action) || plan.action === 'assign-roles' && !permissions(plan.parameters.roles).includes('*');
         if (targets.some(user => administrator(user) && user.status === 'active' && !context.isRestricted(user) && disabling(user))) {
             const disabled = new Set(targets.filter(disabling).map(user => user.id));
             const remaining = db.prepare("SELECT data FROM auth_accounts WHERE administrator=1 AND status='active'").all().some(row => { const user = JSON.parse(String(row.data)); return !disabled.has(user.id) && !context.isRestricted(user); });

package/dist/auth-core.js

@@ -27,7 +27,7 @@ export function normalizeEmail(value) {
     if (parts.length !== 2)
         fail(400, 'invalid_email');
     const local = parts[0].toLowerCase(), domain = domainToASCII(parts[1]).toLowerCase();
-    if (!local || local.length > 64 || /[\s\x00-\x1f\x7f"(),:;<>\[\]\\]/.test(local) || !domain || domain.length > 253 || domain.split('.').some(label => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) || local.length + domain.length + 1 > 254)
+    if (!local || local.length > 64 || /[\s\x00-\x1f\x7f"(),:;<>[\]\\]/.test(local) || !domain || domain.length > 253 || domain.split('.').some(label => !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label)) || local.length + domain.length + 1 > 254)
         fail(400, 'invalid_email');
     return local + '@' + domain;
 }

package/dist/auth-flows.d.ts

@@ -25,6 +25,6 @@ export interface AuthFlowOptions {
     };
 }
 export declare function createAuthFlows(options: AuthFlowOptions, http: AuthHttp, mount: string, registration: boolean): {
-    buttons(csrf: string, link?: boolean, text?: (value: string) => string, locale?: string, presentation?: PresentationContext): string;
+    buttons(csrf: string, link?: boolean, _text?: (value: string) => string, locale?: string, presentation?: PresentationContext): string;
     handle(request: ExtensionRequest): Promise<AuthHttpResponse | undefined>;
 };

package/dist/auth-flows.js

@@ -42,7 +42,7 @@ export function createAuthFlows(options, http, mount, registration) {
     const cookie = (value, maxAge = 600) => ['set-cookie', `${flowCookie}=${value}; Path=/; Secure; HttpOnly; SameSite=None; Max-Age=${maxAge}`];
     const finish = async (request, result) => { const headers = options.onSession ? await options.onSession(request, result) : []; return wantsJson(request) ? jsonResponse(200, { user: result.user, csrf: http.token(result.token), ...(result.principal.restrictions ? { restrictions: result.principal.restrictions } : {}) }, [...http.sessionHeaders(result.token), cookie('', 0), ...headers]) : jsonResponse(303, { redirect: mount + '/account' }, [['location', mount + '/account'], ...http.sessionHeaders(result.token), cookie('', 0), ...headers]); };
     return {
-        buttons(csrf, link = false, text = value => value, locale, presentation) { return Object.keys(providers).map(name => `<form method="post" action="${escapeHtml(mount + '/providers/' + name + (link ? '/link' : '/start') + (locale ? '?lang=' + encodeURIComponent(locale) : ''))}">${csrfField(csrf)}<button type="submit">${escapeHtml((presentation ?? defaultPresentation.resolve()).text(link ? 'provider.link' : 'provider.signIn', { provider: name }))}</button></form>`).join(''); },
+        buttons(csrf, link = false, _text = value => value, locale, presentation) { return Object.keys(providers).map(name => `<form method="post" action="${escapeHtml(mount + '/providers/' + name + (link ? '/link' : '/start') + (locale ? '?lang=' + encodeURIComponent(locale) : ''))}">${csrfField(csrf)}<button type="submit">${escapeHtml((presentation ?? defaultPresentation.resolve()).text(link ? 'provider.link' : 'provider.signIn', { provider: name }))}</button></form>`).join(''); },
         async handle(request) {
             let presentation = (options.presentation ?? defaultPresentation).resolve({ ...(request.query.get('lang') ? { queryLocale: request.query.get('lang') } : {}), ...(request.headers.get('accept-language') ? { acceptLanguage: request.headers.get('accept-language') } : {}) });
             const tr = (key, values) => escapeHtml(presentation.text(key, values));

package/dist/auth-store.js

@@ -46,19 +46,26 @@ export async function openAuthStore(options) {
     };
     worker.on('error', fail);
     worker.on('exit', fail);
-    await new Promise((accept, reject) => {
-        const timer = setTimeout(() => { void worker.terminate(); reject(new AuthError(503, 'auth_store_unavailable')); }, 15000);
-        worker.once('message', (message) => {
-            clearTimeout(timer);
-            if (message.ready)
-                accept();
-            else {
-                void worker.terminate();
-                reject(new AuthError(503, ['auth_configuration_changed', 'configuration_approval_mismatch', 'configuration_roles_invalid', 'configuration_admin_required'].includes(message.error ?? '') ? message.error : 'auth_store_unavailable'));
-            }
+    try {
+        await new Promise((accept, reject) => {
+            const timer = setTimeout(() => { reject(new AuthError(503, 'auth_store_unavailable')); }, 15000);
+            worker.once('message', (message) => {
+                clearTimeout(timer);
+                if (message.ready)
+                    accept();
+                else {
+                    reject(new AuthError(503, ['auth_configuration_changed', 'configuration_approval_mismatch', 'configuration_roles_invalid', 'configuration_admin_required'].includes(message.error ?? '') ? message.error : 'auth_store_unavailable'));
+                }
+            });
+            worker.once('error', () => { clearTimeout(timer); reject(new AuthError(503, 'auth_store_unavailable')); });
         });
-        worker.once('error', () => { clearTimeout(timer); reject(new AuthError(503, 'auth_store_unavailable')); });
-    });
+    }
+    catch (error) {
+        // A rejected open must release SQLite handles before its caller can
+        // retry, restore or remove the database (Windows cannot unlink them).
+        await worker.terminate();
+        throw error;
+    }
     worker.on('message', (message) => {
         const p = pending.get(message.id);
         if (!p)

package/dist/auth.js

@@ -125,7 +125,7 @@ export function authExtension(options) {
                 try {
                     await Promise.race([options.sendNotice({ email, event, ...(locale ? { locale } : {}), signal: controller.signal }), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('timeout')); }, 5000); })]);
                 }
-                catch { }
+                catch { /* Notification delivery is best-effort: a failed or timed-out notice must not fail the operation that triggered it. */ }
                 finally {
                     if (timer)
                         clearTimeout(timer);
@@ -160,7 +160,7 @@ export function authExtension(options) {
                             const session = http.session(request), actor = session ? await service.authenticate(session) : null;
                             accountLocale = actor ? (await service.getUser(actor.id))?.profile?.locale : undefined;
                         }
-                        catch { }
+                        catch { /* An unreadable session only means no account locale to prefer; fall back to the request locale. */ }
                     }
                     const presentation = source().resolve({ ...(accountLocale ? { accountLocale } : {}), ...(request.query.get('lang') ? { queryLocale: request.query.get('lang') } : {}), ...(request.headers.get('accept-language') ? { acceptLanguage: request.headers.get('accept-language') } : {}) });
                     const tr = (key, values) => escapeHtml(presentation.text(key, values));
@@ -370,7 +370,7 @@ export function authExtension(options) {
                                 try {
                                     await Promise.race([options.sendEmailCode({ email, flowId: issued.flowId, code: issued.code, locale: presentation.locale, signal: controller.signal }), new Promise((_, reject) => { timer = setTimeout(() => { controller.abort(); reject(new Error('timeout')); }, 5000); })]);
                                 }
-                                catch { }
+                                catch { /* Delivery is best-effort here too: the code is already issued, and the flow continues on the verification step. */ }
                                 finally {
                                     if (timer)
                                         clearTimeout(timer);

package/dist/backup.js

@@ -61,7 +61,8 @@ async function snapshot(sourceInput, destinationInput, projectRoot) {
         const copied = await lstat(file);
         if (!copied.isFile() || copied.size > 1073741824)
             throw new Error('Backup exceeds size limit');
-        const handle = await open(file, 'r');
+        // Windows FlushFileBuffers requires a writable handle.
+        const handle = await open(file, 'r+');
         try {
             await handle.sync();
         }
@@ -71,12 +72,16 @@ async function snapshot(sourceInput, destinationInput, projectRoot) {
         // Linking is atomic and refuses any existing destination, including a raced-in symlink.
         await link(file, destination);
         await rm(file);
-        const directory = await open(parent, 'r');
-        try {
-            await directory.sync();
-        }
-        finally {
-            await directory.close();
+        // Node cannot open/flush directory handles this way on Windows.
+        // File bytes were flushed above; POSIX also flushes the new directory entry.
+        if (process.platform !== 'win32') {
+            const directory = await open(parent, 'r');
+            try {
+                await directory.sync();
+            }
+            finally {
+                await directory.close();
+            }
         }
         return { format: 'urlcode-auth-sqlite-v1', bytes: copied.size };
     }

package/dist/challenge.js

@@ -10,7 +10,7 @@ export function createTurnstileChallenge(options) {
         throw new Error('Invalid Turnstile hostname');
     }
     const timeout = options.timeoutMs ?? 5000;
-    if (!key(options.secret) || !key(options.siteKey) || hostname !== options.hostname || !hostname || /[\/:@?#]/.test(hostname) || !Number.isInteger(timeout) || timeout < 10 || timeout > 5000)
+    if (!key(options.secret) || !key(options.siteKey) || hostname !== options.hostname || !hostname || /[/:@?#]/.test(hostname) || !Number.isInteger(timeout) || timeout < 10 || timeout > 5000)
         throw new Error('Invalid Turnstile configuration');
     let active = 0;
     return Object.freeze({ widget: Object.freeze({ siteKey: options.siteKey, action: 'auth' }), async verify(input) {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.1.0-alpha.3",
+  "version": "0.1.0-alpha.6",
   "type": "module",
   "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/jimhoyd-com/urlcode-auth.git"
+    "url": "git+https://github.com/jimhoyd-com/urlcode.git",
+    "directory": "packages/auth"
   },
   "publishConfig": {
     "access": "public"
@@ -18,7 +19,7 @@
     "build": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "pretest": "node scripts/check-sqlite.mjs",
-    "test": "node --conditions=development --test test/*.test.ts",
+    "test": "node --conditions=development --test --test-timeout=300000 test/*.test.ts",
     "verify": "npm run typecheck && npm run build && npm test"
   },
   "exports": {
@@ -38,6 +39,7 @@
     "THREAT-MODEL.md"
   ],
   "devDependencies": {
+    "@jimhoyd/urlcode": "file:../..",
     "@types/node": "26.5.1",
     "typescript": "6.0.3"
   },
@@ -56,8 +58,8 @@
   "bin": {
     "urlcode-auth": "./dist/cli.js"
   },
-  "homepage": "https://github.com/jimhoyd-com/urlcode-auth#readme",
+  "homepage": "https://github.com/jimhoyd-com/urlcode/tree/main/packages/auth#readme",
   "bugs": {
-    "url": "https://github.com/jimhoyd-com/urlcode-auth/issues"
+    "url": "https://github.com/jimhoyd-com/urlcode/issues"
   }
 }