@pellux/goodvibes-sdk 1.0.0 → 1.2.0

package/dist/platform/push/delivery.js

@@ -0,0 +1,117 @@
+/**
+ * push/delivery.ts
+ *
+ * The single place a push message is actually encrypted and sent. Every send —
+ * a `push.subscriptions.verify` test, or an approval/completion fan-out — flows
+ * through `deliverToSubscription`, so the honesty rules live in one spot:
+ *
+ *  - A push service that answers 404/410 means the browser subscription is gone;
+ *    the record is pruned and the receipt says `pruned`, never a fake success.
+ *  - Any other non-2xx (or a transport error) is reported as `failed` with the
+ *    status/reason, never swallowed into a success.
+ *  - The request carries the RFC 8188 `Content-Encoding: aes128gcm` body plus
+ *    the `TTL`, `Urgency`, and VAPID `Authorization` headers a push service
+ *    requires.
+ *
+ * The endpoint is whatever the browser registered. In tests that is a local
+ * HTTP sink; in production it is the browser vendor's push service. This module
+ * never contacts a hard-coded external service of its own.
+ */
+import { encryptPushPayload } from './encryption.js';
+const DEFAULT_TTL_SECONDS = 24 * 60 * 60;
+const GONE_STATUSES = new Set([404, 410]);
+function defaultTransport() {
+    return async (url, init) => {
+        // Re-wrap over a plain ArrayBuffer so the body matches fetch's BodyInit.
+        const res = await fetch(url, {
+            method: init.method,
+            headers: init.headers,
+            body: new Uint8Array(init.body),
+        });
+        return { status: res.status };
+    };
+}
+function endpointOrigin(endpoint) {
+    try {
+        return new URL(endpoint).origin;
+    }
+    catch {
+        return 'invalid';
+    }
+}
+function messagePlaintext(message) {
+    return Buffer.from(JSON.stringify({ title: message.title, body: message.body, data: message.data ?? {} }), 'utf8');
+}
+/**
+ * Encrypt and send one message to one subscription, prune-on-gone, and return
+ * an honest receipt. The subscription's `lastOutcome` is stamped either way.
+ */
+export async function deliverToSubscription(subscription, message, deps) {
+    const origin = endpointOrigin(subscription.endpoint);
+    const transport = deps.transport ?? defaultTransport();
+    let httpStatus;
+    try {
+        const encrypted = encryptPushPayload(subscription.keys, messagePlaintext(message));
+        const authorization = await deps.vapid.buildAuthorizationHeader(subscription.endpoint);
+        const headers = {
+            'content-encoding': encrypted.contentEncoding,
+            'content-type': 'application/octet-stream',
+            ttl: String(message.ttlSeconds ?? DEFAULT_TTL_SECONDS),
+            urgency: message.urgency ?? 'normal',
+            authorization,
+        };
+        const result = await transport(subscription.endpoint, {
+            method: 'POST',
+            headers,
+            body: encrypted.body,
+        });
+        httpStatus = result.status;
+    }
+    catch (error) {
+        await deps.store.recordOutcome(subscription.id, 'failed');
+        return {
+            subscriptionId: subscription.id,
+            endpointOrigin: origin,
+            outcome: 'failed',
+            detail: `delivery request failed: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    if (httpStatus >= 200 && httpStatus < 300) {
+        await deps.store.recordOutcome(subscription.id, 'delivered');
+        return { subscriptionId: subscription.id, endpointOrigin: origin, outcome: 'delivered', httpStatus };
+    }
+    if (GONE_STATUSES.has(httpStatus)) {
+        // The subscription is gone at the push service — prune it (delete means
+        // delete) and report the prune with the status that proved it dead.
+        await deps.store.remove(subscription.id);
+        return {
+            subscriptionId: subscription.id,
+            endpointOrigin: origin,
+            outcome: 'pruned',
+            httpStatus,
+            detail: `push endpoint reported ${httpStatus} gone; subscription removed`,
+        };
+    }
+    await deps.store.recordOutcome(subscription.id, 'failed');
+    return {
+        subscriptionId: subscription.id,
+        endpointOrigin: origin,
+        outcome: 'failed',
+        httpStatus,
+        detail: `push service returned ${httpStatus}`,
+    };
+}
+/**
+ * Fan one message out to every stored subscription, delivering (and pruning) in
+ * sequence. Returns one receipt per subscription — an empty array when there
+ * are no subscriptions at all (the honest "nobody to notify" result, not a
+ * silent success).
+ */
+export async function deliverToAll(message, deps) {
+    const subscriptions = await deps.store.all();
+    const receipts = [];
+    for (const subscription of subscriptions) {
+        receipts.push(await deliverToSubscription(subscription, message, deps));
+    }
+    return receipts;
+}

package/dist/platform/push/encryption.d.ts

@@ -0,0 +1,41 @@
+/**
+ * push/encryption.ts
+ *
+ * Browser-push payload encryption, implemented with Node's built-in crypto
+ * (node:crypto) — no third-party web-push dependency. This is the daemon-side
+ * (Node/Bun) delivery path only; nothing here is imported by the runtime-neutral
+ * or browser bundles (see scripts/browser-compat-check.ts).
+ *
+ * Two standards are combined here, exactly as a browser Push service expects:
+ *
+ *  - RFC 8291 (Message Encryption for Web Push): derive a shared secret from an
+ *    ephemeral P-256 keypair and the subscription's public key + auth secret.
+ *  - RFC 8188 (aes128gcm content encoding): expand that secret into a
+ *    content-encryption key + nonce and encrypt one record, then frame it with
+ *    the salt / record-size / sender-public-key header the receiver reads back.
+ *
+ * The output Buffer is the raw request body sent to the subscription endpoint
+ * with `Content-Encoding: aes128gcm`.
+ */
+/** The subscription's own key material, base64url-encoded (browser PushSubscription shape). */
+export interface SubscriptionKeyMaterial {
+    /** The receiver's public key — 65-byte uncompressed P-256 point, base64url. */
+    readonly p256dh: string;
+    /** The receiver's 16-byte authentication secret, base64url. */
+    readonly auth: string;
+}
+export interface EncryptedPushPayload {
+    /** The aes128gcm request body: header || ciphertext || GCM tag. */
+    readonly body: Buffer;
+    /** Always `aes128gcm` — the value for the Content-Encoding request header. */
+    readonly contentEncoding: 'aes128gcm';
+}
+/**
+ * Encrypt `plaintext` for a subscription's key material.
+ *
+ * A fresh ephemeral sender keypair and salt are generated per call (RFC 8291
+ * requires this — the same salt/key pair must never encrypt two messages), so
+ * the result is non-deterministic by design.
+ */
+export declare function encryptPushPayload(keys: SubscriptionKeyMaterial, plaintext: Buffer): EncryptedPushPayload;
+//# sourceMappingURL=encryption.d.ts.map

package/dist/platform/push/encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"encryption.d.ts","sourceRoot":"","sources":["../../../src/platform/push/encryption.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAIH,+FAA+F;AAC/F,MAAM,WAAW,uBAAuB;IACtC,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+DAA+D;IAC/D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,mEAAmE;IACnE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8EAA8E;IAC9E,QAAQ,CAAC,eAAe,EAAE,WAAW,CAAC;CACvC;AAyBD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,uBAAuB,EAC7B,SAAS,EAAE,MAAM,GAChB,oBAAoB,CA2CtB"}

package/dist/platform/push/encryption.js

@@ -0,0 +1,82 @@
+/**
+ * push/encryption.ts
+ *
+ * Browser-push payload encryption, implemented with Node's built-in crypto
+ * (node:crypto) — no third-party web-push dependency. This is the daemon-side
+ * (Node/Bun) delivery path only; nothing here is imported by the runtime-neutral
+ * or browser bundles (see scripts/browser-compat-check.ts).
+ *
+ * Two standards are combined here, exactly as a browser Push service expects:
+ *
+ *  - RFC 8291 (Message Encryption for Web Push): derive a shared secret from an
+ *    ephemeral P-256 keypair and the subscription's public key + auth secret.
+ *  - RFC 8188 (aes128gcm content encoding): expand that secret into a
+ *    content-encryption key + nonce and encrypt one record, then frame it with
+ *    the salt / record-size / sender-public-key header the receiver reads back.
+ *
+ * The output Buffer is the raw request body sent to the subscription endpoint
+ * with `Content-Encoding: aes128gcm`.
+ */
+import { createCipheriv, createECDH, createHmac, randomBytes } from 'node:crypto';
+/**
+ * Single fixed record size. Push payloads here (an approval summary, a
+ * completion note) are far below this, so one aes128gcm record always
+ * suffices; a payload that would not fit is rejected honestly rather than
+ * silently truncated or split.
+ */
+const RECORD_SIZE = 4096;
+const KEY_INFO_PREFIX = Buffer.from('WebPush: info\0', 'utf8');
+const CEK_INFO = Buffer.from('Content-Encoding: aes128gcm\0', 'utf8');
+const NONCE_INFO = Buffer.from('Content-Encoding: nonce\0', 'utf8');
+/** HKDF (RFC 5869) specialized to a single output block (length <= 32). */
+function hkdf(salt, ikm, info, length) {
+    const prk = createHmac('sha256', salt).update(ikm).digest();
+    const okm = createHmac('sha256', prk).update(Buffer.concat([info, Buffer.from([0x01])])).digest();
+    return okm.subarray(0, length);
+}
+function base64UrlToBuffer(value) {
+    return Buffer.from(value, 'base64url');
+}
+/**
+ * Encrypt `plaintext` for a subscription's key material.
+ *
+ * A fresh ephemeral sender keypair and salt are generated per call (RFC 8291
+ * requires this — the same salt/key pair must never encrypt two messages), so
+ * the result is non-deterministic by design.
+ */
+export function encryptPushPayload(keys, plaintext) {
+    const receiverPublic = base64UrlToBuffer(keys.p256dh);
+    const authSecret = base64UrlToBuffer(keys.auth);
+    if (receiverPublic.length !== 65) {
+        throw new Error('Push subscription p256dh key is not a 65-byte uncompressed P-256 point');
+    }
+    if (authSecret.length !== 16) {
+        throw new Error('Push subscription auth secret is not 16 bytes');
+    }
+    // Ephemeral sender (application-server) keypair for this one message.
+    const sender = createECDH('prime256v1');
+    sender.generateKeys();
+    const senderPublic = sender.getPublicKey();
+    const sharedSecret = sender.computeSecret(receiverPublic);
+    const salt = randomBytes(16);
+    // RFC 8291: mix the shared secret with the auth secret and both public keys.
+    const keyInfo = Buffer.concat([KEY_INFO_PREFIX, receiverPublic, senderPublic]);
+    const ikm = hkdf(authSecret, sharedSecret, keyInfo, 32);
+    // RFC 8188: expand into the content-encryption key and nonce.
+    const contentEncryptionKey = hkdf(salt, ikm, CEK_INFO, 16);
+    const nonce = hkdf(salt, ikm, NONCE_INFO, 12);
+    // One record: plaintext followed by the 0x02 last-record delimiter.
+    const record = Buffer.concat([plaintext, Buffer.from([0x02])]);
+    if (record.length + 16 > RECORD_SIZE) {
+        throw new Error(`Push payload too large for a single aes128gcm record (max ${RECORD_SIZE - 17} bytes)`);
+    }
+    const cipher = createCipheriv('aes-128-gcm', contentEncryptionKey, nonce);
+    const ciphertext = Buffer.concat([cipher.update(record), cipher.final(), cipher.getAuthTag()]);
+    // aes128gcm header: salt(16) | record-size(4, big-endian) | keyid-len(1) | keyid(=senderPublic).
+    const header = Buffer.alloc(16 + 4 + 1 + senderPublic.length);
+    salt.copy(header, 0);
+    header.writeUInt32BE(RECORD_SIZE, 16);
+    header.writeUInt8(senderPublic.length, 20);
+    senderPublic.copy(header, 21);
+    return { body: Buffer.concat([header, ciphertext]), contentEncoding: 'aes128gcm' };
+}

package/dist/platform/push/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * push/index.ts — the browser-push module barrel (VAPID custody, subscription
+ * store, RFC 8291 encryption, and the delivery path). Daemon-side only; not
+ * part of the runtime-neutral or browser bundles.
+ */
+export { encryptPushPayload } from './encryption.js';
+export type { SubscriptionKeyMaterial, EncryptedPushPayload } from './encryption.js';
+export { VapidManager, VAPID_SECRET_KEY } from './vapid.js';
+export type { VapidSecretStore, VapidManagerOptions } from './vapid.js';
+export { PushSubscriptionStore, toPublicSubscription } from './subscription-store.js';
+export type { RegisterSubscriptionInput } from './subscription-store.js';
+export { deliverToSubscription, deliverToAll } from './delivery.js';
+export type { PushTransport, DeliveryDeps } from './delivery.js';
+export { PushService } from './service.js';
+export type { PushServiceDeps, SubscribeInput, ApprovalSource, ApprovalNotice } from './service.js';
+export type { StoredPushSubscription, PublicPushSubscription, PushDeliveryOutcome, PushDeliveryReceipt, PushUrgency, PushMessage, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/platform/push/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/platform/push/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACrD,YAAY,EAAE,uBAAuB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACrF,OAAO,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC5D,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AACxE,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AACtF,YAAY,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACpE,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AACjE,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpG,YAAY,EACV,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,WAAW,GACZ,MAAM,YAAY,CAAC"}

package/dist/platform/push/index.js

@@ -0,0 +1,10 @@
+/**
+ * push/index.ts — the browser-push module barrel (VAPID custody, subscription
+ * store, RFC 8291 encryption, and the delivery path). Daemon-side only; not
+ * part of the runtime-neutral or browser bundles.
+ */
+export { encryptPushPayload } from './encryption.js';
+export { VapidManager, VAPID_SECRET_KEY } from './vapid.js';
+export { PushSubscriptionStore, toPublicSubscription } from './subscription-store.js';
+export { deliverToSubscription, deliverToAll } from './delivery.js';
+export { PushService } from './service.js';

package/dist/platform/push/service.d.ts

@@ -0,0 +1,75 @@
+/**
+ * push/service.ts
+ *
+ * PushService — the seam the gateway verbs and the daemon event sources both
+ * talk to. It owns the subscription store, the VAPID key custody, and the
+ * delivery path, and it turns a real daemon event (an approval that needs a
+ * decision) into a fan-out of encrypted pushes.
+ *
+ * Honest-degrade posture, end to end:
+ *  - No subscriptions -> `deliver()` returns an empty receipt list; nothing is
+ *    faked as sent.
+ *  - A subscription whose endpoint is gone (404/410) is pruned by the delivery
+ *    path and reported as `pruned`.
+ *  - VAPID keys are minted lazily on first real need; a daemon that never uses
+ *    push never generates or stores a key.
+ */
+import { type PushTransport } from './delivery.js';
+import { PushSubscriptionStore } from './subscription-store.js';
+import { VapidManager } from './vapid.js';
+import type { PublicPushSubscription, PushDeliveryReceipt, PushMessage, SubscriptionKeyMaterial } from './types.js';
+/** The slice of the approval broker the push delivery source subscribes to. */
+export interface ApprovalSource {
+    subscribe(listener: (approval: ApprovalNotice) => void): () => void;
+}
+/** The minimum an approval record needs to expose to become a push. */
+export interface ApprovalNotice {
+    readonly id: string;
+    readonly status: string;
+    readonly request?: {
+        readonly tool?: string;
+        readonly analysis?: {
+            readonly summary?: string;
+        };
+    } | undefined;
+}
+export interface PushServiceDeps {
+    readonly vapid: VapidManager;
+    readonly store: PushSubscriptionStore;
+    /** Overridable delivery transport; production uses the built-in fetch. */
+    readonly transport?: PushTransport | undefined;
+}
+export interface SubscribeInput {
+    readonly principalId: string;
+    readonly endpoint: string;
+    readonly keys: SubscriptionKeyMaterial;
+}
+export declare class PushService {
+    private readonly vapid;
+    private readonly store;
+    private readonly transport?;
+    /** Approval ids already pushed, so re-publishes (claim/approve) don't re-notify. */
+    private readonly notifiedApprovals;
+    constructor(deps: PushServiceDeps);
+    /** The public VAPID key clients subscribe with. */
+    getPublicKey(): Promise<string>;
+    subscribe(input: SubscribeInput): Promise<PublicPushSubscription>;
+    listSubscriptions(principalId: string): Promise<PublicPushSubscription[]>;
+    /** Delete a subscription for a principal. False when the id was already absent. */
+    unsubscribe(id: string, principalId: string): Promise<boolean>;
+    /**
+     * Send a test push to one of the principal's subscriptions and return the
+     * honest receipt (delivered / pruned / failed). Returns null when the id is
+     * not a subscription owned by this principal, so the verb can 404.
+     */
+    verify(id: string, principalId: string): Promise<PushDeliveryReceipt | null>;
+    /** Fan a message out to every stored subscription. */
+    deliver(message: PushMessage): Promise<PushDeliveryReceipt[]>;
+    /**
+     * Wire a real event source: when an approval is created (status `pending`),
+     * push it to every registered device. Later re-publishes of the same approval
+     * (claimed/approved/denied) do not re-notify. Returns an unsubscribe handle.
+     */
+    attachApprovalSource(source: ApprovalSource): () => void;
+}
+//# sourceMappingURL=service.d.ts.map

package/dist/platform/push/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../../src/platform/push/service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAuC,KAAK,aAAa,EAAE,MAAM,eAAe,CAAC;AACxF,OAAO,EAAE,qBAAqB,EAAwB,MAAM,yBAAyB,CAAC;AACtF,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC1C,OAAO,KAAK,EACV,sBAAsB,EACtB,mBAAmB,EACnB,WAAW,EACX,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAEpB,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,QAAQ,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;CACrE;AAED,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;YAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,GAAG,SAAS,CAAC;CAC9G;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;CAChD;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;CACxC;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAe;IACrC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwB;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAA4B;IACvD,oFAAoF;IACpF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqB;gBAE3C,IAAI,EAAE,eAAe;IAMjC,mDAAmD;IACnD,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAIzB,SAAS,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAKvE,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAIzE,mFAAmF;IACnF,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI9D;;;;OAIG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC;IAclF,sDAAsD;IACtD,OAAO,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,EAAE,CAAC;IAI7D;;;;OAIG;IACH,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,IAAI;CAsBzD"}

package/dist/platform/push/service.js

@@ -0,0 +1,95 @@
+/**
+ * push/service.ts
+ *
+ * PushService — the seam the gateway verbs and the daemon event sources both
+ * talk to. It owns the subscription store, the VAPID key custody, and the
+ * delivery path, and it turns a real daemon event (an approval that needs a
+ * decision) into a fan-out of encrypted pushes.
+ *
+ * Honest-degrade posture, end to end:
+ *  - No subscriptions -> `deliver()` returns an empty receipt list; nothing is
+ *    faked as sent.
+ *  - A subscription whose endpoint is gone (404/410) is pruned by the delivery
+ *    path and reported as `pruned`.
+ *  - VAPID keys are minted lazily on first real need; a daemon that never uses
+ *    push never generates or stores a key.
+ */
+import { logger } from '../utils/logger.js';
+import { deliverToAll, deliverToSubscription } from './delivery.js';
+import { PushSubscriptionStore, toPublicSubscription } from './subscription-store.js';
+import { VapidManager } from './vapid.js';
+export class PushService {
+    vapid;
+    store;
+    transport;
+    /** Approval ids already pushed, so re-publishes (claim/approve) don't re-notify. */
+    notifiedApprovals = new Set();
+    constructor(deps) {
+        this.vapid = deps.vapid;
+        this.store = deps.store;
+        this.transport = deps.transport;
+    }
+    /** The public VAPID key clients subscribe with. */
+    getPublicKey() {
+        return this.vapid.getPublicKey();
+    }
+    async subscribe(input) {
+        const record = await this.store.register(input);
+        return toPublicSubscription(record);
+    }
+    listSubscriptions(principalId) {
+        return this.store.listPublic(principalId);
+    }
+    /** Delete a subscription for a principal. False when the id was already absent. */
+    unsubscribe(id, principalId) {
+        return this.store.remove(id, principalId);
+    }
+    /**
+     * Send a test push to one of the principal's subscriptions and return the
+     * honest receipt (delivered / pruned / failed). Returns null when the id is
+     * not a subscription owned by this principal, so the verb can 404.
+     */
+    async verify(id, principalId) {
+        const record = await this.store.get(id);
+        if (!record || record.principalId !== principalId)
+            return null;
+        return deliverToSubscription(record, {
+            title: 'GoodVibes test notification',
+            body: 'Browser push is wired up and working.',
+            urgency: 'normal',
+        }, { vapid: this.vapid, store: this.store, transport: this.transport });
+    }
+    /** Fan a message out to every stored subscription. */
+    deliver(message) {
+        return deliverToAll(message, { vapid: this.vapid, store: this.store, transport: this.transport });
+    }
+    /**
+     * Wire a real event source: when an approval is created (status `pending`),
+     * push it to every registered device. Later re-publishes of the same approval
+     * (claimed/approved/denied) do not re-notify. Returns an unsubscribe handle.
+     */
+    attachApprovalSource(source) {
+        return source.subscribe((approval) => {
+            if (approval.status !== 'pending')
+                return;
+            if (this.notifiedApprovals.has(approval.id))
+                return;
+            this.notifiedApprovals.add(approval.id);
+            const tool = approval.request?.tool ?? 'a tool';
+            const summary = approval.request?.analysis?.summary ?? 'A pending action needs your decision.';
+            // Fire-and-forget: an approval must never block on a push, and a delivery
+            // failure is already captured as an honest receipt/outcome inside deliver().
+            void this.deliver({
+                title: 'Approval required',
+                body: `${tool}: ${summary}`,
+                data: { kind: 'approval', approvalId: approval.id },
+                urgency: 'high',
+            }).catch((error) => {
+                logger.warn('PushService: approval fan-out failed', {
+                    approvalId: approval.id,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            });
+        });
+    }
+}

package/dist/platform/push/subscription-store.d.ts

@@ -0,0 +1,50 @@
+/**
+ * push/subscription-store.ts
+ *
+ * The on-disk record of which devices an operator has registered for browser
+ * push. Persisted with the same atomic-JSON `PersistentStore` the approval and
+ * session stores use — the capability URLs and key material stay on disk in the
+ * daemon's own state directory, never on the wire.
+ *
+ * Delete means delete: `remove()` drops the record entirely (it does not flag a
+ * tombstone), and `list()` cannot return it afterward. Pruning a dead endpoint
+ * uses the same `remove()` path.
+ */
+import type { PublicPushSubscription, StoredPushSubscription, SubscriptionKeyMaterial } from './types.js';
+export interface RegisterSubscriptionInput {
+    readonly principalId: string;
+    readonly endpoint: string;
+    readonly keys: SubscriptionKeyMaterial;
+}
+/** The redacted, wire-safe projection of a stored subscription. */
+export declare function toPublicSubscription(record: StoredPushSubscription): PublicPushSubscription;
+export declare class PushSubscriptionStore {
+    private readonly store;
+    private records;
+    constructor(filePath: string);
+    private ensureLoaded;
+    private flush;
+    /**
+     * Register (or refresh) a subscription. Two subscriptions from the same
+     * principal for the same endpoint collapse onto one record — a browser that
+     * re-subscribes with rotated keys updates in place rather than piling up
+     * duplicate capability URLs.
+     */
+    register(input: RegisterSubscriptionInput): Promise<StoredPushSubscription>;
+    /** All subscriptions for a principal, redacted for the wire. */
+    listPublic(principalId: string): Promise<PublicPushSubscription[]>;
+    /** The full record (endpoint + keys) for a delivery. Not for the wire. */
+    get(id: string): Promise<StoredPushSubscription | null>;
+    /** Every stored subscription — the delivery fan-out reads this. Not for the wire. */
+    all(): Promise<readonly StoredPushSubscription[]>;
+    /**
+     * Delete a subscription. Returns true if a record was actually removed, false
+     * if the id was already absent — the caller reports an honest 404 rather than
+     * a 200-noop. An optional `principalId` scopes the delete so one operator
+     * cannot remove another's device.
+     */
+    remove(id: string, principalId?: string): Promise<boolean>;
+    /** Record the outcome of the last delivery attempt against a subscription. */
+    recordOutcome(id: string, outcome: StoredPushSubscription['lastOutcome']): Promise<void>;
+}
+//# sourceMappingURL=subscription-store.d.ts.map

package/dist/platform/push/subscription-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subscription-store.d.ts","sourceRoot":"","sources":["../../../src/platform/push/subscription-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAMpB,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;CACxC;AAcD,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,sBAAsB,GAAG,sBAAsB,CAU3F;AAED,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAwC;IAC9D,OAAO,CAAC,OAAO,CAAyC;gBAE5C,QAAQ,EAAE,MAAM;YAId,YAAY;YAOZ,KAAK;IAInB;;;;;OAKG;IACG,QAAQ,CAAC,KAAK,EAAE,yBAAyB,GAAG,OAAO,CAAC,sBAAsB,CAAC;IAyBjF,gEAAgE;IAC1D,UAAU,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,EAAE,CAAC;IAOxE,0EAA0E;IACpE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,sBAAsB,GAAG,IAAI,CAAC;IAK7D,qFAAqF;IAC/E,GAAG,IAAI,OAAO,CAAC,SAAS,sBAAsB,EAAE,CAAC;IAIvD;;;;;OAKG;IACG,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAWhE,8EAA8E;IACxE,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,sBAAsB,CAAC,aAAa,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAQ/F"}

package/dist/platform/push/subscription-store.js

@@ -0,0 +1,123 @@
+/**
+ * push/subscription-store.ts
+ *
+ * The on-disk record of which devices an operator has registered for browser
+ * push. Persisted with the same atomic-JSON `PersistentStore` the approval and
+ * session stores use — the capability URLs and key material stay on disk in the
+ * daemon's own state directory, never on the wire.
+ *
+ * Delete means delete: `remove()` drops the record entirely (it does not flag a
+ * tombstone), and `list()` cannot return it afterward. Pruning a dead endpoint
+ * uses the same `remove()` path.
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import { PersistentStore } from '../state/persistent-store.js';
+function endpointOrigin(endpoint) {
+    try {
+        return new URL(endpoint).origin;
+    }
+    catch {
+        return 'invalid';
+    }
+}
+function endpointHash(endpoint) {
+    return createHash('sha256').update(endpoint).digest('base64url').slice(0, 16);
+}
+/** The redacted, wire-safe projection of a stored subscription. */
+export function toPublicSubscription(record) {
+    return {
+        id: record.id,
+        principalId: record.principalId,
+        endpointOrigin: endpointOrigin(record.endpoint),
+        endpointHash: endpointHash(record.endpoint),
+        createdAt: record.createdAt,
+        lastDeliveryAt: record.lastDeliveryAt,
+        lastOutcome: record.lastOutcome,
+    };
+}
+export class PushSubscriptionStore {
+    store;
+    records = null;
+    constructor(filePath) {
+        this.store = new PersistentStore(filePath);
+    }
+    async ensureLoaded() {
+        if (this.records)
+            return this.records;
+        const snapshot = await this.store.load();
+        this.records = snapshot?.subscriptions ? [...snapshot.subscriptions] : [];
+        return this.records;
+    }
+    async flush() {
+        await this.store.persist({ subscriptions: this.records ?? [] });
+    }
+    /**
+     * Register (or refresh) a subscription. Two subscriptions from the same
+     * principal for the same endpoint collapse onto one record — a browser that
+     * re-subscribes with rotated keys updates in place rather than piling up
+     * duplicate capability URLs.
+     */
+    async register(input) {
+        const records = await this.ensureLoaded();
+        const existingIndex = records.findIndex((r) => r.principalId === input.principalId && r.endpoint === input.endpoint);
+        const now = Date.now();
+        if (existingIndex >= 0) {
+            const prior = records[existingIndex];
+            const updated = { ...prior, keys: input.keys };
+            records[existingIndex] = updated;
+            await this.flush();
+            return updated;
+        }
+        const record = {
+            id: `push-${randomUUID()}`,
+            principalId: input.principalId,
+            endpoint: input.endpoint,
+            keys: input.keys,
+            createdAt: now,
+        };
+        records.push(record);
+        await this.flush();
+        return record;
+    }
+    /** All subscriptions for a principal, redacted for the wire. */
+    async listPublic(principalId) {
+        const records = await this.ensureLoaded();
+        return records
+            .filter((r) => r.principalId === principalId)
+            .map(toPublicSubscription);
+    }
+    /** The full record (endpoint + keys) for a delivery. Not for the wire. */
+    async get(id) {
+        const records = await this.ensureLoaded();
+        return records.find((r) => r.id === id) ?? null;
+    }
+    /** Every stored subscription — the delivery fan-out reads this. Not for the wire. */
+    async all() {
+        return [...(await this.ensureLoaded())];
+    }
+    /**
+     * Delete a subscription. Returns true if a record was actually removed, false
+     * if the id was already absent — the caller reports an honest 404 rather than
+     * a 200-noop. An optional `principalId` scopes the delete so one operator
+     * cannot remove another's device.
+     */
+    async remove(id, principalId) {
+        const records = await this.ensureLoaded();
+        const index = records.findIndex((r) => r.id === id && (principalId === undefined || r.principalId === principalId));
+        if (index < 0)
+            return false;
+        records.splice(index, 1);
+        await this.flush();
+        return true;
+    }
+    /** Record the outcome of the last delivery attempt against a subscription. */
+    async recordOutcome(id, outcome) {
+        const records = await this.ensureLoaded();
+        const index = records.findIndex((r) => r.id === id);
+        if (index < 0)
+            return;
+        const prior = records[index];
+        records[index] = { ...prior, lastDeliveryAt: Date.now(), lastOutcome: outcome };
+        await this.flush();
+    }
+}