@huynle/hub 0.6.1 → 0.7.2

package/src/central/agent/session-tokens.ts

@@ -0,0 +1,227 @@
+// Hub-minted session tokens (design §1.3): a bearer credential for one session of one machine, which the hub
+// pushes to the spoke reporting the session (sessionTokens op, see ../session-token-push.ts) and the spoke hands
+// to the session's shells.
+//
+// Format: `hst1.<b64url(payload JSON)>.<b64url(HMAC-SHA256(secret of kid, "hst1." + payload part))>`, where the
+// payload is {typ, uid, mid, sid, exp (ms since the epoch), kid, ue (user epoch), me (machine epoch), aud (the
+// hub's public URL)}. One algorithm, one prefix; anything else is not a session token.
+//
+// typ "session" is the shell token (HUB_SESSION_TOKEN; any code in the session's shells can read it): its actor
+// is via "shell" and can never act. typ "act" (phase 3, decision #1) is the act token, pushed only to spokes
+// announcing "actTokens" (actTokens op), which never put it in any environment; its actor is via "act", the only
+// session actor act verbs may admit (canActAsSession). The signature covers typ, so one cannot be turned into the other.
+//
+// A token is accepted while all of this holds: signature (constant-time) under a known kid, audience, expiry,
+// the user's and machine's current token epochs, the machine exists, is not revoked and still belongs to uid,
+// the user exists (the resolver refuses disabled users), and that machine still reports the session for uid.
+// Tokens and secrets are never logged and never appear in this object's JSON or inspect output.
+import { createHmac, timingSafeEqual } from "node:crypto"
+import { SESSION_TOKEN_MAX_CHARS } from "../../protocol"
+import type { Store } from "../store"
+import type { TokenKeys } from "../token-keys"
+import type { BearerVerifier, SessionActor, VerifyResult } from "./actor"
+
+export const SESSION_TOKEN_PREFIX = "hst1"
+/** How long a session token is valid. */
+export const SESSION_TOKEN_LIFETIME_MS = 24 * 60 * 60 * 1000
+
+/** What the verifier needs to know about live sessions (implemented by the registry). */
+export interface SessionLiveness {
+  /** Tenant (user ID) of a reported session (Registry.sessionTenant). */
+  sessionTenant(sessionID: string): string | undefined
+  /** Whether a connected process of the machine reports the session (for the machine's tenant). */
+  machineReports(machineID: string, sessionID: string): boolean
+}
+
+export interface SessionTokensOptions {
+  readonly keys: TokenKeys
+  readonly store: Store
+  readonly sessions: SessionLiveness
+  /** The hub's public URL: the tokens' audience. */
+  readonly publicURL: string
+  readonly now?: () => number
+  readonly lifetimeMs?: number
+}
+
+export interface MintedSessionToken {
+  readonly token: string
+  /** Expiry, ms since the epoch. */
+  readonly exp: number
+  /** The machine's stamp when minted (see SessionTokens.stamp). */
+  readonly stamp: string
+}
+
+/** Token types: "session" for shells, "act" for act verbs (the hub tool). */
+export type SessionTokenType = "session" | "act"
+
+interface Claims {
+  readonly typ: SessionTokenType
+  readonly uid: string
+  readonly mid: string
+  readonly sid: string
+  readonly exp: number
+  readonly kid: string
+  readonly ue: number
+  readonly me: number
+  readonly aud: string
+}
+
+const CLAIM_KEYS = ["typ", "uid", "mid", "sid", "exp", "kid", "ue", "me", "aud"].sort().join()
+const B64URL = /^[A-Za-z0-9_-]+$/
+/** HMAC-SHA256 output length. */
+const SIG_BYTES = 32
+
+const text = (v: unknown): v is string => typeof v === "string" && v.length > 0
+const count = (v: unknown): v is number => typeof v === "number" && Number.isSafeInteger(v) && v >= 0
+
+/** Canonical base64url only (no padding, no other alphabet, no non-zero trailing bits). */
+function decode(part: string): Buffer | undefined {
+  if (!B64URL.test(part)) return undefined
+  const bytes = Buffer.from(part, "base64url")
+  return bytes.toString("base64url") === part ? bytes : undefined
+}
+
+function parseClaims(bytes: Buffer): Claims | undefined {
+  let raw: unknown
+  try {
+    raw = JSON.parse(bytes.toString("utf8"))
+  } catch {
+    return undefined
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return undefined
+  const c = raw as Record<string, unknown>
+  if (Object.keys(c).sort().join() !== CLAIM_KEYS) return undefined
+  if ((c.typ !== "session" && c.typ !== "act") || !text(c.uid) || !text(c.mid) || !text(c.sid) || !text(c.kid) || !text(c.aud)) return undefined
+  if (!count(c.exp) || !count(c.ue) || !count(c.me)) return undefined
+  return c as unknown as Claims
+}
+
+const sign = (secret: Buffer, payload: string): Buffer => createHmac("sha256", secret).update(`${SESSION_TOKEN_PREFIX}.${payload}`).digest()
+
+export class SessionTokens {
+  readonly lifetimeMs: number
+  readonly verifier: BearerVerifier
+  readonly #keys: TokenKeys
+  readonly #store: Store
+  readonly #sessions: SessionLiveness
+  readonly #aud: string
+  readonly #now: () => number
+
+  constructor(options: SessionTokensOptions) {
+    this.#keys = options.keys
+    this.#store = options.store
+    this.#sessions = options.sessions
+    this.#aud = options.publicURL
+    this.#now = options.now ?? Date.now
+    this.lifetimeMs = options.lifetimeMs ?? SESSION_TOKEN_LIFETIME_MS
+    this.verifier = { kind: "session", verify: (token) => this.verifyFresh(token) }
+  }
+
+  /** The owner of an enrolled, unrevoked machine whose user exists and is enabled. */
+  #owner(machineID: string): string | undefined {
+    const machine = this.#store.machines().find((m) => m.id === machineID)
+    if (!machine || machine.revoked) return undefined
+    const user = this.#store.user(machine.ownerID)
+    return user && !user.disabled ? user.id : undefined
+  }
+
+  /**
+   * What a machine's tokens depend on besides the session: owner, active kid, user and machine epochs. Tokens
+   * minted under another stamp are stale (resend them); undefined when the machine cannot get tokens.
+   */
+  stamp(machineID: string): string | undefined {
+    const uid = this.#owner(machineID)
+    if (!uid) return undefined
+    return JSON.stringify([uid, this.#keys.active().kid, this.#store.userEpoch(uid), this.#store.machineEpoch(machineID)])
+  }
+
+  /**
+   * A token for a session of the machine's owner (undefined when the machine is unknown, revoked or its owner
+   * disabled, or the session belongs to another tenant or to nobody).
+   */
+  mint(machineID: string, sessionID: string): MintedSessionToken | undefined {
+    return this.#mint("session", machineID, sessionID)
+  }
+
+  /** An act token (typ "act") for the session, under the same rules as mint. Only for the actTokens op. */
+  mintAct(machineID: string, sessionID: string): MintedSessionToken | undefined {
+    return this.#mint("act", machineID, sessionID)
+  }
+
+  #mint(typ: SessionTokenType, machineID: string, sessionID: string): MintedSessionToken | undefined {
+    const uid = this.#owner(machineID)
+    if (!uid || this.#sessions.sessionTenant(sessionID) !== uid) return undefined
+    const { kid, secret } = this.#keys.active()
+    const exp = this.#now() + this.lifetimeMs
+    const claims: Claims = {
+      typ,
+      uid,
+      mid: machineID,
+      sid: sessionID,
+      exp,
+      kid,
+      ue: this.#store.userEpoch(uid),
+      me: this.#store.machineEpoch(machineID),
+      aud: this.#aud,
+    }
+    const payload = Buffer.from(JSON.stringify(claims)).toString("base64url")
+    const stamp = JSON.stringify([uid, kid, claims.ue, claims.me])
+    return { token: `${SESSION_TOKEN_PREFIX}.${payload}.${sign(secret, payload).toString("base64url")}`, exp, stamp }
+  }
+
+  /** The session actor of a valid token, "expired" for a genuine token past its expiry, else undefined (from memory). */
+  verify(token: string): VerifyResult {
+    const claims = this.#genuine(token)
+    return claims && claims !== "expired" ? this.#current(claims) : claims
+  }
+
+  /**
+   * verify, after reading the token's user and machine again (a shared store's security re-check: a revocation,
+   * epoch bump or disabled user on another pod applies at once). The bearer verifier uses this.
+   */
+  async verifyFresh(token: string): Promise<VerifyResult> {
+    const claims = this.#genuine(token)
+    if (!claims || claims === "expired") return claims
+    await this.#store.recheck({ users: [claims.uid], machines: [claims.mid] })
+    return this.#current(claims)
+  }
+
+  /** The claims of a token signed with a known key for this hub, "expired" past its expiry, else undefined. */
+  #genuine(token: string): Claims | "expired" | undefined {
+    if (typeof token !== "string" || token.length > SESSION_TOKEN_MAX_CHARS) return undefined
+    const parts = token.split(".")
+    if (parts.length !== 3 || parts[0] !== SESSION_TOKEN_PREFIX) return undefined
+    const [, payload, sigPart] = parts as [string, string, string]
+    const body = decode(payload)
+    const sig = decode(sigPart)
+    if (!body || !sig || sig.length !== SIG_BYTES) return undefined
+    const claims = parseClaims(body)
+    if (!claims) return undefined
+    const secret = this.#keys.key(claims.kid)
+    if (!secret) return undefined
+    const expected = sign(secret, payload)
+    if (expected.length !== sig.length || !timingSafeEqual(expected, sig)) return undefined
+    if (claims.aud !== this.#aud) return undefined
+    if (this.#now() >= claims.exp) return "expired"
+    return claims
+  }
+
+  /** The session actor while the token's epochs, machine, user and session are all still current. */
+  #current(claims: Claims): VerifyResult {
+    if (claims.ue !== this.#store.userEpoch(claims.uid) || claims.me !== this.#store.machineEpoch(claims.mid)) return undefined
+    const machine = this.#store.machines().find((m) => m.id === claims.mid)
+    if (!machine || machine.revoked || machine.ownerID !== claims.uid) return undefined
+    if (!this.#store.user(claims.uid)) return undefined
+    if (this.#sessions.sessionTenant(claims.sid) !== claims.uid || !this.#sessions.machineReports(claims.mid, claims.sid)) return undefined
+    const actor: SessionActor = { kind: "session", userID: claims.uid, machineID: claims.mid, sessionID: claims.sid, via: claims.typ === "act" ? "act" : "shell" }
+    return actor
+  }
+
+  toJSON(): { audience: string; lifetimeMs: number } {
+    return { audience: this.#aud, lifetimeMs: this.lifetimeMs }
+  }
+
+  [Symbol.for("nodejs.util.inspect.custom")](): string {
+    return `SessionTokens(${this.#aud})`
+  }
+}

package/src/central/agent/versioned.ts

@@ -0,0 +1,26 @@
+// Read-modify-write over a StateStore key with optimistic versions: retried when another writer got there first.
+import type { StateStore } from "../backend/types"
+
+/** Attempts before a contended update gives up (each one re-reads the key). */
+const ATTEMPTS = 16
+
+/**
+ * Applies `change` to the key's current value (undefined: missing) and writes the result with ifVersion.
+ * `change` returning undefined leaves the key alone. Resolves with the written value (or undefined).
+ */
+export async function updateVersioned<T>(
+  state: StateStore,
+  userID: string,
+  collection: string,
+  key: string,
+  change: (current: T | undefined) => T | undefined,
+): Promise<T | undefined> {
+  for (let attempt = 0; attempt < ATTEMPTS; attempt++) {
+    const current = await state.get<T>(userID, collection, key)
+    const next = change(current?.value)
+    if (next === undefined) return undefined
+    const result = await state.put(userID, collection, key, next, { ifVersion: current?.version ?? 0 })
+    if (result.ok) return next
+  }
+  throw new Error(`state update of ${collection}/${key} kept conflicting`)
+}

package/src/central/agent/watch.ts

@@ -0,0 +1,112 @@
+// GET /api/agent/watch (design §4; lifecycle design "Events"): a live SSE view of the canonical agent event journal
+// (events.ts), for orchestrator loops. The same events, visibility and filters as GET /api/agent/events, read with
+// the same read() (events-routes.ts), so the two never define events differently. Not the console's /api/events.
+//
+//   ?blocked=1        blocker events only (blocker.*)
+//   ?session=<addr>   only that session's tree (an address resolved for the caller; several for a @@role)
+//   ?cursor=… or Last-Event-ID: resume after a cursor this stream (or GET /api/agent/events) gave; a bad one is
+//                     400 invalid_cursor before the stream starts
+//
+// Frames (each `data:` line one JSON object; `id:` lines carry the resumable cursor):
+//   {type: "ready", at}                                  first, once subscribed
+//   {id: "evt_…", at, type, subject, data}               a journal event (no free text)
+//   {type: "reset", at, refresh: [...]}                  the cursor was no longer covered: re-read those
+//   event: ping                                          every heartbeat while idle (default 20 s), with the cursor
+// When the hub drains (shutting down), the stream ends with `retry: 2000` (reconnect, to another pod, after it).
+import type { AgentActor } from "./actor"
+import type { AgentEvent } from "./events"
+import { read, RESET_REFRESH, type EventsPage, type EventsRouteDeps } from "./events-routes"
+
+export const WATCH_HEARTBEAT_MS = 20_000
+/** Draining: the `retry:` (ms) an ending watch stream sends. */
+export const WATCH_RETRY_MS = 2_000
+const RETRY = `retry: ${WATCH_RETRY_MS}\n\n`
+const SSE_HEADERS = { "content-type": "text/event-stream", "cache-control": "no-cache", connection: "keep-alive" }
+const PAGE = 200
+
+export interface WatchOptions {
+  readonly events: EventsRouteDeps
+  readonly userID: string
+  readonly actor: AgentActor
+  readonly signal: AbortSignal
+  /** Resume after this cursor (none: from now). */
+  readonly cursor?: string
+  /** Only these event types (exact, or `blocker.*`). */
+  readonly types?: readonly string[]
+  /** Only events of these sessions or of trees rooted at them. */
+  readonly sessions?: ReadonlySet<string>
+  readonly heartbeatMs?: number
+  readonly now?: () => number
+  /** Aborted when the hub drains: the stream ends with a `retry:` hint. */
+  readonly draining?: AbortSignal
+}
+
+/** The watch stream; throws invalid_cursor (before streaming) for a cursor this hub did not give this user. */
+export async function watchStream(options: WatchOptions): Promise<Response> {
+  if (options.draining?.aborted) return new Response(RETRY, { headers: SSE_HEADERS })
+  const { userID, actor } = options
+  const now = options.now ?? Date.now
+  const heartbeatMs = options.heartbeatMs ?? WATCH_HEARTBEAT_MS
+  const filters = { limit: PAGE, types: options.types ?? [], ...(options.sessions ? { sessions: options.sessions } : {}) }
+  const first = await read(options.events, userID, actor, { ...filters, ...(options.cursor ? { cursor: options.cursor } : {}), wait: 0 })
+  const encoder = new TextEncoder()
+  const stop = new AbortController()
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      let open = true
+      const close = () => {
+        if (!open) return
+        open = false
+        stop.abort()
+        try {
+          controller.close()
+        } catch {}
+      }
+      const write = (chunk: string) => {
+        if (!open) return
+        try {
+          controller.enqueue(encoder.encode(chunk))
+        } catch {
+          close()
+        }
+      }
+      const frame = (data: object, id?: string) => write(`${id ? `id: ${id}\n` : ""}data: ${JSON.stringify(data)}\n\n`)
+      const emit = (page: EventsPage) => {
+        if (page.reset) return frame({ type: "reset", at: now(), refresh: page.refresh ?? RESET_REFRESH }, page.cursor)
+        if (page.events.length === 0) return write(`event: ping\nid: ${page.cursor}\ndata: 0\n\n`)
+        page.events.forEach((event: AgentEvent, i) => frame(event, i === page.events.length - 1 ? page.cursor : undefined))
+      }
+      options.signal.addEventListener("abort", () => close(), { once: true })
+      options.draining?.addEventListener(
+        "abort",
+        () => {
+          write(RETRY)
+          close()
+        },
+        { once: true },
+      )
+      frame({ type: "ready", at: now() }, options.cursor && !first.reset ? options.cursor : first.cursor)
+      if (first.reset || first.events.length) emit(first)
+      let cursor = first.cursor
+      while (open && !stop.signal.aborted) {
+        let page: EventsPage
+        try {
+          page = await read(options.events, userID, actor, { ...filters, cursor, wait: heartbeatMs / 1000 }, stop.signal)
+        } catch (cause) {
+          console.error(`[hub] agent watch read failed: ${(cause as Error).message}`)
+          write(RETRY)
+          return close()
+        }
+        if (stop.signal.aborted) break
+        emit(page)
+        cursor = page.cursor
+      }
+      close()
+    },
+    cancel() {
+      stop.abort()
+    },
+  })
+  return new Response(stream, { headers: SSE_HEADERS })
+}

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

@@ -0,0 +1,86 @@
+// The webhook API on /api/agent (P4-T10; decision znbg8xa5 #8), over Webhooks (webhooks.ts):
+//
+//   POST   /api/agent/webhooks        {url, events?, label?} → 201 {webhook, secret} (the secret only here)
+//   GET    /api/agent/webhooks        → {webhooks}
+//   GET    /api/agent/webhooks/:id    → {webhook, deliveries} (recent deliveries, oldest first)
+//   DELETE /api/agent/webhooks/:id    → 204 (its pending deliveries are dropped)
+//
+// Who: users (all of their registrations, their own and their app tokens'); app tokens with sessions:launch (the
+// scope of the only events so far, launch.*), which see and delete only the registrations they made and get only
+// the events of launches they started. Sessions cannot register webhooks. Another user's registration, or (apps)
+// one the token did not make, is 404 not_found.
+import type { Store } from "../store"
+import type { AgentActor } from "./actor"
+import { AgentError } from "./errors"
+import type { AgentRoute } from "./routes"
+import { webhookEventScopes, type WebhookOwner, type Webhooks } from "./webhooks"
+
+// A literal: routes.ts imports this module.
+const PATH = "/api/agent/webhooks"
+const NO_STORE = { "cache-control": "no-store" }
+/** Users; apps with sessions:launch. */
+export const WEBHOOK_SCOPE = "events:subscribe"
+const ALLOW = { scope: WEBHOOK_SCOPE } as const
+
+export type RouteWebhooks = Pick<Webhooks, "register" | "list" | "get" | "remove" | "deliveries">
+
+/** The registrations an actor manages: an app token its own, a user all (undefined). */
+const ownerOf = (actor: AgentActor): WebhookOwner | undefined => (actor.kind === "app" ? `app:${actor.tokenID}` : undefined)
+
+const notFound = (id: string) => new AgentError("not_found", `No webhook ${id}`)
+
+const requireEventScopes = (actor: AgentActor, events: unknown) => {
+  if (actor.kind !== "app") return
+  const patterns = events === undefined ? ["launch.*"] : Array.isArray(events) && events.every((e) => typeof e === "string") ? events : []
+  const missing = webhookEventScopes(patterns).filter((scope) => !actor.scopes.includes(scope))
+  if (missing.length) throw new AgentError("forbidden", `Webhook events need scope ${missing.join(", ")}`)
+}
+
+async function bodyOf(request: Request): Promise<Record<string, unknown>> {
+  const raw = JSON.parse(await request.text()) 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>
+}
+
+export function webhookRoutes(webhooks: RouteWebhooks, store?: Pick<Store, "audit">): AgentRoute[] {
+  return [
+    {
+      method: "POST",
+      path: PATH,
+      allow: ALLOW,
+      async handle({ request, actor, user }) {
+        const input = await bodyOf(request)
+        requireEventScopes(actor, input.events)
+        const result = await webhooks.register(user.id, ownerOf(actor) ?? "user", { url: input.url, events: input.events, label: input.label })
+        await store?.audit({ actor: user.id, action: "webhook.create", target: result.webhook.id, detail: new URL(result.webhook.url).host })
+        return Response.json(result, { status: 201, headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: PATH,
+      allow: ALLOW,
+      handle: async ({ actor, user }) => Response.json({ webhooks: await webhooks.list(user.id, ownerOf(actor)) }, { headers: NO_STORE }),
+    },
+    {
+      method: "GET",
+      path: `${PATH}/:id`,
+      allow: ALLOW,
+      async handle({ params, actor, user }) {
+        const webhook = await webhooks.get(user.id, params.id!, ownerOf(actor))
+        if (!webhook) throw notFound(params.id!)
+        return Response.json({ webhook, deliveries: await webhooks.deliveries(user.id, webhook.id) }, { headers: NO_STORE })
+      },
+    },
+    {
+      method: "DELETE",
+      path: `${PATH}/:id`,
+      allow: ALLOW,
+      async handle({ params, actor, user }) {
+        if (!(await webhooks.remove(user.id, params.id!, ownerOf(actor)))) throw notFound(params.id!)
+        await store?.audit({ actor: user.id, action: "webhook.delete", target: params.id! })
+        return new Response(null, { status: 204, headers: NO_STORE })
+      },
+    },
+  ]
+}