@crouton-kit/crouter 0.3.57 → 0.3.59

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);
+    }
+}

package/dist/clients/web/server.js

@@ -15,6 +15,13 @@
 //                             and relay frames VERBATIM both directions. The relay
 //                             adds NOTHING — the browser is the SAME protocol peer
 //                             as `crtr surface attach`.
+//   • Web push (§push)      → GET  /__crtr/push/vapid-public-key, POST/DELETE
+//                             /__crtr/push/subscribe. A server-side diff engine
+//                             (push-engine.ts) watches the SAME SSE invalidations
+//                             above and sends web-push to a persisted, auth-scoped
+//                             registry (push-registry.ts) — see D8 in the mobile-web
+//                             design. Behind the identical auth boundary as the rest
+//                             of this server.
 //
 // §0 ONE-WRITER INVARIANT: the WS relay is ONLY a socket relay. It NEVER calls
 // reviveNode, NEVER spawns `pi --session`, NEVER touches SessionManager, and
@@ -29,10 +36,12 @@
 // clients) — the broker fans out natively, so there is no bridge-side fan-out.
 import { createServer as createHttpServer } from 'node:http';
 import { createConnection, isIP } from 'node:net';
+import { createHash } from 'node:crypto';
 import { createReadStream, existsSync, statSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, extname, join, normalize, resolve } from 'node:path';
 import { WebSocketServer } from 'ws';
+import webpush from 'web-push';
 import { viewSocketPath } from '../../core/canvas/paths.js';
 import { getNode } from '../../core/canvas/index.js';
 import { BROKER_READ_CAPS, CLIENT_READ_CAPS, FrameDecoder, FrameOverflowError, } from '../../core/runtime/broker-protocol.js';
@@ -41,9 +50,13 @@ import { clearFault, recordFault } from '../../core/runtime/fault.js';
 import { createLocalTransport } from '../../core/view/transport-local.js';
 import { createBurstCoalescingTransport } from '../../core/view/transport-cache.js';
 import { runSourceRequest } from '../../core/view/bridge.js';
+import { canvasSnapshotLeaf } from '../../commands/canvas-snapshot.js';
+import { humanList } from '../../commands/human/queue.js';
 import { startEventHub } from './events.js';
 import { createDevServer } from './dev-server.js';
 import { SOURCE_CACHE_TTL_MS, isCoalescableSourceRequest } from './source-cache.js';
+import { PushLastSeenStore, PushRegistryStore, PushRequestError, loadOrCreateVapidKeypair, parsePushDeleteBody, parsePushSubscriptionBody, pushBodyMaxBytes, } from './push-registry.js';
+import { PushDiffEngine } from './push-engine.js';
 const HERE = dirname(fileURLToPath(import.meta.url));
 /** Candidate dirs to serve the shell SPA bundle from, in priority order: an
  *  explicit override, the compiled-module-relative `dist/web-client/` (what
@@ -158,6 +171,32 @@ function readBody(req) {
         req.on('error', rej);
     });
 }
+/** Like `readBody`, but aborts the moment the accumulated body exceeds
+ *  `maxBytes` — so a push endpoint never buffers arbitrary attacker memory
+ *  before validation rejects it. Rejects with PushRequestError(413), which the
+ *  push error handler maps to a 413 response. */
+function readBodyCapped(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let total = 0;
+        req.on('data', (c) => {
+            total += c.length;
+            if (total > maxBytes) {
+                reject(new PushRequestError(413, 'push subscription body is too large'));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        req.on('error', reject);
+    });
+}
+/** Derive the persisted auth scope from a bearer token: a short, stable hash so
+ *  the raw secret never touches disk. */
+function scopeForToken(secret) {
+    return `token:${createHash('sha256').update(secret).digest('base64url').slice(0, 16)}`;
+}
 /** Serve a static file from the client dir, with SPA fallback to index.html for
  *  any unmatched (non-asset) GET — so `/` and `/node/<id>` both boot the app
  *  shell. Returns true if it wrote a response. */
@@ -385,13 +424,92 @@ export async function startWebServer(opts) {
             return true;
         return allowedOrigins.has(origin);
     };
-    const requestAllowed = (req) => {
-        if (requestTokenMatches(req, token))
-            return true;
+    const authorizeRequest = (req) => {
+        if (token !== undefined && requestTokenMatches(req, token)) {
+            return { allowed: true, scope: scopeForToken(token) };
+        }
         if (tokenRequired)
-            return false;
-        return originAllowed(req.headers.origin);
+            return { allowed: false };
+        if (!originAllowed(req.headers.origin))
+            return { allowed: false };
+        return { allowed: true, scope: 'local' };
     };
+    // The set of auth scopes this server actually authorizes — the push diff
+    // engine sends ONLY to subscriptions whose authScope is in this set (design
+    // line 252: identical boundary to /__crtr/source). Mirrors authorizeRequest:
+    // a token authorizes scopeForToken(token); a tokenless request is authorized
+    // only when !tokenRequired, as scope 'local'. A record left by a rotated/old
+    // token has a different digest and is therefore excluded.
+    const targetScopes = new Set();
+    if (token !== undefined)
+        targetScopes.add(scopeForToken(token));
+    if (!tokenRequired)
+        targetScopes.add('local');
+    // §push — the server-side web-push registry + diff engine (design D8). One
+    // persisted, auth-scoped subscription registry; one locally-generated VAPID
+    // identity signing every send; one diff engine that re-reads canvas+decks on
+    // the SAME SSE invalidations the browser clients get (via eventHub.subscribe,
+    // no HTTP self-loop) and pushes 'done'/'needs-you' notifications.
+    const pushRegistry = new PushRegistryStore();
+    const pushLastSeen = new PushLastSeenStore();
+    const vapid = loadOrCreateVapidKeypair();
+    webpush.setVapidDetails(vapid.subject, vapid.publicKey, vapid.privateKey);
+    // Page through every pending human ask, keeping only entries with the deck
+    // provenance (job + conversation) the payload/dedupe logic needs.
+    const collectPendingAsks = async () => {
+        const out = [];
+        let cursor;
+        for (let page = 0; page < 50; page++) {
+            const result = (await humanList.run({
+                limit: 100,
+                ...(cursor !== undefined ? { cursor } : {}),
+            }));
+            for (const item of result.items) {
+                if (item.job_id === undefined || item.conversation_id === undefined)
+                    continue;
+                out.push({
+                    id: item.id,
+                    jobId: item.job_id,
+                    title: item.title ?? item.job_id,
+                    conversationId: item.conversation_id,
+                    conversationTitle: item.conversation_title ?? item.conversation_id,
+                    blockedSince: item.blocked_since,
+                });
+            }
+            if (result.next_cursor === null)
+                break;
+            cursor = result.next_cursor;
+        }
+        return out;
+    };
+    const pushEngine = new PushDiffEngine({
+        registry: pushRegistry,
+        lastSeen: pushLastSeen,
+        readCanvasNodes: async () => {
+            const snap = (await canvasSnapshotLeaf.run({}));
+            return snap.nodes;
+        },
+        readPendingAsks: collectPendingAsks,
+        isTargetScope: (s) => targetScopes.has(s),
+        sendPush: async (record, payload) => {
+            try {
+                await webpush.sendNotification({ endpoint: record.endpoint, keys: record.keys }, JSON.stringify(payload));
+                return 'sent';
+            }
+            catch (err) {
+                const statusCode = err.statusCode;
+                return statusCode === 404 || statusCode === 410 ? 'gone' : 'error';
+            }
+        },
+    });
+    // A restart is not an attention event — record current state, send nothing.
+    await pushEngine.seed();
+    const unsubscribePush = eventHub.subscribe((kind) => {
+        if (kind === 'nodes')
+            void pushEngine.onNodesInvalidation();
+        else if (kind === 'inbox')
+            void pushEngine.onInboxInvalidation();
+    });
     // Assigned before listen() when --dev; the request handler closes over it.
     let vite;
     const httpServer = createHttpServer((req, res) => {
@@ -408,7 +526,7 @@ export async function startWebServer(opts) {
                     res.end('method not allowed\n');
                     return;
                 }
-                if (!requestAllowed(req)) {
+                if (!authorizeRequest(req).allowed) {
                     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
                     res.end('forbidden\n');
                     return;
@@ -434,7 +552,7 @@ export async function startWebServer(opts) {
                     res.end('method not allowed\n');
                     return;
                 }
-                if (!requestAllowed(req)) {
+                if (!authorizeRequest(req).allowed) {
                     res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
                     res.end('forbidden\n');
                     return;
@@ -442,6 +560,70 @@ export async function startWebServer(opts) {
                 eventHub.addClient(res);
                 return;
             }
+            // §push — the VAPID public key a browser needs to subscribe. Read-only,
+            // non-secret, but behind the same auth boundary as everything else so a
+            // foreign page can't even enumerate the surface.
+            if (pathname === '/__crtr/push/vapid-public-key') {
+                if (req.method !== 'GET') {
+                    res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'GET' });
+                    res.end('method not allowed\n');
+                    return;
+                }
+                if (!authorizeRequest(req).allowed) {
+                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('forbidden\n');
+                    return;
+                }
+                res.writeHead(200, { 'content-type': 'application/json' });
+                res.end(JSON.stringify({ publicKey: vapid.publicKey }));
+                return;
+            }
+            // §push — subscribe (POST) / unsubscribe (DELETE). Validation lives in
+            // parsePush*Body, which rejects oversized/malformed/private/http/file
+            // shapes BEFORE any persistence, throwing PushRequestError with a status.
+            if (pathname === '/__crtr/push/subscribe') {
+                const auth = authorizeRequest(req);
+                if (!auth.allowed) {
+                    res.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+                    res.end('forbidden\n');
+                    return;
+                }
+                const handlePushError = (e) => {
+                    if (e instanceof PushRequestError) {
+                        res.writeHead(e.statusCode, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: false, error: e.message }));
+                        return;
+                    }
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }));
+                };
+                if (req.method === 'POST') {
+                    void readBodyCapped(req, pushBodyMaxBytes())
+                        .then((body) => {
+                        const record = parsePushSubscriptionBody(body, auth.scope);
+                        const stored = pushRegistry.upsert(record);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true, id: stored.id, authScope: stored.authScope }));
+                    })
+                        .catch(handlePushError);
+                    return;
+                }
+                if (req.method === 'DELETE') {
+                    void readBodyCapped(req, pushBodyMaxBytes())
+                        .then((body) => {
+                        const { endpoint } = parsePushDeleteBody(body);
+                        // Scoped: a caller may only delete a subscription it owns.
+                        const deleted = pushRegistry.deleteByEndpoint(endpoint, auth.scope);
+                        res.writeHead(200, { 'content-type': 'application/json' });
+                        res.end(JSON.stringify({ ok: true, deleted }));
+                    })
+                        .catch(handlePushError);
+                    return;
+                }
+                res.writeHead(405, { 'content-type': 'text/plain; charset=utf-8', allow: 'POST, DELETE' });
+                res.end('method not allowed\n');
+                return;
+            }
             // --dev: Vite middleware owns all remaining asset/HTML serving (incl. its
             // own SPA fallback). It is mounted AFTER the bridge + SSE checks above, so
             // those never fall through to Vite.
@@ -490,7 +672,7 @@ export async function startWebServer(opts) {
                 socket.destroy();
                 return;
             }
-            if (!requestAllowed(req)) {
+            if (!authorizeRequest(req).allowed) {
                 socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
                 socket.destroy();
                 return;
@@ -533,6 +715,7 @@ export async function startWebServer(opts) {
                 `http://localhost:${port}`,
             ]);
             const close = () => new Promise((done) => {
+                unsubscribePush();
                 eventHub.close();
                 void vite?.close().catch(() => {
                     /* best-effort */