@north-light/crouter 0.3.173 → 0.3.175

package/dist/clients/web/push-registry.js

@@ -1,373 +0,0 @@
-import { createHash } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import webpush from 'web-push';
-import { crtrHome } from '../../core/canvas/paths.js';
-const SCHEMA_VERSION = 1;
-const PUSH_DIR = 'push';
-const BODY_MAX_BYTES = 16 * 1024;
-const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
-const P256DH_MIN_LEN = 20;
-const P256DH_MAX_LEN = 256;
-const AUTH_MIN_LEN = 8;
-const AUTH_MAX_LEN = 128;
-const DEFAULT_VAPID_SUBJECT = 'mailto:push@localhost';
-export class PushRequestError extends Error {
-    statusCode;
-    constructor(statusCode, message) {
-        super(message);
-        this.name = 'PushRequestError';
-        this.statusCode = statusCode;
-    }
-}
-function pushDir() {
-    return join(crtrHome(), PUSH_DIR);
-}
-export function registryPath() {
-    return join(pushDir(), 'registry.json');
-}
-export function lastSeenPath() {
-    return join(pushDir(), 'last-seen.json');
-}
-export function vapidPath() {
-    return join(pushDir(), 'vapid.json');
-}
-export function pushBodyMaxBytes() {
-    return BODY_MAX_BYTES;
-}
-function atomicWriteJson(path, value) {
-    mkdirSync(dirname(path), { recursive: true });
-    const tmp = `${path}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
-    writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
-    renameSync(tmp, path);
-}
-function readJsonFile(path) {
-    return JSON.parse(readFileSync(path, 'utf8'));
-}
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-function isString(value) {
-    return typeof value === 'string';
-}
-function isNumber(value) {
-    return typeof value === 'number';
-}
-function hasOnlyKeys(value, keys) {
-    const allowed = new Set(keys);
-    return Object.keys(value).every((key) => allowed.has(key));
-}
-// SSRF defense for the push endpoint: rather than trying to classify every
-// non-public IP/DNS-rebinding shape (a hand-rolled private-IP blocklist is
-// necessarily incomplete, and a hostname that resolves safely at subscribe
-// time can rebind to loopback/private space before the actual send — a
-// DNS TOCTOU no string/IP check at subscribe time alone can close), we instead
-// allowlist the ENDPOINT HOST itself. Every real Web Push subscription's
-// endpoint is minted by the browser vendor's own push service — there is no
-// self-hosted push service in this deployment's threat model — so restricting
-// outbound sends to that small, known set of hosts means no user/browser-
-// controlled host, IP literal, or DNS name ever reaches the outbound sender.
-// This subsumes the rebinding TOCTOU (only known-good vendor CDN hosts are
-// ever contacted), a trailing-dot bypass (canonicalized away below), and an
-// incomplete IP-range blocklist (no IP literal is ever allowlisted).
-const PUSH_SERVICE_HOST_ALLOWLIST = [
-    'fcm.googleapis.com', // Chromium/Chrome/Edge
-    'android.googleapis.com', // legacy Chrome/Android (GCM)
-    'updates.push.services.mozilla.com', // Firefox
-    'web.push.apple.com', // Safari (macOS/iOS 16.4+)
-    'notify.windows.com', // Windows/legacy Edge (WNS)
-    'wns.windows.com', // Windows/legacy Edge (WNS)
-];
-/** Lowercase and strip trailing DNS root dot(s) (`localhost.` -> `localhost`,
- *  `fcm.googleapis.com.` -> `fcm.googleapis.com`) so a canonicalization gap can
- *  never smuggle a host past a suffix check that only recognizes the
- *  dot-free form. */
-function canonicalizeHostname(hostname) {
-    return hostname.toLowerCase().replace(/\.+$/, '');
-}
-function isAllowedPushHost(hostname) {
-    const host = canonicalizeHostname(hostname);
-    return PUSH_SERVICE_HOST_ALLOWLIST.some((allowed) => host === allowed || host.endsWith(`.${allowed}`));
-}
-/** Re-checkable at any later point (e.g. immediately before an outbound send,
- *  not just at subscribe time) with no dependency on DNS resolution — the
- *  allowlist match is a pure string check, so there is nothing to TOCTOU. */
-export function isAllowedPushEndpoint(endpoint) {
-    let url;
-    try {
-        url = new URL(endpoint);
-    }
-    catch {
-        return false;
-    }
-    return url.protocol === 'https:' && isAllowedPushHost(url.hostname);
-}
-export function normalizeEndpoint(endpoint) {
-    if (!isString(endpoint))
-        throw new PushRequestError(400, 'push endpoint must be a string');
-    const trimmed = endpoint.trim();
-    if (trimmed === '')
-        throw new PushRequestError(400, 'push endpoint must not be empty');
-    let url;
-    try {
-        url = new URL(trimmed);
-    }
-    catch {
-        throw new PushRequestError(400, 'push endpoint is not a valid URL');
-    }
-    if (url.protocol !== 'https:') {
-        throw new PushRequestError(400, 'push endpoint must use https:');
-    }
-    if (url.username !== '' || url.password !== '') {
-        throw new PushRequestError(400, 'push endpoint must not include credentials');
-    }
-    if (!isAllowedPushHost(url.hostname)) {
-        throw new PushRequestError(400, 'push endpoint host is not a recognized push service');
-    }
-    return url.toString();
-}
-export function subscriptionIdForEndpoint(endpoint) {
-    return createHash('sha256').update(endpoint).digest('base64url');
-}
-function normalizeBase64Url(value, field, minLen, maxLen) {
-    if (!isString(value))
-        throw new PushRequestError(400, `push subscription keys.${field} must be a string`);
-    const trimmed = value.trim();
-    if (trimmed.length < minLen || trimmed.length > maxLen) {
-        throw new PushRequestError(400, `push subscription keys.${field} must be between ${minLen} and ${maxLen} characters`);
-    }
-    if (!BASE64URL_RE.test(trimmed)) {
-        throw new PushRequestError(400, `push subscription keys.${field} must be base64url`);
-    }
-    return trimmed;
-}
-function normalizePrefs(value) {
-    if (value === undefined)
-        return { doneNotifications: true };
-    if (!isRecord(value) || !hasOnlyKeys(value, ['doneNotifications'])) {
-        throw new PushRequestError(400, 'push subscription prefs must contain only doneNotifications');
-    }
-    const doneNotifications = value['doneNotifications'];
-    if (doneNotifications === undefined)
-        return { doneNotifications: true };
-    if (typeof doneNotifications !== 'boolean') {
-        throw new PushRequestError(400, 'push subscription prefs.doneNotifications must be boolean');
-    }
-    return { doneNotifications };
-}
-function parsePushBody(rawBody) {
-    if (Buffer.byteLength(rawBody, 'utf8') > BODY_MAX_BYTES) {
-        throw new PushRequestError(413, 'push subscription body is too large');
-    }
-    let parsed;
-    try {
-        parsed = JSON.parse(rawBody);
-    }
-    catch {
-        throw new PushRequestError(400, 'push subscription body is not valid JSON');
-    }
-    if (!isRecord(parsed) || !hasOnlyKeys(parsed, ['endpoint', 'expirationTime', 'keys', 'prefs'])) {
-        throw new PushRequestError(400, 'push subscription body must be a browser PushSubscription shape');
-    }
-    return parsed;
-}
-export function parsePushSubscriptionBody(rawBody, authScope, now = Date.now()) {
-    const parsed = parsePushBody(rawBody);
-    const endpoint = normalizeEndpoint(parsed['endpoint']);
-    const keys = parsed['keys'];
-    if (!isRecord(keys) || !hasOnlyKeys(keys, ['p256dh', 'auth'])) {
-        throw new PushRequestError(400, 'push subscription keys must contain p256dh and auth');
-    }
-    const p256dh = normalizeBase64Url(keys['p256dh'], 'p256dh', P256DH_MIN_LEN, P256DH_MAX_LEN);
-    const auth = normalizeBase64Url(keys['auth'], 'auth', AUTH_MIN_LEN, AUTH_MAX_LEN);
-    const expirationTime = parsed['expirationTime'];
-    if (expirationTime !== undefined && expirationTime !== null && !isNumber(expirationTime)) {
-        throw new PushRequestError(400, 'push subscription expirationTime must be a number or null');
-    }
-    const prefs = normalizePrefs(parsed['prefs']);
-    return {
-        id: subscriptionIdForEndpoint(endpoint),
-        endpoint,
-        keys: { p256dh, auth },
-        authScope,
-        createdAt: now,
-        lastSeenAt: now,
-        prefs,
-    };
-}
-export function parsePushDeleteBody(rawBody) {
-    const parsed = parsePushBody(rawBody);
-    const endpoint = normalizeEndpoint(parsed['endpoint']);
-    return { endpoint };
-}
-function isValidRecord(value) {
-    return (isRecord(value) &&
-        isString(value.id) &&
-        isString(value.endpoint) &&
-        isRecord(value.keys) &&
-        isString(value.keys['p256dh']) &&
-        isString(value.keys['auth']) &&
-        isString(value.authScope) &&
-        isNumber(value.createdAt) &&
-        isNumber(value.lastSeenAt) &&
-        isRecord(value.prefs) &&
-        typeof value.prefs['doneNotifications'] === 'boolean');
-}
-function isValidRegistryFile(value) {
-    return (isRecord(value) &&
-        value.schemaVersion === SCHEMA_VERSION &&
-        Array.isArray(value.records) &&
-        value.records.every(isValidRecord));
-}
-function isValidLastSeenFile(value) {
-    if (!isRecord(value) || value.schemaVersion !== SCHEMA_VERSION || !isNumber(value.updatedAt))
-        return false;
-    if (!isRecord(value.roots))
-        return false;
-    for (const record of Object.values(value.roots)) {
-        if (!isRecord(record) || !isString(record.status) || !isNumber(record.attention_count))
-            return false;
-    }
-    return true;
-}
-function loadRegistryFile(path) {
-    if (!existsSync(path))
-        return { schemaVersion: SCHEMA_VERSION, records: [] };
-    const parsed = readJsonFile(path);
-    if (!isValidRegistryFile(parsed)) {
-        throw new Error(`invalid push registry file: ${path}`);
-    }
-    return parsed;
-}
-function loadLastSeenFile(path) {
-    if (!existsSync(path)) {
-        return { schemaVersion: SCHEMA_VERSION, updatedAt: 0, roots: {} };
-    }
-    const parsed = readJsonFile(path);
-    if (!isValidLastSeenFile(parsed)) {
-        throw new Error(`invalid push last-seen file: ${path}`);
-    }
-    return parsed;
-}
-function isValidVapidFile(value) {
-    return (isRecord(value) &&
-        value.schemaVersion === SCHEMA_VERSION &&
-        isString(value.publicKey) &&
-        isString(value.privateKey) &&
-        isString(value.subject));
-}
-/** Load the persisted VAPID keypair, generating and persisting a fresh one on
- *  first run. One keypair per server identity (design D8/push contract) —
- *  every subscription is signed with the same public key for the life of this
- *  `crtrHome()`. The private key never leaves this file/process. */
-export function loadOrCreateVapidKeypair(path = vapidPath(), subject = DEFAULT_VAPID_SUBJECT) {
-    if (existsSync(path)) {
-        const parsed = readJsonFile(path);
-        if (!isValidVapidFile(parsed)) {
-            throw new Error(`invalid push VAPID keyfile: ${path}`);
-        }
-        return parsed;
-    }
-    const { publicKey, privateKey } = webpush.generateVAPIDKeys();
-    const file = { schemaVersion: SCHEMA_VERSION, publicKey, privateKey, subject };
-    atomicWriteJson(path, file);
-    return file;
-}
-function normalizeStoredRecord(record, existing) {
-    const endpoint = normalizeEndpoint(record.endpoint);
-    const id = subscriptionIdForEndpoint(endpoint);
-    const createdAt = existing?.createdAt ?? record.createdAt;
-    return {
-        id,
-        endpoint,
-        keys: {
-            p256dh: normalizeBase64Url(record.keys.p256dh, 'p256dh', P256DH_MIN_LEN, P256DH_MAX_LEN),
-            auth: normalizeBase64Url(record.keys.auth, 'auth', AUTH_MIN_LEN, AUTH_MAX_LEN),
-        },
-        authScope: record.authScope,
-        createdAt,
-        lastSeenAt: record.lastSeenAt,
-        prefs: { doneNotifications: record.prefs.doneNotifications },
-    };
-}
-export class PushRegistryStore {
-    path;
-    state;
-    byId = new Map();
-    constructor(path = registryPath()) {
-        this.path = path;
-        this.state = loadRegistryFile(path);
-        for (const record of this.state.records) {
-            const normalized = normalizeStoredRecord(record);
-            this.byId.set(normalized.id, normalized);
-        }
-        this.persist();
-    }
-    snapshot() {
-        return [...this.byId.values()];
-    }
-    listByScope(authScope) {
-        return [...this.byId.values()].filter((record) => record.authScope === authScope);
-    }
-    upsert(record) {
-        const normalized = normalizeStoredRecord(record, this.byId.get(record.id));
-        this.byId.set(normalized.id, normalized);
-        this.persist();
-        return normalized;
-    }
-    touchById(id, lastSeenAt) {
-        const existing = this.byId.get(id);
-        if (existing === undefined)
-            return null;
-        const next = { ...existing, lastSeenAt };
-        this.byId.set(id, next);
-        this.persist();
-        return next;
-    }
-    /** Scoped delete for the HTTP DELETE verb: a caller may only remove a
-     *  subscription it owns (its authScope matches the stored record's). Pruning a
-     *  service-reported-gone endpoint is a separate, unscoped path (`deleteById`). */
-    deleteByEndpoint(endpoint, authScope) {
-        const id = subscriptionIdForEndpoint(normalizeEndpoint(endpoint));
-        const existing = this.byId.get(id);
-        if (existing === undefined || existing.authScope !== authScope)
-            return false;
-        return this.deleteById(id);
-    }
-    deleteById(id) {
-        if (!this.byId.delete(id))
-            return false;
-        this.persist();
-        return true;
-    }
-    persist() {
-        this.state = { schemaVersion: SCHEMA_VERSION, records: [...this.byId.values()] };
-        atomicWriteJson(this.path, this.state);
-    }
-}
-export class PushLastSeenStore {
-    path;
-    state;
-    constructor(path = lastSeenPath()) {
-        this.path = path;
-        this.state = loadLastSeenFile(path);
-        this.persist();
-    }
-    snapshot() {
-        return {
-            schemaVersion: this.state.schemaVersion,
-            updatedAt: this.state.updatedAt,
-            roots: { ...this.state.roots },
-        };
-    }
-    replace(next) {
-        if (!isValidLastSeenFile(next)) {
-            throw new Error('attempted to persist an invalid push last-seen snapshot');
-        }
-        this.state = next;
-        this.persist();
-    }
-    persist() {
-        atomicWriteJson(this.path, this.state);
-    }
-}

package/dist/clients/web/server.d.ts

@@ -1,19 +0,0 @@
-export interface WebServerOptions {
-    port: number;
-    host?: string;
-    token?: string;
-    /** --dev: mount a Vite dev server (middleware mode, HMR) for asset serving
-     *  instead of the static dist/web-client/ bundle. The bridge + SSE + WS relay
-     *  are identical in both modes. */
-    dev?: boolean;
-}
-export interface RunningWebServer {
-    url: string;
-    port: number;
-    clientDir: string;
-    close: () => Promise<void>;
-}
-/** Build + start the unified web server. Binds the requested host/port and
- *  resolves once the server is listening. Async because --dev awaits a Vite
- *  middleware server before listening. */
-export declare function startWebServer(opts: WebServerOptions): Promise<RunningWebServer>;