src/tools/repo-guards.ts

Functions

Imports

It imports src/github/client.ts, src/log.ts, src/scope.ts, src/store-guards.ts, src/tools/docs.ts, src/tools/surface.ts. Imported by src/tools/repo.ts.

Source

1import { fail, ok, type ToolCtx } from "./docs";
2import { repoWriteFlags } from "../scope";
3import { surfaceOf } from "./surface";
4import { resolveRepo } from "../github/client";
5import { auditStatement } from "../store-guards";
6import { logEvent } from "../log";
7
8// The wrappers every repo tool runs through. guardedRead resolves the repo and asks
9// the repos axis before a read; guardedWrite does the same for a mutation, computes
10// the flags it needs (repoWriteFlags), runs it, and writes its audit row. Every repo
11// mutation goes through guardedWrite (test/blast-radius.test.ts).
12export function repoGuards(ctx: ToolCtx) {
13  const { env, db, actor } = ctx;
14
15  // The repos axis, asked about the repo this call actually reaches. The registrar
16  // can only compare a fully qualified owner/name; a label is a selector, and
17  // omitting it is the default. So every repo tool resolves the selector against the
18  // namespace mapping here and asks checkScope about the result. Without this the
19  // axis would bind nothing on the default call path: an admin remap of a namespace's
20  // primary would silently redirect every driver scoped to the old repo. It costs one
21  // D1 read per repo call.
22  // `op` is the operation; the check names the served tool and action that run it.
23  const scopedRepo = async (op: string, namespace: string, selector: string | undefined) => {
24    const resolved = await resolveRepo(env, namespace, selector);
25    return { resolved, refusal: ctx.scope({ ...surfaceOf(op), namespace, repo: resolved.full }) };
26  };
27
28  // The read tools' wrapper: resolve, check the axis, then run. Reads are open to any
29  // admitted client by grant, and the axis is what says WHICH repo they may read.
30  const guardedRead = async (op: string, namespace: string, selector: string | undefined, fn: () => Promise<unknown>) => {
31    try {
32      const { refusal } = await scopedRepo(op, namespace, selector);
33      if (refusal) return fail(refusal);
34      return ok(await fn());
35    } catch (err) {
36      return fail(err instanceof Error ? err.message : String(err));
37    }
38  };
39
40  // Repo writes are operator-gated and audit-logged. The whole result (which
41  // includes the resolved repo) goes into params so a misdirected write is
42  // diagnosable from the log; path is the file path where one applies.
43  const guardedWrite = async (
44    action: string,
45    namespace: string,
46    path: string | null,
47    fn: () => Promise<Record<string, unknown>>,
48    // What the call is actually asking to do, which is what decides the flags. The
49    // registrar has already checked the tool, the grant, the namespace and the repo
50    // selector by now; a wrapper could not have checked these, because `mode:
51    // "direct"` needs can_direct_write and `mode: "pr"` does not.
52    intent: { path?: string; mode?: string; action?: string; allow_workflow_write?: boolean; force?: boolean; repo?: string; surface?: { tool: string; action?: string } } = {}
53  ) => {
54    // Every repo mutation passes through here, so the flag check is here and not in
55    // each tool. test/scope-coverage.test.ts derives that no repo write tool reaches
56    // GitHub any other way.
57    // Resolved first, so the repos axis is asked about the repo this write reaches.
58    // A namespace that cannot be resolved fails here, before anything is written.
59    let resolvedRepo: string;
60    try {
61      resolvedRepo = (await resolveRepo(env, namespace, intent.repo)).full;
62    } catch (err) {
63      return fail(err instanceof Error ? err.message : String(err));
64    }
65    // `action` is the operation (the audit row's action); the check names the served
66    // tool and action that run it (src/tools/surface.ts surfaceOf), which is what the
67    // tools axis narrows on. Without the action a reviewer minted
68    // ["capsid_open_pr", "capsid_open_pr.comment"] could open a pull request. The
69    // registrar checks it too; this is the one place every repo mutation passes through.
70    const served = intent.surface ?? surfaceOf(action, intent.action);
71    const refusal = ctx.scope({
72      tool: served.tool,
73      namespace,
74      repo: resolvedRepo,
75      action: served.action,
76      grant: "write",
77      flags: repoWriteFlags(served.tool, served.action, { ...intent, path: intent.path ?? path ?? undefined }),
78    });
79    if (refusal) return fail(refusal);
80    let result: Record<string, unknown>;
81    try {
82      result = await fn();
83    } catch (err) {
84      return fail(err instanceof Error ? err.message : String(err));
85    }
86    // The mutation already landed: fn() has committed to GitHub, and GitHub cannot
87    // join a D1 transaction. A failed audit INSERT is reported as a warning on a
88    // success, because a caller told "failed" would retry into a second commit. The
89    // D1-only tools do not need this: delete, move and finalize put the audit
90    // INSERT inside the same batch as the mutation.
91    try {
92      await auditStatement(db, actor, action, namespace, path, result).run();
93    } catch (err) {
94      logEvent("error", "AUDIT_INSERT_FAILED", { message: `AUDIT_INSERT_FAILED ${action} ${namespace}/${path ?? ""}: ${err instanceof Error ? err.message : String(err)}` });
95      return ok({
96        ...result,
97        audit_warning:
98          `THE ${action} SUCCEEDED and is described by this result, but the audit_log row could not be written: ` +
99          `${err instanceof Error ? err.message : String(err)}. Do not retry this call; the change is already made.`,
100      });
101    }
102    return ok(result);
103  };
104
105  return { guardedRead, guardedWrite };
106}