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

package/dist/backup.js

@@ -0,0 +1,121 @@
+import { Worker, isMainThread, parentPort, workerData } from 'node:worker_threads';
+import { DatabaseSync, backup } from 'node:sqlite';
+import { open, lstat, stat, realpath, mkdtemp, rm, link } from 'node:fs/promises';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+function outside(project, path) { const rel = relative(project, path); return Boolean(rel && (isAbsolute(rel) || rel === '..' || rel.startsWith('..' + sep))); }
+function patched(version) { const [a = 0, b = 0, c = 0] = version.split('.').map(Number); return a > 3 || a === 3 && (b > 51 || b === 51 && c >= 3 || b === 50 && c >= 7 || b === 44 && c >= 6); }
+async function snapshot(sourceInput, destinationInput, projectRoot) {
+    if (!isMainThread || !patched(process.versions.sqlite || ''))
+        throw new Error('Backup requires a patched SQLite host');
+    if (!isAbsolute(sourceInput) || !isAbsolute(destinationInput) || !isAbsolute(projectRoot))
+        throw new Error('Backup paths must be absolute');
+    const project = await realpath(projectRoot), sourceInfo = await lstat(sourceInput), source = await realpath(sourceInput), parent = await realpath(dirname(destinationInput)), destination = join(parent, basename(destinationInput));
+    if (!outside(project, source) || !outside(project, destination))
+        throw new Error('Auth backups and databases must be outside the project');
+    if (!sourceInfo.isFile() || sourceInfo.isSymbolicLink() || sourceInfo.nlink !== 1 || process.platform !== 'win32' && (sourceInfo.mode & 0o077) !== 0 || sourceInfo.size > 1073741824)
+        throw new Error('Backup source must be a private regular database below 1 GiB');
+    const parentInfo = await stat(parent);
+    if (!parentInfo.isDirectory() || process.platform !== 'win32' && (parentInfo.mode & 0o077) !== 0)
+        throw new Error('Backup destination directory must be private');
+    if (resolve(source) === resolve(destination))
+        throw new Error('Backup cannot replace its source');
+    try {
+        await lstat(destination);
+        throw new Error('Backup destination already exists');
+    }
+    catch (error) {
+        if (!(error instanceof Error && 'code' in error && error.code === 'ENOENT'))
+            throw error;
+    }
+    const temporary = await mkdtemp(join(parent, '.urlcode-backup-')), file = join(temporary, 'snapshot.sqlite');
+    let worker;
+    try {
+        const created = await open(file, 'wx', 0o600);
+        await created.close();
+        worker = new Worker(new URL(import.meta.url), { workerData: { urlcodeAuthBackup: true, source, destination: file }, env: {}, execArgv: [], stdout: true, stderr: true, resourceLimits: { maxOldGenerationSizeMb: 32 } });
+        worker.stdout.resume();
+        worker.stderr.resume();
+        const active = worker;
+        await new Promise((accept, reject) => {
+            let done = false;
+            const finish = (error) => {
+                if (done)
+                    return;
+                done = true;
+                clearTimeout(timer);
+                if (error)
+                    reject(error);
+                else
+                    accept();
+            };
+            const timer = setTimeout(() => { void active.terminate(); finish(new Error('Backup exceeded time limit')); }, 30000);
+            active.once('message', (message) => finish(message.ok ? undefined : new Error('Database backup validation failed')));
+            active.once('error', () => finish(new Error('Database backup failed')));
+            active.once('exit', code => {
+                if (!done)
+                    finish(new Error(`Database backup worker exited (${code})`));
+            });
+        });
+        await active.terminate();
+        worker = undefined;
+        const copied = await lstat(file);
+        if (!copied.isFile() || copied.size > 1073741824)
+            throw new Error('Backup exceeds size limit');
+        const handle = await open(file, 'r');
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        // 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();
+        }
+        return { format: 'urlcode-auth-sqlite-v1', bytes: copied.size };
+    }
+    finally {
+        await worker?.terminate();
+        await rm(temporary, { recursive: true, force: true });
+    }
+}
+/** Consistent online SQLite snapshot, including committed WAL pages. Never copies a live database file. */
+export function createBackup(options) { return snapshot(options.database, options.destination, options.projectRoot); }
+/** Restores to a new isolated path only. Operator retains matching keys and static configuration separately. */
+export function restoreBackup(options) { return snapshot(options.backup, options.destination, options.projectRoot); }
+if (!isMainThread && workerData?.urlcodeAuthBackup) {
+    const source = new DatabaseSync(String(workerData.source), { readOnly: true, allowExtension: false });
+    try {
+        source.exec('PRAGMA trusted_schema=OFF; PRAGMA query_only=ON; PRAGMA busy_timeout=1000;');
+        if (source.prepare('PRAGMA user_version').get()?.user_version !== 1 || source.prepare('PRAGMA application_id').get()?.application_id !== 1430345032)
+            throw new Error('Unsupported auth database');
+        const schema = source.prepare("SELECT type,name FROM sqlite_master WHERE name NOT LIKE 'sqlite_%'").all();
+        if (schema.some(row => !['table', 'index'].includes(String(row.type)) || !String(row.name).startsWith('auth_')))
+            throw new Error('Unexpected database schema');
+        await backup(source, String(workerData.destination), { rate: 128 });
+        const check = new DatabaseSync(String(workerData.destination), { readOnly: true, allowExtension: false });
+        try {
+            check.exec('PRAGMA trusted_schema=OFF; PRAGMA query_only=ON;');
+            const integrity = check.prepare('PRAGMA integrity_check').all();
+            if (integrity.length !== 1 || Object.values(integrity[0])[0] !== 'ok' || check.prepare('PRAGMA foreign_key_check').all().length)
+                throw new Error('Invalid backup integrity');
+        }
+        finally {
+            check.close();
+        }
+        parentPort.postMessage({ ok: true });
+    }
+    catch {
+        parentPort.postMessage({ ok: false });
+    }
+    finally {
+        source.close();
+        parentPort.close();
+    }
+}

package/dist/challenge-ui.d.ts

@@ -0,0 +1,11 @@
+export interface TurnstileWidget {
+    siteKey: string;
+    action: 'auth';
+}
+export declare const turnstileOrigin = "https://challenges.cloudflare.com";
+export declare const turnstileScript: string;
+/** Only typed operator configuration can add this fixed third-party widget to trusted package forms. */
+export declare function addTurnstileWidgets(markup: string, widget?: TurnstileWidget): {
+    markup: string;
+    enabled: boolean;
+};

package/dist/challenge-ui.js

@@ -0,0 +1,18 @@
+export const turnstileOrigin = 'https://challenges.cloudflare.com';
+export const turnstileScript = turnstileOrigin + '/turnstile/v0/api.js';
+/** Only typed operator configuration can add this fixed third-party widget to trusted package forms. */
+export function addTurnstileWidgets(markup, widget) {
+    if (!widget)
+        return { markup, enabled: false };
+    if (typeof widget.siteKey !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(widget.siteKey) || widget.action !== 'auth' || Object.keys(widget).some(key => !['siteKey', 'action'].includes(key)))
+        throw new Error('Invalid challenge widget');
+    let count = 0;
+    const result = markup.replace(/<form\b([^>]*)>/gi, (tag, attributes) => {
+        if (!/(?:^|\s)method=(?:"post"|'post')(?=\s|$)/i.test(attributes))
+            return tag;
+        if (++count > 16)
+            throw new Error('Too many challenge forms');
+        return tag + `<div class="cf-turnstile" data-sitekey="${widget.siteKey}" data-action="auth" data-response-field-name="challengeToken"></div>`;
+    });
+    return { markup: result, enabled: count > 0 };
+}

package/dist/challenge.d.ts

@@ -0,0 +1,21 @@
+export interface AuthChallengeInput {
+    token: string;
+    client: string;
+    signal: AbortSignal;
+}
+export interface AuthChallenge {
+    verify(input: AuthChallengeInput): Promise<boolean>;
+    widget?: {
+        siteKey: string;
+        action: 'auth';
+    };
+}
+export interface TurnstileChallengeOptions {
+    secret: string;
+    siteKey: string;
+    hostname: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/** Fixed upstream only. Siteverify tokens are single-use; never cache a verdict. */
+export declare function createTurnstileChallenge(options: TurnstileChallengeOptions): AuthChallenge;

package/dist/challenge.js

@@ -0,0 +1,65 @@
+import { isIP } from 'node:net';
+/** Fixed upstream only. Siteverify tokens are single-use; never cache a verdict. */
+export function createTurnstileChallenge(options) {
+    const key = (value) => typeof value === 'string' && /^[A-Za-z0-9_-]{10,256}$/.test(value);
+    let hostname;
+    try {
+        hostname = new URL('https://' + options.hostname).hostname;
+    }
+    catch {
+        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)
+        throw new Error('Invalid Turnstile configuration');
+    let active = 0;
+    return Object.freeze({ widget: Object.freeze({ siteKey: options.siteKey, action: 'auth' }), async verify(input) {
+            if (input.signal.aborted || !isIP(input.client) || typeof input.token !== 'string' || input.token.length < 1 || input.token.length > 2048 || /[\x00-\x20\x7f]/.test(input.token) || active >= 32)
+                return false;
+            active++;
+            const controller = new AbortController();
+            let timer;
+            const pending = (async () => {
+                const response = await (options.fetch ?? fetch)('https://challenges.cloudflare.com/turnstile/v0/siteverify', { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' }, body: new URLSearchParams({ secret: options.secret, response: input.token, remoteip: input.client }), signal: AbortSignal.any([input.signal, controller.signal]) });
+                if (response.status !== 200 || Number(response.headers.get('content-length') || 0) > 8192) {
+                    await response.body?.cancel();
+                    return false;
+                }
+                const reader = response.body?.getReader();
+                if (!reader)
+                    return false;
+                const chunks = [];
+                let size = 0;
+                try {
+                    for (;;) {
+                        const item = await reader.read();
+                        if (item.done)
+                            break;
+                        size += item.value.byteLength;
+                        if (size > 8192)
+                            return false;
+                        chunks.push(item.value);
+                    }
+                }
+                finally {
+                    await reader.cancel().catch(() => { });
+                    reader.releaseLock();
+                }
+                const value = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+                const timestamp = typeof value.challenge_ts === 'string' ? Date.parse(value.challenge_ts) : NaN;
+                return value.success === true && value.hostname === hostname && value.action === 'auth' && Number.isFinite(timestamp) && timestamp <= Date.now() + 60000 && timestamp >= Date.now() - 300000;
+            })();
+            // A verifier that ignores cancellation retains its slot instead of allowing unbounded work.
+            void pending.finally(() => { active--; }).catch(() => { });
+            try {
+                return await Promise.race([pending, new Promise(resolve => { timer = setTimeout(() => { controller.abort(); resolve(false); }, timeout); })]);
+            }
+            catch {
+                return false;
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        } });
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+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 { verifyDeployment } from "./deployment-check.js";
+import { parseArgs } from 'node:util';
+import { isAbsolute } from 'node:path';
+import { realpath, stat } from 'node:fs/promises';
+import { pathToFileURL } from 'node:url';
+import { createBackup, restoreBackup } from "./backup.js";
+import { initAuthentication } from "./scaffold.js";
+async function input() {
+    const chunks = [];
+    let size = 0;
+    for await (const part of process.stdin) {
+        const bytes = Buffer.from(part);
+        size += bytes.length;
+        if (size > 1048576)
+            throw new Error('Input exceeds limit');
+        chunks.push(bytes);
+    }
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Invalid input');
+    return value;
+}
+function string(value) {
+    if (typeof value !== 'string' || !value)
+        throw new Error('Required input missing');
+    return value;
+}
+let service;
+try {
+    const { values, positionals } = parseArgs({ allowPositionals: true, options: { 'operator-file': { type: 'string' }, directory: { type: 'string' }, help: { type: 'boolean' } } });
+    const command = positionals[0];
+    if (values.help || !command)
+        process.stdout.write('urlcode-auth init --directory NEW_DIRECTORY\nurlcode-auth bootstrap|users|sessions|revoke|audit|import|rotate-key|purge|cleanup|configuration|doctor|validate --operator-file /absolute/operator/auth.mjs\nurlcode-auth auth-baseline (offline synthetic checks)\nurlcode-auth verify-deployment (JSON origin/authMount on stdin)\nurlcode-auth backup|restore (JSON paths on stdin)\nSecrets and operation data use bounded JSON stdin, never argv. Operator module default-exports an AuthService.\n');
+    else {
+        if (positionals.length !== 1)
+            throw new Error('Invalid command');
+        let output;
+        if (command === 'init') {
+            output = await initAuthentication(string(values.directory));
+        }
+        else if (command === 'auth-baseline') {
+            if (values['operator-file'] || values.directory)
+                throw new Error('Baseline accepts no operator files');
+            const { runAuthBaseline } = await import("./auth-baseline.js");
+            const result = await runAuthBaseline();
+            output = result;
+            if (!result.passed)
+                process.exitCode = 1;
+        }
+        else if (command === 'verify-deployment') {
+            const data = await input();
+            const result = await verifyDeployment({ origin: string(data.origin), authMount: string(data.authMount), ...(data.allowDevelopment === true ? { allowDevelopment: true } : {}), ...(data.allowTurnstile === true ? { allowTurnstile: true } : {}) });
+            output = result;
+            if (!result.passed)
+                process.exitCode = 1;
+        }
+        else if (command === 'backup' || command === 'restore') {
+            const data = await input(), destination = string(data.destination), projectRoot = string(data.projectRoot);
+            output = command === 'backup' ? await createBackup({ database: string(data.database), destination, projectRoot }) : await restoreBackup({ backup: string(data.backup), destination, projectRoot });
+        }
+        else {
+            if (!['bootstrap', 'users', 'sessions', 'revoke', 'audit', 'import', 'rotate-key', 'purge', 'cleanup', 'configuration', 'doctor', 'validate'].includes(command))
+                throw new Error('Invalid command');
+            if (!values['operator-file'] || !isAbsolute(values['operator-file']))
+                throw new Error('Provide an absolute operator file');
+            const file = await realpath(values['operator-file']), info = await stat(file);
+            if (!info.isFile() || info.size > 1048576)
+                throw new Error('Invalid operator file');
+            service = (await import(__rewriteRelativeImportExtension(pathToFileURL(file).href))).default;
+            if (!service || typeof service.close !== 'function' || typeof service.bootstrapAdmin !== 'function')
+                throw new Error('Invalid operator service');
+            const data = ['bootstrap', 'sessions', 'revoke', 'import'].includes(command) ? await input() : {};
+            if (command === 'bootstrap')
+                output = (await service.bootstrapAdmin({ email: string(data.email), password: string(data.password) })).user;
+            else if (command === 'users')
+                output = await service.listUsers({ limit: 100 });
+            else if (command === 'audit')
+                output = await service.listAudit({ limit: 100 });
+            else if (command === 'rotate-key')
+                output = await service.rotateEncryptionKey();
+            else if (command === 'purge')
+                output = await service.purgeDeleted();
+            else if (command === 'cleanup')
+                output = await service.cleanup({ limit: 1000 });
+            else if (command === 'configuration')
+                output = { revision: await service.getConfigurationRevision(), registration: service.getRegistrationMode(), security: service.getSecurityPolicy(), roles: service.getRoles() };
+            else if (command === 'validate') {
+                const { validateAuthService } = await import("./auth-baseline.js");
+                output = await validateAuthService(service);
+            }
+            else if (command === 'doctor')
+                output = { database: 'ready', registration: service.getRegistrationMode(), security: service.getSecurityPolicy(), accounts: (await service.dashboard()).users, liveProviders: 'unverified' };
+            else if (command === 'import') {
+                if (!Array.isArray(data.users))
+                    throw new Error('Users array required');
+                const users = data.users.map((user) => {
+                    if (!user || typeof user !== 'object' || Array.isArray(user))
+                        throw new Error('Invalid user');
+                    const row = user;
+                    if (Object.keys(row).some(key => !['email', 'passwordHash', 'emailVerified'].includes(key)) || row.emailVerified !== undefined && typeof row.emailVerified !== 'boolean')
+                        throw new Error('Invalid user field');
+                    return { email: string(row.email), passwordHash: string(row.passwordHash), ...(typeof row.emailVerified === 'boolean' ? { emailVerified: row.emailVerified } : {}) };
+                });
+                output = await service.importUsers(users);
+            }
+            else if (command === 'sessions')
+                output = await service.listSessions(string(data.accountId));
+            else {
+                await service.revokeSessions(string(data.accountId));
+                output = { revoked: true };
+            }
+        }
+        process.stdout.write(JSON.stringify(output) + '\n');
+    }
+}
+catch {
+    process.stderr.write('Auth operation failed; check command, operator configuration and input.\n');
+    process.exitCode = 1;
+}
+finally {
+    try {
+        await service?.close();
+    }
+    catch {
+        process.stderr.write('Auth cleanup failed.\n');
+        process.exitCode = 1;
+    }
+}

package/dist/deployment-check.d.ts

@@ -0,0 +1,16 @@
+export interface DeploymentCheckOptions {
+    origin: string;
+    authMount: string;
+    allowDevelopment?: boolean;
+    allowTurnstile?: boolean;
+}
+export interface DeploymentCheckResult {
+    passed: boolean;
+    checks: {
+        name: string;
+        passed: boolean;
+    }[];
+    liveProviders: 'unverified';
+}
+/** Anonymous, read-only checks. No credentials, redirects, mail sends or account mutations. */
+export declare function verifyDeployment(options: DeploymentCheckOptions, transport?: typeof fetch): Promise<DeploymentCheckResult>;

package/dist/deployment-check.js

@@ -0,0 +1,41 @@
+/** Anonymous, read-only checks. No credentials, redirects, mail sends or account mutations. */
+export async function verifyDeployment(options, transport = fetch) {
+    const origin = new URL(options.origin);
+    if (origin.origin !== options.origin || origin.username || origin.password || !(origin.protocol === 'https:' || options.allowDevelopment === true && origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname)))
+        throw new Error('Canonical HTTPS origin required');
+    if (!/^\/[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)*$/.test(options.authMount) || options.authMount.length > 256)
+        throw new Error('Explicit auth mount required');
+    const checks = [];
+    for (const [path, expected] of [['/login', 200], ['/account', 401]]) {
+        const controller = new AbortController(), timer = setTimeout(() => controller.abort(), 5000);
+        const prefix = path === '/login' ? 'login' : 'anonymous-account';
+        try {
+            const response = await transport(options.origin + options.authMount + path, { method: 'GET', headers: { accept: 'text/html' }, credentials: 'omit', redirect: 'manual', signal: controller.signal });
+            const add = (name, passed) => checks.push({ name: prefix + '.' + name, passed });
+            add('status', response.status === expected);
+            add('no-store', /(?:^|,)\s*no-store\s*(?:,|$)/i.test(response.headers.get('cache-control') ?? ''));
+            add('private-referrer', ['no-referrer', 'strict-origin'].includes(response.headers.get('referrer-policy') ?? ''));
+            add('nosniff', response.headers.get('x-content-type-options') === 'nosniff');
+            const directives = (response.headers.get('content-security-policy') ?? '').split(';').map(item => item.trim().split(/\s+/)).filter(item => item[0]);
+            const csp = new Map(directives.map(([name, ...values]) => [name, values.join(' ')]));
+            const sources = (name) => (csp.get(name) ?? '').split(/\s+/).filter(Boolean);
+            const challengeSource = (source) => options.allowTurnstile === true && source === 'https://challenges.cloudflare.com';
+            add('content-security-policy', csp.size === directives.length && csp.get('default-src') === "'none'" && csp.get('base-uri') === "'none'" && csp.get('frame-ancestors') === "'none'" && csp.get('form-action') === "'self'" && sources('script-src').every(source => /^'nonce-[A-Za-z0-9+/]{16,}={0,2}'$/.test(source) || challengeSource(source)) && sources('frame-src').every(source => source === "'none'" || challengeSource(source)) && sources('connect-src').every(source => source === "'none'" || source === "'self'" || challengeSource(source)));
+            const cookies = response.headers.getSetCookie();
+            add('cookie-policy', cookies.every(cookie => {
+                const [pair, ...attributes] = cookie.split(';').map(value => value.trim());
+                const attrs = new Map(attributes.map(value => { const at = value.indexOf('='); return at < 0 ? [value.toLowerCase(), ''] : [value.slice(0, at).toLowerCase(), value.slice(at + 1)]; }));
+                return pair?.startsWith('__Host-') === true && !pair.startsWith('__Host-urlcode-session=') && attrs.has('secure') && attrs.has('httponly') && attrs.get('path') === '/' && !attrs.has('domain') && ['Strict', 'Lax'].includes(attrs.get('samesite') ?? '');
+            }));
+            // Cancel without reading account markup, debug bodies or unexpected proxy output.
+            await response.body?.cancel();
+        }
+        catch {
+            checks.push({ name: prefix + '.reachable', passed: false });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return { passed: checks.every(check => check.passed), checks, liveProviders: 'unverified' };
+}

package/dist/disposable-domain-data.d.ts

@@ -0,0 +1 @@
+export declare const disposableDomainData: readonly string[];