@oscharko-dev/keiko 0.1.0-beta.0

package/dist/tools/sandbox.js

@@ -0,0 +1,121 @@
+// PURE sandbox logic: the trust boundary's decision functions. No filesystem, no spawn, no
+// node:child_process imports — every effect lives in exec.ts/writer.ts. These functions are
+// individually unit-testable so the security invariants (env isolation, deny-by-default) are
+// pinned down. Only node:path (a pure string utility) is imported here.
+import { basename } from "node:path";
+// Builds the child env by copying ONLY allowlisted names that are present in the parent.
+// NEVER spreads `...processEnv`, so no credential-bearing variable can leak into the child.
+export function buildSandboxEnv(processEnv, allowlist) {
+    const env = {};
+    for (const name of allowlist) {
+        const value = processEnv[name];
+        if (value !== undefined) {
+            env[name] = value;
+        }
+    }
+    return env;
+}
+// Collects the values of every parent env var that is NOT on the allowlist, so the command's
+// captured stdout/stderr can be scrubbed of any secret a child still managed to print (e.g. a
+// tool that reads a token from its own config and echoes it). Empty/short values are skipped to
+// avoid over-redaction. The allowlisted, non-secret values (PATH, HOME, …) are deliberately kept.
+export function collectSensitiveEnvValues(processEnv, allowlist) {
+    const allowed = new Set(allowlist);
+    const values = [];
+    for (const [name, value] of Object.entries(processEnv)) {
+        if (allowed.has(name)) {
+            continue;
+        }
+        if (value !== undefined && value.length >= 6) {
+            values.push(value);
+        }
+    }
+    return values;
+}
+function hasPathSeparator(value) {
+    return value.includes("/") || value.includes("\\");
+}
+function hasNul(value) {
+    return value.includes("\u0000");
+}
+// Resolves the subcommand: the first non-flag token, skipping leading flags AND the value of any
+// value-taking flag (`--prefix DIR`, `-C DIR`). This is the S-H2 fix — a value can no longer
+// masquerade as the subcommand. `--flag=value` carries its value inline, so only the flag token is
+// consumed. Returns undefined when no subcommand token is present.
+function resolveSubcommand(rule, args) {
+    const valueFlags = new Set(rule.valueFlags ?? []);
+    let skipNext = false;
+    for (const arg of args) {
+        if (skipNext) {
+            skipNext = false; // this token is the value of the preceding value-flag; skip it
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            return arg;
+        }
+        // A `-f=value` / `--flag=value` token carries its own value; consume just this token.
+        if (!arg.includes("=") && valueFlags.has(arg)) {
+            skipNext = true; // the following token is this flag's value
+        }
+    }
+    return undefined;
+}
+// Denies the whole invocation if any denied flag (e.g. npm/npx `-c`/`--call`) appears anywhere in
+// args, in either `--call x` or `--call=x` form. These execute a transitive shell (S-H2).
+function hasDeniedFlag(rule, args) {
+    const denied = rule.denyFlags;
+    if (denied === undefined) {
+        return false;
+    }
+    return args.some((arg) => {
+        const flag = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+        return denied.includes(flag);
+    });
+}
+function checkAllowlistMode(rule, allowed, sub) {
+    if (sub === undefined || !allowed.includes(sub)) {
+        return { allowed: false, reason: `subcommand not allowed: ${rule.executable} ${sub ?? ""}` };
+    }
+    return { allowed: true };
+}
+function checkDenylistMode(rule, sub) {
+    // Deny-by-default on the subcommand: when a known-subcommand set is declared, an unrecognized
+    // first non-flag token (e.g. a stray path from a value-flag bypass) is denied.
+    if (rule.knownSubcommands !== undefined &&
+        (sub === undefined || !rule.knownSubcommands.includes(sub))) {
+        return { allowed: false, reason: `unrecognized subcommand: ${rule.executable} ${sub ?? ""}` };
+    }
+    if (rule.deniedSubcommands !== undefined &&
+        sub !== undefined &&
+        rule.deniedSubcommands.includes(sub)) {
+        return { allowed: false, reason: `subcommand denied: ${rule.executable} ${sub}` };
+    }
+    return { allowed: true };
+}
+function checkSubcommand(rule, args) {
+    if (hasDeniedFlag(rule, args)) {
+        return { allowed: false, reason: `denied flag for ${rule.executable}` };
+    }
+    const sub = resolveSubcommand(rule, args);
+    if (rule.allowedSubcommands !== undefined) {
+        return checkAllowlistMode(rule, rule.allowedSubcommands, sub);
+    }
+    return checkDenylistMode(rule, sub);
+}
+// PURE deny-by-default decision. The executable must be a BARE name (no path separators, no
+// NUL): we match by basename against the rules and reject anything unlisted. This is evaluated
+// BEFORE any spawn, so a denied command never reaches child_process.
+export function isCommandAllowed(rules, executable, args) {
+    if (executable.length === 0 || hasNul(executable)) {
+        return { allowed: false, reason: "empty or NUL-containing executable" };
+    }
+    if (hasPathSeparator(executable)) {
+        return { allowed: false, reason: "executable must be a bare PATH-resolved name" };
+    }
+    const name = basename(executable);
+    const rule = rules.find((candidate) => candidate.executable === name);
+    if (rule === undefined) {
+        return { allowed: false, reason: `executable not allowlisted: ${name}` };
+    }
+    return checkSubcommand(rule, args);
+}

package/dist/tools/schemas.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from "../gateway/types.js";
+export declare const TOOL_DEFINITIONS: readonly ToolDefinition[];

package/dist/tools/schemas.js

@@ -0,0 +1,51 @@
+// The model-facing tool contract: 6 ToolDefinitions with JSON-Schema `parameters`. Kept apart
+// from registry.ts so the dispatch logic stays small and the schema table is a single frozen
+// surface the gateway/model see. No runtime logic — just the frozen definitions.
+function obj(properties, required) {
+    return { type: "object", properties, required, additionalProperties: false };
+}
+export const TOOL_DEFINITIONS = Object.freeze([
+    {
+        name: "read_file",
+        description: "Read a UTF-8 file inside the workspace. Output is redacted; files above the byte cap are rejected.",
+        parameters: obj({
+            path: { type: "string", description: "Workspace-relative file path." },
+            maxBytes: { type: "number", description: "Optional read cap in bytes." },
+        }, ["path"]),
+    },
+    {
+        name: "list_files",
+        description: "List workspace files (deny-list and optional .gitignore applied).",
+        parameters: obj({
+            maxDepth: { type: "number", description: "Optional recursion depth cap." },
+            maxFiles: { type: "number", description: "Optional result count cap." },
+            applyGitignore: { type: "boolean", description: "Apply the .gitignore subset." },
+        }, []),
+    },
+    {
+        name: "inspect_package_scripts",
+        description: "Return the `scripts` object from a package.json inside the workspace.",
+        parameters: obj({ path: { type: "string", description: "Optional path; defaults to package.json." } }, []),
+    },
+    {
+        name: "run_command",
+        description: "Run an allowlisted read-only command (npm/git by default) with no shell, a clean env, " +
+            "a trusted executable path, a workspace cwd, a timeout, and capped redacted output.",
+        parameters: obj({
+            command: { type: "string", description: "Bare executable name (PATH-resolved)." },
+            args: { type: "array", items: { type: "string" }, description: "Argument vector." },
+            cwd: { type: "string", description: "Optional workspace-relative working directory." },
+            timeoutMs: { type: "number", description: "Optional wall-time budget in ms." },
+        }, ["command"]),
+    },
+    {
+        name: "propose_patch",
+        description: "Validate a unified diff and return a dry-run preview. Never writes to disk.",
+        parameters: obj({ diff: { type: "string", description: "Unified diff text." } }, ["diff"]),
+    },
+    {
+        name: "apply_patch",
+        description: "Apply a validated unified diff atomically. Fail-closed: refuses unless apply is enabled.",
+        parameters: obj({ diff: { type: "string", description: "Unified diff text." } }, ["diff"]),
+    },
+]);

package/dist/tools/terminal-policy.d.ts

@@ -0,0 +1,9 @@
+import type { CommandRule } from "./types.js";
+declare const FROZEN_NONE: readonly string[];
+export declare const TERMINAL_COMMAND_RULES: readonly CommandRule[];
+export interface TerminalCommandDecision {
+    readonly allowed: boolean;
+    readonly reason?: string | undefined;
+}
+export declare function isTerminalCommandAllowed(command: string, args: readonly string[]): TerminalCommandDecision;
+export { FROZEN_NONE as TERMINAL_NO_FLAGS };

package/dist/tools/terminal-policy.js

@@ -0,0 +1,313 @@
+// ADR-0018 D3 — permitted-command policy for the UI terminal tool. A separate, narrower allowlist
+// than the harness DEFAULT_COMMAND_RULES so the human-facing terminal cannot widen the agent surface.
+// The CommandRule schema (allowedSubcommands / denyFlags / valueFlags) handles the structural
+// shape; `isTerminalCommandAllowed` adds a thin Layer-2 pass for flag policies that `CommandRule`
+// cannot express (node's positional-arg ban, git branch/remote mutation).
+// Pure module: no IO, no spawn, no fs.
+import { isCommandAllowed } from "./sandbox.js";
+const FROZEN_NONE = Object.freeze([]);
+// Read-only inspection commands. Each rule is conservative: omitted subcommands are denied by the
+// allowlist mode; the only flag policy expressed here is what CommandRule already supports.
+export const TERMINAL_COMMAND_RULES = Object.freeze([
+    { executable: "ls" },
+    { executable: "cat" },
+    { executable: "head" },
+    { executable: "tail" },
+    { executable: "wc", denyFlags: Object.freeze(["--files0-from"]) },
+    { executable: "grep" },
+    { executable: "pwd" },
+    { executable: "echo" },
+    {
+        executable: "find",
+        denyFlags: Object.freeze([
+            "-exec",
+            "-execdir",
+            "-ok",
+            "-okdir",
+            "-delete",
+            "-fprint",
+            "-fprint0",
+            "-fprintf",
+            "-fls",
+            "-files0-from",
+        ]),
+    },
+    {
+        executable: "tree",
+        denyFlags: Object.freeze(["-o", "--output"]),
+    },
+    // node: only --version/-v allowed. Enforced positionally in Layer 2 (a per-arg policy is not
+    // expressible in CommandRule).
+    { executable: "node" },
+    {
+        executable: "npm",
+        allowedSubcommands: Object.freeze(["ls", "list", "help"]),
+        denyFlags: Object.freeze([
+            "-c",
+            "--call",
+            "--prefix",
+            "--global",
+            "-g",
+            "--location",
+        ]),
+    },
+    {
+        executable: "git",
+        allowedSubcommands: Object.freeze([
+            "status",
+            "diff",
+            "log",
+            "show",
+            "rev-parse",
+            "ls-files",
+            "describe",
+            "blame",
+            "cat-file",
+            "branch",
+            "remote",
+        ]),
+        valueFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+        ]),
+        denyFlags: Object.freeze([
+            "-C",
+            "-c",
+            "--git-dir",
+            "--work-tree",
+            "--namespace",
+            "--exec-path",
+            "--ext-diff",
+            "--textconv",
+            "--output",
+            "--no-index",
+            "--contents",
+        ]),
+    },
+]);
+// Flags that delete, write, or execute via find. Any of these anywhere in args denies.
+const FIND_DENY_FLAGS = new Set([
+    "-exec",
+    "-execdir",
+    "-ok",
+    "-okdir",
+    "-delete",
+    "-fprint",
+    "-fprint0",
+    "-fprintf",
+    "-fls",
+    "-files0-from",
+]);
+const TREE_DENY_FLAGS = new Set(["-o", "--output"]);
+// Only --version and -v are accepted for node. Every other positional or flag is denied.
+const NODE_ALLOWED_ARGS = new Set(["--version", "-v"]);
+// Branch mutation flags (A2). Scoped to `git branch` only — these deny branch creation, deletion,
+// copy, rename, and force operations. `-c`/`-C` are included here because for `branch` they mean
+// copy, not the git-global config flag (which is caught by A5 before we reach here).
+const GIT_BRANCH_DENY_FLAGS = new Set([
+    "-D",
+    "-d",
+    "-m",
+    "-M",
+    "--delete",
+    "-c",
+    "-C",
+    "-f",
+    "--copy",
+    "--force",
+    "--set-upstream-to",
+    "--unset-upstream",
+    "--edit-description",
+]);
+// Global git flags that modify git's own config, working-tree, cwd, or execution path (A5 /
+// ADR-0018 S-H2). These are checked BEFORE subcommand resolution so they cannot be smuggled via a
+// value-flag value that happens to look like a subcommand.
+const GIT_GLOBAL_DENY_FLAGS = new Set([
+    "-C",
+    "-c",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--exec-path",
+]);
+const GIT_UNSAFE_FLAGS = new Set([
+    "--ext-diff",
+    "--textconv",
+    "--output",
+    "--no-index",
+    "--contents",
+]);
+function denied(reason) {
+    return { allowed: false, reason };
+}
+function checkFind(args) {
+    for (const arg of args) {
+        if (FIND_DENY_FLAGS.has(arg)) {
+            return denied(`find: denied flag ${arg}`);
+        }
+    }
+    return { allowed: true };
+}
+function checkTree(args) {
+    for (const arg of args) {
+        const flag = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+        if (TREE_DENY_FLAGS.has(flag) || arg.startsWith("-o")) {
+            return denied(`tree: denied write flag ${flag}`);
+        }
+    }
+    return { allowed: true };
+}
+function checkNode(args) {
+    for (const arg of args) {
+        if (!NODE_ALLOWED_ARGS.has(arg)) {
+            return denied("node: only --version/-v is permitted");
+        }
+    }
+    return { allowed: true };
+}
+// Shared value-flags used by gitSubcommand and argsAfterSubcommand. Kept as a module-level
+// constant (not re-created per call) so the hot-path doesn't allocate on every invocation.
+const GIT_VALUE_FLAGS = new Set([
+    "-C",
+    "-c",
+    "--git-dir",
+    "--work-tree",
+    "--namespace",
+    "--exec-path",
+]);
+// Resolves the git subcommand (first non-flag arg, skipping value-flag pairs). Returns undefined
+// when the subcommand can't be determined — the caller treats that as not-a-mutation.
+function gitSubcommand(args) {
+    let skipNext = false;
+    for (const arg of args) {
+        if (skipNext) {
+            skipNext = false;
+            continue;
+        }
+        if (!arg.startsWith("-")) {
+            return arg;
+        }
+        if (!arg.includes("=") && GIT_VALUE_FLAGS.has(arg)) {
+            skipNext = true;
+        }
+    }
+    return undefined;
+}
+// Returns the slice of args that appears AFTER the first token equal to `subcommand`, skipping
+// value-flag pairs using the same walk as gitSubcommand. Returns undefined when not found.
+function argsAfterSubcommand(args, subcommand) {
+    // Convert to a mutable array for indexed access so we can use a for...of without a C-style loop
+    // (avoids noUncheckedIndexedAccess while remaining tsc-clean under no-non-null-assertion).
+    const arr = Array.from(args);
+    let skipNext = false;
+    for (const [i, arg] of arr.entries()) {
+        if (skipNext) {
+            skipNext = false;
+            continue;
+        }
+        if (arg === subcommand) {
+            return args.slice(i + 1);
+        }
+        if (arg.startsWith("-") && !arg.includes("=") && GIT_VALUE_FLAGS.has(arg)) {
+            skipNext = true;
+        }
+    }
+    return undefined;
+}
+// A2 — After resolving the `branch` subcommand, walk the remaining args. Any non-flag positional
+// (a branch name operand) denies creation/switching. Deny all known mutation flags.
+function checkGitBranch(argsAfterBranch) {
+    for (const arg of argsAfterBranch) {
+        const flag = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+        if (GIT_BRANCH_DENY_FLAGS.has(flag)) {
+            return denied(`git branch: denied mutation flag ${flag}`);
+        }
+        if (!arg.startsWith("-")) {
+            // A bare positional after `branch` is a branch name operand — implies creation or mutation.
+            return denied("git branch: positional operand denied (read-only listing only)");
+        }
+    }
+    return { allowed: true };
+}
+// A1 — After resolving the `remote` subcommand, walk the remaining args. No non-flag positional is
+// allowed: `show`, `update`, and `prune` can contact remotes, while add/rm/rename/set-url mutate
+// config. `git remote` and `git remote -v` remain local read-only inspection.
+function checkGitRemote(argsAfterRemote) {
+    for (const arg of argsAfterRemote) {
+        if (arg.startsWith("-")) {
+            // Pure flag (e.g. -v / --verbose) — already covered by the CommandRule valueFlags/denyFlags
+            // at Layer 1, but we allow flags through here to avoid double-denying them.
+            continue;
+        }
+        return denied(`git remote: subcommand "${arg}" is denied (read-only: use flags only)`);
+    }
+    return { allowed: true };
+}
+function deniedGitFlag(arg) {
+    const flag = arg.includes("=") ? arg.slice(0, arg.indexOf("=")) : arg;
+    // A5 — Deny global config/env-injection and cwd-shifting flags before resolving the subcommand.
+    if (GIT_GLOBAL_DENY_FLAGS.has(flag) ||
+        arg.startsWith("-C") ||
+        (arg.startsWith("-c") && !arg.startsWith("--"))) {
+        return `git: denied global flag ${flag}`;
+    }
+    if (GIT_UNSAFE_FLAGS.has(flag)) {
+        return `git: denied unsafe flag ${flag}`;
+    }
+    return undefined;
+}
+function checkGitFlags(args) {
+    for (const arg of args) {
+        const reason = deniedGitFlag(arg);
+        if (reason !== undefined)
+            return denied(reason);
+    }
+    return { allowed: true };
+}
+function checkGitSubcommand(args) {
+    const sub = gitSubcommand(args);
+    if (sub === "branch") {
+        const rest = argsAfterSubcommand(args, "branch") ?? [];
+        return checkGitBranch(rest);
+    }
+    if (sub === "remote") {
+        const rest = argsAfterSubcommand(args, "remote") ?? [];
+        return checkGitRemote(rest);
+    }
+    return { allowed: true };
+}
+function checkGit(args) {
+    const flags = checkGitFlags(args);
+    if (!flags.allowed)
+        return flags;
+    return checkGitSubcommand(args);
+}
+// Pure deny-by-default decision for a terminal command. Layer 1 is the shared `isCommandAllowed`
+// (validates the executable and applies CommandRule's subcommand allowlist/denyFlags/valueFlags).
+// Layer 2 here adds the per-command flag policies that CommandRule cannot express (find / tree /
+// node / git branch and remote mutation flags).
+export function isTerminalCommandAllowed(command, args) {
+    const layer1 = isCommandAllowed(TERMINAL_COMMAND_RULES, command, args);
+    if (!layer1.allowed) {
+        return { allowed: false, reason: layer1.reason };
+    }
+    if (command === "find") {
+        return checkFind(args);
+    }
+    if (command === "tree") {
+        return checkTree(args);
+    }
+    if (command === "node") {
+        return checkNode(args);
+    }
+    if (command === "git") {
+        return checkGit(args);
+    }
+    return { allowed: true };
+}
+// Re-export so callers don't have to import from sandbox.ts directly.
+export { FROZEN_NONE as TERMINAL_NO_FLAGS };

package/dist/tools/types.d.ts

@@ -0,0 +1,99 @@
+export type NetworkPolicy = "inherit" | "none";
+export interface SandboxPolicy {
+    readonly envAllowlist: readonly string[];
+    readonly network: NetworkPolicy;
+    readonly maxOutputBytes: number;
+    readonly defaultTimeoutMs: number;
+    readonly terminationGraceMs: number;
+}
+export declare const DEFAULT_ENV_ALLOWLIST: readonly string[];
+export declare const DEFAULT_SANDBOX_POLICY: SandboxPolicy;
+export interface CommandRule {
+    readonly executable: string;
+    readonly allowedSubcommands?: readonly string[] | undefined;
+    readonly deniedSubcommands?: readonly string[] | undefined;
+    readonly valueFlags?: readonly string[] | undefined;
+    readonly denyFlags?: readonly string[] | undefined;
+    readonly knownSubcommands?: readonly string[] | undefined;
+}
+export declare const DEFAULT_COMMAND_RULES: readonly CommandRule[];
+export interface CommandRunInput {
+    readonly command: string;
+    readonly args?: readonly string[] | undefined;
+    readonly cwd?: string | undefined;
+    readonly timeoutMs?: number | undefined;
+    readonly signal: AbortSignal;
+}
+export interface CommandResult {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly exitCode: number | null;
+    readonly signal: string | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly durationMs: number;
+    readonly timedOut: boolean;
+    readonly truncated: boolean;
+}
+export type PatchChangeKind = "create" | "modify" | "delete";
+export interface PatchHunk {
+    readonly oldStart: number;
+    readonly oldLines: number;
+    readonly newStart: number;
+    readonly newLines: number;
+    readonly lines: readonly string[];
+}
+export interface PatchFileChange {
+    readonly path: string;
+    readonly kind: PatchChangeKind;
+    readonly hunks: readonly PatchHunk[];
+    readonly addedLines: number;
+    readonly removedLines: number;
+}
+export type PatchRejectionCode = "size-limit" | "binary" | "path-unsafe" | "path-denied" | "line-limit" | "file-limit" | "malformed";
+export interface PatchRejection {
+    readonly code: PatchRejectionCode;
+    readonly message: string;
+    readonly path?: string | undefined;
+}
+export interface PatchConflict {
+    readonly path: string;
+    readonly hunkIndex: number;
+    readonly reason: string;
+}
+export interface PatchValidation {
+    readonly ok: boolean;
+    readonly files: readonly PatchFileChange[];
+    readonly totalChangedLines: number;
+    readonly totalBytes: number;
+    readonly normalizedDiff?: string | undefined;
+    readonly reasons: readonly PatchRejection[];
+    readonly conflicts: readonly PatchConflict[];
+}
+export interface PatchLimits {
+    readonly maxPatchBytes: number;
+    readonly maxChangedLines: number;
+    readonly maxFilesChanged: number;
+}
+export declare const DEFAULT_PATCH_LIMITS: PatchLimits;
+export interface PatchApplyResult {
+    readonly changedFiles: readonly string[];
+    readonly created: readonly string[];
+    readonly deleted: readonly string[];
+}
+export interface ToolHostConfig {
+    readonly sandbox: SandboxPolicy;
+    readonly commandRules: readonly CommandRule[];
+    readonly patchLimits: PatchLimits;
+    readonly applyEnabled: boolean;
+    readonly maxReadBytes: number;
+}
+export declare const DEFAULT_TOOL_HOST_CONFIG: ToolHostConfig;
+export interface ToolHostConfigInput {
+    readonly sandbox?: Partial<SandboxPolicy> | undefined;
+    readonly commandRules?: readonly CommandRule[] | undefined;
+    readonly patchLimits?: Partial<PatchLimits> | undefined;
+    readonly applyEnabled?: boolean | undefined;
+    readonly maxReadBytes?: number | undefined;
+}
+export declare function resolveToolHostConfig(input: ToolHostConfigInput | undefined): ToolHostConfig;