@arnilo/prism 0.1.7 → 0.2.1

package/dist/pinned-fetch.js

@@ -0,0 +1,246 @@
+/**
+ * DNS-pinned outbound fetch primitive (0.2.1 task 4).
+ *
+ * One resolve per request, bounded to 1..32 addresses, family-verified, and
+ * every candidate checked against `assertSsrfAllowedUrl` BEFORE the connect —
+ * the connect itself uses a node lookup hook that returns exactly the pinned
+ * address, so the socket cannot re-resolve (DNS-rebinding defense). Redirects
+ * are rejected outright (3xx), and the response stream is byte-bounded.
+ *
+ * Throws `MediaContentError` (`ssrf_denied` for address violations, `redirect`
+ * for 3xx). Error messages are parameterized by `errorPrefix` so each caller
+ * (MCP, OIDC, OPA, content) keeps its own taxonomy and message text.
+ *
+ * NOTE: imports from ./content.js and is imported by it (content's default
+ * media fetch routes through here) — a deliberate ESM cycle; both modules only
+ * reference the other's exports inside function bodies, never at module scope.
+ */
+import { lookup as dnsLookup } from "node:dns/promises";
+import { request as httpRequest } from "node:http";
+import { request as httpsRequest } from "node:https";
+import { isIP } from "node:net";
+import { assertSsrfAllowedUrl, MediaContentError } from "./content.js";
+/** One DNS-pinned, redirect-free, byte-bounded fetch. See module comment. */
+export async function pinnedFetch(url, init, options) {
+    const errorPrefix = options?.errorPrefix ?? "Request";
+    const hostnameErrorPrefix = options?.hostnameErrorPrefix ?? errorPrefix;
+    if (url.username || url.password)
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} URL must not embed credentials`);
+    if (url.hash)
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} URL must not contain a fragment`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} URL must use https: (got ${url.protocol})`);
+    }
+    if (url.protocol === "http:" && !(options?.allowLoopback === true && isLoopbackHostname(url.hostname))) {
+        throw new MediaContentError("ssrf_denied", `Plaintext ${errorPrefix} is allowed only for an explicitly enabled loopback endpoint`);
+    }
+    if (!(options?.allowLoopback === true && isLoopbackHostname(url.hostname))) {
+        try {
+            assertSsrfAllowedUrl(url.href, options?.ssrf);
+        }
+        catch (error) {
+            if (error instanceof MediaContentError && error.code === "unsupported_url_scheme")
+                throw error;
+            throw new MediaContentError("ssrf_denied", `${errorPrefix} URL is not public`, { cause: error });
+        }
+    }
+    const signal = init?.signal;
+    const address = await resolvePinnedAddress(url, options?.resolver ?? defaultResolver, signal, options?.allowLoopback === true, options?.ssrf);
+    const response = await requestPinned(url, address, init, errorPrefix);
+    if (response.status >= 300 && response.status < 400) {
+        await response.body?.cancel();
+        throw new MediaContentError("redirect", `${errorPrefix} redirects are not allowed (status ${response.status})`);
+    }
+    return options?.maxResponseBytes === undefined ? response : boundResponse(response, options.maxResponseBytes, errorPrefix);
+}
+export async function resolvePinnedAddress(url, resolver, signal, allowLoopback, ssrf, hostnameErrorPrefix = "Request") {
+    signal?.throwIfAborted();
+    const hostname = normalizeHostname(url.hostname);
+    const family = isIP(hostname);
+    const addresses = family
+        ? [{ address: hostname, family: family }]
+        : await raceAbort(resolver(hostname, signal ?? new AbortController().signal), signal);
+    if (addresses.length < 1 || addresses.length > 32)
+        throw new MediaContentError("fetch_failed", `${hostnameErrorPrefix} hostname returned an invalid address count`);
+    for (const candidate of addresses) {
+        const normalized = normalizeHostname(candidate.address);
+        if (isIP(normalized) !== candidate.family)
+            throw new MediaContentError("fetch_failed", `${hostnameErrorPrefix} hostname resolver returned an invalid address`);
+        if (allowLoopback && isLoopbackHostname(hostname)) {
+            if (!isLoopbackAddress(normalized))
+                throw new MediaContentError("ssrf_denied", `${hostnameErrorPrefix} loopback hostname resolved outside loopback`);
+            continue;
+        }
+        const literal = candidate.family === 6 ? `[${normalized}]` : normalized;
+        // Fail closed on resolved candidates: an explicit hostname allow-list is honored
+        // for the URL itself, but every resolved address is still private-checked.
+        const candidatePolicy = ssrf?.allowedHostnames?.length ? { denyPrivateHosts: ssrf.denyPrivateHosts } : ssrf;
+        try {
+            assertSsrfAllowedUrl(`${url.protocol}//${literal}`, candidatePolicy);
+        }
+        catch (error) {
+            throw new MediaContentError("ssrf_denied", `${hostnameErrorPrefix} hostname resolved to a private or non-public address`, {
+                cause: error,
+            });
+        }
+    }
+    // ponytail: pin first validated address; add bounded public-address retry only if availability data requires it.
+    const selected = addresses[0];
+    return { address: normalizeHostname(selected.address), family: selected.family };
+}
+export async function defaultResolver(hostname) {
+    return dnsLookup(hostname, { all: true, verbatim: true });
+}
+export async function requestPinned(url, address, init, errorPrefix = "Request") {
+    const body = await requestBody(init?.body, errorPrefix);
+    const headers = new Headers(init?.headers);
+    const method = init?.method ?? "GET";
+    const request = url.protocol === "https:" ? httpsRequest : httpRequest;
+    return new Promise((resolve, reject) => {
+        const nodeRequest = request(url, {
+            method,
+            headers: Object.fromEntries(headers.entries()),
+            signal: init?.signal ?? undefined,
+            lookup: ((_hostname, options, callback) => {
+                if (options.all)
+                    callback(null, [{ address: address.address, family: address.family }]);
+                else
+                    callback(null, address.address, address.family);
+            }),
+        }, (incoming) => {
+            const responseHeaders = new Headers();
+            for (const [name, value] of Object.entries(incoming.headers)) {
+                if (Array.isArray(value))
+                    for (const item of value)
+                        responseHeaders.append(name, item);
+                else if (value !== undefined)
+                    responseHeaders.set(name, value);
+            }
+            const noBody = method === "HEAD" || incoming.statusCode === 204 || incoming.statusCode === 304;
+            const iterator = incoming[Symbol.asyncIterator]();
+            const stream = noBody
+                ? null
+                : new ReadableStream({
+                    async pull(controller) {
+                        try {
+                            const next = await iterator.next();
+                            if (next.done)
+                                controller.close();
+                            else
+                                controller.enqueue(new Uint8Array(next.value));
+                        }
+                        catch (error) {
+                            controller.error(error);
+                        }
+                    },
+                    cancel(reason) {
+                        incoming.destroy(reason instanceof Error ? reason : undefined);
+                    },
+                });
+            resolve(new Response(stream, {
+                status: incoming.statusCode ?? 500,
+                statusText: incoming.statusMessage,
+                headers: responseHeaders,
+            }));
+        });
+        nodeRequest.on("error", reject);
+        if (body)
+            nodeRequest.end(body);
+        else
+            nodeRequest.end();
+    });
+}
+async function requestBody(body, errorPrefix) {
+    if (body === undefined || body === null)
+        return undefined;
+    if (typeof body === "string")
+        return new TextEncoder().encode(body);
+    if (body instanceof URLSearchParams)
+        return new TextEncoder().encode(body.toString());
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    if (ArrayBuffer.isView(body))
+        return new Uint8Array(body.buffer, body.byteOffset, body.byteLength);
+    if (body instanceof Blob)
+        return new Uint8Array(await body.arrayBuffer());
+    throw new MediaContentError("ssrf_denied", `${errorPrefix} request body type is not supported by the pinned transport`);
+}
+export function boundResponse(response, maxBytes, errorPrefix = "Request") {
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        void response.body?.cancel();
+        throw new MediaContentError("ssrf_denied", `${errorPrefix} response exceeds ${maxBytes} bytes`);
+    }
+    if (!response.body)
+        return response;
+    const reader = response.body.getReader();
+    let bytes = 0;
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await reader.read();
+                if (next.done) {
+                    reader.releaseLock();
+                    controller.close();
+                    return;
+                }
+                bytes += next.value.byteLength;
+                if (bytes > maxBytes) {
+                    await reader.cancel();
+                    reader.releaseLock();
+                    controller.error(new MediaContentError("ssrf_denied", `${errorPrefix} response exceeds ${maxBytes} bytes`));
+                    return;
+                }
+                controller.enqueue(next.value);
+            }
+            catch (error) {
+                try {
+                    reader.releaseLock();
+                }
+                catch {
+                    /* Already released after EOF/overflow. */
+                }
+                controller.error(error);
+            }
+        },
+        async cancel(reason) {
+            await reader.cancel(reason);
+            try {
+                reader.releaseLock();
+            }
+            catch {
+                /* Already released after EOF/overflow. */
+            }
+        },
+    });
+    return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+export async function raceAbort(promise, signal) {
+    if (!signal)
+        return promise;
+    signal.throwIfAborted();
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        signal.addEventListener("abort", abort, { once: true });
+        promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+    });
+}
+export function normalizeHostname(value) {
+    return value
+        .toLowerCase()
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "");
+}
+export function isLoopbackHostname(value) {
+    const hostname = normalizeHostname(value);
+    return hostname === "localhost" || hostname.endsWith(".localhost") || isLoopbackAddress(hostname);
+}
+export function isLoopbackAddress(value) {
+    const address = normalizeHostname(value);
+    if (address === "::1")
+        return true;
+    if (isIP(address) !== 4)
+        return false;
+    return Number(address.split(".", 1)[0]) === 127;
+}
+//# sourceMappingURL=pinned-fetch.js.map

package/dist/providers/openai-compatible.d.ts

@@ -21,7 +21,7 @@ export interface OpenAICompatibleProviderOptions {
     readonly extraHeaders?: (request: ProviderRequest) => Record<string, string>;
     /** Final body transform applied last (token limits, compat stripping). Wins over everything. */
     readonly transformBody?: (body: JsonObject, request: ProviderRequest) => JsonObject;
-    /** Require `[DONE]` and a `finish_reason` before emitting `done`; truncated streams yield an error. `done` then carries the final usage. */
+    /** Require `[DONE]` and a `finish_reason` before emitting `done`; truncated streams yield an error. `done` then carries the final usage. Default `true` (fail-closed); set `false` explicitly to accept streams that end without completion evidence. */
     readonly strictCompletion?: boolean;
     /** Emit the final stream usage on the `done` event (without strict completion checks). */
     readonly doneUsage?: boolean;
@@ -34,7 +34,7 @@ export interface OpenAICompatibleProviderOptions {
 }
 export interface OpenAIChatEventsOptions {
     readonly signal?: AbortSignal;
-    /** Require `[DONE]` and a `finish_reason`; `done` then carries the final usage. */
+    /** Require `[DONE]` and a `finish_reason`; `done` then carries the final usage. Default `true` (fail-closed); set `false` explicitly to accept streams that end without completion evidence. */
     readonly strictCompletion?: boolean;
     /** Emit the final stream usage on the `done` event. */
     readonly doneUsage?: boolean;

package/dist/providers/openai-compatible.js

@@ -72,7 +72,7 @@ export async function* openAIChatEvents(body, options = {}) {
         yield providerError(new ProviderTransportError("incomplete_delta", `Incomplete tool call delta at index ${incomplete[0]}`));
         return;
     }
-    if (options.strictCompletion && (!sawDoneMarker || !sawFinishReason)) {
+    if ((options.strictCompletion ?? true) && (!sawDoneMarker || !sawFinishReason)) {
         // Truncated streams must fail loudly — emitting done would mark partial output as succeeded.
         yield providerError(new Error(`Chat stream ended without completion evidence ` +
             `([DONE]: ${sawDoneMarker ? "received" : "missing"}, ` +
@@ -82,7 +82,7 @@ export async function* openAIChatEvents(body, options = {}) {
     for (const call of tools.values()) {
         yield providerToolCall(toolCallFromArgumentsText(call.id, call.name, call.argumentsText));
     }
-    yield providerDone(options.strictCompletion || options.doneUsage ? usage : undefined);
+    yield providerDone((options.strictCompletion ?? true) || options.doneUsage ? usage : undefined);
 }
 export function createOpenAICompatibleProvider(options) {
     const providerId = options.id ?? "openai-compatible";

package/dist/providers/transport.d.ts

@@ -14,7 +14,7 @@ export interface SseEvent {
     readonly data: string;
     readonly comments?: readonly string[];
 }
-export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta";
+export type ProviderTransportErrorCode = "sse_buffer_overflow" | "sse_event_overflow" | "response_body_overflow" | "aborted" | "invalid_json_arguments" | "incomplete_delta" | "response_body_shape";
 export declare class ProviderTransportError extends Error {
     readonly code: ProviderTransportErrorCode;
     readonly limitBytes?: number;
@@ -32,6 +32,15 @@ export interface ReadSseEventsOptions extends BoundedStreamLimits {
 export interface ReadBoundedResponseTextOptions extends BoundedStreamLimits {
     readonly secrets?: readonly (string | undefined)[];
 }
+export interface ReadBoundedResponseJsonOptions extends ReadBoundedResponseTextOptions {
+    /** Max JSON nesting depth. Default: 32. */
+    readonly maxDepth?: number;
+    /** Max object properties / array elements per container. Default: 4_096. */
+    readonly maxProperties?: number;
+    /** Caller-supplied shape gate; failure throws `response_body_shape`. */
+    readonly shape?: (value: unknown) => boolean;
+    readonly signal?: AbortSignal;
+}
 export interface ParseJsonObjectArgumentsOptions {
     readonly toolName?: string;
     readonly maxBytes?: number;
@@ -42,6 +51,10 @@ export declare function readSseEvents(body: ReadableStream<Uint8Array>, options?
 export declare function readSseData(body: ReadableStream<Uint8Array>, options?: ReadSseEventsOptions): AsyncGenerator<string>;
 /** Read a response body with a hard byte ceiling; redacts optional secrets. */
 export declare function readBoundedResponseText(response: Response, options?: ReadBoundedResponseTextOptions): Promise<string>;
+/** Read a success body with the same byte ceiling as {@link readBoundedResponseText}, then parse it as JSON
+ *  with depth/property caps and an optional caller-supplied shape gate. Malformed JSON, over-limit nesting,
+ *  or shape failure throw `ProviderTransportError` with code `response_body_shape`. */
+export declare function readBoundedResponseJson<T>(response: Response, options?: ReadBoundedResponseJsonOptions): Promise<T>;
 export type ParseJsonObjectArgumentsResult = {
     readonly ok: true;
     readonly value: JsonObject;

package/dist/providers/transport.js

@@ -218,6 +218,49 @@ export async function readBoundedResponseText(response, options) {
         }
     }
 }
+function assertJsonBounds(value, maxDepth, maxProperties, depth = 0) {
+    if (depth > maxDepth) {
+        throw new ProviderTransportError("response_body_shape", `JSON nesting exceeded ${maxDepth} levels`);
+    }
+    if (value === null || typeof value !== "object")
+        return;
+    if (Array.isArray(value)) {
+        if (value.length > maxProperties) {
+            throw new ProviderTransportError("response_body_shape", `JSON array exceeded ${maxProperties} elements`);
+        }
+        for (const entry of value)
+            assertJsonBounds(entry, maxDepth, maxProperties, depth + 1);
+        return;
+    }
+    const keys = Object.keys(value);
+    if (keys.length > maxProperties) {
+        throw new ProviderTransportError("response_body_shape", `JSON object exceeded ${maxProperties} properties`);
+    }
+    for (const key of keys)
+        assertJsonBounds(value[key], maxDepth, maxProperties, depth + 1);
+}
+/** Read a success body with the same byte ceiling as {@link readBoundedResponseText}, then parse it as JSON
+ *  with depth/property caps and an optional caller-supplied shape gate. Malformed JSON, over-limit nesting,
+ *  or shape failure throw `ProviderTransportError` with code `response_body_shape`. */
+export async function readBoundedResponseJson(response, options) {
+    throwIfAborted(options?.signal);
+    const text = await readBoundedResponseText(response, options);
+    throwIfAborted(options?.signal);
+    const maxDepth = options?.maxDepth ?? 32;
+    const maxProperties = options?.maxProperties ?? 4_096;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new ProviderTransportError("response_body_shape", "Response body is not valid JSON");
+    }
+    assertJsonBounds(parsed, maxDepth, maxProperties);
+    if (options?.shape && !options.shape(parsed)) {
+        throw new ProviderTransportError("response_body_shape", "Response body does not match the expected shape");
+    }
+    return parsed;
+}
 /** Parse streamed tool arguments without throwing; prefer this for recoverable tool-call recovery. */
 export function tryParseJsonObjectArguments(text, options) {
     const maxBytes = options?.maxBytes ?? DEFAULT_MAX_ARGUMENT_BYTES;

package/docs/agent-session-runtime.md

@@ -187,6 +187,8 @@ Set `runState` with a host-owned `CheckpointStore`, stable `definitionRevision`,
 
 `*_for_run` outcomes append a `StickyDecision` to the durable run state: later calls in the same run matching the scope exactly (all recorded fields) proceed or are blocked without a new suspension, policy still enforced at dispatch. Sticky decisions expire when the run reaches any terminal status. Caps: 32 pending decisions per run (hard 128), 64 sticky decisions (hard 256), 2 KB decision reasons, 16 KB elicitation payloads.
 
+**Runtime input validation (0.2.0, plan 020 Task 2).** Every public resume entrypoint (`resumeAgentRun`, `resumeAgentRunStream`, `AgentRunLifecycle.resume()`/`resumeStream()`) validates the complete resume input in core before any checkpoint read/write, agent resolution, subscription, or tool execution: a non-null object, positive safe-integer `expectedVersion`, exactly one of `decision`/`decisions`, legacy `decision` exactly `approve`/`deny`, and a non-empty batch ≤ 128 entries whose entries are objects with a bounded non-empty `approvalId`, a whitelisted outcome, an optional string `reason` within the 2 KB limit, and JSON-object `modifiedArguments`/`elicitation` within the 16 KB limit. Unknown legacy decisions (e.g. `"sideways"`) and malformed untyped batches fail closed with `AgentDecisionError` (`ERR_PRISM_DECISION_INVALID`/`..._LIMIT`/`..._DUPLICATE`) under a **no-side-effect guarantee**: zero checkpoint writes/CAS changes, zero tool calls, zero resumed events. This holds for plain-JavaScript and `as any` callers; the server's transport parser is defense in depth, not the security boundary. State-dependent checks (foreign/stale approval ids, scope, schema, policy) still run in the atomic batch resolver.
+
 ```ts
 const result = await session.run("Publish draft", {
   runState: { checkpoints, definitionRevision: "2026-07-20.1", interruptBeforeTool: true },

package/docs/coding-security.md

@@ -13,7 +13,7 @@
 | `createSandboxCodingTools` / `createSandboxReadOnlyTools` | Thin wrappers that return `tools` only (compat); still require `workspaceMode`. |
 | `createSandboxFilesystemOperations` / `createSandboxRepositoryOperations` | Optional execFile-backed FS/list/search backends for a disposable sandbox tree. |
 | `createDockerSandbox(options)` | Creates one disposable non-root Docker container with read-only root/source, bounded tmpfs workspace, typed `execFile`, import/export, and stop/kill/cleanup. |
-| `createNativeSandbox(options)` | Linux-only network-free backend: every command runs in a fresh network namespace (`unshare`), POSIX `ulimit` hard caps, cwd-in-root containment; fails closed at creation on platforms/privileges that cannot deny egress. Docker remains the stronger, documented reference backend. |
+| `createNativeSandbox(options)` | Linux-only network-free backend: every command runs in a fresh network namespace (`unshare`), POSIX `ulimit` hard caps, cwd-in-root containment; fails closed at creation on platforms/privileges that cannot deny egress. Reports truthful capability metadata (`networkIsolated`/`egressRestricted` true, `filesystemIsolated`/`processIsolated`/`privilegeIsolated` false). Docker remains the stronger, documented reference backend. |
 | `SandboxProcessHandle` | Optional long-running process handle (`write`/`signal`/`kill`/`release`/`wait`) returned by `DisposableSandbox.startProcess?`. |
 | `createEgressPolicy(options)` | Deny-all allow-list policy: exact host/port/protocol rules plus frozen `npm-registry` / `github` presets; SHA-256 fingerprint. |
 | `createAllowListEgressProxy(options)` | HTTP forward proxy + CONNECT tunnel enforcing the policy: pinned DNS (rebinding defense), private/metadata IP denial, redirect re-validation + hop cap, byte/time caps, per-decision audit, attestation for sandbox composition. |
@@ -34,7 +34,7 @@ Use this package when coding tools need path scoping, human approval, command ru
 
 Use `createDockerSandbox()` when the host wants a production-reference containment boundary. Prism does **not** claim OS-level isolation unless the host constructs this adapter (or supplies an equivalent custom `DisposableSandbox`). Default policy denies shell/write/edit/delete/move without an `approve` callback and rejects paths outside configured roots. Coding shell definitions are marked `exclusive: true`, matching the approval policy's shell decision, so a single-shot turn containing shell work runs sequentially even when `toolConcurrency > 1`. Non-shell turns retain configured parallelism.
 
-Use `createNativeSandbox()` when the host has no container runtime and needs network-free containment (0.1.6, plan 018 closeout `native-sandbox`). Linux only; creation fails closed with a documented error on other platforms or when the OS cannot create a network namespace (no root/CAP_SYS_ADMIN and no unprivileged user namespaces). Every command runs in a fresh netns — **loopback is down**, so even localhost connections fail; hosts that need loopback keep the Docker backend. Containment is egress denial + `ulimit` hard caps (address space from `memoryBytes`, CPU-time wall backstop, fd count from `maxFds`) + cwd-inside-root (`assertPathInsideRoots`, symlink-aware). The native backend does **not** isolate the filesystem: commands run as the invoking OS user with full host-tree access, so pair it with `createSandboxCodingComposition`/`createSandboxFilesystemOperations` (per-op `assertSandboxPath`) and the approval policy, exactly as with any custom `DisposableSandbox`. Host env is never inherited; `env` is an exact allow-list (PATH only by default). No `startProcess` (ProcessSessions fails closed with `ERR_PRISM_PROCESS_UNSUPPORTED`), no CPU-rate/pids/fs-size caps (cgroup-only). Secrets passed as `secrets` are redacted from surfaced errors. See `docs/_evidence/phase18-primitive-review.md` for the full threat model.
+Use `createNativeSandbox()` when the host has no container runtime and needs network-free containment (0.1.6, plan 018 closeout `native-sandbox`). Linux only; creation fails closed with a documented error on other platforms or when the OS cannot create a network namespace (no root/CAP_SYS_ADMIN and no unprivileged user namespaces). Every command runs in a fresh netns — **loopback is down**, so even localhost connections fail; hosts that need loopback keep the Docker backend. Containment is egress denial + `ulimit` hard caps (address space from `memoryBytes`, CPU-time wall backstop, fd count from `maxFds`) + cwd-inside-root (`assertPathInsideRoots`, symlink-aware). The native backend does **not** isolate the filesystem: commands run as the invoking OS user with full host-tree access, so pair it with `createSandboxCodingComposition`/`createSandboxFilesystemOperations` (per-op `assertSandboxPath`) and the approval policy, exactly as with any custom `DisposableSandbox`. Its `capabilities` report `networkIsolated: true` and `egressRestricted: true` but `filesystemIsolated`/`processIsolated`/`privilegeIsolated: false` — the native backend is never a containment boundary for untrusted code (see [Sandbox capabilities](#sandbox-capabilities-020-plan-020-task-4)). Host env is never inherited; `env` is an exact allow-list (PATH only by default). No `startProcess` (ProcessSessions fails closed with `ERR_PRISM_PROCESS_UNSUPPORTED`), no CPU-rate/pids/fs-size caps (cgroup-only). Secrets passed as `secrets` are redacted from surfaced errors. See `docs/_evidence/phase18-primitive-review.md` for the full threat model.
 
 Use `createEgressPolicy()` + `createAllowListEgressProxy()` when a coding agent needs outbound network access under an explicit allow list: package installs, forge API calls, or source fetches — never unrestricted egress. The proxy is inert until `start()`; nothing binds or resolves on import or construction.
 
@@ -104,7 +104,27 @@ const sandbox = await createDockerSandbox({ docker, image, sourceRoot, user, net
 
 `createCodingApprovalPolicy()` returns an `ExecutionPolicy`. Allowed checks return `ExecutionDecision { allowed: true }`; denied checks include a stable reason; shell decisions set `exclusive: true`. Sandbox adapters return coding-agent-compatible `BashOperations`, receive `onData(Buffer)` for ordered stdout/stderr forwarding through the shell tool's existing bounded accumulator, and never grant policy approval themselves.
 
-`createSandboxCodingComposition()` returns `{ tools, composition }` where `SandboxCodingComposition` carries `workspaceMode`, `containmentClaim`, `mixedWiringAllowed`, `warnings`, `workspaceRoot`, and optional `treeIdentity` (from `importIdentity` / `lastExportIdentity`). `containmentClaim` is `true` only for sandbox mode with tree backends bound and mixed wiring denied. Host mode and escape-hatch mixed wiring always set `containmentClaim: false` — never treat host mode as contained execution.
+`createSandboxCodingComposition()` returns `{ tools, composition }` where `SandboxCodingComposition` carries `workspaceMode`, `capabilities`, `containmentClaim` (deprecated), `mixedWiringAllowed`, `warnings`, `workspaceRoot`, and optional `treeIdentity` (from `importIdentity` / `lastExportIdentity`). `capabilities` is a complete, frozen `SandboxCapabilities` object: `workspaceCoherent` derives from actual shell/filesystem/repository wiring; the isolation fields derive only from validated adapter capability metadata, never from `execFile`/`close` duck typing or custom operations being present. Host mode and escape-hatch mixed wiring always report no isolation capability — never treat host mode as contained execution.
+
+### Sandbox capabilities (0.2.0, plan 020 Task 4)
+
+Every sandbox backend and every composition reports a frozen, complete capability object:
+
+| Capability | Meaning | Docker | Native | Custom / omitted |
+| --- | --- | --- | --- | --- |
+| `workspaceCoherent` | Shell, filesystem, and repository tools observe one workspace tree. | true | true | true only when tree backends are bound and mixed wiring denied |
+| `filesystemIsolated` | Sandbox processes cannot touch the host filesystem. | true | **false** (full host-tree access by design) | false unless host attests |
+| `networkIsolated` | No reachable network. | true only for `network: { mode: "none" }` | true (fresh netns per command, egress denied, loopback down) | false unless host attests |
+| `processIsolated` | Sandbox processes run in a separate process namespace. | true | **false** | false unless host attests |
+| `privilegeIsolated` | Sandbox processes cannot obtain host privileges. | **false** (root-in-container without user namespaces is not reliable) | **false** | false unless host attests |
+| `egressRestricted` | Any egress is forced through a controlled proxy/firewall. | true for mode `none`, or a custom network carrying a validated `EgressAttestation` | true (no egress at all) | false unless host attests |
+
+Rules:
+
+- **Omission is false.** A `SandboxAdapter` without `capabilities` metadata — or with malformed metadata (non-object, missing fields, non-boolean values, unknown keys) — resolves every isolation field false. `resolveSandboxCapabilities()` validates, copies, and freezes explicit metadata; a backend can never gain a capability by omission, interface shape, or mixed wiring.
+- **Explicit metadata is host attestation.** Prism validates shape and freezes the object; the host is responsible for the underlying controls being real.
+- **`containmentClaim` is deprecated (0.2.0).** Retained for 0.1.7 compatibility as the conservative projection `workspaceCoherent && filesystemIsolated && networkIsolated && processIsolated` (privilege isolation excluded). It can only be `true` when every required capability is true — never authorize a security-sensitive action from this boolean alone; use `composition.capabilities`.
+- **Capability construction is O(1)** — one small frozen object per sandbox/composition; no command, filesystem, Docker, DNS, or network operation.
 
 `createDockerSandbox()` returns a `DisposableSandbox`: typed `execFile(file, args)`, shell-compatible `exec`, `status`, cooperative `stop`, forced `kill`, and idempotent `close`. Import may surface `importIdentity`; successful export updates `lastExportIdentity`. `close({ export })` can stream a bounded workspace tar plus SHA-256/entry/byte metadata through a host callback; checkpoints should retain only host artifact references/hashes, never whole workspaces. Optional `startProcess?(SandboxExecFileRequest)` returns a `SandboxProcessHandle` for long-running work consumed by coding-agent `createProcessSessions({ sandbox })`; absence means one-shot-only — ProcessSessions fails closed with `ERR_PRISM_PROCESS_UNSUPPORTED` (no native fallback). The Docker reference adapter does not implement `startProcess` yet; capability is detected, never assumed. See [Process sessions](process-sessions.md).
 
@@ -151,7 +171,8 @@ const { tools, composition } = createSandboxCodingComposition("/srv/jobs/task-1/
   executionPolicy: policy,
   repository: { exclude: [".git", "node_modules", "dist"] },
 });
-// composition.containmentClaim === true when backends are bound
+// composition.capabilities.filesystemIsolated === true for the Docker adapter with network: none
+// composition.containmentClaim is deprecated compatibility metadata only
 
 // Same-tree Git/check (opt-in; not folded into coding tools):
 const gitTools = createGitTools(composition.workspaceRoot, {
@@ -161,7 +182,7 @@ const gitTools = createGitTools(composition.workspaceRoot, {
 
 // Host mode (explicit non-contained): omit sandbox; never claim containment.
 const host = createSandboxCodingComposition(hostCwd, { workspaceMode: "host", executionPolicy: policy });
-// host.composition.containmentClaim === false
+// host.composition.capabilities: workspaceCoherent only; every isolation field false; containmentClaim false
 
 await sandbox.execFile({ file: "npm", args: ["test"], cwd: "/workspace" });
 await sandbox.close({
@@ -173,7 +194,7 @@ await sandbox.close({
 
 Policies are ordinary host values: attach one globally through `createCodingTools()`/`createReadOnlyTools()`/`createSandboxCodingComposition()` or per tool. A per-tool policy overrides the shared policy. `SandboxAdapter` / `DisposableSandbox` are replaceable and host-owned; approval policy and sandboxing are separate layers. Custom remote sandboxes can implement `DisposableSandbox` without using Docker.
 
-`createSandboxCodingComposition()` requires `workspaceMode`. Sandbox mode auto-wires FS/list/search through `DisposableSandbox.execFile` (or host-supplied custom operations) so mutations stay on the disposable tree until export. Host mode runs every coding tool against the host cwd and never sets `containmentClaim`. Sandbox shell + host FS throws unless `allowMixedWorkspaceWiring: true` (warnings + `containmentClaim: false`). Opt-in structured Git tools (`createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`) share the same tree/cwd; Prism still never pushes or opens PRs. Optional `@arnilo/prism-browser` can share the same disposable boundary: use `assertBrowserSandboxNetwork()` before browse-ready custom networks, and `createSharedSandboxBrowserOptions({ workspaceRoot, downloadsRoot, containedProxyAttestation })` so uploads/downloads align with `/workspace` and `/downloads`. Close the browser context before disposing the sandbox.
+`createSandboxCodingComposition()` requires `workspaceMode`. Sandbox mode auto-wires FS/list/search through `DisposableSandbox.execFile` (or host-supplied custom operations) so mutations stay on the disposable tree until export. Host mode runs every coding tool against the host cwd and reports no isolation capability (`containmentClaim` deprecated false). Sandbox shell + host FS throws unless `allowMixedWorkspaceWiring: true` (warnings + all capabilities false). Opt-in structured Git tools (`createGitTools(composition.workspaceRoot, { execFile: sandbox.execFile, commitIdentity })`) share the same tree/cwd; Prism still never pushes or opens PRs. Optional `@arnilo/prism-browser` can share the same disposable boundary: use `assertBrowserSandboxNetwork()` before browse-ready custom networks, and `createSharedSandboxBrowserOptions({ workspaceRoot, downloadsRoot, containedProxyAttestation })` so uploads/downloads align with `/workspace` and `/downloads`. Close the browser context before disposing the sandbox.
 
 The Docker reference adapter starts by recorded container ID/label, uses argument arrays only, mounts source read-only, populates a size-bounded tmpfs `/workspace`, drops all capabilities, enables `no-new-privileges`, runs with `--init`, and never exposes the Docker socket, privileged mode, or host PID/IPC namespaces. Image pull/build/update stays outside Prism. Protected real-Docker checks are opt-in via `PRISM_TEST_DOCKER_SANDBOX=1` with host-supplied `PRISM_TEST_DOCKER_BIN` and digest-pinned `PRISM_TEST_DOCKER_IMAGE`.
 

package/docs/credential-storage.md

@@ -248,6 +248,7 @@ const providers = createOpenAIProviderPackage({ apiKey });
 - Never log passphrases, derived keys, or decrypted credential payloads.
 - Optional host KMS: `encryptWithHostKms` / `decryptWithHostKms` wrap a random AES-256-GCM DEK via host `HostKms.wrapKey`/`unwrapKey` (timeout ≤ 60 s). Envelope sizes reuse vault/file caps. Keys are never logged. `createMemoryHostKms` is for tests only.
 - Storage is not OAuth eligibility. A durable store may persist credentials for a provider only after the host selects a provider-authorized flow; it must not be used to piggyback on a vendor CLI or consumer subscription.
+- OIDC JWKS fetches (0.2.1) are DNS-pinned through the core `pinnedFetch` primitive: one resolve per request, every resolved address SSRF-checked before the connect (rebinding defense), redirects rejected outright, and the JWKS body read under a hard byte ceiling; oversized documents fail closed as a parse error, never as a rotatable transport failure.
 - Live keychain tests are opt-in (`PRISM_TEST_KEYCHAIN=1`); default `npm test` stays offline.
 
 ## MCP authentication boundary

package/docs/credentials-and-redaction.md

@@ -124,6 +124,7 @@ A future provider-local OAuth adapter needs published permission for third-party
 - `resolveCredentialValue()` and `createExplicitCredentialResolver()` do not cache values. Add host-side caching only if a real credential source needs it.
 - `refreshOAuthCredential()` only calls the supplied OAuth provider and optional store; it has no built-in persistence or retry loop.
 - OpenAI Codex device-code OAuth polls inside `createOpenAICodexOAuthProvider().login()` with bounded delays and abort support via `OAuthLoginCallbacks.signal`. Token-endpoint failures redact authorization codes, PKCE verifiers, device/user codes, and access/refresh tokens when those values are known.
+- The shared bounded device/token flow lives in core `pollDeviceCodeToken` (0.2.1) and is used by the OpenAI Codex provider and the credentials-node OAuth 2.0 provider (Microsoft 365 / Google Workspace). It owns the RFC 8628 device-code request and poll loop (`authorization_pending` continue, `slow_down` +5s backoff, expiry deadline, abort), reads every response body under the shared byte ceiling, parses success bodies with a fail-closed shape gate (an `access_token` string is required), and redacts device/user codes, authorization codes, PKCE verifiers, and tokens from every thrown error. Adapter-specific fields (message prefix, extra token params, account binding) are plain options, never subclasses.
 
 ## Related APIs
 

package/docs/host-security.md

@@ -147,7 +147,7 @@ Wire those values where they matter: provider adapters receive the resolved cred
 - AG-UI MCP Apps requires negotiated `mcpApps`, exact proxy origin/auth, owned-run context, approval, one bridge, separate-origin sandbox (`allow-scripts allow-same-origin`), and no-wider CSP. Never execute HTML in host origin or retry a UI mutation; Task 4 adds recovery.
 - AG-UI A2A requires exact-origin verified client, host-owned task selection/correlation, explicit data/tool/A2UI projection, and reauthorized follow/cancel.
 - `@arnilo/prism-server` exposes no agent/workflow by default and requires `authorize()` for every matched operation. Derive complete tenant/account/user ownership from validated host identity, never request JSON. Workflow active identity and cancellation compare exact ownership; a tenant-only scope intentionally cannot cancel a checkpoint/run carrying account or user identity. The artifact review service (`createArtifactService`) requires authenticated identity + thread ownership on every attach/revise/compare/approve/reject/download, resolves concurrent reviewers via checkpoint CAS (no lost approvals), rejects local filesystem paths in `uri`/citations, redacts records before persist and on response, and serves downloads only through signed expiring links that are reauthorized against the token's ownership per request. When a blob store is wired (`bodies: ArtifactBodyStore`, 0.0.28), delivery links additionally resolve through `bodies.presign`; the reference `createS3ArtifactBodyStore` verifies ownership on every operation, verifies size/SHA-256/MIME on put and get (fail closed), refuses delete under legal hold (host `isHeld` callback), keeps credentials host-resolved, and never discloses bucket/path/key in errors, telemetry, or artifact records. Pass the current explicitly revised workflow definition so recursive hash mismatch fails before abort or durable mutation. Configure exact host/origin allow-lists where needed, wire redaction before execution, retain tool/workflow policy checks, and adapt the Web handler behind host TLS/rate limits. Disconnect abort is default; persistent reconnect/status belongs to durable workflow checkpoints, not an invented in-memory agent result cache.
-- Coding tools from `@arnilo/prism-coding-agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects; shared policy propagation includes `createReadOnlyTools()`. They enforce finite text-scan/image/edit/write/shell limits, repository list/search depth/entry/match/scan/time caps, structured Git path/ref/message/output/patch/worktree caps, named-check concurrency/output caps, a 600-second default shell wall time, and a 64 MiB default total-output ceiling. Opt-in `createGitTools()` uses argument arrays with hooks/credential prompts/external diff disabled, requires host `commitIdentity` for commits, and never pushes or opens PRs. Successful truncated shell output leaves a host-owned exclusive `0600` temp file; delete `metadata.fullOutputPath` after use. Error/abort/timeout/overflow removes unpublished spills. Custom read/edit/shell/repository backends must honor supplied caps/signals. Use `@arnilo/prism-coding-security` for path roots, command rules, identity-scoped approval caching, required `workspaceMode` on `createSandboxCodingComposition()` / `createSandboxCodingTools()`, and the optional `createDockerSandbox()` reference adapter. **Host mode is never contained execution** (`containmentClaim: false`). Sandbox mode claims containment only when FS backends target the disposable tree; mixed wiring requires `allowMixedWorkspaceWiring` and still does not claim containment. Limits alone are not containment: construct the Docker adapter (absolute CLI, digest-pinned image, network none by default) or an equivalent host sandbox before treating coding execution as production-safe. Docker daemon/image trust, egress firewall/proxy, and artifact retention remain host-owned.
+- Coding tools from `@arnilo/prism-coding-agent` accept an optional `ExecutionPolicy` checked inside each tool before side effects; shared policy propagation includes `createReadOnlyTools()`. They enforce finite text-scan/image/edit/write/shell limits, repository list/search depth/entry/match/scan/time caps, structured Git path/ref/message/output/patch/worktree caps, named-check concurrency/output caps, a 600-second default shell wall time, and a 64 MiB default total-output ceiling. Opt-in `createGitTools()` uses argument arrays with hooks/credential prompts/external diff disabled, requires host `commitIdentity` for commits, and never pushes or opens PRs. Successful truncated shell output leaves a host-owned exclusive `0600` temp file; delete `metadata.fullOutputPath` after use. Error/abort/timeout/overflow removes unpublished spills. Custom read/edit/shell/repository backends must honor supplied caps/signals. Use `@arnilo/prism-coding-security` for path roots, command rules, identity-scoped approval caching, required `workspaceMode` on `createSandboxCodingComposition()` / `createSandboxCodingTools()`, and the optional `createDockerSandbox()` reference adapter. **Host mode is never contained execution** (every isolation capability false). Sandbox mode reports isolation only from validated adapter capability metadata: `composition.capabilities` carries the frozen `SandboxCapabilities` object (`workspaceCoherent`, `filesystemIsolated`, `networkIsolated`, `processIsolated`, `privilegeIsolated`, `egressRestricted`); the deprecated `containmentClaim` is a conservative projection and must never be used alone. Authorize security-sensitive actions from the individual capabilities the policy actually needs — e.g. require `filesystemIsolated` before hosting untrusted coding tasks, and `egressRestricted` before any network-capable run. Mixed wiring requires `allowMixedWorkspaceWiring` and still reports no isolation. Limits alone are not containment: construct the Docker adapter (absolute CLI, digest-pinned image, network none by default) or an equivalent host sandbox before treating coding execution as production-safe. Docker daemon/image trust, egress firewall/proxy, and artifact retention remain host-owned.
 - Allow-list egress (0.0.26, `@arnilo/prism-coding-security`): `createEgressPolicy()` is deny-all with exact host/port/protocol rules and frozen `npm-registry`/`github` presets; `createAllowListEgressProxy()` is an HTTP forward proxy + CONNECT tunnel that pins DNS answers and verifies the connected address (rebinding defense), denies private/link-local/metadata ranges unless a rule opts in, re-validates every redirect hop against policy, and cuts oversized/slow transfers at frozen byte/time caps. TLS passes through without interception. Every allow/deny writes an audit record with no secrets. The proxy is inert until `start()`; `reloadPolicy()` is the only rule change path. `composeEgressSandboxNetwork(proxy.attestation(), name)` records validated attestation as `prism.egress.*` container labels — evidence, not enforcement: the host must restrict the Docker network so the proxy is the only reachable path, and `denyDirectEgress: true` is a claim the host makes true by topology. The proxy is not a firewall and cannot stop a container whose network reaches the internet directly.
 - Optional `@arnilo/prism-browser` requires a host-supplied Playwright Browser (`playwright-core@1.61.0` peer). Import is inert. One non-persistent context belongs to one run; actions serialize; refs are snapshot-scoped; CSS/evaluate/CDP/persistent profiles are denied. Context routing + `serviceWorkers: "block"` deny file/data/blob/devtools/private/loopback by default and require contained-proxy attestation for external egress (Playwright routing is defense in depth, not DNS containment). Uploads are realpath-rooted; downloads quarantine with hash/MIME until host `approveRelease`; screenshots return bounded `ImageContent`. Observation vs mutation/high-impact actions map to `ExecutionPolicy`. Treat snapshot/page text as untrusted external content. Close contexts with `browser_close` or `manager.closeRun(runId)` on abort/terminal. Browser control endpoint, binary/image pin, and real egress firewall/proxy remain host-owned. Shared sandbox: `createSharedSandboxBrowserOptions()` + `assertBrowserSandboxNetwork()`.
 - Browser verified-state checkpoints (0.0.14, `createBrowserCheckpointLedger()`) store URL + domain-state hash + host data refs only — never serialized browser internals (cookies/storage/contexts). After any resume/interruption the ledger fails closed (`assertVerifiedBeforeSideEffect`) until the host reloads + verifies, so side effects never replay on stale state.