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

package/dist/senders.js

@@ -0,0 +1,153 @@
+import { createEmailCopy } from "./email-copy.js";
+import { SESv2Client, SendEmailCommand } from '@aws-sdk/client-sesv2';
+import { randomUUID } from 'node:crypto';
+import { open, realpath, stat, readdir } from 'node:fs/promises';
+import { join, relative, isAbsolute } from 'node:path';
+import { normalizeEmail } from "./auth-core.js";
+const events = { 'registration-attempt': 'Someone tried to create an account with your email address. Your existing account was not changed.', 'new-device': 'A new device signed in to your account.', 'password-changed': 'Your account password changed.', 'email-changed': 'Your account email address changed.' };
+function location(options, development = false) {
+    const origin = new URL(options.origin);
+    if (origin.origin !== options.origin || origin.username || origin.password || !(origin.protocol === 'https:' || development && origin.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(origin.hostname)))
+        throw new Error('Sender requires a canonical HTTPS origin');
+    if (!/^\/[a-zA-Z0-9_-]+(?:\/[a-zA-Z0-9_-]+)*$/.test(options.authMount) || options.authMount.length > 256)
+        throw new Error('Sender requires an explicit auth mount');
+    return { origin: origin.origin, mount: options.authMount, emailCopy: options.emailCopy ?? createEmailCopy() };
+}
+function sender(where, deliver, cleanup = () => { }) {
+    let closed = false, active = 0;
+    async function send(message, signal) {
+        if (closed)
+            throw new Error('Sender is closed');
+        if (active >= 4)
+            throw new Error('Sender is busy');
+        signal.throwIfAborted();
+        active++;
+        const controller = new AbortController(), abort = () => controller.abort(), timer = setTimeout(abort, 5000);
+        signal.addEventListener('abort', abort, { once: true });
+        let rejectAbort = () => { };
+        try {
+            await Promise.race([deliver(message, controller.signal), new Promise((_resolve, reject) => {
+                    rejectAbort = () => reject(new Error('Email delivery aborted'));
+                    controller.signal.addEventListener('abort', rejectAbort, { once: true });
+                    if (controller.signal.aborted)
+                        rejectAbort();
+                })]);
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', abort);
+            controller.signal.removeEventListener('abort', rejectAbort);
+            active--;
+        }
+    }
+    const notice = (email, key, values, signal, locale) => send({ email: normalizeEmail(email), ...where.emailCopy.render(key, values, locale) }, signal);
+    const result = Object.assign(async (message) => {
+        if (!message || !['verify-email', 'reset-password', 'cancel-deletion', 'invitation', 'verify-email-change', 'cancel-email-change'].includes(message.purpose) || typeof message.token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.token))
+            throw new Error('Invalid token delivery');
+        const paths = { 'verify-email': '/verify', 'reset-password': '/reset', 'cancel-deletion': '/cancel-deletion', invitation: '/register', 'verify-email-change': '/verify-email-change', 'cancel-email-change': '/cancel-email-change' };
+        const url = new URL(where.mount + paths[message.purpose], where.origin);
+        url.searchParams.set('token', message.token);
+        await notice(message.email, message.purpose, { link: url.href }, message.signal, message.locale);
+    }, {
+        async sendEmailCode(message) {
+            if (!message || typeof message.code !== 'string' || !/^\d{6}$/.test(message.code) || typeof message.flowId !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.flowId))
+                throw new Error('Invalid email code delivery');
+            const url = new URL(where.mount + '/email-code', where.origin);
+            url.searchParams.set('flowId', message.flowId);
+            await notice(message.email, 'sign-in-code', { link: url.href, code: message.code }, message.signal, message.locale);
+        },
+        async sendSignupCode(message) {
+            if (!message || typeof message.code !== 'string' || !/^\d{6}$/.test(message.code))
+                throw new Error('Invalid signup code delivery');
+            await notice(message.email, 'signup-code', { link: new URL(where.mount + '/signup', where.origin).href, code: message.code }, message.signal, message.locale);
+        },
+        async sendFactorRecovery(message) {
+            if (!message || typeof message.verificationToken !== 'string' || typeof message.cancelToken !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.verificationToken) || !/^[A-Za-z0-9_-]{43}$/.test(message.cancelToken))
+                throw new Error('Invalid factor recovery delivery');
+            const url = new URL(where.mount + '/recover-factor/confirm', where.origin), cancel = new URL(where.mount + '/recover-factor/cancel', where.origin);
+            url.searchParams.set('token', message.verificationToken);
+            cancel.searchParams.set('token', message.cancelToken);
+            await notice(message.email, 'factor-recovery', { link: url.href, cancelLink: cancel.href }, message.signal, message.locale);
+        },
+        async sendManualRecovery(message) {
+            if (!message || typeof message.token !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(message.token))
+                throw new Error('Invalid manual recovery delivery');
+            const email = normalizeEmail(message.email), oldEmail = normalizeEmail(message.oldEmail), url = new URL(where.mount + '/restore-access', where.origin);
+            url.searchParams.set('token', message.token);
+            await notice(oldEmail, 'manual-recovery-warning', {}, message.signal, message.locale);
+            await notice(email, 'manual-recovery', { link: url.href }, message.signal, message.locale);
+        },
+        async sendAccountAdministration(message) {
+            if (!message || !['token', 'notice'].includes(message.kind))
+                throw new Error('Invalid account administration delivery');
+            if (message.kind === 'token')
+                return result({ email: message.email, token: message.token, purpose: message.purpose, signal: message.signal, ...(message.locale ? { locale: message.locale } : {}) });
+            if (!['verify-email', 'force-password-reset', 'schedule-deletion', 'cancel-deletion', 'remove-passkey', 'remove-external', 'request-email-change', 'assign-roles', 'resend-verification'].includes(message.action))
+                throw new Error('Invalid administration notice');
+            await notice(message.email, ('admin-' + message.action), { link: where.origin + where.mount + '/account' }, message.signal, message.locale);
+        },
+        async notify(message) {
+            if (!message || !Object.hasOwn(events, message.event))
+                throw new Error('Invalid security notice');
+            await notice(message.email, message.event, { link: where.origin + where.mount + '/account' }, message.signal, message.locale);
+        },
+        close() { if (closed)
+            return; closed = true; cleanup(); }
+    });
+    return result;
+}
+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());
+}
+/** Development only. File output uses exclusive 0600 notices in an existing private directory outside the project. */
+export async function createDevelopmentSender(options) {
+    if (options.allowDevelopment !== true)
+        throw new Error('Development delivery requires explicit allowDevelopment');
+    const where = location(options, true), maximum = options.maxMessages ?? 100;
+    if (!Number.isInteger(maximum) || maximum < 1 || maximum > 1000)
+        throw new Error('Invalid development notice limit');
+    let directory;
+    if (options.directory !== undefined) {
+        directory = await realpath(options.directory);
+        const project = await realpath(options.projectRoot);
+        const rel = relative(project, directory);
+        if (!rel || !isAbsolute(rel) && rel !== '..' && !rel.startsWith('..' + (process.platform === 'win32' ? '\\' : '/')))
+            throw new Error('Development notices must be outside the project');
+        const info = await stat(directory);
+        if (!info.isDirectory() || process.platform !== 'win32' && (info.mode & 0o077) !== 0)
+            throw new Error('Development notice directory must be private');
+    }
+    else if (options.allowConsoleTokens !== true)
+        throw new Error('Console tokens require explicit allowConsoleTokens');
+    let count = 0;
+    return sender(where, async (message, signal) => {
+        signal.throwIfAborted();
+        if (count >= maximum)
+            throw new Error('Development notice limit reached');
+        count++;
+        const text = JSON.stringify({ development: true, ...message }) + '\n';
+        if (Buffer.byteLength(text) > 4096)
+            throw new Error('Development notice too large');
+        if (directory) {
+            if ((await readdir(directory)).length >= maximum)
+                throw new Error('Development notice directory limit reached');
+            signal.throwIfAborted();
+            const file = await open(join(directory, randomUUID() + '.json'), 'wx', 0o600);
+            try {
+                await file.writeFile(text);
+                await file.sync();
+            }
+            finally {
+                await file.close();
+            }
+        }
+        else {
+            signal.throwIfAborted();
+            (options.write ?? console.log)(text);
+        }
+    });
+}

package/dist/user-query.d.ts

@@ -0,0 +1,28 @@
+import type { DatabaseSync } from 'node:sqlite';
+export interface UserQuery {
+    limit?: number;
+    after?: string;
+    query?: string;
+    status?: 'active' | 'locked' | 'pending-delete';
+    role?: string;
+    method?: 'password' | 'passkey' | 'oidc';
+    verified?: boolean;
+    locale?: string;
+    createdFrom?: number;
+    createdTo?: number;
+    lastSeenFrom?: number;
+    lastSeenTo?: number;
+    sort?: 'id' | 'email' | 'displayName' | 'created' | 'lastSeen';
+    direction?: 'asc' | 'desc';
+}
+export interface ValidatedUserQuery extends UserQuery {
+    limit: number;
+    sort: NonNullable<UserQuery['sort']>;
+    direction: 'asc' | 'desc';
+}
+export declare function validateUserQuery(input?: UserQuery): ValidatedUserQuery;
+/** Reads only stored auth metadata. Sort expressions are fixed; all user values are bound parameters. */
+export declare function queryUsers(db: DatabaseSync, raw: UserQuery): {
+    users: unknown[];
+    next?: string;
+};

package/dist/user-query.js

@@ -0,0 +1,81 @@
+import { createHash, createHmac, randomBytes } from 'node:crypto';
+export function validateUserQuery(input = {}) {
+    if (!input || typeof input !== 'object' || Array.isArray(input) || Object.keys(input).some(key => !['limit', 'after', 'query', 'status', 'role', 'method', 'verified', 'locale', 'createdFrom', 'createdTo', 'lastSeenFrom', 'lastSeenTo', 'sort', 'direction'].includes(key)))
+        throw new Error('Invalid user filter');
+    const result = { ...input, limit: input.limit ?? 50, sort: input.sort ?? 'id', direction: input.direction ?? 'asc' };
+    if (!Number.isInteger(result.limit) || result.limit < 1 || result.limit > 100 || !['id', 'email', 'displayName', 'created', 'lastSeen'].includes(result.sort) || !['asc', 'desc'].includes(result.direction))
+        throw new Error('Invalid user page');
+    if (result.query !== undefined && (typeof result.query !== 'string' || result.query.length > 254 || /[\x00-\x1f\x7f]/.test(result.query)) || result.role !== undefined && (typeof result.role !== 'string' || !/^[a-z][a-z0-9._-]{0,63}$/.test(result.role)) || result.status !== undefined && !['active', 'locked', 'pending-delete'].includes(result.status) || result.method !== undefined && !['password', 'passkey', 'oidc'].includes(result.method) || result.verified !== undefined && typeof result.verified !== 'boolean')
+        throw new Error('Invalid user filter');
+    if (result.locale !== undefined && (typeof result.locale !== 'string' || result.locale.length > 64 || !/^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/.test(result.locale)))
+        throw new Error('Invalid locale filter');
+    for (const key of ['createdFrom', 'createdTo', 'lastSeenFrom', 'lastSeenTo'])
+        if (result[key] !== undefined && (!Number.isSafeInteger(result[key]) || result[key] < 0))
+            throw new Error('Invalid user date');
+    if (result.createdFrom !== undefined && result.createdTo !== undefined && result.createdFrom > result.createdTo || result.lastSeenFrom !== undefined && result.lastSeenTo !== undefined && result.lastSeenFrom > result.lastSeenTo)
+        throw new Error('Invalid user date range');
+    if (result.after !== undefined && (typeof result.after !== 'string' || result.after.length > 1024 || !/^[A-Za-z0-9_-]+$/.test(result.after)))
+        throw new Error('Invalid user cursor');
+    return result;
+}
+function filterHash(input) {
+    const { after: _after, limit: _limit, ...filters } = input;
+    return createHash('sha256').update(JSON.stringify(Object.fromEntries(Object.entries(filters).sort(([a], [b]) => a.localeCompare(b))))).digest('hex');
+}
+// Process-local keys keep identifiers confidential; restarting the worker invalidates live cursors.
+const cursorKeys = new WeakMap();
+function sortHash(db, id, value) {
+    let key = cursorKeys.get(db);
+    if (!key) {
+        key = randomBytes(32);
+        cursorKeys.set(db, key);
+    }
+    return createHmac('sha256', key).update(JSON.stringify([id, value])).digest('hex');
+}
+/** Reads only stored auth metadata. Sort expressions are fixed; all user values are bound parameters. */
+export function queryUsers(db, raw) {
+    const input = validateUserQuery(raw), fingerprint = filterHash(input), where = [], values = [];
+    const add = (sql, ...params) => { where.push(sql); values.push(...params); };
+    if (input.query)
+        add("(instr(lower(email),lower(?))>0 OR instr(lower(display_name),lower(?))>0 OR instr(id,?)>0 OR instr(lower(masked_email),lower(?))>0)", input.query, input.query, input.query, input.query);
+    if (input.status)
+        add('status=?', input.status);
+    if (input.role)
+        add("EXISTS(SELECT 1 FROM json_each(json_extract(data,'$.roles')) WHERE value=?)", input.role);
+    if (input.verified !== undefined)
+        add("COALESCE(json_extract(data,'$.emailVerified'),0)=?", input.verified ? 1 : 0);
+    if (input.locale)
+        add("lower(COALESCE(json_extract(data,'$.profile.locale'),''))=lower(?)", input.locale);
+    if (input.method === 'password')
+        add("length(COALESCE(json_extract(data,'$.passwordHash'),''))>0");
+    if (input.method === 'passkey')
+        add('EXISTS(SELECT 1 FROM auth_passkeys p WHERE p.account_id=observed.id)');
+    if (input.method === 'oidc')
+        add('EXISTS(SELECT 1 FROM auth_external e WHERE e.account_id=observed.id)');
+    for (const [key, column, comparison] of [['createdFrom', 'created', '>='], ['createdTo', 'created', '<='], ['lastSeenFrom', 'last_seen', '>='], ['lastSeenTo', 'last_seen', '<=']])
+        if (input[key] !== undefined)
+            add(`${column}${comparison}?`, input[key]);
+    const column = { id: 'id', email: 'email', displayName: 'display_name', created: 'created', lastSeen: 'last_seen' }[input.sort];
+    const observed = `WITH observed AS (SELECT a.id,a.email,a.status,a.data,COALESCE(json_extract(a.data,'$.profile.displayName'),'') AS display_name,COALESCE(json_extract(a.data,'$.created'),0) AS created,MAX(COALESCE(json_extract(a.data,'$.lastSeen'),0),COALESCE((SELECT MAX(d.last_seen) FROM auth_devices d WHERE d.account_id=a.id),0),COALESCE((SELECT MAX(s.last_seen) FROM auth_sessions s WHERE s.account_id=a.id),0)) AS last_seen,substr(a.email,1,1)||'***'||substr(a.email,instr(a.email,'@')) AS masked_email FROM auth_accounts a)`;
+    if (input.after) {
+        let cursor;
+        try {
+            cursor = JSON.parse(Buffer.from(input.after, 'base64url').toString('utf8'));
+        }
+        catch {
+            throw new Error('Invalid user cursor');
+        }
+        if (!Array.isArray(cursor) || cursor.length !== 3 || cursor[0] !== fingerprint || typeof cursor[1] !== 'string' || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(cursor[1]) || typeof cursor[2] !== 'string' || !/^[a-f0-9]{64}$/.test(cursor[2]))
+            throw new Error('Invalid user cursor');
+        // Keep private sort values on the server. Live pages restart if their boundary changed.
+        const boundary = db.prepare(`${observed} SELECT ${column} AS sort_value FROM observed WHERE id=?`).get(cursor[1]);
+        if (!boundary || sortHash(db, cursor[1], boundary.sort_value) !== cursor[2])
+            throw new Error('Invalid user cursor; restart the user search');
+        const cmp = input.direction === 'asc' ? '>' : '<';
+        add(`(${column}${cmp}? OR (${column}=? AND id${cmp}?))`, boundary.sort_value, boundary.sort_value, cursor[1]);
+    }
+    const direction = input.direction === 'asc' ? 'ASC' : 'DESC';
+    const rows = db.prepare(`${observed} SELECT id,data,last_seen AS observed_last_seen,${column} AS sort_value FROM observed ${where.length ? 'WHERE ' + where.join(' AND ') : ''} ORDER BY ${column} ${direction},id ${direction} LIMIT ?`).all(...values, input.limit + 1);
+    const more = rows.length > input.limit, selected = rows.slice(0, input.limit), last = selected.at(-1);
+    return { users: selected.map(row => ({ ...JSON.parse(String(row.data)), observedLastSeen: Number(row.observed_last_seen) })), ...(more && last ? { next: Buffer.from(JSON.stringify([fingerprint, last.id, sortHash(db, String(last.id), last.sort_value)])).toString('base64url') } : {}) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jimhoyd/urlcode-auth",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.2",
   "type": "module",
   "description": "Operator-installed authentication extension for URLCode: accounts, sessions, passkeys, OIDC, TOTP and trusted account pages",
   "license": "Apache-2.0",