@pellux/goodvibes-sdk 1.0.0 → 1.1.0

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"}

package/dist/platform/push/vapid.js

@@ -0,0 +1,113 @@
+/**
+ * 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.
+ */
+import { createPrivateKey, generateKeyPairSync, sign as cryptoSign } from 'node:crypto';
+/** The secret key under which the keypair is stored (a secrets-store key, not a config key). */
+export const VAPID_SECRET_KEY = 'push.vapid.keypair';
+const DEFAULT_SUBJECT = 'mailto:goodvibes-push@localhost';
+/** VAPID JWTs are short-lived; RFC 8292 caps `exp` at 24h. Use 12h. */
+const JWT_LIFETIME_SECONDS = 12 * 60 * 60;
+function base64UrlFromBuffer(buffer) {
+    return buffer.toString('base64url');
+}
+function base64UrlJson(value) {
+    return Buffer.from(JSON.stringify(value), 'utf8').toString('base64url');
+}
+/** Derive the 65-byte uncompressed public point (base64url) from a P-256 JWK. */
+function publicKeyFromJwk(jwk) {
+    if (!jwk.x || !jwk.y)
+        throw new Error('VAPID JWK is missing its public coordinates');
+    const point = Buffer.concat([
+        Buffer.from([0x04]),
+        Buffer.from(jwk.x, 'base64url'),
+        Buffer.from(jwk.y, 'base64url'),
+    ]);
+    return base64UrlFromBuffer(point);
+}
+export class VapidManager {
+    store;
+    subject;
+    inflight = null;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.subject = options.subject && options.subject.length > 0 ? options.subject : DEFAULT_SUBJECT;
+    }
+    /** The public application-server key clients subscribe with. Generates on first call. */
+    async getPublicKey() {
+        const keypair = await this.ensureKeypair();
+        return keypair.publicKey;
+    }
+    /**
+     * Build the `Authorization: vapid ...` header value for one delivery to
+     * `endpoint`. The JWT's audience is the endpoint's origin (RFC 8292).
+     */
+    async buildAuthorizationHeader(endpoint) {
+        const keypair = await this.ensureKeypair();
+        const audience = new URL(endpoint).origin;
+        const jwt = this.signJwt(audience, keypair.privateJwk);
+        return `vapid t=${jwt}, k=${keypair.publicKey}`;
+    }
+    signJwt(audience, privateJwk) {
+        const header = base64UrlJson({ typ: 'JWT', alg: 'ES256' });
+        const payload = base64UrlJson({
+            aud: audience,
+            exp: Math.floor(Date.now() / 1000) + JWT_LIFETIME_SECONDS,
+            sub: this.subject,
+        });
+        const signingInput = `${header}.${payload}`;
+        const key = createPrivateKey({ key: privateJwk, format: 'jwk' });
+        // ieee-p1363 gives the raw r||s (64-byte) JOSE signature ES256 requires,
+        // not Node's default DER encoding.
+        const signature = cryptoSign('sha256', Buffer.from(signingInput, 'utf8'), {
+            key,
+            dsaEncoding: 'ieee-p1363',
+        });
+        return `${signingInput}.${base64UrlFromBuffer(signature)}`;
+    }
+    /**
+     * 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.
+     */
+    ensureKeypair() {
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.loadOrGenerate().catch((error) => {
+            // A failed attempt must not poison every later call.
+            this.inflight = null;
+            throw error;
+        });
+        return this.inflight;
+    }
+    async loadOrGenerate() {
+        const existing = await this.store.get(VAPID_SECRET_KEY);
+        if (existing) {
+            const parsed = JSON.parse(existing);
+            if (parsed.publicKey && parsed.privateJwk)
+                return parsed;
+        }
+        const { publicKey, privateKey } = generateKeyPairSync('ec', { namedCurve: 'prime256v1' });
+        const privateJwk = privateKey.export({ format: 'jwk' });
+        const keypair = {
+            publicKey: publicKeyFromJwk(publicKey.export({ format: 'jwk' })),
+            privateJwk,
+        };
+        await this.store.set(VAPID_SECRET_KEY, JSON.stringify(keypair));
+        return keypair;
+    }
+}

package/dist/platform/runtime/feature-flags/flags.js

@@ -343,9 +343,9 @@ export const FEATURE_FLAGS = [
         runtimeToggleable: true,
     },
     {
-        // NOTE: control-plane-gateway is the ONE tier-10 flag that defaults ON (One-Platform
-        // Wave 1). A stock daemon (no config) must be able to stream companion chat over SSE;
-        // leaving this OFF made a fresh daemon return 503 on the live-stream path (the W1
+        // NOTE: control-plane-gateway is the ONE tier-10 flag that defaults ON (One-Platform).
+        // A stock daemon (no config) must be able to stream companion chat over SSE;
+        // leaving this OFF made a fresh daemon return 503 on the live-stream path (the
         // "stock daemon is dead" bug).
         //
         // HONEST SURFACE STATEMENT: flipping this default ON DOES expose surface — just not

package/dist/platform/runtime/fleet/adapters/agent.d.ts

@@ -5,7 +5,7 @@ import type { ProcessActivity, ProcessNode, ProcessState, ProcessUsage } from '.
 export declare function chainNodeId(chainId: string): string;
 /** Subtask node ids are namespaced to avoid colliding with agent/process ids. */
 export declare function subtaskNodeId(subtaskId: string): string;
-/** Work-item node ids are namespaced to avoid colliding with agent/process ids (Wave 4, wo701). */
+/** Work-item node ids are namespaced to avoid colliding with agent/process ids. */
 export declare function workItemNodeId(workItemId: string): string;
 /**
  * One activity side-table entry. Registry-owned; populated from the EXISTING
@@ -35,7 +35,7 @@ export interface AgentAdapterContext {
     readonly chainIds: ReadonlySet<string>;
     /** Raw WrfcSubtask ids present in this snapshot. */
     readonly subtaskIds: ReadonlySet<string>;
-    /** Raw orchestration-engine WorkItem ids present in this snapshot (Wave 4, wo701). */
+    /** Raw orchestration-engine WorkItem ids present in this snapshot. */
     readonly workItemIds: ReadonlySet<string>;
     /** orchestrationNodeId → owning agentId, for parentNodeId edge resolution. */
     readonly agentIdByOrchestrationNodeId: ReadonlyMap<string, string>;

package/dist/platform/runtime/fleet/adapters/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/fleet/adapters/agent.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE,UAAU,GAAG,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;IAC/H,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC3D,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,gFAAgF;IAChF,QAAQ,CAAC,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,sFAAsF;IACtF,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,4BAA4B,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnE,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACtG;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,CAYlF;AA8ED,iCAAiC;AACjC,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,mBAAmB,GAAG,WAAW,CA6CrF"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../../../../../src/platform/runtime/fleet/adapters/agent.ts"],"names":[],"mappings":"AAAA,qFAAqF;AAErF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,KAAK,EACV,eAAe,EACf,WAAW,EACX,YAAY,EACZ,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,+EAA+E;AAC/E,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE,UAAU,GAAG,gBAAgB,GAAG,WAAW,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC,CAAC;IAC/H,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,GAAG,SAAS,CAAC;IAChD,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB;AAED,0EAA0E;AAC1E,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,sFAAsF;IACtF,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAC3D,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,8EAA8E;IAC9E,QAAQ,CAAC,uBAAuB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACtD,gFAAgF;IAChF,QAAQ,CAAC,yBAAyB,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,kBAAkB,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,kDAAkD;IAClD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,oDAAoD;IACpD,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACzC,sEAAsE;IACtE,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IAC1C,8EAA8E;IAC9E,QAAQ,CAAC,4BAA4B,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACnE,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,KAAK,EAAE,YAAY,KAAK,MAAM,GAAG,IAAI,CAAC,GAAG,SAAS,CAAC;IACtG;;;;OAIG;IACH,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAC;CACrC;AAED,wDAAwD;AACxD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,CAYlF;AA8ED,iCAAiC;AACjC,wBAAgB,UAAU,CAAC,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,mBAAmB,GAAG,WAAW,CA6CrF"}