@namzu/sandbox 13.0.0 → 15.0.0

package/dist/backends/kubernetes/privilege-probe.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Acquire-time privilege probe: prove the guest process really was
+ * deprivileged, rather than assume the entrypoint did its job.
+ *
+ * The image's entrypoint mounts the workspace as root and then
+ * `exec setpriv --reuid --regid --clear-groups --inh-caps=-all
+ * --bounding-set=-all --no-new-privs -- tini -- node agent.cjs` (`tini` is
+ * the container's pid 1 so it can reap an orphan `agent.cjs` itself never
+ * spawned — see `k8s/entrypoint.sh` and the Dockerfile). Nothing in
+ * `agent.cjs` knows about any of that, and nothing on the host can see it
+ * either — an image built from an older entrypoint, a `RuntimeClass` change,
+ * a hand-edited `SandboxTemplate` all produce a sandbox that works perfectly
+ * and is not deprivileged. So the backend asks the guest, once, before it
+ * hands a caller a handle.
+ *
+ * ## Why `execute`, and why not `read-file`
+ *
+ * The guest's `read-file` resolves every path against `READ_ROOTS`
+ * (`WORKSPACE_ROOT` only), so it cannot reach `/proc` at all, and widening
+ * `READ_ROOTS` to make the probe work would hand every caller of `readFile`
+ * a window into the guest's process tree for the sake of one diagnostic.
+ * `handleExecute` jails only `cwd`, so a command whose ARGUMENT is an
+ * absolute path outside the workspace runs fine. The probe therefore spends
+ * one `exec` and touches no jail.
+ *
+ * ## Why all four masks
+ *
+ * Checking `CapEff` alone is a true-looking answer: an ordinary unprivileged
+ * process shows `CapEff: 0000000000000000` whether or not its bounding set
+ * was ever dropped, so a container running as uid 0 with the full bounding
+ * set still passes. `CapBnd` is the one that says a capability can never be
+ * regained; `CapInh` and `CapPrm` close the two ways one could be carried
+ * across an exec. `NoNewPrivs: 1` is what makes a setuid binary inside the
+ * guest unable to raise any of it back.
+ *
+ * ## Why every failure is a refusal
+ *
+ * A probe that could not run, one that never answered at all, output that
+ * could not be parsed and a process that is genuinely privileged are all
+ * reasons NOT to hand back a handle, and they are separated only in the error
+ * TEXT — a distroless image with no `cat` on `PATH` must be diagnosable as
+ * exactly that rather than read as a hardening failure. There is no
+ * configuration that turns this off.
+ *
+ * ## The clock is the caller's, and it lives in `index.ts`
+ *
+ * Nothing here has a timeout: the probe is one `exec`, and the budget it may
+ * spend belongs to the `create()` that ordered it. `admitProbedSandbox` runs
+ * it under an `OperationDeadline` and turns an expiry into
+ * {@link privilegeProbeTimedOut}, so a guest that accepts the connection and
+ * then goes quiet is refused on the caller's clock rather than on the
+ * execution controller's five-minute generic default.
+ */
+import type { SandboxExecResult } from '@namzu/sdk';
+/**
+ * The probe command. `cat` rather than an absolute `/bin/cat` so a guest
+ * that keeps its coreutils somewhere else still answers, and rather than a
+ * shell so there is no quoting to get wrong. A guest without it fails with
+ * a spawn error the refusal repeats verbatim.
+ */
+export declare const PRIVILEGE_PROBE_COMMAND = "cat";
+/** `/proc/self/status` — of the process the guest agent spawns, which
+ * inherits exactly the agent's own credentials and capability masks. */
+export declare const PRIVILEGE_PROBE_ARGS: readonly string[];
+/** Why a probe refused. The text says the same thing in words. */
+export type PrivilegeProbeFailure = 
+/** The `exec` failed, exited non-zero, or never answered at all. */
+'probe-failed'
+/** It ran, but its output is not a readable `/proc/<pid>/status`. */
+ | 'unreadable-output'
+/** It ran, it parsed, and the process has capabilities it should not. */
+ | 'privileged';
+/**
+ * Raised by {@link runPrivilegeProbe} and {@link parseProcStatus}. The
+ * `reason` is the machine-readable form of the distinction the message
+ * draws in prose: `'privileged'` means the guest is under-hardened, and the
+ * other two mean the backend could not tell.
+ */
+export declare class KubernetesPrivilegeProbeError extends Error {
+    readonly reason: PrivilegeProbeFailure;
+    readonly name = "KubernetesPrivilegeProbeError";
+    constructor(reason: PrivilegeProbeFailure, message: string, options?: ErrorOptions);
+}
+/**
+ * The five fields the probe reads, parsed. The four capability masks are
+ * `bigint` because a capability mask is 64 bits wide and `Number` stops
+ * being exact at 53 — `000001ffffffffff` is only 41 bits today, but a mask
+ * that silently rounds is precisely the bug this whole module exists to
+ * catch.
+ */
+export interface ProcStatusPrivileges {
+    readonly capInh: bigint;
+    readonly capPrm: bigint;
+    readonly capEff: bigint;
+    readonly capBnd: bigint;
+    /** `prctl(PR_GET_NO_NEW_PRIVS)`, 0 or 1 as the kernel prints it. */
+    readonly noNewPrivs: number;
+}
+/**
+ * Parse `/proc/<pid>/status` into the five fields that decide admission.
+ *
+ * Pure: no transport, no clock, no I/O. Everything it cannot read is a
+ * throw, never a default — a zero substituted for a missing mask is the one
+ * mistake that would make this function report hardening that is not there.
+ */
+export declare function parseProcStatus(text: string): ProcStatusPrivileges;
+/**
+ * Admit only an all-zero capability set with `no_new_privs` set. Every
+ * non-zero mask is named in the refusal, because "one of them is set" sends
+ * the reader back to the guest to find out which.
+ */
+export declare function assertDeprivileged(privileges: ProcStatusPrivileges, sandboxName: string): void;
+/**
+ * Run the probe over an already-built sandbox's `exec` and admit or refuse.
+ *
+ * `run` is the sandbox's own `exec`, not the raw transport, so the probe
+ * traverses exactly the path every later call will: reserve, admit, stream,
+ * confirm. A probe that cannot get through this is a sandbox a caller
+ * cannot use either.
+ */
+export declare function runPrivilegeProbe(run: (command: string, args: string[]) => Promise<SandboxExecResult>, sandboxName: string): Promise<ProcStatusPrivileges>;
+/**
+ * The refusal for a probe that never answered.
+ *
+ * A guest that accepts the TCP connection and then goes quiet — an agent
+ * process out of memory, an event loop blocked by the workload, a container
+ * alive with a listener that has stopped reading — cannot be told apart from
+ * a healthy one by the wire alone, so the caller's acquire budget is the only
+ * thing that ends the wait. That expiry is a `'probe-failed'` like any other
+ * way the probe could not run, but it gets its own words: "the deadline
+ * expired" on its own says nothing about WHICH half of the acquire stopped
+ * answering, and a reader who sees `cat` blamed for a hang goes looking for a
+ * missing binary that is not missing.
+ */
+export declare function privilegeProbeTimedOut(sandboxName: string, timeoutMs: number, cause: unknown): KubernetesPrivilegeProbeError;
+//# sourceMappingURL=privilege-probe.d.ts.map

package/dist/backends/kubernetes/privilege-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"privilege-probe.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/privilege-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAQ,CAAA;AAE5C;wEACwE;AACxE,eAAO,MAAM,oBAAoB,EAAE,SAAS,MAAM,EAA0B,CAAA;AAE5E,kEAAkE;AAClE,MAAM,MAAM,qBAAqB;AAChC,oEAAoE;AAClE,cAAc;AAChB,qEAAqE;GACnE,mBAAmB;AACrB,yEAAyE;GACvE,YAAY,CAAA;AAEf;;;;;GAKG;AACH,qBAAa,6BAA8B,SAAQ,KAAK;IAItD,QAAQ,CAAC,MAAM,EAAE,qBAAqB;IAHvC,SAAkB,IAAI,mCAAkC;gBAG9C,MAAM,EAAE,qBAAqB,EACtC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAIvB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,oEAAoE;IACpE,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;CAC3B;AAuBD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,oBAAoB,CA8BlE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAe9F;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACtC,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,iBAAiB,CAAC,EACpE,WAAW,EAAE,MAAM,GACjB,OAAO,CAAC,oBAAoB,CAAC,CA6B/B;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CACrC,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACZ,6BAA6B,CAQ/B"}

package/dist/backends/kubernetes/privilege-probe.js

@@ -0,0 +1,185 @@
+/**
+ * Acquire-time privilege probe: prove the guest process really was
+ * deprivileged, rather than assume the entrypoint did its job.
+ *
+ * The image's entrypoint mounts the workspace as root and then
+ * `exec setpriv --reuid --regid --clear-groups --inh-caps=-all
+ * --bounding-set=-all --no-new-privs -- tini -- node agent.cjs` (`tini` is
+ * the container's pid 1 so it can reap an orphan `agent.cjs` itself never
+ * spawned — see `k8s/entrypoint.sh` and the Dockerfile). Nothing in
+ * `agent.cjs` knows about any of that, and nothing on the host can see it
+ * either — an image built from an older entrypoint, a `RuntimeClass` change,
+ * a hand-edited `SandboxTemplate` all produce a sandbox that works perfectly
+ * and is not deprivileged. So the backend asks the guest, once, before it
+ * hands a caller a handle.
+ *
+ * ## Why `execute`, and why not `read-file`
+ *
+ * The guest's `read-file` resolves every path against `READ_ROOTS`
+ * (`WORKSPACE_ROOT` only), so it cannot reach `/proc` at all, and widening
+ * `READ_ROOTS` to make the probe work would hand every caller of `readFile`
+ * a window into the guest's process tree for the sake of one diagnostic.
+ * `handleExecute` jails only `cwd`, so a command whose ARGUMENT is an
+ * absolute path outside the workspace runs fine. The probe therefore spends
+ * one `exec` and touches no jail.
+ *
+ * ## Why all four masks
+ *
+ * Checking `CapEff` alone is a true-looking answer: an ordinary unprivileged
+ * process shows `CapEff: 0000000000000000` whether or not its bounding set
+ * was ever dropped, so a container running as uid 0 with the full bounding
+ * set still passes. `CapBnd` is the one that says a capability can never be
+ * regained; `CapInh` and `CapPrm` close the two ways one could be carried
+ * across an exec. `NoNewPrivs: 1` is what makes a setuid binary inside the
+ * guest unable to raise any of it back.
+ *
+ * ## Why every failure is a refusal
+ *
+ * A probe that could not run, one that never answered at all, output that
+ * could not be parsed and a process that is genuinely privileged are all
+ * reasons NOT to hand back a handle, and they are separated only in the error
+ * TEXT — a distroless image with no `cat` on `PATH` must be diagnosable as
+ * exactly that rather than read as a hardening failure. There is no
+ * configuration that turns this off.
+ *
+ * ## The clock is the caller's, and it lives in `index.ts`
+ *
+ * Nothing here has a timeout: the probe is one `exec`, and the budget it may
+ * spend belongs to the `create()` that ordered it. `admitProbedSandbox` runs
+ * it under an `OperationDeadline` and turns an expiry into
+ * {@link privilegeProbeTimedOut}, so a guest that accepts the connection and
+ * then goes quiet is refused on the caller's clock rather than on the
+ * execution controller's five-minute generic default.
+ */
+/**
+ * The probe command. `cat` rather than an absolute `/bin/cat` so a guest
+ * that keeps its coreutils somewhere else still answers, and rather than a
+ * shell so there is no quoting to get wrong. A guest without it fails with
+ * a spawn error the refusal repeats verbatim.
+ */
+export const PRIVILEGE_PROBE_COMMAND = 'cat';
+/** `/proc/self/status` — of the process the guest agent spawns, which
+ * inherits exactly the agent's own credentials and capability masks. */
+export const PRIVILEGE_PROBE_ARGS = ['/proc/self/status'];
+/**
+ * Raised by {@link runPrivilegeProbe} and {@link parseProcStatus}. The
+ * `reason` is the machine-readable form of the distinction the message
+ * draws in prose: `'privileged'` means the guest is under-hardened, and the
+ * other two mean the backend could not tell.
+ */
+export class KubernetesPrivilegeProbeError extends Error {
+    reason;
+    name = 'KubernetesPrivilegeProbeError';
+    constructor(reason, message, options) {
+        super(message, options);
+        this.reason = reason;
+    }
+}
+const CAPABILITY_FIELDS = ['CapInh', 'CapPrm', 'CapEff', 'CapBnd'];
+const NO_NEW_PRIVS_FIELD = 'NoNewPrivs';
+/** Clip a value before it goes into an error message. */
+function clip(value) {
+    return value.length > 40 ? `${value.slice(0, 40)}…` : value;
+}
+function readField(text, field) {
+    for (const rawLine of text.split(/\r?\n/)) {
+        const colon = rawLine.indexOf(':');
+        if (colon < 0)
+            continue;
+        if (rawLine.slice(0, colon).trim() !== field)
+            continue;
+        return rawLine.slice(colon + 1).trim();
+    }
+    throw new KubernetesPrivilegeProbeError('unreadable-output', `the privilege probe ran but its output carries no ${field} line, so this sandbox's privileges could not be read. The probe is \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` — a guest whose /proc is not mounted, or whose kernel does not publish ${field}, cannot be admitted, because an unreadable answer is not a safe one.`);
+}
+/**
+ * Parse `/proc/<pid>/status` into the five fields that decide admission.
+ *
+ * Pure: no transport, no clock, no I/O. Everything it cannot read is a
+ * throw, never a default — a zero substituted for a missing mask is the one
+ * mistake that would make this function report hardening that is not there.
+ */
+export function parseProcStatus(text) {
+    const masks = CAPABILITY_FIELDS.map((field) => {
+        const raw = readField(text, field);
+        // The kernel prints a bare, fixed-width hex mask with no `0x`. A
+        // `0x` prefix, a sign, whitespace inside, or anything non-hex means
+        // this is not the file this parser thinks it is.
+        if (!/^[0-9a-fA-F]+$/.test(raw)) {
+            throw new KubernetesPrivilegeProbeError('unreadable-output', `the privilege probe ran but ${field} is ${JSON.stringify(clip(raw))}, which is not the bare hexadecimal capability mask /proc/<pid>/status publishes, so this sandbox's privileges could not be read.`);
+        }
+        return BigInt(`0x${raw}`);
+    });
+    const noNewPrivsRaw = readField(text, NO_NEW_PRIVS_FIELD);
+    if (!/^\d+$/.test(noNewPrivsRaw)) {
+        throw new KubernetesPrivilegeProbeError('unreadable-output', `the privilege probe ran but ${NO_NEW_PRIVS_FIELD} is ${JSON.stringify(clip(noNewPrivsRaw))}, which is not the integer /proc/<pid>/status publishes, so this sandbox's privileges could not be read.`);
+    }
+    return {
+        capInh: masks[0],
+        capPrm: masks[1],
+        capEff: masks[2],
+        capBnd: masks[3],
+        noNewPrivs: Number(noNewPrivsRaw),
+    };
+}
+/**
+ * Admit only an all-zero capability set with `no_new_privs` set. Every
+ * non-zero mask is named in the refusal, because "one of them is set" sends
+ * the reader back to the guest to find out which.
+ */
+export function assertDeprivileged(privileges, sandboxName) {
+    const offenders = [];
+    if (privileges.capInh !== 0n)
+        offenders.push(`CapInh=${privileges.capInh.toString(16)}`);
+    if (privileges.capPrm !== 0n)
+        offenders.push(`CapPrm=${privileges.capPrm.toString(16)}`);
+    if (privileges.capEff !== 0n)
+        offenders.push(`CapEff=${privileges.capEff.toString(16)}`);
+    if (privileges.capBnd !== 0n)
+        offenders.push(`CapBnd=${privileges.capBnd.toString(16)}`);
+    if (privileges.noNewPrivs !== 1)
+        offenders.push(`NoNewPrivs=${privileges.noNewPrivs}`);
+    if (offenders.length === 0)
+        return;
+    throw new KubernetesPrivilegeProbeError('privileged', `kubernetes sandbox ${sandboxName} is PRIVILEGED and was refused: ${offenders.join(', ')} (every capability mask must be 0 and NoNewPrivs must be 1). The probe ran and was read successfully — this is the guest's real state, not a diagnostic failure. The image's entrypoint is expected to end with \`exec setpriv --reuid --regid --clear-groups --inh-caps=-all --bounding-set=-all --no-new-privs -- tini -- node agent.cjs\`; a sandbox that reaches this message is running with capabilities the workload could use.`);
+}
+/**
+ * Run the probe over an already-built sandbox's `exec` and admit or refuse.
+ *
+ * `run` is the sandbox's own `exec`, not the raw transport, so the probe
+ * traverses exactly the path every later call will: reserve, admit, stream,
+ * confirm. A probe that cannot get through this is a sandbox a caller
+ * cannot use either.
+ */
+export async function runPrivilegeProbe(run, sandboxName) {
+    let result;
+    try {
+        result = await run(PRIVILEGE_PROBE_COMMAND, [...PRIVILEGE_PROBE_ARGS]);
+    }
+    catch (error) {
+        throw new KubernetesPrivilegeProbeError('probe-failed', `the privilege probe could not run in kubernetes sandbox ${sandboxName}: ${error instanceof Error ? error.message : String(error)}. The probe is \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\`; an image without it on PATH cannot be admitted, because a sandbox whose privileges cannot be checked is refused rather than trusted.`, { cause: error });
+    }
+    if (result.exitCode !== 0) {
+        throw new KubernetesPrivilegeProbeError('probe-failed', `the privilege probe could not run in kubernetes sandbox ${sandboxName}: \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` exited ${result.exitCode}${result.stderr.trim() ? ` (${clip(result.stderr.trim())})` : ''}. This is a diagnostic failure, not a privilege failure — the sandbox is refused because its state is unknown.`);
+    }
+    const privileges = parseProcStatus(result.stdout);
+    assertDeprivileged(privileges, sandboxName);
+    return privileges;
+}
+/**
+ * The refusal for a probe that never answered.
+ *
+ * A guest that accepts the TCP connection and then goes quiet — an agent
+ * process out of memory, an event loop blocked by the workload, a container
+ * alive with a listener that has stopped reading — cannot be told apart from
+ * a healthy one by the wire alone, so the caller's acquire budget is the only
+ * thing that ends the wait. That expiry is a `'probe-failed'` like any other
+ * way the probe could not run, but it gets its own words: "the deadline
+ * expired" on its own says nothing about WHICH half of the acquire stopped
+ * answering, and a reader who sees `cat` blamed for a hang goes looking for a
+ * missing binary that is not missing.
+ */
+export function privilegeProbeTimedOut(sandboxName, timeoutMs, cause) {
+    return new KubernetesPrivilegeProbeError('probe-failed', `the privilege probe could not run in kubernetes sandbox ${sandboxName}: the guest accepted the connection and did not answer \`${PRIVILEGE_PROBE_COMMAND} ${PRIVILEGE_PROBE_ARGS.join(' ')}\` within ${timeoutMs} ms, so the probe was abandoned. This is a diagnostic failure, not a privilege failure — the sandbox is refused because its state is unknown. A wedged agent (out of memory, an event loop blocked by the workload) looks exactly like this from the host; check the pod's logs before raising the acquire budget.`, { cause });
+}
+//# sourceMappingURL=privilege-probe.js.map

package/dist/backends/kubernetes/privilege-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"privilege-probe.js","sourceRoot":"","sources":["../../../src/backends/kubernetes/privilege-probe.ts"],"names":[],"mappings":"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"}

package/dist/backends/kubernetes/rbac.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The verbs a CLAIM-ONLY host issues — the pool-only path, written down once
+ * so `k8s/manifests/rbac-claimant.yaml`, and the test that compares it to both
+ * this list and the call sites behind it, cannot drift from the code they
+ * describe.
+ *
+ * A host that sets `warmPoolName` and never creates a `Sandbox` itself needs
+ * a strictly smaller grant than `k8s/manifests/rbac.yaml`'s, and the smaller
+ * it is the more it matters that it is EXACT. Two failure directions, and
+ * this constant is the one place both are decided:
+ *
+ *  - **Too few verbs** is a `403` on a flow nobody ran in review. The four
+ *    `list` verbs are the load-bearing ones, and the two a host can go a long
+ *    time without noticing are the sharp ones: `sandboxclaims: list` is the
+ *    crash-recovery read (`releaseKubernetesTaskSandboxes`) and the
+ *    pool-membership read (`readKubernetesTaskCapacity`), and `pods: list` is
+ *    `readBoundPod`'s fallback read by the bound Sandbox's own selector and
+ *    `readKubernetesTaskCapacity`'s count of Pending pods. The ACQUIRE path
+ *    never notices either is missing — `create()` never lists either
+ *    collection, so a claim is still created, bound, renewed and released
+ *    exactly as before — which makes the failure DEFERRED rather than quiet:
+ *    the `await client.request` inside each of those two functions rejects
+ *    with a `KubernetesCredentialError` (`403`), and neither call catches one,
+ *    so the first release or capacity read a host makes fails loudly, with the
+ *    refused verb and the collection's path in the error. The other two are
+ *    load-bearing SOONER: `list` is what both policy checks need, and the
+ *    ingress one runs by default before every create.
+ *  - **One verb too many** is the vulnerability class issue #500 is about: a
+ *    `sandboxes: create` grant against a namespace running a privileged
+ *    workspace template is an arbitrary privileged pod for anyone holding
+ *    it. Every verb below has a call site named against it in the list.
+ *
+ * The path this describes is the CLAIM path, not the task tier as a whole:
+ * with `warmPoolName` unset the same backend POSTs a `Sandbox` instead of a
+ * claim, reads its `SandboxTemplate` first, and patches and deletes that
+ * object — none of which is granted here, deliberately. See the manifest's
+ * own header for what it declines to grant and why.
+ *
+ * Kept honest by a test rather than by review, and the test reaches the CODE
+ * rather than only this list: `k8s/__tests__/manifests.test.ts` reads the
+ * pool-only path's own files — `index.ts`, `objects.ts`, `ingress-policy.ts`,
+ * `egress-policy.ts` — as text, resolves every literal `client.request(
+ * '<METHOD>', <path>, …)` in them to the `(apiGroup, resource, verb)` triple
+ * the builder that path goes through addresses, and FAILS on anything it
+ * cannot resolve — an unknown builder, a path it cannot follow, a builder
+ * call with anything appended to it (`podPath(ns, name) + '/log'` is the
+ * `pods/log` subresource, which RBAC authorizes separately), a name the source
+ * writes a second path to — the guard reads four spellings, wherever each is
+ * written rather than only where it opens a statement: a plain assignment
+ * (`path = …`, the one-line branch included), a compound one (`path += …`), a
+ * `for (path of …)` binding, and a destructuring target (`({ path } = …)`) — as
+ * a `const`/`let`/`var`-declared name, whose initializer is then not what a
+ * request through it sends, or as a wrapper's own path parameter, whose call
+ * sites then do not say what it sends — a path
+ * that is a parameter of a body whose call sites the scan has not been told
+ * about, a wrapper declared as such in a file the scan does not read — so a new
+ * request has to declare itself instead of escaping. WHICH files those are
+ * is not a list that can quietly stop covering the path: every `.ts` under
+ * `src/backends/kubernetes/` that reaches the client — calling
+ * `client.request(…)` itself in either spelling the scan reads, the literal
+ * one or a computed `client['request']`, or naming `listPolicies`, the one
+ * wrapper the scan knows, which takes its path as an argument; every half read
+ * on text with its comments blanked — is either scanned or declared off the
+ * path with its reason, so a file that reaches the client fails that test
+ * until someone decides which of the two it is. The triples it
+ * observes must be exactly this list, plus the four the pool-LESS branch
+ * issues and this grant declines by design. A request added to the pool-only
+ * path therefore fails that test naming the resource, the file and the line,
+ * instead of surfacing as a `403` in a host's log — and so does a rule here
+ * with no call site, which is a grant wider than the code needs.
+ *
+ * What that test still cannot see, so none of the above reads stronger than
+ * it is: the files it declares off the path — `workspace.ts`, `k8s-client.ts`,
+ * `transport.ts` — are never resolved to triples, a wrapper call site in one
+ * of them included, since call sites are read from the scanned files only; and
+ * that a claimant host never reaches `workspace.ts` is a claim about the
+ * DEPLOYMENT (`warmPoolName` set, no `Sandbox` created by that host), which
+ * nothing in this repository measures. A wrapper reached by ANOTHER name is outside that file predicate,
+ * which matches the wrapper's name and not its identity: a file importing a
+ * re-export of it, or calling a helper one level further out that calls it, is
+ * neither scanned nor required to be declared. A request whose path is a
+ * parameter of an expression-bodied arrow is likewise outside what the scan
+ * matches, and a body the scan could not register — a class method, or an
+ * object literal's shorthand method, declared INSIDE one of the bodies it
+ * reads — is attributed to the body that encloses it, so its own parameters
+ * are invisible. The assignment guard is by name in the file it resolves in,
+ * not by scope, so a BINDING it registers nowhere shadows nothing there: a
+ * destructuring parameter (`function f({ path })`) keeps its positional slot
+ * without a name this scan can match, a `catch (path)` is not read at all, and
+ * a write made to an exported binding from ANOTHER module is not in that file's
+ * text — which is also to say that an assignment to a same-named local in an
+ * unrelated function of the same file refuses the request too, a false refusal
+ * rather than an escape. A parameter carrying a DEFAULT is written with an `=`
+ * (`function f(path = …)`, `function f({ path } = {})`), so the guard reads it
+ * and refuses the request rather than resolving it — a refusal, where the bare
+ * pattern would have resolved or failed; and a destructuring pattern nested
+ * inside another (`({ a: { path } } = …)`) is read by neither spelling, which
+ * is measured green.
+ *
+ * **That list is the SHORT form, not the list.** It is carried in full in the
+ * header of `k8s/__tests__/manifests.test.ts`, which also holds two bullets
+ * this paragraph does not: `a path assembled by an operation the scan does not
+ * model`, and `the cluster` (nothing there contacts an API server, so no live
+ * `Role` is measured).
+ *
+ * Exported from the package root because the grant is a property of the
+ * backend, not of a file this package does not publish: `k8s/` is outside
+ * the `files` array, so a consumer cannot read the YAML out of `node_modules`
+ * — it can, however, compare its own applied `Role` against this.
+ */
+/** An RBAC verb this backend issues. No wildcard, and none is ever added. */
+export type KubernetesRbacVerb = 'create' | 'get' | 'list' | 'patch' | 'delete';
+/**
+ * One `rules[]` entry, in the shape RBAC itself uses — one resource per
+ * entry, which is also how the shipped manifests are written, so a rule here
+ * and a rule there compare field for field.
+ */
+export interface KubernetesRbacRule {
+    /** The `apiGroups` entry, verbatim: `''` for the core group. */
+    readonly apiGroup: string;
+    readonly resource: string;
+    readonly verbs: readonly KubernetesRbacVerb[];
+}
+/**
+ * Every verb the pool-only path issues, each pinned to its call site in
+ * `./index.ts` (and, for the policy checks, `./ingress-policy.ts` /
+ * `./egress-policy.ts`):
+ *
+ *  - `sandboxclaims` — `create` is the acquire's POST (`createPath`), `get`
+ *    the readiness poll that waits for the controller to bind one, `patch`
+ *    the lease renewal that keeps a long run's claim alive, `delete` the
+ *    release `destroy()` and a failed acquire's cleanup both send, and
+ *    `list` the two host-invoked reads named above.
+ *  - `sandboxes: get` — read for `status.selector` when the pod-by-name GET
+ *    comes back gone, which on the claim path is the ONLY way to find the
+ *    bound pod: a claim has no `podSelector` of its own to fall back on.
+ *  - `sandboxwarmpools: get` — `readKubernetesTaskCapacity` reads the
+ *    configured pool's own `status.readyReplicas`/`spec.replicas` before a
+ *    host admits more work.
+ *  - `pods` — `get` by name for the agent's bind token and, under
+ *    `agentAddress: 'pod-ip'`, its address, plus the whole-namespace `list`
+ *    that counts in-flight scale-up. The two policy checks use NO pod
+ *    subresource; the agent's protocol is a socket the guest serves, not
+ *    `pods/exec`.
+ *  - `networkpolicies` / `ciliumnetworkpolicies` — `list` is the ingress
+ *    coverage check (on by default before every create) and the egress UNION
+ *    check (on by default whenever `config.egress` is set); `get` is the
+ *    egress named-object check, also only under `config.egress`. Under
+ *    `engine: 'core'` the Cilium rule simply never matches, and a cluster
+ *    with no Cilium CRDs installed never has an object to match it.
+ */
+export declare const KUBERNETES_CLAIMANT_RBAC_RULES: readonly KubernetesRbacRule[];
+//# sourceMappingURL=rbac.d.ts.map

package/dist/backends/kubernetes/rbac.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rbac.d.ts","sourceRoot":"","sources":["../../../src/backends/kubernetes/rbac.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6GG;AAEH,6EAA6E;AAC7E,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAA;AAE/E;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IAClC,gEAAgE;IAChE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,kBAAkB,EAAE,CAAA;CAC7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,kBAAkB,EAqCtE,CAAA"}