@huynle/hub 0.9.1 → 0.10.0

package/src/central/agent/subscription-routes.ts

@@ -0,0 +1,174 @@
+// The session subscription API on /api/agent (decision 74qawely; docs/subscriptions.md), over Subscriptions
+// (subscriptions.ts):
+//
+//   POST   /api/agent/subscriptions      {subscriber?, to, types?, delivery?, batch?, maxPerHour?, expires?, note?}
+//                                         → 201 {subscription}
+//   GET    /api/agent/subscriptions?session=<addr>   → {subscriptions}
+//   GET    /api/agent/subscriptions/:id  → {subscription}
+//   DELETE /api/agent/subscriptions/:id  → 204
+//
+// Who: a session token subscribes ITSELF only (`subscriber` absent or naming itself, else 403 forbidden) and sees and
+// removes only the subscriptions it is the subscriber of. Users manage all of theirs (`subscriber` required; `?session=`
+// lists what a session subscribes to and what subscribes to it). App tokens need events:subscribe and sessions:read,
+// plus the scope of each selected family (messages:read, sessions:launch, sessions:manage) and, for any delivery but
+// silent (which never wakes or steers), messages:send — as for POST /msg; they see and remove only
+// the subscriptions they created. A subscription that is not the caller's is 404 not_found, like a missing one.
+// Notices always go to the subscriber session and respect ITS visibility, whoever created the subscription.
+import { boundedJson } from "./body"
+import type { Store } from "../store"
+import type { AgentActor } from "./actor"
+import type { Directory } from "./directory"
+import { AgentError } from "./errors"
+import type { AgentRoute } from "./routes"
+import { parseSubscriptionTypes, SUBSCRIPTION_EVENT_TYPES, SUBSCRIPTION_FAMILIES, type SubscriptionOwner, type Subscriptions, typeMatches } from "./subscriptions"
+import { type Census, type TeamDiscovery, teamScoped, visible } from "../teams/discovery"
+
+// A literal: routes.ts imports this module.
+const PATH = "/api/agent/subscriptions"
+const NO_STORE = { "cache-control": "no-store" }
+/** The scopes every app subscription needs. */
+export const SUBSCRIPTION_APP_SCOPES: readonly string[] = ["events:subscribe", "sessions:read"]
+
+export type RouteSubscriptions = Pick<Subscriptions, "create" | "list" | "get" | "remove">
+
+export interface SubscriptionRouteDeps {
+  readonly subscriptions: RouteSubscriptions
+  readonly directory: Pick<Directory, "resolve">
+  /** Address resolution with team visibility (HWA-40); absent: the directory. */
+  readonly discovery?: Pick<TeamDiscovery, "census" | "resolve">
+  readonly store?: Pick<Store, "audit">
+}
+
+/** The scope an app needs per type (computed on use: routes.ts and subscriptions.ts import each other through events-routes). */
+const scopeOf = (type: string): string | undefined =>
+  type === "message.changed" ? "messages:read" : type === "launch.changed" ? "sessions:launch" : [...(SUBSCRIPTION_FAMILIES.naming ?? []), ...(SUBSCRIPTION_FAMILIES.manage ?? [])].includes(type) ? "sessions:manage" : undefined
+
+/** The scopes an app needs for these type patterns beyond SUBSCRIPTION_APP_SCOPES (state qualifiers: none). */
+export function subscriptionTypeScopes(patterns: readonly string[]): string[] {
+  const scopes = new Set<string>()
+  for (const type of SUBSCRIPTION_EVENT_TYPES) {
+    const scope = scopeOf(type)
+    if (scope && patterns.some((p) => !p.startsWith("state:") && typeMatches([p], { type, data: {} }))) scopes.add(scope)
+  }
+  return [...scopes]
+}
+
+const notFound = (id: string) => new AgentError("not_found", `No subscription ${id}`)
+
+const ownerOf = (actor: AgentActor): SubscriptionOwner => (actor.kind === "app" ? `app:${actor.tokenID}` : actor.kind === "session" ? `ses:${actor.sessionID}` : "user")
+
+/** What a caller may see and remove: an app what it created, a session what it subscribes, the user everything. */
+const onlyFor = (actor: AgentActor): { by?: SubscriptionOwner; subscriber?: string } =>
+  actor.kind === "app" ? { by: ownerOf(actor) } : actor.kind === "session" ? { subscriber: actor.sessionID } : {}
+
+function requireAppScopes(actor: AgentActor, extra: readonly string[] = []): void {
+  if (actor.kind !== "app") return
+  const missing = [...SUBSCRIPTION_APP_SCOPES, ...extra].filter((scope) => !actor.scopes.includes(scope))
+  if (missing.length) throw new AgentError("forbidden", `Subscriptions need scope ${missing.join(", ")}`)
+}
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const raw = (await boundedJson(request)) as unknown
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) throw new AgentError("invalid", "Body must be a JSON object")
+  return raw as Record<string, unknown>
+}
+
+/** The sessions of a team (by name or ID) the census's caller may see; none when it may not see the team. */
+export function teamMembers(census: Census, name: string): string[] {
+  const team = census.teams.get(name) ?? [...census.teams.values()].find((t) => t.name === name)
+  if (!team || (teamScoped(census) && !census.callerTeams.has(team.id))) return []
+  return [...census.seats].filter(([sessionID, seats]) => seats.some((s) => s.teamID === team.id) && visible(census, sessionID)).map(([sessionID]) => sessionID)
+}
+
+/**
+ * Subscriptions' resolveTarget with team visibility: the sessions an address (`#team` included) names for the
+ * subscriber session. Without discovery: the directory (and no teams).
+ */
+export function subscriptionResolver(directory: Pick<Directory, "resolve">, discovery?: Pick<TeamDiscovery, "census" | "resolve">) {
+  return async (userID: string, subscriberID: string, addr: string): Promise<string[]> => {
+    if (!discovery) return addr.startsWith("#") ? [] : directory.resolve(userID, addr).sessions.map((s) => s.sessionID)
+    const census = await discovery.census(userID, { kind: "session", userID, machineID: "", sessionID: subscriberID, via: "shell" })
+    if (addr.startsWith("#")) return teamMembers(census, addr.slice(1))
+    return discovery.resolve(census, addr).sessions.map((s) => s.sessionID)
+  }
+}
+
+export function subscriptionRoutes(deps: SubscriptionRouteDeps): AgentRoute[] {
+  /** The one session an address names for the caller (a role with several holders is ambiguous). */
+  const one = async (userID: string, actor: AgentActor, addr: string): Promise<string> => {
+    const sessions = deps.discovery ? deps.discovery.resolve(await deps.discovery.census(userID, actor), addr).sessions : deps.directory.resolve(userID, addr).sessions
+    if (sessions.length !== 1) throw new AgentError("ambiguous", `${addr} names ${sessions.length} sessions`, { extra: { candidates: sessions.slice(0, 20).map((s) => ({ sessionID: s.sessionID, ...(s.name ? { name: s.name } : {}) })) } })
+    return sessions[0]!.sessionID
+  }
+  const ALLOW = { session: true, app: true } as const
+  return [
+    {
+      method: "POST",
+      path: PATH,
+      allow: ALLOW,
+      async handle({ request, actor, user }) {
+        requireAppScopes(actor)
+        const input = await bodyOf(request)
+        // Waking or steering a session is a send: an app needs messages:send for any delivery but silent.
+        requireAppScopes(actor, [...subscriptionTypeScopes(parseSubscriptionTypes(input.types)), ...(input.delivery === "silent" ? [] : ["messages:send"])])
+        let subscriber: string
+        if (actor.kind === "session") {
+          subscriber = actor.sessionID
+          if (input.subscriber !== undefined && input.subscriber !== null) {
+            if (typeof input.subscriber !== "string" || (await one(user.id, actor, input.subscriber)) !== actor.sessionID) throw new AgentError("forbidden", "A session subscribes only itself", { hint: "Leave subscriber out" })
+          }
+        } else {
+          if (typeof input.subscriber !== "string" || !input.subscriber.trim()) throw new AgentError("invalid", "subscriber is required: the session that gets the notices (@name, ses_…)")
+          subscriber = await one(user.id, actor, input.subscriber.trim())
+        }
+        const result = await deps.subscriptions.create(user.id, ownerOf(actor), {
+          subscriber,
+          to: input.to,
+          types: input.types,
+          delivery: input.delivery,
+          batch: input.batch,
+          maxPerHour: input.maxPerHour,
+          expires: input.expires,
+          note: input.note,
+        })
+        await deps.store?.audit({ actor: user.id, action: "subscription.create", target: result.subscription.id, detail: subscriber })
+        return Response.json(result, { status: 201, headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: PATH,
+      allow: ALLOW,
+      async handle({ url, actor, user }) {
+        requireAppScopes(actor)
+        const addr = url.searchParams.get("session")
+        const about = addr ? await one(user.id, actor, addr) : undefined
+        const subscriptions = await deps.subscriptions.list(user.id, { ...onlyFor(actor), ...(about !== undefined ? { about } : {}) })
+        return Response.json({ subscriptions }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: `${PATH}/:id`,
+      allow: ALLOW,
+      async handle({ params, actor, user }) {
+        requireAppScopes(actor)
+        const found = await deps.subscriptions.get(user.id, params.id!)
+        const only = onlyFor(actor)
+        if (!found || (only.by !== undefined && found.by !== only.by) || (only.subscriber !== undefined && found.subscriber !== only.subscriber)) throw notFound(params.id!)
+        return Response.json({ subscription: found }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PATH}/:id`,
+      allow: ALLOW,
+      async handle({ params, actor, user }) {
+        requireAppScopes(actor)
+        if (!(await deps.subscriptions.remove(user.id, params.id!, onlyFor(actor)))) throw notFound(params.id!)
+        await deps.store?.audit({ actor: user.id, action: "subscription.delete", target: params.id! })
+        return new Response(null, { status: 204, headers: NO_STORE })
+      },
+    },
+  ]
+}