@pellux/goodvibes-sdk 0.38.0 → 1.1.0

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

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

@@ -0,0 +1,68 @@
+/**
+ * push/types.ts
+ *
+ * Shared shapes for the browser-push subscription lifecycle and delivery path.
+ *
+ * Custody note: a stored subscription's `endpoint` is a capability URL (anyone
+ * holding it can push to that device) and its `keys` are the receiver's
+ * encryption material. Neither is ever returned over the wire — read verbs
+ * hand back the redacted `PublicPushSubscription` view instead. The VAPID
+ * private key never appears in any shape here at all; it lives only inside the
+ * secrets store (see push/vapid.ts).
+ */
+import type { SubscriptionKeyMaterial } from './encryption.js';
+export type { SubscriptionKeyMaterial } from './encryption.js';
+/** A subscription as stored on disk (contains capability URL + key material). */
+export interface StoredPushSubscription {
+    readonly id: string;
+    /** The principal (operator identity) that registered this device. */
+    readonly principalId: string;
+    /** The browser Push endpoint — a capability URL, kept off the wire. */
+    readonly endpoint: string;
+    readonly keys: SubscriptionKeyMaterial;
+    readonly createdAt: number;
+    /** Timestamp of the last delivery attempt, if any. */
+    readonly lastDeliveryAt?: number | undefined;
+    /** Outcome of the last delivery attempt, if any. */
+    readonly lastOutcome?: PushDeliveryOutcome | undefined;
+}
+/**
+ * The redacted, wire-safe view of a subscription. The capability URL and key
+ * material are deliberately absent; the origin + short hash are enough to
+ * identify a device in a management UI without handing the capability back out.
+ */
+export interface PublicPushSubscription {
+    readonly id: string;
+    readonly principalId: string;
+    /** The endpoint's origin only (e.g. `https://push.example`), never the full path. */
+    readonly endpointOrigin: string;
+    /** A short, stable hash of the full endpoint, for de-duplication in a UI. */
+    readonly endpointHash: string;
+    readonly createdAt: number;
+    readonly lastDeliveryAt?: number | undefined;
+    readonly lastOutcome?: PushDeliveryOutcome | undefined;
+}
+export type PushDeliveryOutcome = 'delivered' | 'pruned' | 'failed' | 'skipped';
+/** Per-subscription result of a delivery fan-out, honest about what happened. */
+export interface PushDeliveryReceipt {
+    readonly subscriptionId: string;
+    readonly endpointOrigin: string;
+    readonly outcome: PushDeliveryOutcome;
+    /** The push service's HTTP status, when a request was actually made. */
+    readonly httpStatus?: number | undefined;
+    /** Plain-language reason, especially for `pruned`/`failed`/`skipped`. */
+    readonly detail?: string | undefined;
+}
+/** Message urgency, mapped straight onto the push `Urgency` header. */
+export type PushUrgency = 'very-low' | 'low' | 'normal' | 'high';
+/** The notification a caller wants delivered to the operator's devices. */
+export interface PushMessage {
+    readonly title: string;
+    readonly body: string;
+    /** Optional structured data the service worker can act on (e.g. a deep link). */
+    readonly data?: Record<string, unknown> | undefined;
+    readonly urgency?: PushUrgency | undefined;
+    /** How long (seconds) the push service should retain the message if offline. */
+    readonly ttlSeconds?: number | undefined;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/platform/push/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,YAAY,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAE/D,iFAAiF;AACjF,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,oDAAoD;IACpD,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACxD;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,qFAAqF;IACrF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,WAAW,CAAC,EAAE,mBAAmB,GAAG,SAAS,CAAC;CACxD;AAED,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEhF,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,wEAAwE;IACxE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACzC,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC;AAED,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEjE,2EAA2E;AAC3E,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,SAAS,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC1C"}

package/dist/platform/push/types.js

@@ -0,0 +1,13 @@
+/**
+ * push/types.ts
+ *
+ * Shared shapes for the browser-push subscription lifecycle and delivery path.
+ *
+ * Custody note: a stored subscription's `endpoint` is a capability URL (anyone
+ * holding it can push to that device) and its `keys` are the receiver's
+ * encryption material. Neither is ever returned over the wire — read verbs
+ * hand back the redacted `PublicPushSubscription` view instead. The VAPID
+ * private key never appears in any shape here at all; it lives only inside the
+ * secrets store (see push/vapid.ts).
+ */
+export {};

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

@@ -0,0 +1,54 @@
+/**
+ * push/vapid.ts
+ *
+ * VAPID (RFC 8292) key custody and request signing for browser push.
+ *
+ * KEY CUSTODY — the load-bearing rule of this file:
+ *  - The daemon generates one P-256 keypair on first need.
+ *  - The WHOLE keypair (including the private component) is persisted only
+ *    through the SecretsManager, exactly like any other credential — into the
+ *    secure store, or the plaintext secrets file, per the active secret policy.
+ *    It is NEVER written into the config, so it can never ride out in the
+ *    secret-free config snapshot.
+ *  - The private key is used only here, to sign the short-lived VAPID JWT that
+ *    authorizes one delivery. It is never logged and never returned by any read
+ *    verb.
+ *  - Only the PUBLIC key leaves the daemon: `getPublicKey()` feeds the
+ *    `push.vapid.get` verb and the `k=` parameter of the Authorization header.
+ */
+/** The narrow slice of SecretsManager this module needs — get/set one secret. */
+export interface VapidSecretStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+}
+export interface VapidManagerOptions {
+    /**
+     * The `sub` claim of the VAPID JWT — a `mailto:` or `https:` contact the push
+     * service can reach. Defaults to a local mailto when unset.
+     */
+    readonly subject?: string | undefined;
+}
+/** The secret key under which the keypair is stored (a secrets-store key, not a config key). */
+export declare const VAPID_SECRET_KEY = "push.vapid.keypair";
+export declare class VapidManager {
+    private readonly store;
+    private readonly subject;
+    private inflight;
+    constructor(store: VapidSecretStore, options?: VapidManagerOptions);
+    /** The public application-server key clients subscribe with. Generates on first call. */
+    getPublicKey(): Promise<string>;
+    /**
+     * Build the `Authorization: vapid ...` header value for one delivery to
+     * `endpoint`. The JWT's audience is the endpoint's origin (RFC 8292).
+     */
+    buildAuthorizationHeader(endpoint: string): Promise<string>;
+    private signJwt;
+    /**
+     * Load the keypair from the secrets store, or generate and persist one on
+     * first use. Concurrent callers share a single in-flight generation so two
+     * simultaneous first-time deliveries cannot mint two keypairs.
+     */
+    private ensureKeypair;
+    private loadOrGenerate;
+}
+//# sourceMappingURL=vapid.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vapid.d.ts","sourceRoot":"","sources":["../../../src/platform/push/vapid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAC/B,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACzC,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAChD;AASD,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAED,gGAAgG;AAChG,eAAO,MAAM,gBAAgB,uBAAuB,CAAC;AAyBrD,qBAAa,YAAY;IAIX,OAAO,CAAC,QAAQ,CAAC,KAAK;IAHlC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAA4C;gBAE/B,KAAK,EAAE,gBAAgB,EAAE,OAAO,GAAE,mBAAwB;IAIvF,yFAAyF;IACnF,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAKrC;;;OAGG;IACG,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOjE,OAAO,CAAC,OAAO;IAkBf;;;;OAIG;IACH,OAAO,CAAC,aAAa;YAUP,cAAc;CAe7B"}