@huynle/hub 0.6.1 → 0.7.1

package/src/central/agent/actor.ts

@@ -0,0 +1,193 @@
+// The credential resolver: every /api request resolves to at most one AgentActor, from exactly one credential.
+//
+// Credentials (design §1.3, §14.2):
+// - device cookie (`voice_device`, browsers): a DeviceRecord token; same-origin writes only (checked by callers)
+// - device token (`Authorization: Bearer <device token>`, native apps): the same secret as the cookie,
+//   resolved through the same device lookup, with the same powers; bearer requests skip the same-origin check
+// - session token (P1-T5) and app token (P1-T7): bearer tokens resolved by a BearerVerifier
+//
+// A request with both a device cookie and a bearer token the hub recognises is refused ("mixed"): credentials
+// never mix. A bearer the hub does not recognise next to the cookie (e.g. one an auth proxy adds) is ignored: the
+// request is a cookie request, same-origin check included.
+// Tokens are never logged; the device lookup is constant-time (Store.findDevice).
+import type { DeviceRecord, UserRecord } from "../store"
+
+/** The user, signed in as one of their devices (cookie in a browser, device token in an app). */
+export interface UserActor {
+  readonly kind: "user"
+  readonly userID: string
+  readonly deviceID: string
+  readonly via: "cookie" | "device-token"
+}
+
+/** A session, through the session token the hub minted for it (P1-T5). */
+export interface SessionActor {
+  readonly kind: "session"
+  readonly userID: string
+  readonly machineID: string
+  readonly sessionID: string
+  /**
+   * Which of the session's tokens: "shell" (typ session, in its shells' environment) or "act" (typ act, held by
+   * the spoke for the hub tool only). The hub's verifier always sets it; absent counts as "shell" (canActAsSession).
+   */
+  readonly via?: "shell" | "act"
+}
+
+/** A user-created app/agent token (P1-T7). */
+export interface AppActor {
+  readonly kind: "app"
+  readonly userID: string
+  readonly tokenID: string
+  readonly scopes: readonly string[]
+  readonly label?: string
+}
+
+export type AgentActor = UserActor | SessionActor | AppActor
+
+export type Credential = "cookie" | "device-token" | "session-token" | "app-token"
+
+/**
+ * Resolves one kind of bearer token (session tokens: P1-T5, app tokens: P1-T7). `verify` answers the actor for
+ * a token it recognises and accepts, "expired" for one of its tokens that expired, and undefined otherwise
+ * (not its token, bad signature, revoked). It must compare secrets in constant time and never log them. The
+ * resolver still refuses actors of unknown or disabled users, and actors of another kind than `kind`.
+ */
+export interface BearerVerifier {
+  readonly kind: "session" | "app"
+  verify(token: string): VerifyResult | Promise<VerifyResult>
+}
+
+export type VerifyResult = SessionActor | AppActor | "expired" | undefined
+
+export type Resolution =
+  | { readonly ok: true; readonly credential: Credential; readonly actor: AgentActor; readonly user: UserRecord; readonly device?: DeviceRecord }
+  | {
+      readonly ok: false
+      /** none: no credential; invalid: unknown, revoked or disabled; expired: a verifier's token expired; mixed: cookie + bearer. */
+      readonly reason: "none" | "invalid" | "expired" | "mixed"
+      /** The request carried a bearer token (callers answer with token wording). */
+      readonly bearer: boolean
+    }
+
+export interface ResolverDeps {
+  readonly cookieName: string
+  /** Device of a token (cookie value or device token); constant-time. Async on a shared store (it re-reads the device and its owner). */
+  findDevice(token: string): DeviceRecord | undefined | Promise<DeviceRecord | undefined>
+  user(id: string): UserRecord | undefined
+  /** Session and app token verifiers, tried in order after the device lookup. */
+  readonly verifiers?: readonly BearerVerifier[]
+}
+
+/** How a request authenticates: decides the same-origin check (cookie requests) and the mixed refusal. */
+export type CredentialMode = "none" | "cookie" | "bearer" | "mixed"
+
+export type Resolver = ((request: Request) => Promise<Resolution>) & {
+  /** none, cookie (incl. a cookie next to a foreign bearer), bearer, or mixed (cookie + a hub bearer). */
+  mode(request: Request): Promise<CredentialMode>
+}
+
+/** `Bearer <token>`; a Bearer header whose value is not one token still counts as a (invalid, empty) bearer. */
+const BEARER = /^\s*Bearer(?:\s+(.*))?$/i
+
+/** The device cookie and the bearer token of a request (an Authorization header with another scheme is neither). */
+export function readCredentials(request: Request, cookieName: string): { cookie?: string; bearer?: string } {
+  const out: { cookie?: string; bearer?: string } = {}
+  for (const part of (request.headers.get("cookie") ?? "").split(";")) {
+    const [name, ...rest] = part.trim().split("=")
+    if (name === cookieName) {
+      out.cookie = rest.join("=")
+      break
+    }
+  }
+  const match = BEARER.exec(request.headers.get("authorization") ?? "")
+  if (match) {
+    const token = (match[1] ?? "").trim()
+    out.bearer = /\s/.test(token) ? "" : token
+  }
+  return out
+}
+
+const CREDENTIAL: Record<"session" | "app", Credential> = { session: "session-token", app: "app-token" }
+
+export function createResolver(deps: ResolverDeps): Resolver {
+  const verifiers = deps.verifiers ?? []
+  const activeUser = (id: string) => {
+    const user = deps.user(id)
+    return user && !user.disabled ? user : undefined
+  }
+  const byDevice = async (token: string, via: UserActor["via"]): Promise<Resolution | undefined> => {
+    const device = token ? await deps.findDevice(token) : undefined
+    const user = device && activeUser(device.ownerID)
+    if (!device || !user) return undefined
+    return { ok: true, credential: via, actor: { kind: "user", userID: user.id, deviceID: device.id, via }, user, device }
+  }
+
+  /** The bearer is a hub credential (a device token, or a token a verifier answers for, expired included). */
+  const recognised = async (token: string): Promise<boolean> => {
+    if (!token) return false
+    if (await deps.findDevice(token)) return true
+    for (const verifier of verifiers) if ((await verifier.verify(token)) !== undefined) return true
+    return false
+  }
+  const mode = async (request: Request): Promise<CredentialMode> => {
+    const { cookie, bearer } = readCredentials(request, deps.cookieName)
+    if (bearer === undefined) return cookie === undefined ? "none" : "cookie"
+    if (cookie === undefined) return "bearer"
+    return (await recognised(bearer)) ? "mixed" : "cookie"
+  }
+
+  const resolve = async (request: Request): Promise<Resolution> => {
+    const { cookie, bearer } = readCredentials(request, deps.cookieName)
+    if (cookie !== undefined && (bearer === undefined || !(await recognised(bearer)))) {
+      return (await byDevice(cookie, "cookie")) ?? { ok: false, reason: "invalid", bearer: false }
+    }
+    if (bearer === undefined) return { ok: false, reason: "none", bearer: false }
+    if (cookie !== undefined) return { ok: false, reason: "mixed", bearer: true }
+    if (!bearer) return { ok: false, reason: "invalid", bearer: true }
+    const device = await byDevice(bearer, "device-token")
+    if (device) return device
+    for (const verifier of verifiers) {
+      const result = await verifier.verify(bearer)
+      if (result === undefined) continue
+      if (result === "expired") return { ok: false, reason: "expired", bearer: true }
+      if (result.kind !== verifier.kind) continue
+      const user = activeUser(result.userID)
+      if (!user) return { ok: false, reason: "invalid", bearer: true }
+      return { ok: true, credential: CREDENTIAL[verifier.kind], actor: result, user }
+    }
+    return { ok: false, reason: "invalid", bearer: true }
+  }
+  return Object.assign(resolve, { mode })
+}
+
+/** Which actors an /api/agent route admits besides user actors (cookie and device token reach every route). */
+export interface AgentAllow {
+  /** Session tokens may call it (phase-limited verbs). */
+  readonly session?: boolean
+  /** App tokens holding this scope may call it. */
+  readonly scope?: string
+  /** Any app token may call it (introspection such as whoami). */
+  readonly app?: boolean
+  /**
+   * An act verb: sessions may call it only through their act token (canActAsSession), never their shell token,
+   * whatever `session` says. App tokens still need `scope`.
+   */
+  readonly act?: boolean
+}
+
+/** Whether a session actor came with the session's act token; shell tokens (and anything else) never act. */
+export function canActAsSession(actor: AgentActor): boolean {
+  return actor.kind === "session" && actor.via === "act"
+}
+
+/** Route classes on /api/agent: users everywhere (incl. token management), sessions where allowed, apps by scope. */
+export function agentAllows(allow: AgentAllow, actor: AgentActor): boolean {
+  switch (actor.kind) {
+    case "user":
+      return true
+    case "session":
+      return allow.act === true ? canActAsSession(actor) : allow.session === true
+    case "app":
+      return allow.app === true || (allow.scope !== undefined && actor.scopes.includes(allow.scope))
+  }
+}

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

@@ -0,0 +1,142 @@
+// App/agent tokens (P1-T7, design §1.3, §7): bearer tokens a user creates for an app, CLI or external agent.
+//
+// Format: `hat_<id>_<secret>`; id is 16 hex characters (the AppToken id, no `_`), secret is 32 random bytes in
+// base64url. Only sha256(token) is stored, on UserRecord.agent.appTokens (see ../agent-data.ts); the token is
+// shown once, in the creation response. Tokens are global: the verifier finds the owner by id, then compares
+// the hashes in constant time. Revoking deletes the entry; the resolver refuses tokens of disabled users.
+//
+// Management (create, list, revoke) is for user actors only (allow {}): a session or app token cannot mint or
+// see tokens (escalation guard).
+import { randomBytes, timingSafeEqual } from "node:crypto"
+import type { AppToken } from "../agent-data"
+import { hashToken, type Store } from "../store"
+import type { AppActor, BearerVerifier } from "./actor"
+import { AgentError } from "./errors"
+import type { AgentRoute } from "./routes"
+
+/**
+ * Scopes an app token may hold: reading sessions; sending (msg, ask, reply, decline, mute) and reading messages;
+ * acting on sessions (approve, deny, answer, prompt, stop) and launching sessions (phase 4), each of which still
+ * needs a grant held by the token (with the act verb, or `launch` covering the repo).
+ */
+export const APP_SCOPES: readonly string[] = ["sessions:read", "messages:send", "messages:read", "sessions:act", "sessions:launch"]
+export const DEFAULT_APP_SCOPES: readonly string[] = ["sessions:read"]
+export const MAX_APP_TOKENS = 50
+export const MAX_APP_TOKEN_LABEL = 100
+
+const PREFIX = "/api/agent/app-tokens"
+const TOKEN = /^hat_([0-9a-f]{16})_([A-Za-z0-9_-]{43,})$/
+const NO_STORE = { "cache-control": "no-store" }
+
+/** Constant-time comparison of two hex digests. */
+function sameHash(a: string, b: string): boolean {
+  const x = Buffer.from(a, "hex")
+  const y = Buffer.from(b, "hex")
+  return x.length === y.length && x.length > 0 && timingSafeEqual(x, y)
+}
+
+const scopesOf = (token: AppToken): string[] => (Array.isArray(token.scopes) ? token.scopes.filter((s): s is string => typeof s === "string") : [...DEFAULT_APP_SCOPES])
+
+/** The app token verifier: `hat_<id>_<secret>` → the owner's app actor; anything else → undefined. */
+export function appTokenVerifier(store: Store): BearerVerifier {
+  return {
+    kind: "app",
+    async verify(token: string): Promise<AppActor | undefined> {
+      const match = TOKEN.exec(token)
+      if (!match) return undefined
+      const id = match[1]!
+      const owner = store.users().find((user) => user.agent?.appTokens?.some((t) => t.id === id))
+      if (!owner) return undefined
+      // A revocation on another pod applies at once: read the owner again (a no-op for the file store).
+      await store.recheck({ users: [owner.id] })
+      const record = store.user(owner.id)?.agent?.appTokens?.find((t) => t.id === id)
+      if (!record || !sameHash(record.tokenHash, hashToken(token))) return undefined
+      const label = typeof record.label === "string" ? record.label : undefined
+      return { kind: "app", userID: owner.id, tokenID: record.id, scopes: scopesOf(record), ...(label ? { label } : {}) }
+    },
+  }
+}
+
+interface CreateInput {
+  label?: string
+  scopes: string[]
+}
+
+function parseCreate(body: unknown): CreateInput {
+  if (typeof body !== "object" || body === null || Array.isArray(body)) throw new AgentError("invalid", "Body must be a JSON object")
+  const { label, scopes } = body as Record<string, unknown>
+  const out: CreateInput = { scopes: [...DEFAULT_APP_SCOPES] }
+  if (label !== undefined && label !== null) {
+    if (typeof label !== "string") throw new AgentError("invalid", "label must be a string")
+    const trimmed = label.trim()
+    if (trimmed.length > MAX_APP_TOKEN_LABEL) throw new AgentError("invalid", `label must be at most ${MAX_APP_TOKEN_LABEL} characters`)
+    if (trimmed) out.label = trimmed
+  }
+  if (scopes !== undefined) {
+    if (!Array.isArray(scopes) || !scopes.every((s): s is string => typeof s === "string")) throw new AgentError("invalid", "scopes must be an array of strings")
+    const unknown = scopes.filter((s) => !APP_SCOPES.includes(s))
+    if (unknown.length) throw new AgentError("invalid", `Unknown scope: ${unknown[0]}`, { extra: { scopes: APP_SCOPES } })
+    out.scopes = [...new Set(scopes)]
+  }
+  return out
+}
+
+const view = (token: AppToken) => ({
+  id: token.id,
+  ...(typeof token.label === "string" ? { label: token.label } : {}),
+  scopes: scopesOf(token),
+  ...(typeof token.created === "number" ? { created: token.created } : {}),
+})
+
+/** POST, GET and DELETE /api/agent/app-tokens: user actors only. */
+export function appTokenRoutes(store: Store): AgentRoute[] {
+  return [
+    {
+      method: "POST",
+      path: PREFIX,
+      allow: {},
+      async handle({ request, user }) {
+        const input = parseCreate(await request.json())
+        const id = randomBytes(8).toString("hex")
+        const token = `hat_${id}_${randomBytes(32).toString("base64url")}`
+        const record: AppToken = { id, tokenHash: hashToken(token), ...(input.label ? { label: input.label } : {}), scopes: input.scopes, created: Date.now() }
+        let full = false
+        await store.updateAgentData(user.id, (data) => {
+          const tokens = data.appTokens ?? []
+          full = false
+          if (tokens.length >= MAX_APP_TOKENS) {
+            full = true
+            return
+          }
+          data.appTokens = [...tokens, record]
+        })
+        if (full) throw new AgentError("rate_limited", `At most ${MAX_APP_TOKENS} app tokens per user`, { hint: "Revoke unused tokens" })
+        await store.audit({ actor: user.id, action: "app-token.create", target: id, ...(input.label ? { detail: input.label } : {}) })
+        return Response.json({ ...view(record), token }, { status: 201, headers: NO_STORE })
+      },
+    },
+    {
+      method: "GET",
+      path: PREFIX,
+      allow: {},
+      handle: ({ user }) => Response.json({ tokens: (store.agentData(user.id).appTokens ?? []).map(view) }, { headers: NO_STORE }),
+    },
+    {
+      method: "DELETE",
+      path: `${PREFIX}/:id`,
+      allow: {},
+      async handle({ params, user }) {
+        const id = params.id!
+        let found = false
+        await store.updateAgentData(user.id, (data) => {
+          const tokens = data.appTokens ?? []
+          found = tokens.some((t) => t.id === id)
+          if (found) data.appTokens = tokens.filter((t) => t.id !== id)
+        })
+        if (!found) throw new AgentError("not_found", "No such app token")
+        await store.audit({ actor: user.id, action: "app-token.revoke", target: id })
+        return new Response(null, { status: 204, headers: NO_STORE })
+      },
+    },
+  ]
+}

package/src/central/agent/audit.ts

@@ -0,0 +1,185 @@
+// The agent audit (design §5, §7, §11.4): every agent action, {seq, at, actor, verb, target, grant?, decision,
+// reason?, outcome}, in a per-user ring (AGENT_AUDIT_LIMIT, oldest dropped first) in the StateStore. The acting
+// code (approve, deny, answer, prompt, stop, launch, roles) records each attempt, allowed or not.
+//
+// - One key per entry (collection "agent-audit", keyed by the zero-padded sequence) and a per-user counter
+//   ("agent-audit-seq"), so an append is a few small writes in every backend.
+// - Text is sanitised: the reason (bounded), target ids and the grant id (dropped unless short and plain). The verb
+//   is the caller's constant; a malformed one is a bug and throws.
+// - Each new entry goes to `recorded` (the hub sends the owner an SSE 'agent' event); a throwing listener never
+//   fails the record.
+// - Admins see only a hub-wide summary in the Store's audit (who: the user ID; kind: agent.<verb> and the actor
+//   kind; when), never targets, reasons or text (design §7).
+import type { Clock, StateStore } from "../backend/types"
+import type { AuditEntry } from "../store"
+import { type Party, sanitizeText } from "./envelope"
+import { AgentError } from "./errors"
+import { AGENT_PREFIX, type AgentRoute } from "./routes"
+import { updateVersioned } from "./versioned"
+
+/** Entries each user keeps (the oldest are dropped first). */
+export const AGENT_AUDIT_LIMIT = 2000
+/** Characters of an entry's reason. */
+export const AUDIT_REASON_MAX = 500
+/** Entries a list returns by default, and at most. */
+export const AUDIT_PAGE_DEFAULT = 100
+export const AUDIT_PAGE_MAX = 500
+
+/** The policy's decision: allowed, or why not. */
+export type AuditDecision = "allow" | "needs_user" | "forbidden" | "paused" | "rate_limited"
+/** What happened: done, failed, raced (gone), the spoke could not (offline, unsupported), escalated or refused. */
+export type AuditOutcome = "ok" | "failed" | "gone" | "offline" | "unsupported" | "escalated" | "refused"
+
+/** What the action was on: the session, and the permission request or form, or the launch. */
+export interface AuditTarget {
+  readonly sessionID?: string
+  readonly launchID?: string
+  readonly requestID?: string
+  readonly formID?: string
+}
+
+export interface AuditInput {
+  /** Who acted (from the authenticated actor). */
+  readonly actor: Party
+  /** approve, deny, answer, prompt, stop, launch, roles, grant.request, … */
+  readonly verb: string
+  readonly target: AuditTarget
+  /** The grant it acted under. */
+  readonly grant?: string
+  readonly decision: AuditDecision
+  /** The agent's reason (`--why`) or the policy's. */
+  readonly reason?: string
+  readonly outcome: AuditOutcome
+}
+
+export interface AgentAuditEntry extends AuditInput {
+  /** Per user, from 1; newer entries have higher numbers (the list cursor). */
+  readonly seq: number
+  readonly at: number
+}
+
+export interface AuditPage {
+  /** Newest first. */
+  readonly entries: AgentAuditEntry[]
+  /** `before` for the next (older) page; absent on the last one. */
+  readonly next?: number
+}
+
+export interface AuditListOptions {
+  readonly limit?: number
+  /** Only entries older than this seq. */
+  readonly before?: number
+}
+
+export interface AgentAuditDeps {
+  readonly state: StateStore
+  readonly now?: Clock
+  /** The hub-wide admin audit (Store): gets the summary of every entry. */
+  readonly admin?: { audit(entry: Omit<AuditEntry, "at">): void | Promise<void> }
+  /** A new entry, for its owner (the hub's SSE 'agent' event). */
+  readonly recorded?: (userID: string, entry: AgentAuditEntry) => void
+  /** Ring size (default AGENT_AUDIT_LIMIT). */
+  readonly limit?: number
+}
+
+const ENTRIES = "agent-audit"
+const SEQ = "agent-audit-seq"
+const SEQ_KEY = "seq"
+const VERB = /^[a-z][a-z0-9._-]{0,31}$/
+const ID = /^[A-Za-z0-9_.:@-]{1,200}$/
+
+const keyOf = (seq: number) => String(seq).padStart(12, "0")
+const cleanID = (value: string | undefined) => (value !== undefined && ID.test(value) ? value : undefined)
+
+function cleanReason(reason: string | undefined): string | undefined {
+  if (reason === undefined) return undefined
+  const clean = Array.from(sanitizeText(reason).trim()).slice(0, AUDIT_REASON_MAX).join("").trimEnd()
+  return clean || undefined
+}
+
+function cleanTarget(target: AuditTarget): AuditTarget {
+  const out: { -readonly [K in keyof AuditTarget]: AuditTarget[K] } = {}
+  for (const key of ["sessionID", "launchID", "requestID", "formID"] as const) {
+    const id = cleanID(target[key])
+    if (id) out[key] = id
+  }
+  return out
+}
+
+export class AgentAudit {
+  private readonly now: Clock
+  private readonly limit: number
+
+  constructor(private readonly deps: AgentAuditDeps) {
+    this.now = deps.now ?? Date.now
+    this.limit = deps.limit ?? AGENT_AUDIT_LIMIT
+  }
+
+  /** Appends an entry to the user's log (dropping the oldest past the limit) and returns it. */
+  async record(userID: string, input: AuditInput): Promise<AgentAuditEntry> {
+    if (!VERB.test(input.verb)) throw new Error(`agent audit: bad verb ${JSON.stringify(input.verb)}`)
+    const { state } = this.deps
+    const seq = (await updateVersioned<number>(state, userID, SEQ, SEQ_KEY, (current) => (current ?? 0) + 1))!
+    const grant = cleanID(input.grant)
+    const reason = cleanReason(input.reason)
+    const entry: AgentAuditEntry = {
+      seq,
+      at: this.now(),
+      actor: input.actor,
+      verb: input.verb,
+      target: cleanTarget(input.target),
+      ...(grant ? { grant } : {}),
+      decision: input.decision,
+      ...(reason ? { reason } : {}),
+      outcome: input.outcome,
+    }
+    await state.put(userID, ENTRIES, keyOf(seq), entry)
+    if (seq > this.limit) await state.delete(userID, ENTRIES, keyOf(seq - this.limit))
+    await this.deps.admin?.audit({ actor: userID, action: `agent.${entry.verb}`, detail: entry.actor.kind })
+    try {
+      this.deps.recorded?.(userID, entry)
+    } catch (cause) {
+      console.error(`[hub] agent audit listener failed: ${(cause as Error).message}`)
+    }
+    return entry
+  }
+
+  /** The user's entries, newest first, a page at a time. */
+  async list(userID: string, options: AuditListOptions = {}): Promise<AuditPage> {
+    const limit = Math.min(Math.max(Math.floor(options.limit ?? AUDIT_PAGE_DEFAULT), 1), AUDIT_PAGE_MAX)
+    const all = (await this.deps.state.list<AgentAuditEntry>(userID, ENTRIES)).map((e) => e.value).sort((a, b) => b.seq - a.seq)
+    // Entries an interrupted record left past the ring: dropped now.
+    for (const stale of all.splice(this.limit)) await this.deps.state.delete(userID, ENTRIES, keyOf(stale.seq))
+    const older = options.before === undefined ? all : all.filter((e) => e.seq < options.before!)
+    const entries = older.slice(0, limit)
+    return { entries, ...(older.length > limit ? { next: entries[entries.length - 1]!.seq } : {}) }
+  }
+}
+
+const NO_STORE = { "cache-control": "no-store" }
+
+/** A whole number query parameter in [min, max], or undefined when absent (throws invalid). */
+function intQuery(url: URL, name: string, min: number, max: number): number | undefined {
+  const raw = url.searchParams.get(name)
+  if (raw === null) return undefined
+  const value = /^\d{1,15}$/.test(raw) ? Number(raw) : NaN
+  if (!(value >= min && value <= max)) throw new AgentError("invalid", `${name} must be a whole number from ${min} to ${max}`)
+  return value
+}
+
+/** GET /api/agent/audit?limit&before: the caller's own log (users only; sessions and apps never read it). */
+export function auditRoutes(audit: AgentAudit): AgentRoute[] {
+  return [
+    {
+      method: "GET",
+      path: `${AGENT_PREFIX}/audit`,
+      allow: {},
+      handle: async ({ url, user }) => {
+        const limit = intQuery(url, "limit", 1, AUDIT_PAGE_MAX)
+        const before = intQuery(url, "before", 1, Number.MAX_SAFE_INTEGER)
+        const page = await audit.list(user.id, { ...(limit !== undefined ? { limit } : {}), ...(before !== undefined ? { before } : {}) })
+        return Response.json(page, { headers: NO_STORE })
+      },
+    },
+  ]
+}