@crouton-kit/crouter 0.3.57 → 0.3.59

package/dist/clients/web/__tests__/push-engine.test.js

@@ -0,0 +1,302 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { PushDiffEngine } from '../push-engine.js';
+import { PushLastSeenStore, PushRegistryStore } from '../push-registry.js';
+function tmpDir() {
+    return mkdtempSync(join(tmpdir(), 'crtr-push-engine-'));
+}
+function makeStores(dir) {
+    return {
+        registry: new PushRegistryStore(join(dir, 'registry.json')),
+        lastSeen: new PushLastSeenStore(join(dir, 'last-seen.json')),
+    };
+}
+// A real, allowlisted vendor push-service endpoint shape (Chromium/FCM) —
+// endpoints must resolve to one of the small set of known browser-vendor push
+// services (see push-registry.ts's PUSH_SERVICE_HOST_ALLOWLIST).
+function fakeSubscription(id, authScope = 'local') {
+    return {
+        id,
+        endpoint: `https://fcm.googleapis.com/fcm/send/${id}`,
+        keys: { p256dh: 'p'.repeat(32), auth: 'a'.repeat(16) },
+        authScope,
+        createdAt: 0,
+        lastSeenAt: 0,
+        prefs: { doneNotifications: true },
+    };
+}
+/** Seed a registry with one subscription directly (bypassing HTTP validation,
+ *  which is covered in push-registry.test.ts). */
+function seedRegistryWithOneSubscription(registry) {
+    registry.upsert(fakeSubscription('sub-1'));
+}
+function buildHarness(dir, opts = {}) {
+    const { registry, lastSeen } = makeStores(dir);
+    const sent = [];
+    const sentTo = [];
+    const nodes = [];
+    const asks = [];
+    const clock = { now: 1_000_000 };
+    const defaultSend = async (record, payload) => {
+        sent.push(payload);
+        sentTo.push(record.endpoint);
+        return 'sent';
+    };
+    const engine = new PushDiffEngine({
+        registry,
+        lastSeen,
+        readCanvasNodes: () => nodes,
+        readPendingAsks: () => asks,
+        sendPush: opts.sendPush ?? defaultSend,
+        isTargetScope: opts.isTargetScope ?? (() => true),
+        now: () => clock.now,
+        rateWindowMs: opts.rateWindowMs,
+    });
+    return { engine, sent, sentTo, registry, lastSeen, nodes, asks, clock };
+}
+test('seed() sends nothing regardless of current state (no restart storm)', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir);
+        seedRegistryWithOneSubscription(h.registry);
+        h.nodes.push({ node_id: 'root-1', parent: null, status: 'done', attention_count: 0 });
+        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
+        await h.engine.seed();
+        assert.equal(h.sent.length, 0);
+        const snap = h.lastSeen.snapshot();
+        assert.deepEqual(snap.roots['root-1'], { status: 'done', attention_count: 0 });
+        assert.deepEqual(snap.asks['ask-1'], { present: true });
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('active -> done emits exactly one done push, and a repeat pass does not duplicate', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir);
+        seedRegistryWithOneSubscription(h.registry);
+        h.nodes.push({ node_id: 'root-1', parent: null, status: 'active', attention_count: 0 });
+        await h.engine.seed();
+        assert.equal(h.sent.length, 0);
+        h.nodes[0].status = 'done';
+        await h.engine.onNodesInvalidation();
+        assert.equal(h.sent.length, 1);
+        assert.equal(h.sent[0].kind, 'done');
+        assert.equal(h.sent[0].conversationId, 'root-1');
+        // Repeated invalidation with the same (already-done) status must not re-fire.
+        await h.engine.onNodesInvalidation();
+        assert.equal(h.sent.length, 1);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a new ask emits exactly one needs-you push, and repeated invalidations do not duplicate it', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir);
+        seedRegistryWithOneSubscription(h.registry);
+        await h.engine.seed(); // no asks yet
+        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1);
+        assert.equal(h.sent[0].kind, 'needs-you');
+        assert.equal(h.sent[0].askId, 'job-1');
+        // Same ask still pending on a second invalidation — no duplicate.
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a resolved/missing ask never notifies', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir);
+        seedRegistryWithOneSubscription(h.registry);
+        await h.engine.seed();
+        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1);
+        // The ask resolves — it disappears from the pending list.
+        h.asks.length = 0;
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1); // no new push
+        assert.deepEqual(h.lastSeen.snapshot().asks, {});
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('multiple new asks in the same conversation within the rate window coalesce into one push', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir, { rateWindowMs: 30_000 });
+        seedRegistryWithOneSubscription(h.registry);
+        await h.engine.seed();
+        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' }, { id: 'ask-2', jobId: 'job-2', title: 'Approve deploy', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:01.000Z' });
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1);
+        assert.match(h.sent[0].snippet, /\+1 more/);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('push targeting is scope-filtered: only subscriptions on the watched auth boundary are sent to', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir, { isTargetScope: (s) => s === 'token:abc' });
+        // One local-scope sub and one token-scope sub in the SAME registry.
+        h.registry.upsert(fakeSubscription('sub-local', 'local'));
+        h.registry.upsert(fakeSubscription('sub-token', 'token:abc'));
+        h.nodes.push({ node_id: 'root-1', parent: null, status: 'active', attention_count: 0 });
+        await h.engine.seed();
+        h.nodes[0].status = 'done';
+        await h.engine.onNodesInvalidation();
+        // Exactly one send, and it went to the token-scoped endpoint only.
+        assert.equal(h.sent.length, 1);
+        assert.deepEqual(h.sentTo, ['https://fcm.googleapis.com/fcm/send/sub-token']);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a transient send failure does not advance last-seen and is retried next pass', async () => {
+    const dir = tmpDir();
+    try {
+        let call = 0;
+        const attempts = [];
+        const h = buildHarness(dir, {
+            rateWindowMs: 30_000,
+            sendPush: async (_r, payload) => {
+                attempts.push(payload);
+                call += 1;
+                return call === 1 ? 'error' : 'sent';
+            },
+        });
+        seedRegistryWithOneSubscription(h.registry);
+        h.nodes.push({ node_id: 'root-1', parent: null, status: 'active', attention_count: 0 });
+        await h.engine.seed();
+        h.nodes[0].status = 'done';
+        await h.engine.onNodesInvalidation();
+        // The send was attempted but failed transiently — last-seen root must stay
+        // pre-transition ('active') so the edge is re-detected next pass.
+        assert.equal(attempts.length, 1);
+        assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'active');
+        // Advance past the rate window (the failed pass set lastPushAt) and retry.
+        h.clock.now += 60_000;
+        await h.engine.onNodesInvalidation();
+        assert.equal(attempts.length, 2);
+        assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'done');
+        // A further pass does not re-fire.
+        h.clock.now += 60_000;
+        await h.engine.onNodesInvalidation();
+        assert.equal(attempts.length, 2);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a transient failure on one subscription does not cause a retry to re-send to an already-delivered subscription', async () => {
+    const dir = tmpDir();
+    try {
+        // Keyed by endpoint, not `record.id` — upsert() derives the persisted id
+        // from `subscriptionIdForEndpoint(endpoint)`, discarding the fixture's
+        // caller-supplied id, so the endpoint is the stable fixture identity here.
+        const attemptsBySub = new Map();
+        const h = buildHarness(dir, {
+            rateWindowMs: 30_000,
+            sendPush: async (record, _payload) => {
+                const n = (attemptsBySub.get(record.endpoint) ?? 0) + 1;
+                attemptsBySub.set(record.endpoint, n);
+                // sub-ok always succeeds; sub-fail fails transiently on its first
+                // attempt only, then succeeds on retry — so the second pass proves
+                // sub-ok is never touched again while sub-fail finally lands.
+                return record.endpoint.includes('sub-fail') && n === 1 ? 'error' : 'sent';
+            },
+        });
+        h.registry.upsert(fakeSubscription('sub-ok'));
+        h.registry.upsert(fakeSubscription('sub-fail'));
+        h.nodes.push({ node_id: 'root-1', parent: null, status: 'active', attention_count: 0 });
+        await h.engine.seed();
+        h.nodes[0].status = 'done';
+        await h.engine.onNodesInvalidation();
+        // Both subscriptions were attempted once; the event is not fully delivered
+        // (sub-fail errored), so last-seen must stay pre-transition.
+        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-ok'), 1);
+        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-fail'), 1);
+        assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'active');
+        // Retry next pass (past the rate window): sub-ok must NOT be re-sent to —
+        // only sub-fail, which never succeeded, is retried.
+        h.clock.now += 60_000;
+        await h.engine.onNodesInvalidation();
+        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-ok'), 1, 'an already-delivered subscription must not be re-sent to on retry');
+        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-fail'), 2);
+        assert.equal(h.lastSeen.snapshot().roots['root-1'].status, 'done');
+        // Fully delivered now — a further pass does not re-fire for anyone.
+        h.clock.now += 60_000;
+        await h.engine.onNodesInvalidation();
+        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-ok'), 1);
+        assert.equal(attemptsBySub.get('https://fcm.googleapis.com/fcm/send/sub-fail'), 2);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('overlapping inbox invalidations serialize — each distinct ask notifies exactly once', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir);
+        seedRegistryWithOneSubscription(h.registry);
+        await h.engine.seed();
+        // First invalidation kicked off but NOT awaited; a second ask + invalidation
+        // land while the first pass is in-flight. The drain queue must serialize
+        // them so neither ask is notified twice.
+        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
+        const p1 = h.engine.onInboxInvalidation();
+        h.asks.push({ id: 'ask-2', jobId: 'job-2', title: 'Approve deploy', conversationId: 'root-2', conversationTitle: 'Root Two', blockedSince: '2026-01-01T00:00:01.000Z' });
+        const p2 = h.engine.onInboxInvalidation();
+        await Promise.all([p1, p2]);
+        const askIds = h.sent.map((p) => p.askId).sort();
+        assert.deepEqual(askIds, ['job-1', 'job-2']);
+        assert.deepEqual(Object.keys(h.lastSeen.snapshot().asks).sort(), ['ask-1', 'ask-2']);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('a rate-capped ask is suppressed within the window then retried once it clears — never lost, never duplicated', async () => {
+    const dir = tmpDir();
+    try {
+        const h = buildHarness(dir, { rateWindowMs: 30_000 });
+        seedRegistryWithOneSubscription(h.registry);
+        await h.engine.seed();
+        h.asks.push({ id: 'ask-1', jobId: 'job-1', title: 'Pick a color', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:00.000Z' });
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1); // first ask fires immediately
+        // A second, distinct ask lands in the same conversation moments later —
+        // still inside the rate window, so it must be suppressed, not sent.
+        h.asks.push({ id: 'ask-2', jobId: 'job-2', title: 'Approve deploy', conversationId: 'root-1', conversationTitle: 'Root One', blockedSince: '2026-01-01T00:00:05.000Z' });
+        h.clock.now += 5_000;
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 1); // still suppressed
+        assert.equal(h.lastSeen.snapshot().asks['ask-2'], undefined); // left untracked so it retries
+        // Once the rate window clears, the still-pending ask-2 is retried exactly once.
+        h.clock.now += 30_000;
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 2);
+        assert.equal(h.sent[1].askId, 'job-2');
+        // And it never fires a third time on a further no-op pass.
+        await h.engine.onInboxInvalidation();
+        assert.equal(h.sent.length, 2);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});

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

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,177 @@
+import assert from 'node:assert/strict';
+import { createHash } from 'node:crypto';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { PushRegistryStore, PushRequestError, isAllowedPushEndpoint, parsePushDeleteBody, parsePushSubscriptionBody, pushBodyMaxBytes, subscriptionIdForEndpoint, } from '../push-registry.js';
+function tmpDir() {
+    return mkdtempSync(join(tmpdir(), 'crtr-push-registry-'));
+}
+// A real, allowlisted vendor push-service endpoint shape (Chromium/FCM) —
+// endpoints must resolve to one of the small set of known browser-vendor push
+// services; arbitrary hosts (including this suite's old `push.example.com`
+// placeholder) are no longer accepted.
+const VALID_ENDPOINT = 'https://fcm.googleapis.com/fcm/send/abc123';
+const VALID_P256DH = 'p'.repeat(64);
+const VALID_AUTH = 'a'.repeat(22);
+function validBody(overrides = {}) {
+    return JSON.stringify({
+        endpoint: VALID_ENDPOINT,
+        keys: { p256dh: VALID_P256DH, auth: VALID_AUTH },
+        ...overrides,
+    });
+}
+test('a well-formed subscription body parses and persists behind a scoped, non-secret authScope', () => {
+    const dir = tmpDir();
+    try {
+        const record = parsePushSubscriptionBody(validBody(), 'token:deadbeef');
+        assert.equal(record.endpoint, VALID_ENDPOINT);
+        assert.equal(record.authScope, 'token:deadbeef');
+        assert.equal(record.id, subscriptionIdForEndpoint(VALID_ENDPOINT));
+        assert.equal(record.prefs.doneNotifications, true);
+        const registry = new PushRegistryStore(join(dir, 'registry.json'));
+        registry.upsert(record);
+        assert.equal(registry.listByScope('token:deadbeef').length, 1);
+        // The persisted file never carries a raw bearer token \u2014 only the derived
+        // scope string, which is exactly what was passed in above.
+        const onDisk = readFileSync(join(dir, 'registry.json'), 'utf8');
+        assert.ok(onDisk.includes('token:deadbeef'));
+        assert.ok(!onDisk.toLowerCase().includes('bearer'));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('the registry persists only the derived scope digest, never the raw token pre-image', () => {
+    const dir = tmpDir();
+    try {
+        // Mirror scopeForToken (server.ts): scope = 'token:' + sha256(raw).base64url[:16].
+        const raw = 'SUPERSECRET-TOKEN-VALUE';
+        const scope = `token:${createHash('sha256').update(raw).digest('base64url').slice(0, 16)}`;
+        const record = parsePushSubscriptionBody(validBody(), scope);
+        const registry = new PushRegistryStore(join(dir, 'registry.json'));
+        registry.upsert(record);
+        const onDisk = readFileSync(join(dir, 'registry.json'), 'utf8');
+        assert.ok(onDisk.includes(scope));
+        assert.ok(!onDisk.includes(raw));
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('rejects IPv6 and v4-mapped private/localhost endpoints before persistence', () => {
+    for (const endpoint of [
+        'https://[::1]/x',
+        'https://[fc00::1]/x',
+        'https://[fe80::1]/x',
+        'https://[::ffff:127.0.0.1]/x',
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+    }
+});
+test('the endpoint host must be an allowlisted push service — an arbitrary host is rejected even over https', () => {
+    for (const endpoint of [
+        'https://push.example.com/abc123', // not a recognized push-service host
+        'https://evil.attacker.example/abc123',
+        'https://fcm.googleapis.com.attacker.example/abc123', // suffix-spoof attempt
+        'https://notgooglapis.com/fcm/send/abc123',
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+        assert.equal(isAllowedPushEndpoint(endpoint), false, endpoint);
+    }
+});
+test('a trailing DNS root dot never bypasses the allowlist/localhost check', () => {
+    for (const endpoint of ['https://localhost./x', 'https://foo.localhost./x', 'https://fcm.googleapis.com./fcm/send/abc']) {
+        // The last one is a real allowlisted host WITH a trailing dot: it must
+        // canonicalize to the same allowed match, not be rejected as a foreign
+        // host, and localhost-with-trailing-dot must still be rejected.
+        if (endpoint.includes('localhost')) {
+            assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+        }
+        else {
+            assert.doesNotThrow(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), endpoint);
+        }
+    }
+});
+test('the private/reserved IP ranges the old blocklist missed are moot under the allowlist — no IP literal is ever allowed', () => {
+    for (const endpoint of [
+        'https://0.0.0.0/x', // 0.0.0.0/8
+        'https://100.64.0.1/x', // CGNAT 100.64.0.0/10
+        'https://192.0.0.1/x', // 192.0.0.0/24
+        'https://198.18.0.1/x', // 198.18.0.0/15
+        'https://240.0.0.1/x', // 240.0.0.0/4
+        'https://224.0.0.1/x', // multicast
+        'https://[::]/x', // IPv6 unspecified
+        'https://[fe90::1]/x', // fe80::/10, beyond the fe80* prefix
+        'https://[ff02::1]/x', // IPv6 multicast
+        'https://8.8.8.8/x', // a genuinely PUBLIC IP — still not allowlisted
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+    }
+});
+test('every real browser-vendor push-service endpoint shape is allowlisted, including a subdomain form', () => {
+    for (const endpoint of [
+        'https://fcm.googleapis.com/fcm/send/abc123',
+        'https://android.googleapis.com/gcm/send/abc123',
+        'https://updates.push.services.mozilla.com/wpush/v2/abc123',
+        'https://web.push.apple.com/abc123',
+        'https://notify.windows.com/w/abc123',
+        'https://sub.notify.windows.com/w/abc123',
+        'https://wns.windows.com/w/abc123',
+        'https://sub.wns.windows.com/w/abc123',
+    ]) {
+        assert.equal(isAllowedPushEndpoint(endpoint), true, endpoint);
+        assert.doesNotThrow(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), endpoint);
+    }
+});
+test('deleteByEndpoint is scoped: a caller can only remove a subscription it owns', () => {
+    const dir = tmpDir();
+    try {
+        const registry = new PushRegistryStore(join(dir, 'registry.json'));
+        registry.upsert(parsePushSubscriptionBody(validBody(), 'scope-A'));
+        assert.equal(registry.deleteByEndpoint(VALID_ENDPOINT, 'scope-B'), false);
+        assert.equal(registry.listByScope('scope-A').length, 1);
+        assert.equal(registry.deleteByEndpoint(VALID_ENDPOINT, 'scope-A'), true);
+        assert.equal(registry.listByScope('scope-A').length, 0);
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+});
+test('rejects a malformed body shape (unknown keys, missing fields)', () => {
+    assert.throws(() => parsePushSubscriptionBody(JSON.stringify({ endpoint: VALID_ENDPOINT }), 'local'), PushRequestError);
+    assert.throws(() => parsePushSubscriptionBody(JSON.stringify({ endpoint: VALID_ENDPOINT, keys: { p256dh: VALID_P256DH, auth: VALID_AUTH }, extra: 'nope' }), 'local'), PushRequestError);
+    assert.throws(() => parsePushSubscriptionBody('not json', 'local'), PushRequestError);
+});
+test('rejects an oversized body before persistence', () => {
+    const oversized = validBody({ prefs: { doneNotifications: true, pad: 'x'.repeat(pushBodyMaxBytes()) } });
+    assert.throws(() => parsePushSubscriptionBody(oversized, 'local'), PushRequestError);
+});
+test('rejects private/localhost/file/http endpoints before persistence', () => {
+    for (const endpoint of [
+        'http://push.example.com/abc', // not https
+        'https://localhost/abc',
+        'https://127.0.0.1/abc',
+        'https://10.0.0.5/abc',
+        'https://192.168.1.5/abc',
+        'file:///etc/passwd',
+        'not-a-url',
+    ]) {
+        assert.throws(() => parsePushSubscriptionBody(validBody({ endpoint }), 'local'), PushRequestError, endpoint);
+    }
+});
+test('rejects malformed base64url subscription keys', () => {
+    assert.throws(() => parsePushSubscriptionBody(validBody({ keys: { p256dh: 'not base64url!!', auth: VALID_AUTH } }), 'local'), PushRequestError);
+    assert.throws(() => parsePushSubscriptionBody(validBody({ keys: { p256dh: VALID_P256DH, auth: 'short' } }), 'local'), PushRequestError);
+});
+test('DELETE body parses down to just the endpoint', () => {
+    const { endpoint } = parsePushDeleteBody(JSON.stringify({ endpoint: VALID_ENDPOINT }));
+    assert.equal(endpoint, VALID_ENDPOINT);
+    assert.throws(() => parsePushDeleteBody(JSON.stringify({ endpoint: 'https://localhost/x' })), PushRequestError);
+});
+test('the id is a stable hash of the normalized endpoint, independent of scope', () => {
+    const a = parsePushSubscriptionBody(validBody(), 'local');
+    const b = parsePushSubscriptionBody(validBody(), 'token:other');
+    assert.equal(a.id, b.id);
+});

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

@@ -4,6 +4,11 @@ export interface EventHub {
     /** Register an SSE client: writes the event-stream headers, streams events
      *  until the connection closes, and self-removes on close. */
     addClient: (res: ServerResponse) => void;
+    /** Internal, in-process subscription to the same invalidations SSE clients
+     *  receive — for a server-side consumer (the push diff engine) that needs
+     *  the trigger without opening an HTTP/SSE connection to itself. Returns an
+     *  unsubscribe function. */
+    subscribe: (listener: (kind: ChangeKind) => void) => () => void;
     /** Tear down watchers + heartbeat and end all open streams. */
     close: () => void;
 }

package/dist/clients/web/events.js

@@ -36,6 +36,7 @@ export function startEventHub() {
     const clients = new Set();
     const watchers = [];
     const timers = new Map();
+    const listeners = new Set();
     const broadcast = (kind) => {
         const line = `data: ${JSON.stringify({ kind, ts: Date.now() })}\n\n`;
         for (const res of clients) {
@@ -46,6 +47,14 @@ export function startEventHub() {
                 /* a dead stream is reaped by its own 'close' handler */
             }
         }
+        for (const listener of listeners) {
+            try {
+                listener(kind);
+            }
+            catch {
+                /* an in-process consumer's failure must never break SSE fan-out */
+            }
+        }
     };
     // Debounce per kind: an fs event arms a trailing timer; a fresh event within
     // the window resets it, so a write cluster emits exactly once.
@@ -122,6 +131,12 @@ export function startEventHub() {
             res.on('close', drop);
             res.on('error', drop);
         },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
         close() {
             clearInterval(heartbeat);
             for (const t of timers.values())
@@ -144,6 +159,7 @@ export function startEventHub() {
                 }
             }
             clients.clear();
+            listeners.clear();
         },
     };
 }

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

@@ -0,0 +1,108 @@
+import type { NodeLifeStatus } from './web-client/shared/protocol.js';
+import type { PushLastSeenStore, PushRegistryStore, PushSubscriptionRecord } from './push-registry.js';
+/** The subset of `NodeSummary` the diff engine needs — kept minimal and
+ *  decoupled from the full wire type so the engine can be fed by any canvas
+ *  reader (production: `canvas snapshot`; tests: a fixture array). */
+export interface CanvasNodeRow {
+    node_id: string;
+    parent: string | null;
+    status: NodeLifeStatus;
+    attention_count: number;
+}
+/** A pending human ask with just the `DeckSummary` provenance the payload/dedupe
+ *  logic needs (design: "ask provenance comes from DeckSummary"). */
+export interface PendingAsk {
+    /** Opaque, stable inbox-entry id — the dedupe key (never re-notify the same
+     *  unresolved ask). */
+    id: string;
+    /** The interaction job id — carried in the payload as `askId` for the deep-link. */
+    jobId: string;
+    title: string;
+    conversationId: string;
+    conversationTitle: string;
+    blockedSince: string;
+}
+export type PushSendResult = 'sent' | 'gone' | 'error';
+export interface PushPayload {
+    conversationId: string;
+    kind: 'needs-you' | 'done';
+    askId?: string;
+    title: string;
+    snippet: string;
+}
+export interface PushEngineDeps {
+    registry: PushRegistryStore;
+    lastSeen: PushLastSeenStore;
+    /** Re-read the live canvas roster. */
+    readCanvasNodes: () => Promise<CanvasNodeRow[]> | CanvasNodeRow[];
+    /** Re-read every currently pending ask (deck provenance). */
+    readPendingAsks: () => Promise<PendingAsk[]> | PendingAsk[];
+    /** Deliver one push to one subscription. Implementations classify a
+     *  service-side 404/410 as `'gone'` so the engine can prune the record. */
+    sendPush: (record: PushSubscriptionRecord, payload: PushPayload) => Promise<PushSendResult>;
+    /** True iff a subscription's persisted authScope matches the canvas/user this
+     *  engine is watching (design line 252: push is sent ONLY to subscriptions
+     *  whose authScope is on the identical boundary that protects /__crtr/source).
+     *  Required — no lenient default — so a foreign scope can never be targeted. */
+    isTargetScope: (authScope: string) => boolean;
+    now?: () => number;
+    rateWindowMs?: number;
+}
+export declare class PushDiffEngine {
+    private readonly registry;
+    private readonly lastSeen;
+    private readonly readCanvasNodes;
+    private readonly readPendingAsks;
+    private readonly sendPush;
+    private readonly isTargetScope;
+    private readonly now;
+    private readonly rateWindowMs;
+    /** Drain-queue state: only one diff pass mutates last-seen at a time. An
+     *  invalidation arriving mid-pass sets its pending flag and is reprocessed
+     *  when the current pass finishes — no two passes race the same snapshot. */
+    private draining;
+    private pendingNodes;
+    private pendingInbox;
+    /** Per-conversation rate-cap clock. Deliberately in-memory/process-lifetime
+     *  only (not persisted) — a restart re-seeding silently is already the
+     *  no-storm guarantee; the rate cap only smooths a live process's bursts. */
+    private readonly lastPushAt;
+    /** Per-(conversationId+kind) set of subscription ids already delivered for
+     *  the CURRENT still-pending notification. A transient failure on one
+     *  subscription must never cause a later retry to re-send to subscriptions
+     *  that already got `'sent'` — this is exactly what remembers them across
+     *  passes. Cleared the moment the event fully succeeds (or has no eligible
+     *  subscriber left), since a later, distinct event reusing the same key
+     *  must start fresh. */
+    private readonly deliveredForKey;
+    constructor(deps: PushEngineDeps);
+    /** Seed last-seen from a fresh canvas+deck read and send nothing. Call once
+     *  on server start — a restart must never be an attention event. */
+    seed(): Promise<void>;
+    /** 'nodes' invalidation: re-read the canvas roster, emit a 'done' push for
+     *  every conversation root that just crossed into a done|dead|canceled
+     *  status from a non-done status. */
+    onNodesInvalidation(): Promise<void>;
+    onInboxInvalidation(): Promise<void>;
+    /** Serialize passes: if a pass is already running, just set the pending flag
+     *  and return — the running drain loop will pick it up. Otherwise run pending
+     *  passes until none remain. */
+    private drain;
+    private runNodesPass;
+    /** 'inbox' invalidation: re-read pending asks, emit exactly one 'needs-you'
+     *  push per conversation for its NEW (not-yet-notified) asks, coalesced. An
+     *  ask no longer present (resolved/missing) is simply dropped, never
+     *  notified. */
+    private runInboxPass;
+    /** Send one push per ELIGIBLE subscription — one whose authScope is on the
+     *  watched boundary (`isTargetScope`) AND that opted in for this payload kind.
+     *  Respects the per-conversation rate cap; prunes any subscription the push
+     *  service reports gone (404/410) or whose endpoint fails the push-service
+     *  allowlist re-check. Tracks per-subscription delivery for this notification
+     *  (`deliveredForKey`) so a retry after a transient failure on one
+     *  subscription never re-sends to a subscription that already got `'sent'`.
+     *  Returns true iff last-seen may advance: false when suppressed by the rate
+     *  cap OR when a transient send error means the item must be retried next
+     *  pass. A no-eligible pass returns true (nothing to retry). */
+    private emit;
+}