patchwork-os 1.2.0-beta.2.canary.781 → 1.2.0-beta.2.canary.783

package/dist/governance/pluginPolicy.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Plugin policy — may THIS recipe load THAT plugin?
+ *
+ * A recipe's `servers:` list names code that is imported into the bridge
+ * process and handed the tool registry. Before the governed profile,
+ * installing a recipe therefore equalled arbitrary in-process code execution:
+ * nothing between "a YAML file arrived" and "its `index.mjs` ran" asked the
+ * operator anything. Under `governed` (`profile.pluginPolicy === "allowlist"`)
+ * a spec is loaded only when it appears in `config.plugins.allow`, and the
+ * check is made at FOUR points — install, dashboard save, `recipe lint` and
+ * runtime load — because a file on disk may have arrived by any route, so the
+ * runtime never trusts that something upstream validated it.
+ *
+ * Under `compat` every spec is allowed, byte-identical to the previous
+ * behaviour. This module holds no state: every verdict is a pure function of
+ * (spec, profile, allowlist) plus, for integrity, the entrypoint bytes.
+ */
+import type { PatchworkConfig } from "../patchworkConfig.js";
+import type { GovernanceProfile } from "./profile.js";
+export interface AllowEntry {
+    spec: string;
+    version?: string;
+    integrity?: string;
+}
+export interface PluginPolicyInput {
+    profile: Pick<GovernanceProfile, "mode" | "pluginPolicy">;
+    allow: AllowEntry[] | undefined;
+}
+export interface PluginVerdict {
+    spec: string;
+    allowed: boolean;
+    reason: string;
+    entry?: AllowEntry;
+}
+/** The governed posture, for "what WOULD happen" evaluations under compat. */
+export declare const GOVERNED_PLUGIN_POLICY_PROFILE: PluginPolicyInput["profile"];
+export declare const PLUGIN_NOT_ALLOWLISTED = "plugin_not_allowlisted";
+export declare const PLUGIN_INTEGRITY_MISMATCH = "plugin_integrity_mismatch";
+/** Error thrown by the runtime when a spec is refused. `code` is stable. */
+export declare class PluginPolicyError extends Error {
+    readonly code: string;
+    readonly specs: string[];
+    constructor(code: string, message: string, specs: string[]);
+}
+/**
+ * Canonical form of a spec for comparison. Path specs resolve to an absolute
+ * path with the trailing separator dropped, so `./x`, `x/` written as `./x/`
+ * and the absolute form all agree. Package specs are compared verbatim after
+ * trimming — a package name has no equivalent spellings.
+ */
+export declare function normalisePluginSpec(spec: string, cwd?: string): string;
+/**
+ * Pure: (spec, profile, allowlist) → verdict. Exact match on the normalised
+ * spec; no globbing, no prefix matching — a policy that matches loosely is
+ * a policy an attacker can satisfy by naming a sibling directory.
+ */
+export declare function evaluatePluginSpec(spec: string, input: PluginPolicyInput, cwd?: string): PluginVerdict;
+/** Per-spec verdicts for `policy explain` / `doctor`. */
+export declare function explainPluginPolicy(specs: string[], cfg: {
+    profile: PluginPolicyInput["profile"];
+    allow?: AllowEntry[];
+}, cwd?: string): PluginVerdict[];
+/** Convenience: the refused subset, for callers that build one error. */
+export declare function refusedPluginSpecs(specs: string[], input: PluginPolicyInput, cwd?: string): PluginVerdict[];
+/** Build the runtime error for a set of refused verdicts. */
+export declare function pluginNotAllowlistedError(refused: PluginVerdict[]): PluginPolicyError;
+export interface IntegrityResult {
+    ok: boolean;
+    /** "verified" | "skipped" | "mismatch" | "unreadable" | "malformed" */
+    status: "verified" | "skipped" | "mismatch" | "unreadable" | "malformed";
+    reason: string;
+    actual?: string;
+}
+export declare function sha256Integrity(bytes: Buffer): string;
+/**
+ * `sha256-<base64>` over the entrypoint file bytes. Absent integrity is
+ * SKIPPED (and says so) rather than failed: the allowlist entry itself is the
+ * operator's decision, and integrity is an optional tightening of it.
+ */
+export declare function verifyPluginIntegrity(entrypointPath: string, integrity: string | undefined): IntegrityResult;
+/** Extract `servers:` from a parsed recipe object; non-list ⇒ []. */
+export declare function pluginSpecsOf(recipe: unknown): string[];
+/** Extract `servers:` from recipe YAML text; unparseable ⇒ []. */
+export declare function pluginSpecsOfYaml(text: string): string[];
+export declare function policyInputFromConfig(profile: PluginPolicyInput["profile"], cfg: Pick<PatchworkConfig, "plugins"> | undefined): PluginPolicyInput;
+export interface RecipePluginScanRow {
+    /** Recipe file, relative to `recipesDir`. */
+    file: string;
+    /** Recipe `name:` when parseable. */
+    name?: string;
+    verdicts: PluginVerdict[];
+}
+export interface RecipePluginScan {
+    recipesDir: string;
+    /** Recipe files inspected (the denominator). */
+    recipesScanned: number;
+    /** Recipes declaring at least one `servers:` entry. */
+    recipesWithPlugins: number;
+    refusedSpecs: number;
+    rows: RecipePluginScanRow[];
+}
+/**
+ * Every installed recipe's `servers:` specs with their verdicts, for the
+ * doctor governance section. Reports only recipes that declare plugins, but
+ * counts every file read so an empty result is distinguishable from an
+ * unreadable directory.
+ */
+export declare function scanInstalledRecipePlugins(recipesDir: string, cfg: {
+    profile: PluginPolicyInput["profile"];
+    allow?: AllowEntry[];
+}, cwd?: string): RecipePluginScan;

package/dist/governance/pluginPolicy.js

@@ -0,0 +1,247 @@
+/**
+ * Plugin policy — may THIS recipe load THAT plugin?
+ *
+ * A recipe's `servers:` list names code that is imported into the bridge
+ * process and handed the tool registry. Before the governed profile,
+ * installing a recipe therefore equalled arbitrary in-process code execution:
+ * nothing between "a YAML file arrived" and "its `index.mjs` ran" asked the
+ * operator anything. Under `governed` (`profile.pluginPolicy === "allowlist"`)
+ * a spec is loaded only when it appears in `config.plugins.allow`, and the
+ * check is made at FOUR points — install, dashboard save, `recipe lint` and
+ * runtime load — because a file on disk may have arrived by any route, so the
+ * runtime never trusts that something upstream validated it.
+ *
+ * Under `compat` every spec is allowed, byte-identical to the previous
+ * behaviour. This module holds no state: every verdict is a pure function of
+ * (spec, profile, allowlist) plus, for integrity, the entrypoint bytes.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { parse as parseYaml } from "yaml";
+/** The governed posture, for "what WOULD happen" evaluations under compat. */
+export const GOVERNED_PLUGIN_POLICY_PROFILE = Object.freeze({ mode: "governed", pluginPolicy: "allowlist" });
+export const PLUGIN_NOT_ALLOWLISTED = "plugin_not_allowlisted";
+export const PLUGIN_INTEGRITY_MISMATCH = "plugin_integrity_mismatch";
+/** Error thrown by the runtime when a spec is refused. `code` is stable. */
+export class PluginPolicyError extends Error {
+    code;
+    specs;
+    constructor(code, message, specs) {
+        super(message);
+        this.name = "PluginPolicyError";
+        this.code = code;
+        this.specs = specs;
+    }
+}
+function isPathSpec(spec) {
+    return (spec.startsWith("./") ||
+        spec.startsWith("../") ||
+        spec === "." ||
+        spec === ".." ||
+        path.isAbsolute(spec));
+}
+/**
+ * Canonical form of a spec for comparison. Path specs resolve to an absolute
+ * path with the trailing separator dropped, so `./x`, `x/` written as `./x/`
+ * and the absolute form all agree. Package specs are compared verbatim after
+ * trimming — a package name has no equivalent spellings.
+ */
+export function normalisePluginSpec(spec, cwd = process.cwd()) {
+    const trimmed = spec.trim();
+    if (isPathSpec(trimmed)) {
+        const resolved = path.resolve(cwd, trimmed);
+        return resolved.length > 1 ? resolved.replace(/[\\/]+$/, "") : resolved;
+    }
+    return trimmed;
+}
+/**
+ * Pure: (spec, profile, allowlist) → verdict. Exact match on the normalised
+ * spec; no globbing, no prefix matching — a policy that matches loosely is
+ * a policy an attacker can satisfy by naming a sibling directory.
+ */
+export function evaluatePluginSpec(spec, input, cwd = process.cwd()) {
+    const trimmed = spec.trim();
+    if (input.profile.pluginPolicy !== "allowlist") {
+        return { spec: trimmed, allowed: true, reason: "compat profile: open" };
+    }
+    const wanted = normalisePluginSpec(trimmed, cwd);
+    for (const entry of input.allow ?? []) {
+        if (typeof entry?.spec !== "string")
+            continue;
+        if (normalisePluginSpec(entry.spec, cwd) === wanted) {
+            return {
+                spec: trimmed,
+                allowed: true,
+                reason: `allowlisted as "${entry.spec}"`,
+                entry,
+            };
+        }
+    }
+    const size = (input.allow ?? []).length;
+    return {
+        spec: trimmed,
+        allowed: false,
+        reason: size === 0
+            ? "governed profile: plugins.allow is empty — no recipe plugin may load"
+            : `governed profile: "${trimmed}" is not in plugins.allow (${size} entr${size === 1 ? "y" : "ies"})`,
+    };
+}
+/** Per-spec verdicts for `policy explain` / `doctor`. */
+export function explainPluginPolicy(specs, cfg, cwd = process.cwd()) {
+    return specs.map((s) => evaluatePluginSpec(s, { profile: cfg.profile, allow: cfg.allow }, cwd));
+}
+/** Convenience: the refused subset, for callers that build one error. */
+export function refusedPluginSpecs(specs, input, cwd = process.cwd()) {
+    return specs
+        .map((s) => evaluatePluginSpec(s, input, cwd))
+        .filter((v) => !v.allowed);
+}
+/** Build the runtime error for a set of refused verdicts. */
+export function pluginNotAllowlistedError(refused) {
+    const names = refused.map((v) => v.spec);
+    return new PluginPolicyError(PLUGIN_NOT_ALLOWLISTED, `recipe plugin${names.length === 1 ? "" : "s"} ${names.map((n) => `"${n}"`).join(", ")} ` +
+        "not allowlisted under the governed profile — add to config.json " +
+        "`plugins.allow` (spec, optional integrity) or switch to the compat profile", names);
+}
+export function sha256Integrity(bytes) {
+    return `sha256-${createHash("sha256").update(bytes).digest("base64")}`;
+}
+/**
+ * `sha256-<base64>` over the entrypoint file bytes. Absent integrity is
+ * SKIPPED (and says so) rather than failed: the allowlist entry itself is the
+ * operator's decision, and integrity is an optional tightening of it.
+ */
+export function verifyPluginIntegrity(entrypointPath, integrity) {
+    if (integrity === undefined || integrity === null || integrity === "") {
+        return {
+            ok: true,
+            status: "skipped",
+            reason: "no integrity recorded on the allowlist entry",
+        };
+    }
+    const m = /^sha256-([A-Za-z0-9+/]+={0,2})$/.exec(integrity.trim());
+    if (!m) {
+        return {
+            ok: false,
+            status: "malformed",
+            reason: `integrity must be "sha256-<base64>", got ${JSON.stringify(integrity)}`,
+        };
+    }
+    let bytes;
+    try {
+        bytes = readFileSync(entrypointPath);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: "unreadable",
+            reason: `cannot read entrypoint ${entrypointPath}: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    const actual = sha256Integrity(bytes);
+    if (actual !== `sha256-${m[1]}`) {
+        return {
+            ok: false,
+            status: "mismatch",
+            reason: `entrypoint ${entrypointPath} hashes to ${actual}, allowlist says ${integrity.trim()}`,
+            actual,
+        };
+    }
+    return { ok: true, status: "verified", reason: "sha256 matches", actual };
+}
+// ---------------------------------------------------------------------------
+// Recipe scanning (install / save / doctor)
+// ---------------------------------------------------------------------------
+/** Extract `servers:` from a parsed recipe object; non-list ⇒ []. */
+export function pluginSpecsOf(recipe) {
+    if (!recipe || typeof recipe !== "object" || Array.isArray(recipe))
+        return [];
+    const servers = recipe.servers;
+    if (!Array.isArray(servers))
+        return [];
+    return servers.filter((s) => typeof s === "string");
+}
+/** Extract `servers:` from recipe YAML text; unparseable ⇒ []. */
+export function pluginSpecsOfYaml(text) {
+    try {
+        return pluginSpecsOf(parseYaml(text));
+    }
+    catch {
+        return [];
+    }
+}
+export function policyInputFromConfig(profile, cfg) {
+    return { profile, allow: cfg?.plugins?.allow };
+}
+function walkRecipeFiles(dir, out, depth = 0) {
+    if (depth > 4)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (name.startsWith("."))
+            continue;
+        const full = path.join(dir, name);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory())
+            walkRecipeFiles(full, out, depth + 1);
+        else if (/\.(ya?ml|json)$/i.test(name))
+            out.push(full);
+    }
+}
+/**
+ * Every installed recipe's `servers:` specs with their verdicts, for the
+ * doctor governance section. Reports only recipes that declare plugins, but
+ * counts every file read so an empty result is distinguishable from an
+ * unreadable directory.
+ */
+export function scanInstalledRecipePlugins(recipesDir, cfg, cwd = process.cwd()) {
+    const files = [];
+    if (existsSync(recipesDir))
+        walkRecipeFiles(recipesDir, files);
+    const rows = [];
+    let refused = 0;
+    for (const file of files) {
+        let parsed;
+        try {
+            const text = readFileSync(file, "utf-8");
+            parsed = file.toLowerCase().endsWith(".json")
+                ? JSON.parse(text)
+                : parseYaml(text);
+        }
+        catch {
+            continue;
+        }
+        const specs = pluginSpecsOf(parsed);
+        if (specs.length === 0)
+            continue;
+        const verdicts = explainPluginPolicy(specs, cfg, cwd);
+        refused += verdicts.filter((v) => !v.allowed).length;
+        const name = parsed.name;
+        rows.push({
+            file: path.relative(recipesDir, file),
+            ...(typeof name === "string" ? { name } : {}),
+            verdicts,
+        });
+    }
+    return {
+        recipesDir,
+        recipesScanned: files.length,
+        recipesWithPlugins: rows.length,
+        refusedSpecs: refused,
+        rows,
+    };
+}
+//# sourceMappingURL=pluginPolicy.js.map

package/dist/governance/pluginPolicy.js.map

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

package/dist/governance/profile.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Governance profile — the ONE concept that turns Patchwork's opt-in controls
+ * into a coherent posture.
+ *
+ * Phase 0 finding: every headline control (approval gate, automated-trigger
+ * gating, worker authority, policy matrix, agent sandbox, plugin loading, the
+ * kill-switch failure mode) was independently opt-in and independently
+ * fail-open, so a fresh install enforced nothing while looking governed on the
+ * dashboard. This module resolves a single `profile` setting into the existing
+ * primitives — it adds no new decision function of its own.
+ *
+ * Two modes, deliberately only two:
+ *
+ *   - `compat`   — byte-identical to pre-profile behaviour. This is what an
+ *                  install with no `profile` key resolves to, so an existing
+ *                  installation never changes behaviour by upgrading.
+ *   - `governed` — conservative defaults suitable for real business data.
+ *                  `patchwork init` writes this for NEW installs;
+ *                  `patchwork profile governed` opts an existing one in.
+ *
+ * The resolved profile is a plain value. Runtime enforcement, `patchwork
+ * policy explain` and `patchwork doctor` all read the SAME resolved value, so
+ * the explanation cannot describe a posture the runtime is not applying.
+ *
+ * Every field below maps to something that already exists; the comment on
+ * each names the primitive it feeds. Nothing here is a new flag.
+ */
+export declare const PROFILE_MODES: readonly ["governed", "compat"];
+export type ProfileMode = (typeof PROFILE_MODES)[number];
+export interface GovernanceProfile {
+    mode: ProfileMode;
+    /** Whether `profile:` was explicitly present in config (vs defaulted). */
+    declared: boolean;
+    /**
+     * Feeds `Server.approvalGate` / `makeRecipeApprovalFn`. Governed raises the
+     * operator's setting to at least `"high"`; it never lowers an explicit
+     * `"all"`.
+     */
+    approvalGate: "off" | "high" | "all";
+    /**
+     * Feeds `RunnerDeps.gateAutomatedRuns`. Governed: cron / webhook / file-watch
+     * / git-hook / test-run triggers are consulted exactly like a manual run.
+     * Compat: manual only (the worker gate may still set it, as before).
+     */
+    gateAutomatedRuns: boolean;
+    /**
+     * Feeds `FLAG_WORKER_AUTONOMY`: a worker manifest that owns a recipe governs
+     * it. Compat leaves the flag as the operator set it.
+     */
+    workerAuthority: boolean;
+    /** Feeds `FLAG_ENFORCE_POLICY` (`patchwork.policy.yml`). */
+    policyEnforce: boolean;
+    /**
+     * Feeds the subprocess drivers (`src/drivers/*`): under `enforced` an agent
+     * step that declares no `sandbox:` runs contained — read-only tool
+     * allowlist, no WebFetch/WebSearch/Bash, allowlisted environment, no bridge
+     * MCP access. A recipe may widen this EXPLICITLY per step, and the widening
+     * is visible in `policy explain`.
+     */
+    agentContainment: "enforced" | "opt-in";
+    /**
+     * Feeds `loadRecipeServers` / recipe install / dashboard save / lint:
+     * `allowlist` refuses any `servers:` entry not in `config.plugins.allow`.
+     */
+    pluginPolicy: "allowlist" | "open";
+    /**
+     * Feeds `readKillSwitch`: when the kill-switch state cannot be read, treat
+     * it as ENGAGED (refuse) rather than released.
+     */
+    killSwitchFailClosed: boolean;
+    /**
+     * A write tool whose tier was INFERRED from its name (no explicit
+     * `riskDefault`, or a plugin / MCP tool) is queued for approval rather than
+     * trusted on the heuristic.
+     */
+    unknownWriteTools: "gate" | "allow";
+    /**
+     * A tool id nothing is registered under: governed halts the run (a plugin
+     * that failed to load must not produce a green run that did nothing);
+     * compat keeps the documented forward-compat SKIP.
+     */
+    unregisteredTools: "refuse" | "skip";
+    /** Connector-derived values are wrapped in an untrusted-content envelope. */
+    untrustedEnvelope: boolean;
+    /**
+     * Whether a recipe's own `requireApproval: false` may switch off the tier
+     * gate. Governed: no — a recipe cannot opt itself out of the workspace
+     * policy.
+     */
+    recipeOptOutHonoured: boolean;
+}
+export interface ProfileConfigInput {
+    profile?: unknown;
+    approvalGate?: unknown;
+}
+/**
+ * Pure: config → profile. Unknown or absent `profile` ⇒ compat (never a
+ * guess). An explicit but unrecognised value is reported by `doctor`, not
+ * silently promoted to governed.
+ */
+export declare function resolveProfile(cfg: ProfileConfigInput | undefined): GovernanceProfile;
+export declare const COMPAT_PROFILE: GovernanceProfile;
+export declare const GOVERNED_PROFILE: GovernanceProfile;
+export declare function isGoverned(p: GovernanceProfile | undefined): boolean;
+export declare function setActiveProfile(p: GovernanceProfile): void;
+export declare function activeProfile(): GovernanceProfile;
+/** Test seam. */
+export declare function _resetActiveProfileForTesting(): void;
+/**
+ * Tools a contained agent step may use. Read-only by construction: nothing
+ * here writes a file, runs a command, or reaches the network. Names are the
+ * Claude Code built-in tool names; other drivers map them to their own
+ * equivalents (Gemini/Codex have coarser knobs — see each driver).
+ */
+export declare const CONTAINED_AGENT_ALLOWED_TOOLS: readonly string[];
+/**
+ * Tools that are DENIED in every mode when the profile is governed, even when
+ * a recipe widens `allowedTools`. Network egress and shell are the two
+ * capabilities that turn a prompt injection into exfiltration; a recipe that
+ * genuinely needs them must say so with `sandbox: { network: true }` /
+ * `sandbox: { shell: true }`, which `policy explain` reports as a widening.
+ */
+export declare const CONTAINED_AGENT_DENIED_TOOLS: readonly string[];
+export interface AgentContainment {
+    /** True when the driver must apply the allowlist (not merely the deny list). */
+    enforced: boolean;
+    allowedTools: string[];
+    deniedTools: string[];
+    /** Pass only an explicit environment allowlist to the child process. */
+    envAllowlist: boolean;
+    /** Whether the child may reach the bridge's own MCP tool surface. */
+    mcpAccess: boolean;
+    /** Human-readable widenings the recipe requested, for `policy explain`. */
+    widenings: string[];
+}
+export interface StepSandboxRequest {
+    /** Recipe-declared `sandbox: true` / `allowedTools:` (existing fields). */
+    sandbox?: boolean;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    /** Explicit widenings a recipe may request under a governed profile. */
+    network?: boolean;
+    shell?: boolean;
+    mcpAccess?: boolean;
+}
+/**
+ * Pure: (profile, step request) → containment the driver must apply.
+ *
+ * Under `compat` this reproduces today's behaviour exactly: containment only
+ * when the step opted in via `sandbox: true`. Under `governed` the default is
+ * contained, and each widening is recorded so the explanation can show it.
+ */
+export declare function resolveAgentContainment(profile: GovernanceProfile, req: StepSandboxRequest | undefined): AgentContainment;