src/ops-session-auth.ts

Functions

Imports

It imports src/agents.ts, src/http.ts, src/scope.ts. Imported by src/ops-hooks.ts, src/ops-otlp.ts.

Source

1import { resolveAgent, type Agent } from "./agents";
2import { checkScope, JOBS_TOOL } from "./scope";
3import { textResponse as text } from "./http";
4
5// Who is reporting on a Claude Code session, and which job that session is working.
6// The one caller check for the receivers a session posts to on its own: the hook
7// receiver (src/ops-hooks.ts) and the OTLP receiver (src/ops-otlp.ts).
8//
9// The bearer is the session's own driver key. Accepted:
10//   - a minted driver (kind driver, row-backed),
11//   - the admin (a legacy write operator key), for testing.
12// Anything else that resolves is 403; nothing that resolves is 401.
13//
14// The write grant is asked of checkScope (one enforcement point, test/scope.test.ts): what
15// these routes write is part of a job's record, so a read-only caller may not send it.
16// The tool named is "jobs", which every caller that works jobs holds.
17//
18// The job: a driver is bound to the single
19// job it holds claimed, or to none when it holds zero or several. The admin is bound to
20// none.
21
22const SESSION_REALM = "capsid-hooks";
23
24export interface SessionCaller {
25  agent: Agent;
26  job_id: string | null;
27  // The bound job's namespace, or null with no job.
28  namespace: string | null;
29  // last_seen, best effort, after the answer (see handleOperatorMcp in src/routes.ts).
30  touch: () => Promise<void>;
31}
32
33/** Why this agent may not report on a session, or null. */
34export function sessionCallerRefusal(agent: Agent): string | null {
35  if (agent.admin) return null;
36  if (!agent.row || (agent.kind !== "driver" && agent.kind !== "session")) {
37    return `forbidden: ${agent.actor} is not a driver. Hooks and telemetry are posted with the session's own driver key (docs/hooks.md, docs/telemetry.md).`;
38  }
39  return checkScope(agent, { tool: JOBS_TOOL, grant: "write" });
40}
41
42/** The job a caller's session is working: the one job a driver holds claimed. None, or more than one, is no binding. */
43async function sessionJobFor(db: D1Database, agent: Agent): Promise<{ job_id: string; namespace: string } | null> {
44  if (!agent.row || agent.kind !== "driver") return null;
45  // LIMIT 2, so "holds several" is told apart from "holds one" without reading them all.
46  const { results } = await db
47    .prepare("SELECT id, namespace FROM jobs WHERE claimed_by = ?1 AND status = 'claimed' LIMIT 2")
48    .bind(agent.actor)
49    .all<{ id: string; namespace: string }>();
50  const held = results ?? [];
51  return held.length === 1 ? { job_id: held[0].id, namespace: held[0].namespace } : null;
52}
53
54/** The caller and its job, or the refusal to send. */
55export async function resolveSessionCaller(
56  request: Request,
57  env: { DB: D1Database; OPERATOR_KEY_HASH?: string },
58  now: Date = new Date()
59): Promise<SessionCaller | Response> {
60  const resolved = await resolveAgent(request, env, now);
61  if (!resolved) {
62    return text("unauthorized: a driver key is required as Authorization: Bearer <key>", 401, {
63      "WWW-Authenticate": `Bearer realm="${SESSION_REALM}"`,
64    });
65  }
66  const refusal = sessionCallerRefusal(resolved.agent);
67  if (refusal) return text(refusal, 403);
68  const binding = await sessionJobFor(env.DB, resolved.agent);
69  return { agent: resolved.agent, job_id: binding?.job_id ?? null, namespace: binding?.namespace ?? null, touch: resolved.touch };
70}