@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.1

package/dist/push/routes/push.js

@@ -0,0 +1,224 @@
+import { Hono } from "hono";
+import { describeRoute, validator } from "hono-openapi";
+import { resolver } from "hono-openapi";
+import z from "zod";
+import { PushStore } from "../store.js";
+import { PushService } from "../service.js";
+import { PushTypes } from "../types.js";
+import { errors } from "@ericsanchezok/synergy-server/server/error";
+const ForbiddenEndpointError = z
+    .object({
+    message: z.string(),
+})
+    .meta({ ref: "PushEndpointRejected" });
+const CategoriesSchema = z
+    .object({
+    completion: z.boolean(),
+    error: z.boolean(),
+    input: z.boolean(),
+})
+    .meta({ ref: "PushCategories" });
+const SubscriptionSchema = z
+    .object({
+    id: z.string(),
+    endpoint: z.string(),
+    deviceLabel: z.string().optional(),
+    created: z.number(),
+    categories: CategoriesSchema,
+})
+    .meta({ ref: "PushSubscriptionInfo" });
+const SubscribeBody = z.object({
+    endpoint: z.string().url(),
+    keys: z.object({ p256dh: z.string(), auth: z.string() }),
+    deviceLabel: z.string().optional(),
+    categories: CategoriesSchema.optional(),
+});
+export const PushRoute = () => new Hono()
+    .get("/vapid-key", describeRoute({
+    summary: "Get the server's public Web Push VAPID key",
+    description: "Returns the public VAPID key browsers need for PushManager.subscribe. The key pair is generated on first use.",
+    operationId: "push.getVapidKey",
+    responses: {
+        200: {
+            description: "Public VAPID key",
+            content: {
+                "application/json": {
+                    schema: resolver(z.object({ publicKey: z.string() }).meta({ ref: "PushVapidKey" })),
+                },
+            },
+        },
+    },
+}), async (c) => {
+    const keys = await PushStore.vapidKeys();
+    return c.json({ publicKey: keys.publicKey });
+})
+    .get("/subscriptions", describeRoute({
+    summary: "List Web Push subscriptions",
+    description: "List every registered push subscription. Subscription keys are never returned.",
+    operationId: "push.list",
+    responses: {
+        200: {
+            description: "Registered subscriptions without transport keys",
+            content: {
+                "application/json": {
+                    schema: resolver(SubscriptionSchema.array()),
+                },
+            },
+        },
+    },
+}), async (c) => {
+    const all = await PushStore.list();
+    return c.json(all.map((s) => ({
+        id: s.id,
+        endpoint: s.endpoint,
+        ...(s.deviceLabel !== undefined ? { deviceLabel: s.deviceLabel } : {}),
+        created: s.created,
+        categories: s.categories,
+    })));
+})
+    .post("/subscribe", describeRoute({
+    summary: "Register a Web Push subscription",
+    description: "Register a browser push subscription (endpoint + encryption keys). Re-subscribing with the same endpoint updates it in place.",
+    operationId: "push.subscribe",
+    responses: {
+        200: {
+            description: "Subscription stored",
+            content: {
+                "application/json": {
+                    schema: resolver(SubscriptionSchema),
+                },
+            },
+        },
+        ...errors(400),
+    },
+}), validator("json", SubscribeBody), async (c) => {
+    const body = c.req.valid("json");
+    if (!PushTypes.isAllowedPushEndpoint(body.endpoint)) {
+        return c.json(ForbiddenEndpointError.parse({ message: "Push endpoint is not an allowed push service" }), 400);
+    }
+    const stored = await PushStore.upsert(body);
+    return c.json({
+        id: stored.id,
+        endpoint: stored.endpoint,
+        ...(stored.deviceLabel !== undefined ? { deviceLabel: stored.deviceLabel } : {}),
+        created: stored.created,
+        categories: stored.categories,
+    });
+})
+    .post("/unsubscribe", describeRoute({
+    summary: "Remove a Web Push subscription",
+    description: "Remove the subscription matching the given push endpoint.",
+    operationId: "push.unsubscribe",
+    responses: {
+        200: {
+            description: "Subscription removed (idempotent)",
+            content: {
+                "application/json": {
+                    schema: resolver(z.boolean()),
+                },
+            },
+        },
+        ...errors(400),
+    },
+}), validator("json", z.object({ endpoint: z.string().url() })), async (c) => {
+    const body = c.req.valid("json");
+    if (!PushTypes.isAllowedPushEndpoint(body.endpoint)) {
+        return c.json(ForbiddenEndpointError.parse({ message: "Push endpoint is not an allowed push service" }), 400);
+    }
+    await PushStore.removeByEndpoint(body.endpoint);
+    return c.json(true);
+})
+    .post("/test", describeRoute({
+    summary: "Send a test Web Push notification",
+    description: "Send one test notification to verify an existing subscription end to end. With an endpoint, only that subscription receives it.",
+    operationId: "push.test",
+    responses: {
+        200: {
+            description: "Test notification dispatched",
+            content: {
+                "application/json": {
+                    schema: resolver(z.boolean()),
+                },
+            },
+        },
+        404: {
+            description: "Unknown subscription endpoint",
+            content: {
+                "application/json": {
+                    schema: resolver(z.object({ message: z.string() })),
+                },
+            },
+        },
+        502: {
+            description: "Delivery to the requested subscription failed",
+            content: {
+                "application/json": {
+                    schema: resolver(z.object({ message: z.string() })),
+                },
+            },
+        },
+        ...errors(400),
+    },
+}), validator("json", z.object({ endpoint: z.string().url().optional() })), async (c) => {
+    const body = c.req.valid("json");
+    if (body.endpoint && !PushTypes.isAllowedPushEndpoint(body.endpoint)) {
+        return c.json(ForbiddenEndpointError.parse({ message: "Push endpoint is not an allowed push service" }), 400);
+    }
+    const payload = {
+        title: "Synergy push test",
+        body: "If you can read this, device push is working.",
+        href: "/",
+        tag: "push-test",
+        category: "test",
+    };
+    if (body.endpoint) {
+        const existing = await PushStore.findByEndpoint(body.endpoint);
+        if (!existing)
+            return c.json({ message: "Unknown subscription endpoint" }, 404);
+        // Send only to the requested device and surface its delivery failure,
+        // so a rejected endpoint cannot masquerade as a successful test.
+        try {
+            await PushService.sendTo(existing, payload);
+        }
+        catch {
+            return c.json({ message: "Test delivery failed" }, 502);
+        }
+        return c.json(true);
+    }
+    await PushService.send(payload);
+    return c.json(true);
+})
+    .patch("/subscriptions/:id/categories", describeRoute({
+    summary: "Update push category preferences for one subscription",
+    description: "Enable or disable completion/error/input pushes per subscribed device.",
+    operationId: "push.updateCategories",
+    responses: {
+        200: {
+            description: "Categories updated",
+            content: {
+                "application/json": {
+                    schema: resolver(z.boolean()),
+                },
+            },
+        },
+        404: {
+            description: "Unknown subscription id",
+            content: {
+                "application/json": {
+                    schema: resolver(z.object({ message: z.string() })),
+                },
+            },
+        },
+        ...errors(400),
+    },
+}), validator("param", z.object({
+    id: z.string(),
+})), validator("json", CategoriesSchema), async (c) => {
+    const { id } = c.req.valid("param");
+    const existing = await PushStore.list();
+    if (!existing.some((s) => s.id === id)) {
+        return c.json({ message: "Unknown subscription id" }, 404);
+    }
+    await PushStore.updateCategories(id, c.req.valid("json"));
+    return c.json(true);
+});

package/dist/push/service.js

@@ -0,0 +1,93 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context";
+import webpush from "web-push";
+import { PushStore } from "./store.js";
+import { Log } from "@ericsanchezok/synergy-harness/util/log";
+export var PushService;
+(function (PushService) {
+    const log = Log.create({ service: "push.service" });
+    const TTL_BY_CATEGORY = {
+        input: 3600,
+        completion: 300,
+        error: 300,
+        test: 300,
+    };
+    const URGENCY_BY_CATEGORY = {
+        input: "high",
+        completion: "normal",
+        error: "normal",
+        test: "normal",
+    };
+    const runtimeState = RuntimeContext.state(() => ({
+        sendFn: webpush.sendNotification.bind(webpush),
+    }));
+    /** Test seam: replace the transport without touching the real push services. */
+    function setSender(fn) {
+        const instanceState = runtimeState();
+        instanceState.sendFn = fn;
+    }
+    PushService.setSender = setSender;
+    function resetSender() {
+        const instanceState = runtimeState();
+        instanceState.sendFn = webpush.sendNotification.bind(webpush);
+    }
+    PushService.resetSender = resetSender;
+    /**
+     * Fan out one payload to every opted-in subscription. Endpoint failures are
+     * per-device: 404/410 prunes the stale subscription, every other error is
+     * logged and never propagates — a broken device must not block other
+     * devices or the event publisher.
+     */
+    async function send(payload) {
+        const subscriptions = await PushStore.list();
+        const targets = subscriptions.filter((s) => {
+            if (payload.category === "test")
+                return true;
+            return s.categories[payload.category] === true;
+        });
+        if (targets.length === 0)
+            return;
+        const vapid = await PushStore.vapidKeys();
+        const serialized = JSON.stringify(payload);
+        await Promise.allSettled(targets.map((sub) => deliver(sub, serialized, payload.category, vapid)));
+    }
+    PushService.send = send;
+    /**
+     * Deliver one payload to a single subscription (the settings "test" flow).
+     * Rejects on transport failure so the caller can surface why the test did
+     * not arrive; 404/410 still prunes the dead subscription before rejecting.
+     */
+    async function sendTo(subscription, payload) {
+        const vapid = await PushStore.vapidKeys();
+        await deliver(subscription, JSON.stringify(payload), payload.category, vapid, { propagate: true });
+    }
+    PushService.sendTo = sendTo;
+    async function deliver(sub, serialized, category, vapid, options) {
+        const instanceState = runtimeState();
+        try {
+            await instanceState.sendFn({ endpoint: sub.endpoint, keys: sub.keys }, serialized, {
+                TTL: TTL_BY_CATEGORY[category],
+                urgency: URGENCY_BY_CATEGORY[category],
+                vapidDetails: {
+                    // RFC 8292 requires the subject to be a contactable mailto or
+                    // https URI. Apple rejects JWTs whose host cannot be resolved
+                    // (403 BadJwtToken), so this must stay a public, project-owned URL.
+                    subject: "https://github.com/SII-Holos/synergy",
+                    publicKey: vapid.publicKey,
+                    privateKey: vapid.privateKey,
+                },
+            });
+        }
+        catch (error) {
+            const statusCode = error?.statusCode;
+            if (statusCode === 404 || statusCode === 410) {
+                await PushStore.removeById(sub.id).catch(() => undefined);
+                log.info("pruned expired push subscription", { subscriptionID: sub.id });
+            }
+            else {
+                log.warn("push delivery failed", { subscriptionID: sub.id, statusCode, error });
+            }
+            if (options?.propagate)
+                throw error;
+        }
+    }
+})(PushService || (PushService = {}));

package/dist/push/store.js

@@ -0,0 +1,121 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context";
+import { z } from "zod";
+import path from "node:path";
+import webpush from "web-push";
+import { Storage } from "@ericsanchezok/synergy-harness/storage/storage";
+import { StoragePath } from "@ericsanchezok/synergy-harness/storage/path";
+import { Global } from "@ericsanchezok/synergy-harness/global";
+import { PushTypes } from "./types.js";
+import { Log } from "@ericsanchezok/synergy-harness/util/log";
+export var PushStore;
+(function (PushStore) {
+    const log = Log.create({ service: "push.store" });
+    // Subscription endpoints + p256dh/auth and the VAPID private key are
+    // credential material: together they allow authenticated, encrypted pushes
+    // to registered devices. Persist them owner-only, like the provider auth
+    // stores (api-key.ts writes its store through a 0600 handle).
+    function credentialFile(key) {
+        return path.join(Global.Path.data, ...key) + ".json";
+    }
+    async function list() {
+        const ids = await Storage.scan(StoragePath.pushSubscriptionsRoot());
+        const records = await Storage.readMany(ids.map((id) => StoragePath.pushSubscription(id)));
+        return records.filter((x) => Boolean(x));
+    }
+    PushStore.list = list;
+    /**
+     * Idempotent upsert keyed by endpoint: re-subscribing from the same device
+     * refreshes its keys/categories instead of duplicating fan-out targets.
+     */
+    async function upsert(input) {
+        return Storage.transaction(async () => {
+            const existing = await findByEndpoint(input.endpoint);
+            const record = {
+                id: existing?.id ?? `push_${crypto.randomUUID().replace(/-/g, "").slice(0, 16)}`,
+                endpoint: input.endpoint,
+                keys: input.keys,
+                ...(input.deviceLabel !== undefined ? { deviceLabel: input.deviceLabel } : {}),
+                created: existing?.created ?? Date.now(),
+                categories: input.categories ?? existing?.categories ?? PushTypes.DEFAULT_CATEGORIES,
+            };
+            await Storage.write(StoragePath.pushSubscription(record.id), record);
+            return record;
+        });
+    }
+    PushStore.upsert = upsert;
+    async function removeByEndpoint(endpoint) {
+        await Storage.transaction(async () => {
+            const existing = await findByEndpoint(endpoint);
+            if (existing)
+                await Storage.remove(StoragePath.pushSubscription(existing.id));
+        });
+    }
+    PushStore.removeByEndpoint = removeByEndpoint;
+    async function removeById(id) {
+        return Storage.transaction(async () => {
+            const [existing] = await Storage.readMany([StoragePath.pushSubscription(id)]);
+            if (!existing)
+                return false;
+            await Storage.remove(StoragePath.pushSubscription(id));
+            return true;
+        });
+    }
+    PushStore.removeById = removeById;
+    async function findByEndpoint(endpoint) {
+        const all = await list();
+        return all.find((s) => s.endpoint === endpoint);
+    }
+    PushStore.findByEndpoint = findByEndpoint;
+    async function updateCategories(id, categories) {
+        await Storage.transaction(async () => {
+            const [existing] = await Storage.readMany([StoragePath.pushSubscription(id)]);
+            if (existing)
+                await Storage.write(StoragePath.pushSubscription(id), { ...existing, categories });
+        });
+    }
+    PushStore.updateCategories = updateCategories;
+    // Memoized first-use generation keyed by the data home: two concurrent
+    // callers must observe the same key pair (otherwise one subscribes with a
+    // public key the persisted private key no longer backs), and a different
+    // home (isolated test fixture) must not inherit another home's keys.
+    const runtimeState = RuntimeContext.state(() => ({
+        vapidInitHome: undefined,
+        vapidInit: undefined,
+    }));
+    /**
+     * VAPID server keys. Generated once on first use and persisted owner-only;
+     * the private key is a credential — never logged, exported, or returned by
+     * any route.
+     */
+    function vapidKeys() {
+        const instanceState = runtimeState();
+        const home = Global.Path.data;
+        if (instanceState.vapidInit && instanceState.vapidInitHome === home)
+            return instanceState.vapidInit;
+        instanceState.vapidInitHome = home;
+        instanceState.vapidInit = (async () => {
+            const filename = credentialFile(StoragePath.pushVapid());
+            const existing = await Bun.file(filename)
+                .json()
+                .catch((error) => {
+                if (error?.code === "ENOENT")
+                    return;
+                throw error;
+            });
+            if (existing !== undefined)
+                return z.object({ publicKey: z.string().min(1), privateKey: z.string().min(1) }).parse(existing);
+            const generated = webpush.generateVAPIDKeys();
+            await Storage.writeJsonAtomic(filename, JSON.stringify(generated), { private: true, durable: true });
+            log.info("generated VAPID key pair");
+            return generated;
+        })().catch((error) => {
+            const instanceState = runtimeState();
+            // Allow a later caller to retry generation after a transient failure.
+            instanceState.vapidInit = undefined;
+            instanceState.vapidInitHome = undefined;
+            throw error;
+        });
+        return instanceState.vapidInit;
+    }
+    PushStore.vapidKeys = vapidKeys;
+})(PushStore || (PushStore = {}));

package/dist/push/types.js

@@ -0,0 +1,58 @@
+import z from "zod";
+export var PushTypes;
+(function (PushTypes) {
+    PushTypes.Categories = z
+        .object({
+        completion: z.boolean(),
+        error: z.boolean(),
+        input: z.boolean(),
+    })
+        .meta({ ref: "PushCategories" });
+    PushTypes.DEFAULT_CATEGORIES = { completion: true, error: true, input: true };
+    PushTypes.Subscription = z
+        .object({
+        id: z.string(),
+        endpoint: z.string().url(),
+        keys: z.object({ p256dh: z.string(), auth: z.string() }),
+        deviceLabel: z.string().optional(),
+        created: z.number(),
+        categories: PushTypes.Categories,
+    })
+        .meta({ ref: "PushSubscription" });
+    PushTypes.SubscribeInput = z.object({
+        endpoint: z.string().url(),
+        keys: z.object({ p256dh: z.string(), auth: z.string() }),
+        deviceLabel: z.string().optional(),
+        categories: PushTypes.Categories.optional(),
+    });
+    PushTypes.UnsubscribeInput = z.object({
+        endpoint: z.string().url(),
+    });
+    PushTypes.Payload = z.object({
+        title: z.string(),
+        body: z.string(),
+        href: z.string(),
+        tag: z.string(),
+        category: z.enum(["completion", "error", "input", "test"]),
+        badge: z.number().int().nonnegative().optional(),
+    });
+    /**
+     * Web Push endpoints are attacker-controllable URLs; the server POSTs the
+     * encrypted payload to them, so only known browser push service hosts are
+     * accepted (SSRF boundary for /push/subscribe).
+     */
+    function isAllowedPushEndpoint(endpoint) {
+        let parsed;
+        try {
+            parsed = new URL(endpoint);
+        }
+        catch {
+            return false;
+        }
+        if (parsed.protocol !== "https:")
+            return false;
+        const host = parsed.hostname;
+        return (host === "fcm.googleapis.com" || host === "updates.push.services.mozilla.com" || host.endsWith(".push.apple.com"));
+    }
+    PushTypes.isAllowedPushEndpoint = isAllowedPushEndpoint;
+})(PushTypes || (PushTypes = {}));