@ericsanchezok/synergy-workbench 0.0.0-stage → 3.1.0

package/src/push/routes/push.ts

@@ -0,0 +1,267 @@
+import { Hono } from "hono"
+import { describeRoute, validator } from "hono-openapi"
+import { resolver } from "hono-openapi"
+import z from "zod"
+import { PushStore } from "../store"
+import { PushService } from "../service"
+import { PushTypes } from "../types"
+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: PushTypes.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/src/push/service.ts

@@ -0,0 +1,108 @@
+import { RuntimeContext } from "@ericsanchezok/synergy-harness/lifecycle/context"
+import webpush from "web-push"
+import { PushStore } from "./store"
+import { PushTypes } from "./types"
+import { Log } from "@ericsanchezok/synergy-harness/util/log"
+
+export namespace PushService {
+  const log = Log.create({ service: "push.service" })
+
+  type PayloadCategory = PushTypes.Payload["category"]
+
+  const TTL_BY_CATEGORY: Record<PayloadCategory, number> = {
+    input: 3600,
+    completion: 300,
+    error: 300,
+    test: 300,
+  }
+
+  const URGENCY_BY_CATEGORY: Record<PayloadCategory, "high" | "normal"> = {
+    input: "high",
+    completion: "normal",
+    error: "normal",
+    test: "normal",
+  }
+
+  export type SendFn = typeof webpush.sendNotification
+
+  const runtimeState = RuntimeContext.state(() => ({
+    sendFn: webpush.sendNotification.bind(webpush) as SendFn,
+  }))
+
+  /** Test seam: replace the transport without touching the real push services. */
+  export function setSender(fn: SendFn) {
+    const instanceState = runtimeState()
+
+    instanceState.sendFn = fn
+  }
+
+  export function resetSender() {
+    const instanceState = runtimeState()
+
+    instanceState.sendFn = webpush.sendNotification.bind(webpush)
+  }
+
+  /**
+   * 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.
+   */
+  export async function send(payload: PushTypes.Payload): Promise<void> {
+    const subscriptions = await PushStore.list()
+    const targets = subscriptions.filter((s) => {
+      if (payload.category === "test") return true
+      return s.categories[payload.category as "completion" | "error" | "input"] === 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)))
+  }
+
+  /**
+   * 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.
+   */
+  export async function sendTo(subscription: PushTypes.Subscription, payload: PushTypes.Payload): Promise<void> {
+    const vapid = await PushStore.vapidKeys()
+    await deliver(subscription, JSON.stringify(payload), payload.category, vapid, { propagate: true })
+  }
+
+  async function deliver(
+    sub: PushTypes.Subscription,
+    serialized: string,
+    category: PushTypes.Payload["category"],
+    vapid: { publicKey: string; privateKey: string },
+    options?: { propagate?: boolean },
+  ) {
+    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: unknown) {
+      const statusCode = (error as { statusCode?: number })?.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
+    }
+  }
+}

package/src/push/store.ts

@@ -0,0 +1,120 @@
+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"
+import { Log } from "@ericsanchezok/synergy-harness/util/log"
+
+export namespace 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: string[]): string {
+    return path.join(Global.Path.data, ...key) + ".json"
+  }
+
+  export async function list(): Promise<PushTypes.Subscription[]> {
+    const ids = await Storage.scan(StoragePath.pushSubscriptionsRoot())
+    const records = await Storage.readMany<PushTypes.Subscription>(ids.map((id) => StoragePath.pushSubscription(id)))
+    return records.filter((x): x is PushTypes.Subscription => Boolean(x))
+  }
+
+  /**
+   * Idempotent upsert keyed by endpoint: re-subscribing from the same device
+   * refreshes its keys/categories instead of duplicating fan-out targets.
+   */
+  export async function upsert(input: PushTypes.SubscribeInput): Promise<PushTypes.Subscription> {
+    return Storage.transaction(async () => {
+      const existing = await findByEndpoint(input.endpoint)
+      const record: PushTypes.Subscription = {
+        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
+    })
+  }
+
+  export async function removeByEndpoint(endpoint: string): Promise<void> {
+    await Storage.transaction(async () => {
+      const existing = await findByEndpoint(endpoint)
+      if (existing) await Storage.remove(StoragePath.pushSubscription(existing.id))
+    })
+  }
+
+  export async function removeById(id: string): Promise<boolean> {
+    return Storage.transaction(async () => {
+      const [existing] = await Storage.readMany<PushTypes.Subscription>([StoragePath.pushSubscription(id)])
+      if (!existing) return false
+      await Storage.remove(StoragePath.pushSubscription(id))
+      return true
+    })
+  }
+
+  export async function findByEndpoint(endpoint: string): Promise<PushTypes.Subscription | undefined> {
+    const all = await list()
+    return all.find((s) => s.endpoint === endpoint)
+  }
+
+  export async function updateCategories(id: string, categories: PushTypes.Categories): Promise<void> {
+    await Storage.transaction(async () => {
+      const [existing] = await Storage.readMany<PushTypes.Subscription>([StoragePath.pushSubscription(id)])
+      if (existing) await Storage.write(StoragePath.pushSubscription(id), { ...existing, categories })
+    })
+  }
+
+  // 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 as string | undefined,
+    vapidInit: undefined as Promise<{ publicKey: string; privateKey: string }> | 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.
+   */
+  export function vapidKeys(): Promise<{ publicKey: string; privateKey: string }> {
+    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
+  }
+}

package/src/push/types.ts

@@ -0,0 +1,67 @@
+import z from "zod"
+
+export namespace PushTypes {
+  export const Categories = z
+    .object({
+      completion: z.boolean(),
+      error: z.boolean(),
+      input: z.boolean(),
+    })
+    .meta({ ref: "PushCategories" })
+  export type Categories = z.infer<typeof Categories>
+
+  export const DEFAULT_CATEGORIES: Categories = { completion: true, error: true, input: true }
+
+  export const 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: Categories,
+    })
+    .meta({ ref: "PushSubscription" })
+  export type Subscription = z.infer<typeof Subscription>
+
+  export const SubscribeInput = z.object({
+    endpoint: z.string().url(),
+    keys: z.object({ p256dh: z.string(), auth: z.string() }),
+    deviceLabel: z.string().optional(),
+    categories: Categories.optional(),
+  })
+  export type SubscribeInput = z.infer<typeof SubscribeInput>
+
+  export const UnsubscribeInput = z.object({
+    endpoint: z.string().url(),
+  })
+
+  export const 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(),
+  })
+  export type Payload = z.infer<typeof Payload>
+
+  /**
+   * 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).
+   */
+  export function isAllowedPushEndpoint(endpoint: string): boolean {
+    let parsed: URL
+    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")
+    )
+  }
+}