@ours.network/notifications 0.1.1

package/dist/daemon.js

@@ -0,0 +1,353 @@
+// The ours-notifications host daemon: boots the service packet via the
+// @adapt-toolkit SDK, connects to a broker, persists identity + packet state
+// across restarts, consumes the packet's $notify_agent events
+// (notification_posted / marked_read / unregistered), keeps the app-side
+// notification log (notifications.json), and performs WebPush egress.
+//
+// Run directly (node dist/daemon.js) it speaks a JSON-lines control protocol:
+//   stdin  {"cmd":"invite","name":"..."} | {"cmd":"contacts"} | {"cmd":"export_vis"} | {"cmd":"status"}
+//   stdout {"reply":...} for commands; {"event":...} lines for daemon events
+//          (first line after boot: {"event":"ready","cid":...,"version":{...}}).
+import * as fs from 'node:fs';
+import { resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { createInterface } from 'node:readline';
+import { adapt_wrapper } from '@adapt-toolkit/sdk/executables';
+import { PacketWrapperConfigurator } from '@adapt-toolkit/sdk/wrappers';
+import { object_to_adapt_value } from '@adapt-toolkit/sdk/wrapper';
+import { loadConfig } from './config.js';
+import { LogStore } from './log-store.js';
+import { DisabledPushSender } from './push.js';
+import { WebPushSender } from './web-push-sender.js';
+import { startDiscoveryServer } from './http.js';
+import { PresenceRegistry, attachPresenceServer } from './presence.js';
+const SERVICE_NAME = 'ours notifications service';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export async function startDaemon(cfg) {
+    fs.mkdirSync(cfg.stateDir, { recursive: true });
+    const unitFile = fs.readdirSync(cfg.unitDir).find((f) => f.endsWith('.muflo'));
+    if (!unitFile)
+        throw new Error(`no .muflo unit in ${cfg.unitDir} — run scripts/compile-mufl.sh`);
+    const unitHash = unitFile.slice(0, -'.muflo'.length);
+    const unitBytes = new Uint8Array(fs.readFileSync(resolve(cfg.unitDir, unitFile)));
+    const keyPath = resolve(cfg.stateDir, 'identity.key');
+    const dataPath = resolve(cfg.stateDir, 'state_data.bin');
+    const wrapper = await adapt_wrapper.start(['--broker_address', cfg.brokerUrl, '--test_mode',
+        '--logger_config', '--level', 'WARNING', '--stdout', 'stderr', '--logger_config_end']);
+    wrapper.start();
+    await sleep(1500);
+    const logStore = new LogStore(cfg.stateDir);
+    const push = cfg.pushDisabled
+        ? new DisabledPushSender()
+        : new WebPushSender(cfg.vapidSubject, cfg.vapidPublicKey, cfg.vapidPrivateKey, cfg.pushTlsInsecure);
+    const presence = new PresenceRegistry();
+    const listeners = [];
+    const emit = (e) => { for (const cb of listeners)
+        cb(e); };
+    const pending = [];
+    let pw = null;
+    const ro = (name, targ) => pw.packet.ExecuteTransaction(object_to_adapt_value({ name, targ }));
+    const mutate = (name, targ) => new Promise((res, rej) => {
+        const timer = setTimeout(() => rej(new Error(`${name} timed out`)), 20000);
+        pending.push({ resolve: res, reject: rej, timer });
+        pw.add_client_message(object_to_adapt_value({ name, targ }));
+    });
+    function saveState() {
+        try {
+            const bytes = Buffer.from(ro('::actor::export_state').Serialize());
+            // Per-contact tokens grow state O(recipients × contacts) — surface
+            // real-world numbers once the blob crosses 10 MB so capping (LRU/paging)
+            // can be revisited with data.
+            if (bytes.length > 10 * 1024 * 1024) {
+                console.error(`[daemon] state size ${(bytes.length / (1024 * 1024)).toFixed(1)} MB exceeds 10 MB — review per-contact token growth`);
+            }
+            const tmp = `${dataPath}.tmp`;
+            fs.writeFileSync(tmp, bytes);
+            fs.renameSync(tmp, dataPath);
+        }
+        catch (err) {
+            console.error('[daemon] failed to save state:', String(err));
+        }
+    }
+    function readBindings(av) {
+        const out = [];
+        if (av.IsNil())
+            return out;
+        for (let i = 0;; i++) {
+            const b = av.Reduce(i);
+            if (b.IsNil())
+                break;
+            out.push({
+                binding_id: b.Reduce('binding_id').Visualize(),
+                endpoint: b.Reduce('endpoint').Visualize(),
+                p256dh: b.Reduce('p256dh').Visualize(),
+                auth: b.Reduce('auth').Visualize(),
+            });
+        }
+        return out;
+    }
+    function readIds(av) {
+        if (av.IsNil())
+            return null;
+        const out = [];
+        for (let i = 0;; i++) {
+            const e = av.Reduce(i);
+            if (e.IsNil())
+                break;
+            out.push(e.Visualize());
+        }
+        return out;
+    }
+    function handleNotifyAgent(payload) {
+        const event = payload.Reduce('event').Visualize();
+        if (event === 'notification_posted') {
+            const n = payload.Reduce('notification');
+            const record = {
+                notif_id: n.Reduce('notif_id').Visualize(),
+                wire_id: n.Reduce('wire_id').Visualize(),
+                recipient_cid: n.Reduce('recipient_cid').Visualize(),
+                sender_cid: n.Reduce('sender_cid').Visualize(),
+                payload: n.Reduce('payload').Visualize(),
+                date: n.Reduce('date').Visualize(),
+            };
+            const bindings = readBindings(payload.Reduce('bindings'));
+            // BUG-2 foreground gate: a live authed presence socket for the recipient
+            // means their PWA is frontmost — they already got this message in-app, so
+            // SUPPRESS the WebPush. Log it as 'read' for history/badge coherence.
+            // No socket ⇒ recipient is closed/backgrounded ⇒ push as usual. Self-
+            // healing: the socket drop clears presence instantly, so the next post pushes.
+            const suppressed = presence.isOnline(record.recipient_cid);
+            if (suppressed) {
+                logStore.append(record, 'read');
+            }
+            else {
+                logStore.append(record);
+                // One WebPush per binding, log-and-continue on failure (E12) — never
+                // block or crash the ingest on a dead endpoint.
+                void push.sendPushes(bindings, record.payload).then((results) => {
+                    for (const r of results) {
+                        if (!r.ok)
+                            console.error(`[push] ${r.binding_id}: ${r.error ?? r.status}`);
+                    }
+                });
+            }
+            emit({ event, notification: record, bindings, suppressed });
+        }
+        else if (event === 'marked_read') {
+            const recipient = payload.Reduce('recipient_cid').Visualize();
+            const ids = readIds(payload.Reduce('notif_ids'));
+            logStore.markRead(recipient, ids);
+            emit({ event, recipient_cid: recipient, notif_ids: ids });
+        }
+        else if (event === 'unregistered') {
+            const recipient = payload.Reduce('recipient_cid').Visualize();
+            logStore.purgeRecipient(recipient);
+            emit({ event, recipient_cid: recipient });
+        }
+        else {
+            emit({ event });
+        }
+    }
+    function createPacket(seed, signingSecret) {
+        const pcfg = new PacketWrapperConfigurator();
+        const args = ['--unit_hash', unitHash, '--seed_phrase', seed, '--unit_dir_path', cfg.unitDir];
+        if (signingSecret)
+            args.push('--init_trn_argument', JSON.stringify(signingSecret));
+        pcfg.process_arguments(args);
+        return new Promise((res, rej) => {
+            const t = setTimeout(() => rej(new Error('packet creation timed out')), 30000);
+            wrapper.packet_manager.create_packet(pcfg, (p) => {
+                clearTimeout(t);
+                pw = p;
+                pw.on_return_data = (d) => {
+                    const kind = d.Reduce('kind').Visualize();
+                    if (kind === 'save_state') {
+                        saveState();
+                        return;
+                    }
+                    if (kind === 'notify_agent') {
+                        handleNotifyAgent(d.Reduce('payload'));
+                        return;
+                    }
+                    const p2 = pending.shift();
+                    if (p2) {
+                        clearTimeout(p2.timer);
+                        p2.resolve(d.Reduce('payload'));
+                    }
+                };
+                pw.on_transaction_failure = (msg) => {
+                    const p2 = pending.shift();
+                    if (p2) {
+                        clearTimeout(p2.timer);
+                        p2.reject(new Error(msg));
+                    }
+                    else
+                        console.error('[daemon] inbound rejected:', String(msg).split('\n')[0]);
+                };
+                res();
+            }, unitBytes);
+        });
+    }
+    // Boot: restore the persisted identity (same container id via reseed) or
+    // mint a fresh one and persist its SIGN secret + state.
+    if (fs.existsSync(keyPath)) {
+        const secret = fs.readFileSync(keyPath, 'utf8').trim();
+        await createPacket('', secret);
+        if (fs.existsSync(dataPath) && fs.statSync(dataPath).size > 0) {
+            const adaptData = pw.packet.ParseValue(new Uint8Array(fs.readFileSync(dataPath)));
+            await mutate('::actor::import_state', adaptData);
+        }
+    }
+    else {
+        await createPacket(randomBytes(24).toString('hex'));
+        const secretHex = Buffer.from(ro('::actor::export_signing_secret').Serialize()).toString('hex');
+        fs.writeFileSync(keyPath, secretHex, { mode: 0o600 });
+    }
+    // The packet echoes this in every confirm_registration; PRIVATE key stays here.
+    await mutate('::a2a_notifications::set_vapid_public_key', { key: cfg.vapidPublicKey });
+    const cid = pw.packet.GetContainerID().Visualize();
+    const vv = ro('::actor::get_version');
+    const version = {
+        MAJ: Number(vv.Reduce('MAJ').Visualize()),
+        MIN: Number(vv.Reduce('MIN').Visualize()),
+        PATCH: Number(vv.Reduce('PATCH').Visualize()),
+    };
+    const mintInvite = async (name = '') => {
+        const m = await mutate('::a2a_messaging::generate_invite', { name });
+        return Buffer.from(m.Reduce('invite').GetBinary()).toString('hex');
+    };
+    // BUG-2: verify a presence socket belongs to the claimed recipient — PURE TS,
+    // ZERO mufl (app+server-only by design). The panel presents
+    // { recipient, endpoint, auth } from its OWN WebPush subscription; we read the
+    // packet's registration state via the EXISTING ::actor::export_state readonly
+    // and check the pair against a stored binding of registration[recipient]. Runs
+    // only at socket-auth time (foreground reconnect), not per notification, so the
+    // export_state cost is fine. Returns the bound cid on success, else null; never
+    // throws into the WS layer.
+    const verifyPresence = (frame) => {
+        const recipient = frame.recipient;
+        const endpoint = frame.endpoint;
+        const auth = frame.auth;
+        if (typeof recipient !== 'string' || typeof endpoint !== 'string' || typeof auth !== 'string')
+            return null;
+        if (!recipient || !endpoint || !auth)
+            return null;
+        try {
+            const notify = ro('::actor::export_state').Reduce('notify');
+            if (notify.IsNil())
+                return null;
+            const regs = notify.Reduce('notify_registrations');
+            if (regs.IsNil())
+                return null;
+            // notify_registrations is a global_id-keyed map; find the recipient's entry.
+            let reg = null;
+            for (const k of regs.GetKeys()) {
+                if (k.Visualize() === recipient) {
+                    reg = regs.Reduce(k);
+                    break;
+                }
+            }
+            if (!reg || reg.IsNil())
+                return null;
+            const bindings = reg.Reduce('bindings');
+            if (bindings.IsNil())
+                return null;
+            for (let i = 0;; i++) {
+                const b = bindings.Reduce(i);
+                if (b.IsNil())
+                    break;
+                if (b.Reduce('endpoint').Visualize() === endpoint && b.Reduce('auth').Visualize() === auth) {
+                    return recipient;
+                }
+            }
+            return null;
+        }
+        catch (err) {
+            console.error('[presence] verify failed:', String(err).split('\n')[0]);
+            return null;
+        }
+    };
+    let discovery;
+    let presenceServer;
+    if (cfg.discoveryPort !== undefined) {
+        discovery = await startDiscoveryServer(cfg.discoveryPort, cfg.discoveryHost, {
+            serviceName: () => SERVICE_NAME,
+            serviceCid: () => cid,
+            brokerUrl: cfg.brokerUrl,
+            vapidPublicKey: cfg.vapidPublicKey,
+            mintInvite,
+        });
+        // Attach the foreground-presence WebSocket to the SAME server/port (reachable
+        // over the same tunnel as /v1/discovery). No new port, no new tunnel route.
+        presenceServer = attachPresenceServer(discovery, presence, {
+            verify: verifyPresence,
+            onChange: (recipient_cid, online) => emit({ event: 'presence_change', recipient_cid, online }),
+        });
+    }
+    return {
+        cid,
+        version,
+        logStore,
+        onEvent: (cb) => listeners.push(cb),
+        invite: async (name) => {
+            return mintInvite(name);
+        },
+        contacts: () => ro('::a2a_messaging::list_contacts').Visualize(),
+        exportVis: () => ro('::actor::export_state').Visualize(),
+        stop: async () => {
+            saveState();
+            if (presenceServer)
+                await presenceServer.close();
+            if (discovery)
+                await new Promise((res) => discovery.close(() => res()));
+        },
+    };
+}
+// ---- CLI entry (JSON-lines control protocol) --------------------------------
+const isMain = process.argv[1] && resolve(process.argv[1]) === resolve(import.meta.url.replace('file://', ''));
+if (isMain) {
+    const out = (obj) => process.stdout.write(JSON.stringify(obj) + '\n');
+    startDaemon(loadConfig())
+        .then((daemon) => {
+        daemon.onEvent((e) => out(e));
+        out({ event: 'ready', cid: daemon.cid, version: daemon.version });
+        const rl = createInterface({ input: process.stdin });
+        rl.on('line', (line) => {
+            void (async () => {
+                let msg;
+                try {
+                    msg = JSON.parse(line);
+                }
+                catch {
+                    return;
+                }
+                try {
+                    if (msg.cmd === 'invite')
+                        out({ reply: await daemon.invite(msg.name ?? '') });
+                    else if (msg.cmd === 'contacts')
+                        out({ reply: daemon.contacts() });
+                    else if (msg.cmd === 'export_vis')
+                        out({ reply: daemon.exportVis() });
+                    else if (msg.cmd === 'status')
+                        out({ reply: { cid: daemon.cid, version: daemon.version } });
+                    else if (msg.cmd === 'notifications')
+                        out({ reply: daemon.logStore.list() });
+                    else
+                        out({ reply: { error: `unknown cmd ${msg.cmd}` } });
+                }
+                catch (err) {
+                    out({ reply: { error: String(err) } });
+                }
+            })();
+        });
+        const shutdown = () => {
+            void daemon.stop().then(() => process.exit(0));
+        };
+        process.on('SIGTERM', shutdown);
+        process.on('SIGINT', shutdown);
+    })
+        .catch((err) => {
+        console.error('[daemon] boot failed:', err);
+        process.exit(1);
+    });
+}

package/dist/http.js

@@ -0,0 +1,31 @@
+import http from 'node:http';
+const CORS = { 'Access-Control-Allow-Origin': '*' };
+export function startDiscoveryServer(port, host, deps) {
+    const server = http.createServer(async (req, res) => {
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, CORS);
+            return void res.end();
+        }
+        if (req.method === 'GET' && req.url?.split('?')[0] === '/v1/discovery') {
+            try {
+                const invite = await deps.mintInvite();
+                res.writeHead(200, { 'content-type': 'application/json', ...CORS });
+                return void res.end(JSON.stringify({
+                    version: 1,
+                    service_name: deps.serviceName(),
+                    service_cid: deps.serviceCid(),
+                    broker_url: deps.brokerUrl,
+                    vapid_public_key: deps.vapidPublicKey,
+                    invite,
+                }));
+            }
+            catch (e) {
+                res.writeHead(500, { 'content-type': 'application/json', ...CORS });
+                return void res.end(JSON.stringify({ error: String(e) }));
+            }
+        }
+        res.writeHead(404, CORS);
+        res.end();
+    });
+    return new Promise((resolve) => server.listen(port, host, () => resolve(server)));
+}

package/dist/log-store.js

@@ -0,0 +1,48 @@
+// The app-side notification log (notifications.json): the daemon owns
+// storage + read/unread status; the packet only validates and hands records
+// over. v1: unbounded append (documented; GC is an optional enhancement).
+import * as fs from 'node:fs';
+import { resolve } from 'node:path';
+export class LogStore {
+    path;
+    records = [];
+    constructor(dir) {
+        this.path = resolve(dir, 'notifications.json');
+        try {
+            this.records = JSON.parse(fs.readFileSync(this.path, 'utf8'));
+        }
+        catch {
+            this.records = [];
+        }
+    }
+    flush() {
+        const tmp = `${this.path}.tmp`;
+        fs.writeFileSync(tmp, JSON.stringify(this.records, null, 2));
+        fs.renameSync(tmp, this.path);
+    }
+    // status defaults to 'unread'. Foreground-suppressed posts are appended as
+    // 'read' (BUG-2): the recipient already saw the message in-app, so the record
+    // is kept for history but must not inflate the unread badge.
+    append(rec, status = 'unread') {
+        this.records.push({ ...rec, status });
+        this.flush();
+    }
+    // ids === null ⇒ mark ALL of this recipient's notifications read.
+    // Unknown / foreign ids are ignored (E7 — idempotent).
+    markRead(recipientCid, ids) {
+        for (const r of this.records) {
+            if (r.recipient_cid !== recipientCid)
+                continue;
+            if (ids === null || ids.includes(r.notif_id))
+                r.status = 'read';
+        }
+        this.flush();
+    }
+    purgeRecipient(recipientCid) {
+        this.records = this.records.filter((r) => r.recipient_cid !== recipientCid);
+        this.flush();
+    }
+    list() {
+        return this.records;
+    }
+}

package/dist/presence.js

@@ -0,0 +1,157 @@
+// BUG-2 foreground-presence: a long-lived WebSocket per ONLINE recipient device.
+//
+// The panel opens a socket to /v1/presence while its PWA is foreground and lets
+// it die when the app closes/backgrounds (the OS tears the socket down on
+// suspend). A live authed socket for recipient R therefore means "R is
+// frontmost right now" — and the daemon SUPPRESSES R's WebPush while such a
+// socket exists (R already sees the message in-app). The socket dropping is the
+// ONLY liveness signal: instant, certain, and needing no message from the
+// client — which is why this survives an abrupt close that an app-level "I'm
+// gone" beacon never could.
+//
+// AUTH: the first frame is an opaque JSON object the daemon's `verify` inspects
+// (in practice { recipient, endpoint, auth } — R's own WebPush credential). The
+// daemon returns the recipient cid the socket is bound to, or null to reject. A
+// forged credential can only suppress that recipient's own pushes, so proving
+// possession of R's subscription is the right strength.
+//
+// LIVENESS of the socket itself: WS ping/pong (transport level, not an app
+// heartbeat) reaps half-open sockets — e.g. an iOS PWA backgrounded on a flaky
+// network whose TCP close hasn't propagated yet — within ~pingIntervalMs.
+import { WebSocketServer } from 'ws';
+// recipient_cid -> its live authed sockets (a recipient may have >1 device).
+export class PresenceRegistry {
+    online = new Map();
+    isOnline(cid) {
+        const s = this.online.get(cid);
+        return s !== undefined && s.size > 0;
+    }
+    add(cid, ws) {
+        let s = this.online.get(cid);
+        if (!s) {
+            s = new Set();
+            this.online.set(cid, s);
+        }
+        s.add(ws);
+    }
+    remove(cid, ws) {
+        const s = this.online.get(cid);
+        if (!s)
+            return false;
+        const had = s.delete(ws);
+        if (s.size === 0)
+            this.online.delete(cid);
+        return had && !this.isOnline(cid);
+    }
+    onlineCount() { return this.online.size; }
+    socketCount() { let n = 0; for (const s of this.online.values())
+        n += s.size; return n; }
+}
+export function attachPresenceServer(server, registry, deps) {
+    const path = deps.path ?? '/v1/presence';
+    const pingIntervalMs = deps.pingIntervalMs ?? 30_000;
+    const authTimeoutMs = deps.authTimeoutMs ?? 5_000;
+    const wss = new WebSocketServer({ noServer: true });
+    server.on('upgrade', (req, socket, head) => {
+        let pathname = '/';
+        try {
+            pathname = new URL(req.url ?? '/', 'http://localhost').pathname;
+        }
+        catch { /* keep default */ }
+        if (pathname !== path) {
+            socket.destroy();
+            return;
+        }
+        wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req));
+    });
+    wss.on('connection', (ws) => {
+        let boundCid = null;
+        let authed = false;
+        ws.isAlive = true;
+        ws.on('pong', () => { ws.isAlive = true; });
+        const authTimer = setTimeout(() => { if (!authed)
+            ws.close(4001, 'auth timeout'); }, authTimeoutMs);
+        ws.on('message', async (data) => {
+            if (authed)
+                return; // presence is passive after auth; ignore further frames
+            let msg;
+            try {
+                msg = JSON.parse(data.toString());
+            }
+            catch {
+                ws.close(4002, 'bad json');
+                return;
+            }
+            if (typeof msg !== 'object' || msg === null) {
+                ws.close(4003, 'bad auth frame');
+                return;
+            }
+            // Claim this socket's single auth attempt BEFORE the await: verify() yields,
+            // so a second frame racing in during it must not also authenticate. Without
+            // this, two frames for different cids can both register, but only the last
+            // boundCid is cleaned up on close — leaving the first cid "online" forever
+            // (permanent push suppression for that recipient).
+            authed = true;
+            clearTimeout(authTimer);
+            let cid = null;
+            try {
+                cid = await deps.verify(msg);
+            }
+            catch {
+                cid = null;
+            }
+            if (!cid) {
+                try {
+                    ws.send(JSON.stringify({ ok: false, error: 'auth rejected' }));
+                }
+                catch { /* closing */ }
+                ws.close(4004, 'auth rejected');
+                return;
+            }
+            boundCid = cid;
+            registry.add(cid, ws);
+            deps.onChange?.(cid, true);
+            try {
+                ws.send(JSON.stringify({ ok: true }));
+            }
+            catch { /* closing */ }
+        });
+        const drop = () => {
+            clearTimeout(authTimer);
+            if (boundCid) {
+                const wentOffline = registry.remove(boundCid, ws);
+                if (wentOffline)
+                    deps.onChange?.(boundCid, false);
+                boundCid = null;
+            }
+        };
+        ws.on('close', drop);
+        ws.on('error', drop);
+    });
+    // Transport-level keepalive: a socket that misses a pong round is terminated,
+    // which fires 'close' and clears its presence. Bounds the "backgrounded but
+    // socket not yet dropped" window to ~pingIntervalMs.
+    const pinger = setInterval(() => {
+        for (const ws of wss.clients) {
+            if (ws.isAlive === false) {
+                ws.terminate();
+                continue;
+            }
+            ws.isAlive = false;
+            try {
+                ws.ping();
+            }
+            catch { /* terminating */ }
+        }
+    }, pingIntervalMs);
+    if (typeof pinger.unref === 'function')
+        pinger.unref();
+    return {
+        close: () => new Promise((resolve) => {
+            clearInterval(pinger);
+            wss.close(() => resolve());
+            for (const ws of wss.clients)
+                ws.terminate();
+        }),
+    };
+}

package/dist/provision.js

@@ -0,0 +1,29 @@
+// Self-provisioning: make a fresh install "just work" on first boot. Creates the
+// state dir and, if the VAPID keypair is absent, generates + persists it (public
+// 0644, private 0600) into the state dir. The identity signing secret
+// (identity.key → stable cid) is provisioned separately by startDaemon() the
+// first time it boots without one; here we only ensure the state dir + VAPID.
+//
+// Inline VAPID_PUBLIC_KEY/PRIVATE_KEY env keys take precedence and suppress file
+// generation (the operator supplied their own).
+import * as fs from 'node:fs';
+import { dirname } from 'node:path';
+import webpush from 'web-push';
+export function provision(r, env = process.env) {
+    fs.mkdirSync(r.stateDir, { recursive: true });
+    // Operator-supplied inline keys win — nothing to generate.
+    if (env.VAPID_PUBLIC_KEY?.trim() && env.VAPID_PRIVATE_KEY?.trim()) {
+        return { stateDir: r.stateDir, vapidGenerated: false };
+    }
+    const havePublic = fs.existsSync(r.vapidPublicFile);
+    const havePrivate = fs.existsSync(r.vapidPrivateFile);
+    if (havePublic && havePrivate) {
+        return { stateDir: r.stateDir, vapidGenerated: false };
+    }
+    const { publicKey, privateKey } = webpush.generateVAPIDKeys();
+    fs.mkdirSync(dirname(r.vapidPublicFile), { recursive: true });
+    fs.mkdirSync(dirname(r.vapidPrivateFile), { recursive: true });
+    fs.writeFileSync(r.vapidPublicFile, publicKey + '\n', { mode: 0o644 });
+    fs.writeFileSync(r.vapidPrivateFile, privateKey + '\n', { mode: 0o600 });
+    return { stateDir: r.stateDir, vapidGenerated: true };
+}

package/dist/push.js

@@ -0,0 +1,6 @@
+// No-op sender (used when PUSH_DISABLED=1): reports every binding as dropped.
+export class DisabledPushSender {
+    async sendPushes(bindings, _payload) {
+        return bindings.map((b) => ({ binding_id: b.binding_id, ok: false, error: 'push disabled' }));
+    }
+}

package/dist/web-push-sender.js

@@ -0,0 +1,41 @@
+// Real WebPush egress via the `web-push` npm package (VAPID). Per-binding
+// try/catch, log-and-continue on 4xx/5xx — a dead endpoint never
+// fails the batch. Binding auto-prune on 404/410 is a non-v1 enhancement.
+import webpush from 'web-push';
+import { Agent } from 'node:https';
+export class WebPushSender {
+    subject;
+    publicKey;
+    privateKey;
+    agent;
+    constructor(subject, publicKey, privateKey, tlsInsecure = false) {
+        this.subject = subject;
+        this.publicKey = publicKey;
+        this.privateKey = privateKey;
+        // PUSH_TLS_INSECURE=1: accept self-signed push endpoints (the mock-push
+        // integration test / a self-hosted lab). NEVER for real browser pushes.
+        if (tlsInsecure)
+            this.agent = new Agent({ rejectUnauthorized: false });
+    }
+    async sendPushes(bindings, payload) {
+        const results = [];
+        for (const b of bindings) {
+            try {
+                const res = await webpush.sendNotification({ endpoint: b.endpoint, keys: { p256dh: b.p256dh, auth: b.auth } }, payload, {
+                    vapidDetails: { subject: this.subject, publicKey: this.publicKey, privateKey: this.privateKey },
+                    ...(this.agent ? { agent: this.agent } : {}),
+                });
+                results.push({ binding_id: b.binding_id, ok: true, status: res.statusCode });
+            }
+            catch (err) {
+                results.push({
+                    binding_id: b.binding_id,
+                    ok: false,
+                    status: err?.statusCode,
+                    error: String(err?.body || err?.message || err).slice(0, 200),
+                });
+            }
+        }
+        return results;
+    }
+}