wotann 0.5.0 → 0.5.39

package/dist/security/shell-escalation-tiers.js

@@ -0,0 +1,439 @@
+/**
+ * shell-escalation-tiers — Codex-style escalating shell permission tiers.
+ *
+ * Port of the `shell-escalation` pattern from openai/codex
+ * (codex-rs/shell-escalation). Defines 4 tiers of shell-command
+ * permissions, each with explicit escalation policy:
+ *
+ *   - tier 0 (read-only): file reads, ls, cat, grep, git log
+ *   - tier 1 (dev): npm install, edit files in workspace, git commit
+ *   - tier 2 (system): apt/brew install, system services, sudo
+ *   - tier 3 (dangerous): rm -rf, dd, force-push, drop-database
+ *
+ * Each command is classified by the leading binary + arg shape.
+ * Higher tiers require the user (or policy) to explicitly authorize
+ * up to that tier.
+ *
+ * This is the POLICY LAYER. The actual blocking happens in
+ * src/security/command-sanitizer.ts (already shipped) + sandbox
+ * backends. This module computes the required tier from a command
+ * and reports back so callers can decide.
+ *
+ * Composes with bash-arity-policy (which checks per-command arg
+ * counts) — escalation tier covers WHAT the command does, arity
+ * covers HOW THE COMMAND IS BEING CALLED.
+ *
+ * Quality bars:
+ *   - QB#1 immutable: tier rules + verdicts readonly + frozen
+ *   - QB#3 honest: tagged result; never throws
+ *   - QB#7 stateless: pure function
+ *   - QB#11 sibling-site: composes with command-sanitizer + bash-arity
+ *   - QB#19 zombie-free: every export has runtime callers via tests
+ *
+ * Source: github.com/openai/codex/tree/main/codex-rs/shell-escalation
+ */
+export const TIER_NAMES = Object.freeze({
+    0: "read-only",
+    1: "dev",
+    2: "system",
+    3: "dangerous",
+});
+// ── Tier rules ───────────────────────────────────────────────────────
+/** Commands that NEVER mutate state (tier 0). */
+const TIER_0_BINARIES = new Set([
+    "ls",
+    "cat",
+    "head",
+    "tail",
+    "wc",
+    "grep",
+    "egrep",
+    "fgrep",
+    "find",
+    "tree",
+    "file",
+    "stat",
+    "du",
+    "df",
+    "pwd",
+    "echo",
+    "printf",
+    "which",
+    "type",
+    "whereis",
+    "uname",
+    "hostname",
+    "date",
+    "uptime",
+    "ps",
+    "top",
+    "env",
+    "history",
+    "tty",
+    "id",
+    "whoami",
+    "groups",
+    "diff",
+    "comm",
+    "sort",
+    "uniq",
+    "cut",
+    "tr",
+    "rev",
+    "less",
+    "more",
+    "sed", // n.b. sed is read-only WHEN no -i flag; we re-classify -i as tier 1
+    "awk",
+    "jq",
+    "yq",
+    "xmllint",
+    "tac",
+    "od",
+    "hexdump",
+]);
+/** Read-only git operations. */
+const GIT_TIER_0 = new Set([
+    "log",
+    "diff",
+    "status",
+    "branch",
+    "tag",
+    "show",
+    "blame",
+    "reflog",
+    "stash",
+    "config",
+    "remote",
+    "ls-files",
+    "ls-tree",
+    "rev-parse",
+    "rev-list",
+]);
+/** Dev workflow commands (tier 1). */
+const TIER_1_BINARIES = new Set([
+    "npm",
+    "yarn",
+    "pnpm",
+    "bun",
+    "node",
+    "tsx",
+    "deno",
+    "tsc",
+    "vitest",
+    "jest",
+    "mocha",
+    "eslint",
+    "prettier",
+    "biome",
+    "python",
+    "python3",
+    "pip",
+    "pip3",
+    "uv",
+    "poetry",
+    "pipx",
+    "ruff",
+    "mypy",
+    "go",
+    "cargo",
+    "rustc",
+    "rustup",
+    "java",
+    "mvn",
+    "gradle",
+    "make",
+    "ninja",
+    "cmake",
+    "ruby",
+    "gem",
+    "bundle",
+    "rake",
+    "bash",
+    "sh",
+    "zsh",
+    "fish",
+    "mkdir",
+    "touch",
+    "cp",
+    "mv",
+    "ln",
+    "rmdir",
+    "tar",
+    "zip",
+    "unzip",
+    "gzip",
+    "gunzip",
+    "curl",
+    "wget",
+    "http",
+    "httpie",
+    "ssh",
+    "scp",
+    "rsync",
+    "git", // most git ops; tier elevated below
+    "code",
+    "cursor",
+    "subl",
+]);
+/** System-level commands (tier 2). */
+const TIER_2_BINARIES = new Set([
+    "sudo",
+    "su",
+    "doas",
+    "apt",
+    "apt-get",
+    "brew",
+    "dnf",
+    "yum",
+    "pacman",
+    "snap",
+    "systemctl",
+    "service",
+    "launchctl",
+    "killall",
+    "pkill",
+    "iptables",
+    "ufw",
+    "firewall-cmd",
+    "ifconfig",
+    "ip",
+    "route",
+    "netstat",
+    "ss",
+    "mount",
+    "umount",
+    "fdisk",
+    "diskutil",
+    "fsck",
+    "useradd",
+    "usermod",
+    "userdel",
+    "groupadd",
+    "passwd",
+    "chsh",
+    "chpasswd",
+    "chmod",
+    "chown",
+    "chgrp",
+    "setfacl",
+    "getfacl",
+    "docker",
+    "podman",
+    "kubectl",
+    "k9s",
+    "helm",
+]);
+/** Dangerous commands (tier 3). */
+const TIER_3_BINARIES = new Set([
+    "rm",
+    "shred",
+    "dd",
+    "mkfs",
+    "fdisk",
+    "format",
+    "wipefs",
+    "shutdown",
+    "halt",
+    "reboot",
+    "poweroff",
+]);
+const DANGEROUS_GIT_VERBS = new Set([
+    "push", // not always tier-3, but force-push is — checked via flag scan
+    "reset",
+    "rebase",
+    "filter-branch",
+    "filter-repo",
+    "clean", // -fd is tier-3
+    "checkout", // can lose work
+    "switch", // can lose work
+    "restore",
+    "merge", // can fast-forward dangerously
+]);
+// ── Helpers ──────────────────────────────────────────────────────────
+function stripWrappers(tokens) {
+    const wrappers = new Set(["sudo", "doas", "nice", "ionice"]);
+    let i = 0;
+    while (i < tokens.length) {
+        const t = tokens[i];
+        if (t === undefined)
+            break;
+        if (wrappers.has(t)) {
+            i += 1;
+            continue;
+        }
+        if (t === "env") {
+            i += 1;
+            while (i < tokens.length && /^[A-Z_][A-Z0-9_]*=/i.test(tokens[i] ?? "")) {
+                i += 1;
+            }
+            continue;
+        }
+        break;
+    }
+    return tokens.slice(i);
+}
+function classifyGit(args) {
+    const verb = args[0];
+    if (!verb)
+        return 1;
+    if (GIT_TIER_0.has(verb))
+        return 0;
+    if (DANGEROUS_GIT_VERBS.has(verb)) {
+        // git push --force / -f → tier-3
+        if (verb === "push" &&
+            args.some((a) => a === "--force" || a === "-f" || a.startsWith("--force-"))) {
+            return 3;
+        }
+        if (verb === "reset" && args.some((a) => a === "--hard"))
+            return 3;
+        if (verb === "clean" && args.some((a) => /^-[fdx]+$/.test(a)))
+            return 3;
+        if (verb === "filter-branch" || verb === "filter-repo")
+            return 3;
+        return 2;
+    }
+    return 1;
+}
+function classifyChmodChown(binary, args) {
+    // chmod 777 / chown root → tier-3
+    if (binary === "chmod" && args.some((a) => a === "777" || a === "+s" || a.includes("u+s")))
+        return 3;
+    if (binary === "chown" && args.some((a) => a === "root" || a.startsWith("root:")))
+        return 3;
+    return 2;
+}
+function classifyBinary(binary, args) {
+    if (TIER_3_BINARIES.has(binary)) {
+        return Object.freeze({
+            tier: 3,
+            tierName: TIER_NAMES[3],
+            command: binary,
+            reason: `${binary} is in the dangerous-binary set`,
+        });
+    }
+    if (binary === "chmod" || binary === "chown" || binary === "chgrp") {
+        const tier = classifyChmodChown(binary, args);
+        return Object.freeze({
+            tier,
+            tierName: TIER_NAMES[tier],
+            command: binary,
+            reason: tier === 3
+                ? `${binary} with system-level args (777 / root / +s)`
+                : `${binary} is a system-level permission change`,
+        });
+    }
+    if (binary === "git") {
+        const tier = classifyGit(args);
+        return Object.freeze({
+            tier,
+            tierName: TIER_NAMES[tier],
+            command: binary,
+            reason: tier === 0
+                ? `git ${args[0] ?? ""} is read-only`
+                : tier === 3
+                    ? `git ${args[0] ?? ""} with destructive flags`
+                    : `git ${args[0] ?? ""} mutates state`,
+        });
+    }
+    if (TIER_2_BINARIES.has(binary)) {
+        return Object.freeze({
+            tier: 2,
+            tierName: TIER_NAMES[2],
+            command: binary,
+            reason: `${binary} is system-level`,
+        });
+    }
+    // sed -i mutates in place → tier 1 not 0
+    if (binary === "sed" && args.some((a) => a === "-i" || a.startsWith("-i"))) {
+        return Object.freeze({
+            tier: 1,
+            tierName: TIER_NAMES[1],
+            command: binary,
+            reason: `sed -i edits in place`,
+        });
+    }
+    if (TIER_1_BINARIES.has(binary)) {
+        return Object.freeze({
+            tier: 1,
+            tierName: TIER_NAMES[1],
+            command: binary,
+            reason: `${binary} is a dev workflow command`,
+        });
+    }
+    if (TIER_0_BINARIES.has(binary)) {
+        return Object.freeze({
+            tier: 0,
+            tierName: TIER_NAMES[0],
+            command: binary,
+            reason: `${binary} is read-only`,
+        });
+    }
+    // Unknown binary — be conservative: tier 1 (dev) by default
+    return Object.freeze({
+        tier: 1,
+        tierName: TIER_NAMES[1],
+        command: binary,
+        reason: `${binary} is unrecognized; defaulting to dev tier`,
+    });
+}
+// ── Public API ───────────────────────────────────────────────────────
+/**
+ * Classify a tokenized command into a ShellTier. Pure: same input
+ * always produces same output.
+ */
+export function classifyCommand(tokens) {
+    if (tokens.length === 0) {
+        return Object.freeze({
+            tier: 0,
+            tierName: TIER_NAMES[0],
+            command: "",
+            reason: "empty command",
+        });
+    }
+    const stripped = stripWrappers(tokens);
+    const binary = stripped[0];
+    if (!binary) {
+        return Object.freeze({
+            tier: 2,
+            tierName: TIER_NAMES[2],
+            command: "",
+            reason: "wrapper-only command (e.g. bare sudo) — system tier",
+        });
+    }
+    return classifyBinary(binary, stripped.slice(1));
+}
+export function classifyCommandLine(commandLine) {
+    const tokens = commandLine
+        .trim()
+        .split(/\s+/)
+        .filter((s) => s.length > 0);
+    return classifyCommand(tokens);
+}
+/**
+ * Decide whether a classified command may execute given the user's
+ * authorized tier.
+ */
+export function decideEscalation(classification, authorizedTier) {
+    if (classification.tier <= authorizedTier) {
+        return Object.freeze({
+            action: "allow",
+            required: classification.tier,
+            authorized: authorizedTier,
+        });
+    }
+    return Object.freeze({
+        action: "escalate-required",
+        required: classification.tier,
+        authorized: authorizedTier,
+        missing: (classification.tier - authorizedTier),
+        reason: `command requires tier ${classification.tier} (${classification.tierName}); ` +
+            `current authorization is tier ${authorizedTier} (${TIER_NAMES[authorizedTier]})`,
+    });
+}
+/** Convenience: classify + decide in one call. */
+export function checkCommand(commandLine, authorizedTier) {
+    const classification = classifyCommandLine(commandLine);
+    const decision = decideEscalation(classification, authorizedTier);
+    return Object.freeze({ classification, decision });
+}
+//# sourceMappingURL=shell-escalation-tiers.js.map

package/dist/security/shell-escalation-tiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-escalation-tiers.js","sourceRoot":"","sources":["../../src/security/shell-escalation-tiers.ts"],"names":[],"mappings":"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"}

package/dist/session/fork.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Session fork primitive — branch a SQLite-backed session at its last
+ * checkpoint to enable parallel-approach exploration ("try CQRS vs
+ * event-sourcing", "what if we rolled this back and tried a different
+ * tool order"). Ported from the opencode/cline session-fork pattern.
+ *
+ * WHAT: Given a source session id and a `wotannDir`, this module opens
+ *   `<wotannDir>/sessions.db`, materialises the schema if it's missing,
+ *   and atomically copies the source session row + its message thread
+ *   (up to and including its `last_checkpoint`) into a freshly minted
+ *   session id. The new session inherits the source's `last_checkpoint`
+ *   pointer so a follow-on resume/restore command sees the same head.
+ *
+ * WHY: WOTANN already has two checkpoint flavours — `storage/
+ *   checkpoint-supersede.ts` (pure-data rollback algorithm) and
+ *   `autopilot/checkpoint.ts` (JSON file dumps for long-running autopilot
+ *   loops). Neither offers a first-class "branch from here" primitive
+ *   for SQL-backed sessions. The opencode + cline ports both expose this
+ *   as a single transactional copy; we follow that shape so the future
+ *   CLI subcommand has a clean call site.
+ *
+ * WHERE: Imported by the CLI surface that the parent agent will wire up
+ *   sequentially. The DB file path is derived from `req.wotannDir` so
+ *   callers can sandbox it per test or per workspace without changing
+ *   the module's interface.
+ *
+ * HOW:
+ *   1. Lazy-construct (or open) `<wotannDir>/sessions.db` via
+ *      `better-sqlite3`. The schema (`sessions`, `messages`) is created
+ *      with `CREATE TABLE IF NOT EXISTS`, so multiple callers sharing
+ *      the same DB never collide.
+ *   2. Look up the source session row. Honest error envelope on miss:
+ *      `{ok:false, error:"session not found"}`.
+ *   3. Read the source's `last_checkpoint` pointer. If absent or empty,
+ *      `{ok:false, error:"no checkpoint to fork from"}`.
+ *   4. Generate a new session id with `crypto.randomUUID()`.
+ *   5. Inside `db.transaction(...)`, INSERT the new sessions row and
+ *      COPY every message in the source thread whose `seq` is at or
+ *      below the message that backs the checkpoint pointer. better-
+ *      sqlite3 transactions roll back atomically on any thrown error,
+ *      so a partial INSERT can never leave the database half-forked.
+ *   6. Return `{ok:true, newSessionId, sourceCheckpoint, messageCount}`.
+ *
+ * Schema (self-contained — no other module currently owns these tables):
+ *   sessions(id PK, label, last_checkpoint, created_at, source_session)
+ *   messages(session_id, seq, role, content, checkpoint_id,
+ *            PRIMARY KEY (session_id, seq))
+ *
+ *   The `messages.checkpoint_id` column records WHICH checkpoint each
+ *   message was the head for — required so a fork can compute "all
+ *   messages up to the checkpoint" without an external join table. A
+ *   row with `checkpoint_id = NULL` is a regular message; a row with
+ *   `checkpoint_id` non-null is the message that minted that checkpoint.
+ *
+ *   `sessions.last_checkpoint` is the pointer field the task calls out —
+ *   it stores the checkpoint id (a string) so we can locate the cut
+ *   point during fork.
+ *
+ * Honest-stub policy: every failure path returns a typed `ForkResult`
+ * with `ok:false` and a human-readable `error` string. The function
+ * never throws to the caller. Callers can branch on `result.ok` and
+ * surface the `error` in the CLI without try/catch noise.
+ */
+export interface ForkRequest {
+    /** Source session id whose thread we will branch from. */
+    readonly sourceSessionId: string;
+    /**
+     * Optional user-facing label for the new session. If supplied, the
+     * label is stored on the new row exactly as given (caller-owned
+     * formatting); the source's label is NOT inherited automatically so
+     * the user can name the branch after the experiment they're running.
+     */
+    readonly label?: string;
+    /**
+     * Root WOTANN data directory. The session database lives at
+     * `<wotannDir>/sessions.db`. The directory is created if missing so
+     * tests / first-run users don't need to pre-stage it.
+     */
+    readonly wotannDir: string;
+}
+export interface ForkResult {
+    readonly ok: boolean;
+    readonly newSessionId?: string;
+    readonly sourceCheckpoint?: string;
+    readonly error?: string;
+    readonly messageCount?: number;
+}
+/**
+ * Fork a session at its last checkpoint. See module docstring for the
+ * full contract. Never throws — every failure mode is a structured
+ * `ForkResult` with `ok:false` and a `error` string.
+ *
+ * Returns `Promise<ForkResult>` because the task contract specifies an
+ * async signature; the implementation is synchronous under the hood
+ * (better-sqlite3 is sync) but we honour the public shape for
+ * forward-compatibility with the node-sqlite3 / sql.js backends that
+ * `selectStorageAdapter()` may eventually route to.
+ */
+export declare function forkSession(req: ForkRequest): Promise<ForkResult>;
+//# sourceMappingURL=fork.d.ts.map

package/dist/session/fork.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/session/fork.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AASH,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AA0ED;;;;;;;;;;GAUG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAiHvE"}