@crouton-kit/crouter 0.3.57 → 0.3.58

package/dist/clients/web/push-registry.d.ts

@@ -0,0 +1,89 @@
+import type { NodeLifeStatus } from './web-client/shared/protocol.js';
+export interface PushPreferences {
+    doneNotifications: boolean;
+}
+export interface PushSubscriptionRecord {
+    id: string;
+    endpoint: string;
+    keys: {
+        p256dh: string;
+        auth: string;
+    };
+    authScope: string;
+    createdAt: number;
+    lastSeenAt: number;
+    prefs: PushPreferences;
+}
+export interface PushRegistryFile {
+    schemaVersion: number;
+    records: PushSubscriptionRecord[];
+}
+export interface PushLastSeenRootState {
+    status: NodeLifeStatus;
+    attention_count: number;
+}
+export interface PushLastSeenAskState {
+    present: boolean;
+}
+export interface PushLastSeenFile {
+    schemaVersion: number;
+    updatedAt: number;
+    roots: Record<string, PushLastSeenRootState>;
+    asks: Record<string, PushLastSeenAskState>;
+}
+/** A locally generated VAPID keypair, persisted so the same identity signs
+ *  every outbound push across restarts. The private key never leaves this
+ *  file/process — only `publicKey` is ever served to a client. */
+export interface VapidKeypairFile {
+    schemaVersion: number;
+    publicKey: string;
+    privateKey: string;
+    subject: string;
+}
+export declare class PushRequestError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare function registryPath(): string;
+export declare function lastSeenPath(): string;
+export declare function vapidPath(): string;
+export declare function pushBodyMaxBytes(): number;
+/** 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 declare function isAllowedPushEndpoint(endpoint: string): boolean;
+export declare function normalizeEndpoint(endpoint: unknown): string;
+export declare function subscriptionIdForEndpoint(endpoint: string): string;
+export declare function parsePushSubscriptionBody(rawBody: string, authScope: string, now?: number): PushSubscriptionRecord;
+export declare function parsePushDeleteBody(rawBody: string): {
+    endpoint: string;
+};
+/** 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 declare function loadOrCreateVapidKeypair(path?: string, subject?: string): VapidKeypairFile;
+export declare class PushRegistryStore {
+    private readonly path;
+    private state;
+    private readonly byId;
+    constructor(path?: string);
+    snapshot(): PushSubscriptionRecord[];
+    listByScope(authScope: string): PushSubscriptionRecord[];
+    upsert(record: PushSubscriptionRecord): PushSubscriptionRecord;
+    touchById(id: string, lastSeenAt: number): PushSubscriptionRecord | null;
+    /** 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: string, authScope: string): boolean;
+    deleteById(id: string): boolean;
+    private persist;
+}
+export declare class PushLastSeenStore {
+    private readonly path;
+    private state;
+    constructor(path?: string);
+    snapshot(): PushLastSeenFile;
+    replace(next: PushLastSeenFile): void;
+    private persist;
+}

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

@@ -0,0 +1,378 @@
+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) || !isRecord(value.asks))
+        return false;
+    for (const record of Object.values(value.roots)) {
+        if (!isRecord(record) || !isString(record.status) || !isNumber(record.attention_count))
+            return false;
+    }
+    for (const record of Object.values(value.asks)) {
+        if (!isRecord(record) || typeof record.present !== 'boolean')
+            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: {}, asks: {} };
+    }
+    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 },
+            asks: { ...this.state.asks },
+        };
+    }
+    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);
+    }
+}