@theokit/sdk 4.19.4 → 4.21.0

package/dist/sandbox/bwrap.d.cts

@@ -0,0 +1,75 @@
+/**
+ * M53 — bubblewrap argv + honest detection, faithful to Codex's Linux sandbox
+ * (`codex-rs/linux-sandbox/src/bwrap.rs` + `codex-rs/sandboxing/src/bwrap.rs`).
+ *
+ * HONEST SCOPE: filesystem confinement + network isolation via bwrap, PLUS the second stage —
+ * a cBPF seccomp syscall filter (`agents/sandbox/seccomp.ts`), wired in `agents/sandbox/backend.ts`
+ * via `restrictedSeccompPath()`. Portado no M63; este bloco afirmava o contrário até o M67 e
+ * SUBDECLARAVA a postura de segurança real. Limite honesto que permanece: o filtro é **x86_64**
+ * (guarda de arquitetura recusa instalar em outra arch, com WARN, e o confinamento de FS/rede do
+ * bwrap segue valendo) **e** só é instalado quando a rede está restrita (`backend.ts:87`, fiel a
+ * `landlock.rs:96-117`): com rede ligada não há filtro de syscall, apenas o confinamento de FS do
+ * bwrap. `danger-full-access` pula o bwrap por completo, espelhando `bwrap.rs:245-252`.
+ * Deltas versus o Codex seguem documentados em docs/CODEX-PARITY.md.
+ */
+/**
+ * Os tres modos canonicos do Codex. Definidos AQUI porque sao vocabulario do sandbox, nao da
+ * configuracao do consumidor: `danger-full-access` significa "nao embrulhe", e essa e uma decisao do
+ * subsistema de confinamento.
+ */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export interface BwrapArgvOptions {
+    /** Workspace root — the single RW bind under `workspace-write` (protocol.rs:1189-1200). */
+    cwd: string;
+    /** `true` removes `--unshare-net` (policy `network_access`, default false). */
+    network?: boolean;
+    /** Injectable for tests; defaults to a real `existsSync` check on `<cwd>/.git`. */
+    gitDirExists?: boolean;
+    /**
+     * When present, emit `--clearenv` and re-inject ONLY these vars (Codex env_clear model,
+     * `exec_env.rs:25-31`). Closes the denylist gap: a secret in an oddly-named var never reaches the
+     * sandboxed child. Omitted ⇒ inherit the parent env (backward-compatible; SDK scrub still applies).
+     */
+    env?: Record<string, string>;
+}
+/**
+ * Pure argv builder. Returns the bwrap flags ending in `--` (caller appends `/bin/sh -c <cmd>`),
+ * or `null` when the policy skips the sandbox entirely (`danger-full-access`).
+ */
+export declare function buildBwrapArgv(mode: SandboxMode, opts: BwrapArgvOptions): string[] | null;
+/** Injectable probes — each mirrors one Codex availability check. */
+export interface BwrapProbes {
+    /** `which bwrap` outside the cwd (anti-hijack, sandboxing/src/bwrap.rs:168-191). */
+    which: () => string | null;
+    /** `bwrap --help` text — must advertise `--perms` (launcher.rs:108-124). */
+    helpText: (bin: string) => string | null;
+    /** Active user-namespace probe with timeout (sandboxing/src/bwrap.rs:74-136). */
+    userns: (bin: string) => boolean;
+}
+export type BwrapDetection = {
+    ok: true;
+    bin: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Honest detection — fail-closed on every probe; NEVER throws (callers WARN + fall back). */
+export declare function detectBwrap(probes?: BwrapProbes): BwrapDetection;
+/** Quantas sondagens reais rodaram. Seam de TESTE — o gate de performance conta isto. */
+export declare function realProbeCount(): number;
+/** Real probes used in production. */
+export declare const realProbes: BwrapProbes;
+/**
+ * `detectBwrap` com memoização — o que a produção deve chamar.
+ *
+ * Note que `detectBwrap` em si **não** memoiza, de propósito: ele aceita probes injetados, e memoizar
+ * ali faria um teste com probes falsos envenenar o cache do processo para todos os outros.
+ *
+ * A revalidação do positivo NÃO é uma re-sondagem: `detectBwrap` gasta três probes (subprocesso
+ * `which` + `--help` + namespace de usuário). Aqui só se confirma que o binário validado continua no
+ * lugar. Se sumiu, o memo é rebaixado a negativo com o motivo dito — nunca promovido a positivo, que
+ * exigiria a sondagem cara de volta.
+ */
+export declare function detectBwrapMemoizado(probes?: BwrapProbes): BwrapDetection;
+/** Seam de TESTE — limpa o memo. Produção nunca chama (ver m71-custo-por-turn#ADR-1). */
+export declare function resetBwrapMemo(): void;

package/dist/sandbox/bwrap.d.ts

@@ -0,0 +1,75 @@
+/**
+ * M53 — bubblewrap argv + honest detection, faithful to Codex's Linux sandbox
+ * (`codex-rs/linux-sandbox/src/bwrap.rs` + `codex-rs/sandboxing/src/bwrap.rs`).
+ *
+ * HONEST SCOPE: filesystem confinement + network isolation via bwrap, PLUS the second stage —
+ * a cBPF seccomp syscall filter (`agents/sandbox/seccomp.ts`), wired in `agents/sandbox/backend.ts`
+ * via `restrictedSeccompPath()`. Portado no M63; este bloco afirmava o contrário até o M67 e
+ * SUBDECLARAVA a postura de segurança real. Limite honesto que permanece: o filtro é **x86_64**
+ * (guarda de arquitetura recusa instalar em outra arch, com WARN, e o confinamento de FS/rede do
+ * bwrap segue valendo) **e** só é instalado quando a rede está restrita (`backend.ts:87`, fiel a
+ * `landlock.rs:96-117`): com rede ligada não há filtro de syscall, apenas o confinamento de FS do
+ * bwrap. `danger-full-access` pula o bwrap por completo, espelhando `bwrap.rs:245-252`.
+ * Deltas versus o Codex seguem documentados em docs/CODEX-PARITY.md.
+ */
+/**
+ * Os tres modos canonicos do Codex. Definidos AQUI porque sao vocabulario do sandbox, nao da
+ * configuracao do consumidor: `danger-full-access` significa "nao embrulhe", e essa e uma decisao do
+ * subsistema de confinamento.
+ */
+export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";
+export interface BwrapArgvOptions {
+    /** Workspace root — the single RW bind under `workspace-write` (protocol.rs:1189-1200). */
+    cwd: string;
+    /** `true` removes `--unshare-net` (policy `network_access`, default false). */
+    network?: boolean;
+    /** Injectable for tests; defaults to a real `existsSync` check on `<cwd>/.git`. */
+    gitDirExists?: boolean;
+    /**
+     * When present, emit `--clearenv` and re-inject ONLY these vars (Codex env_clear model,
+     * `exec_env.rs:25-31`). Closes the denylist gap: a secret in an oddly-named var never reaches the
+     * sandboxed child. Omitted ⇒ inherit the parent env (backward-compatible; SDK scrub still applies).
+     */
+    env?: Record<string, string>;
+}
+/**
+ * Pure argv builder. Returns the bwrap flags ending in `--` (caller appends `/bin/sh -c <cmd>`),
+ * or `null` when the policy skips the sandbox entirely (`danger-full-access`).
+ */
+export declare function buildBwrapArgv(mode: SandboxMode, opts: BwrapArgvOptions): string[] | null;
+/** Injectable probes — each mirrors one Codex availability check. */
+export interface BwrapProbes {
+    /** `which bwrap` outside the cwd (anti-hijack, sandboxing/src/bwrap.rs:168-191). */
+    which: () => string | null;
+    /** `bwrap --help` text — must advertise `--perms` (launcher.rs:108-124). */
+    helpText: (bin: string) => string | null;
+    /** Active user-namespace probe with timeout (sandboxing/src/bwrap.rs:74-136). */
+    userns: (bin: string) => boolean;
+}
+export type BwrapDetection = {
+    ok: true;
+    bin: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/** Honest detection — fail-closed on every probe; NEVER throws (callers WARN + fall back). */
+export declare function detectBwrap(probes?: BwrapProbes): BwrapDetection;
+/** Quantas sondagens reais rodaram. Seam de TESTE — o gate de performance conta isto. */
+export declare function realProbeCount(): number;
+/** Real probes used in production. */
+export declare const realProbes: BwrapProbes;
+/**
+ * `detectBwrap` com memoização — o que a produção deve chamar.
+ *
+ * Note que `detectBwrap` em si **não** memoiza, de propósito: ele aceita probes injetados, e memoizar
+ * ali faria um teste com probes falsos envenenar o cache do processo para todos os outros.
+ *
+ * A revalidação do positivo NÃO é uma re-sondagem: `detectBwrap` gasta três probes (subprocesso
+ * `which` + `--help` + namespace de usuário). Aqui só se confirma que o binário validado continua no
+ * lugar. Se sumiu, o memo é rebaixado a negativo com o motivo dito — nunca promovido a positivo, que
+ * exigiria a sondagem cara de volta.
+ */
+export declare function detectBwrapMemoizado(probes?: BwrapProbes): BwrapDetection;
+/** Seam de TESTE — limpa o memo. Produção nunca chama (ver m71-custo-por-turn#ADR-1). */
+export declare function resetBwrapMemo(): void;