@intutic/sync-daemon 1.10.0 → 2.0.0

package/dist/harness/protectedPaths.d.ts

@@ -0,0 +1,353 @@
+/**
+ * The config files an agent must never write, and the command shapes it must
+ * never run — whichever harness it runs under.
+ *
+ * # Why this is one list
+ *
+ * It was eleven lists, and no two agreed. Measured on 2026-08-04:
+ *
+ * | path | harnesses protecting it |
+ * |---|---|
+ * | `.claude/settings.local.json` | 3 of 11 |
+ * | `.gemini/settings.json` | 5 of 11 |
+ * | `.intutic/events` | 5 of 11 |
+ * | `.codeium/windsurf/hooks.json` | 8 of 11 |
+ * | `.cursor/hooks.json` | 8 of 11 |
+ *
+ * That is not eleven partial views of one intent, it is a **cross-harness
+ * tamper matrix**. The Claude-family lists carried only Claude paths, so an
+ * agent under Claude Code could rewrite `.cursor/hooks.json`,
+ * `.openhands/hooks.json`, `.gemini/settings.json` or the governance plugin
+ * directory unopposed; the other nine could write `.claude/settings.local.json`,
+ * which Claude Code loads at *higher* precedence than the `settings.json` they
+ * all did protect. Whichever harness the agent was running under, it could
+ * disarm a different one.
+ *
+ * A protected-path list is a security control. Eleven copies of a security
+ * control is eleven chances for one to be wrong, and every one of them was.
+ *
+ * # The same was true of the command guards
+ *
+ * Nine writers hand-maintained a `BYPASS_PATTERNS` list. Measured on 2026-08-05:
+ *
+ * | pattern | writers carrying it |
+ * |---|---|
+ * | `chflags nouchg` / `chattr -i` | 9 of 9 |
+ * | `rm -rf .intutic` | 7 of 9 — **`cursorHooks` and `windsurfHooks` had no protected-path command guard at all** |
+ * | `rm -rf .gemini/settings` | 4 of 9 |
+ * | the harness's own env kill-switch | 1 each |
+ *
+ * That last row is the load-bearing one. `claudeCodeHooks` guarded
+ * `CLAUDE_CODE_HOOKS=` and nothing else; `piHooks` guarded `PI_PRE_TOOL_HOOK=`
+ * and nothing else. So under any harness, the *other eight* kill-switches were
+ * free to set — the identical cross-harness hole the path list already had.
+ * `GOVERNANCE_BYPASS_PATTERNS` closes it with one generic pattern rather than
+ * nine specific ones, so a harness added tomorrow is covered on the day it
+ * lands.
+ *
+ * Two writers also used `/chflags\s+nouchg/` where the other seven used a
+ * literal substring. `\s` does not exist in POSIX ERE — see
+ * {@link assertPortableEre} for why that class of divergence is now a load
+ * failure rather than a silent one.
+ *
+ * # Scope
+ *
+ * Universal by design. A Cursor agent has no legitimate reason to edit Claude
+ * Code's settings, and the reverse holds for every pair — so the union is the
+ * correct list for all of them, not a Cursor list plus a Claude list.
+ * Harness-specific additions spread this and append; `harnessProtectedPaths.test.ts`
+ * asserts each is a superset.
+ *
+ * @module
+ */
+/** Governance config that must hold still, for every harness. */
+export declare const UNIVERSAL_PROTECTED_PATHS: readonly string[];
+/**
+ * One command-guard rule, in a form every gate can evaluate identically.
+ *
+ * `source` is matched against the **normalised, padded** command — see
+ * {@link NORMALISE_CONTRACT}. It is deliberately restricted to the intersection
+ * of POSIX ERE and JavaScript `RegExp`; {@link assertPortableEre} enforces that
+ * at module load.
+ */
+/**
+ * Which part of the tool call a rule is matched against.
+ *
+ * Not cosmetic. A `BLOCK:` SOP compiles to a **tool-name** pattern (`Bash`,
+ * `Write`), while every pattern in this file matches **command or path text**.
+ * Evaluating one against the other silently matches nothing — the SOP rules
+ * would have loaded, appeared in the audit trail as active, and never fired.
+ * Making the subject an explicit column means a rule cannot be pointed at the
+ * wrong string by omission.
+ */
+/** `action` is the space-padded action-token string the gate classifies a
+ *  shell command to (`" action:deploy "`, from `ACTION_NEEDLES`) — the subject
+ *  a `review_before: action:deploy` hold rule matches. */
+export type GuardSubject = 'tool' | 'command' | 'target' | 'content' | 'action' | 'any';
+export interface GuardPattern {
+    /** Stable id. Appears in the block message and the audit line, so it is the
+     *  thing a support conversation is conducted in. Never renumber one. */
+    id: string;
+    /** Portable ERE ∩ JS RegExp source. */
+    source: string;
+    /** What {@link source} is matched against. Defaults to `any` — command and
+     *  target, but never the tool name. `content` is the serialized tool input
+     *  (`JSON.stringify(tool_input)` / `$TOOL_INPUT_JSON`), un-normalised — the
+     *  same subject the WHERE argPattern machinery matches, so a content rule
+     *  sees the bytes a Write would put on disk, not a whitespace-collapsed
+     *  rendering of them. */
+    subject?: GuardSubject;
+    /** Matched case-insensitively (`grep -iE` / the JS `i` flag). */
+    ignoreCase?: boolean;
+    /**
+     * What the rule does when it matches.
+     *
+     * `block` refuses the call. `warn` allows it and emits `tool_flagged` — the
+     * advisory tier that earns a pattern its promotion to `block`, following
+     * `sslGateEvaluator.ts` rather than inventing a second discipline. `shadow`
+     * also allows, but emits `tool_would_block`: the rule is certain and the
+     * workspace's interventionMode asked us not to act on it. The two allow-ing
+     * severities are kept apart because a SHADOW rollout is decided on the second
+     * count, and collapsing them into `warn` made it unmeasurable. `hold`
+     * refuses the call like `block` but records it for a human (`tool_held`
+     * plus a v1 hold record) and lets the exact same call through once an
+     * approved bypass for it exists — the `review_before:` / `REQUIRE_APPROVAL:`
+     * tier, one mechanism in every gate since gate body v8.
+     */
+    severity: 'block' | 'warn' | 'shadow' | 'hold';
+    /** Shown to the developer when it fires. Written for someone who is mid-task
+     *  and now blocked, not for a security reviewer. */
+    reason: string;
+    /** Why the rule exists **and what it deliberately does not catch**. The second
+     *  half is not optional: a guard whose limits are undocumented gets mistaken
+     *  for containment. */
+    rationale: string;
+    /** Commands that MUST match. */
+    matches: readonly string[];
+    /** Commands that MUST NOT match — the false-positive contract. A pattern with
+     *  fewer than three of these fails {@link assertGuardTableSane}, because the
+     *  cheapest way to write a guard that never fires wrongly is to never think
+     *  about the case where it would. */
+    notMatches: readonly string[];
+    /**
+     * Argument-level condition from a ` WHERE ` SOP rule, as JS `RegExp` source.
+     *
+     * When present, a rule whose {@link source} has matched (for SOP rules: the
+     * tool NAME) fires only if this also matches the serialized tool input —
+     * `JSON.stringify(tool_input ?? {})`, compact, insertion order, non-ASCII
+     * intact, the exact shape `matchSopRule` in the control plane and
+     * `serialise_tool_input` in intutic-clawde match against. Without this field
+     * a `BLOCK:^shell$ WHERE kubectl\s+apply(?!.*@sha256:)` rule reached the
+     * gates as "block shell unconditionally" — over-blocking `make test` while
+     * failing to express the condition it was written for.
+     *
+     * Deliberately NOT restricted to the portable ERE subset
+     * ({@link assertPortableEre}): it never runs under grep. The JS gates compile
+     * it as a `RegExp`; the bash gates delegate the match to `python3` `re`. The
+     * supported dialect is therefore the JS ∩ Python `re` intersection —
+     * character classes, alternation, anchors, quantifiers, `\s`, lookahead and
+     * lookbehind all agree; named groups do NOT (`(?<n>…)` vs `(?P<n>…)`), nor do
+     * some Unicode escapes. A pattern one engine cannot compile is enforced
+     * name-only by that gate and reported as `rule_downgraded`, never silently
+     * dropped — the same honest-divergence stance the LangGraph port documents in
+     * its snapshot reader.
+     */
+    argPattern?: string;
+}
+export declare const NORMALISE_CONTRACT: {
+    /**
+     * JS: produce the string patterns are matched against.
+     *
+     * Compiled from {@link NORMALISE_JS_EXPR} rather than written out, so it
+     * cannot diverge from what the gates run. `unknown` in, because callers pass
+     * whatever a harness put in its payload.
+     */
+    readonly js: (s: unknown) => string;
+    /** The JS function, emitted verbatim into every JavaScript gate. */
+    readonly jsSource: "function intuticNormalise(s) {\n  return ' ' + String(s == null ? '' : s).replace(/\\s+/g, ' ') + ' ';\n}";
+    /**
+     * The Python function, emitted into the Open WebUI filter.
+     *
+     * `re.sub(r"\s+", " ", …)` rather than the more idiomatic `" ".join(s.split())`,
+     * and the difference is the one a test caught: `split()` **strips** leading and
+     * trailing whitespace, while the JS `replace(/\s+/g, ' ')` collapses it to a
+     * single space and keeps it. So `"  a  b  "` normalised to `" a b "` in Python
+     * and `"  a b  "` in JS and bash. Both match the same patterns, since patterns
+     * use single-space boundaries — but "happens to be equivalent" is not the
+     * property this contract claims, and the next edit would not have been so lucky.
+     *
+     * Python's `\s` on a `str` covers Unicode whitespace (U+00A0, U+3000), matching
+     * JS. The shell fallback cannot, which is why SHELL_EXTRACT pre-passes.
+     */
+    /** Requires `re` in scope — the emitted filter imports it. */
+    readonly pySource: string;
+    /**
+     * Shell: pure parameter expansion — no subshell, no `tr`, no `python3`.
+     *
+     * **ASCII only, and deliberately second in line.** Bash cannot express a
+     * Unicode whitespace class, so this collapses only the C0 set; U+00A0 would
+     * survive it and a pattern written with a literal space would then miss. The
+     * bash gates are not exposed to that because `SHELL_EXTRACT` runs every field
+     * through Python's `" ".join(str(v).split())` *before* this ever sees it —
+     * which is Unicode-aware. This is the belt to that pair of braces, and saying
+     * so here is the point: an earlier version of this comment claimed the three
+     * normalisers were provably identical, and they were not.
+     */
+    readonly shell: string;
+};
+/**
+ * Rejects any pattern that would not mean the same thing to `grep -E` and to
+ * JavaScript.
+ *
+ * Runs at module load rather than from a test, so a non-portable pattern breaks
+ * the import — every writer, every test, immediately — instead of breaking one
+ * test that someone might skip. The failure this prevents is not hypothetical:
+ * `cursorHooks` and `windsurfHooks` shipped `\s+` for a year.
+ *
+ * `\s`, `\d`, `\w` and `\b` are forbidden **even though GNU grep accepts them**,
+ * because GNU grep is not the only grep — busybox and BSD do not, and a customer
+ * running us in an Alpine image would get a gate that silently matches nothing.
+ */
+export declare function assertPortableEre(source: string, id: string): void;
+/**
+ * Commands that disarm governance itself.
+ *
+ * The union of the nine hand-rolled `BYPASS_PATTERNS` lists, plus the two holes
+ * the union exposed: `cursorHooks`/`windsurfHooks` never guarded `.intutic` at
+ * all, and every list guarded only its own harness's env kill-switch.
+ */
+export declare const GOVERNANCE_BYPASS_PATTERNS: readonly GuardPattern[];
+/**
+ * Credential VALUES in the content an agent is about to write.
+ *
+ * The gap this closes, measured before it was built: the PreToolUse gate —
+ * the only enforcement point that runs before the harness executes a tool —
+ * matched tool name, target path and command, never content. A key the model
+ * had seen anywhere in context could be written into a config file and the
+ * gate had no rule that could notice; the proxy's DLP covers the same case
+ * only when LLM traffic actually routes through the proxy, so a
+ * hooks-installed-but-unproxied workspace had zero write-direction scanning.
+ * (GitGuardian's 2025 measurement of why this matters: AI-assisted commits
+ * shipped hardcoded secrets at 3.2% against a 1.5% human baseline.)
+ *
+ * Sources live in `@intutic/shared-types` (`secretPatterns.ts`) because the
+ * pre-commit scan in `tools/cli/src/lib/gitHooks.ts` greps the SAME shapes
+ * over the staged diff — two hand-kept copies of "what is a credential" is
+ * the drift this repo keeps paying for. Fixtures stay here, where the
+ * table's self-test runs.
+ *
+ * ## Severity: block, deliberately skipping the warn-first ramp
+ *
+ * DESTRUCTIVE_COMMAND_PATTERNS shipped at warn to earn promotion on measured
+ * false positives. These four ship at block because both halves of that
+ * trade differ: the patterns are prefix-anchored value shapes already
+ * hard-blocking in production on the MCP proxy's input path with no
+ * false-positive reports, and the failure being prevented — a credential in
+ * a file, then in a commit — is not undone by an undo (the key is burned;
+ * rotation is the only remedy). A warn that lets the write proceed IS the
+ * incident.
+ *
+ * ## What this deliberately does not catch
+ *
+ * A secret split across two Writes, base64/hex-encoded values, secrets
+ * assembled by concatenation in generated code, values reached through
+ * env-var indirection, and any credential format without a distinctive
+ * prefix. Those need entropy analysis and cross-call state that belong in
+ * the proxy's DLP, not in a gate that must stay fast and false-positive-free
+ * to keep its block tier trusted. This is the same floor-vs-DLP split the
+ * warn tier's own comment draws ("arguments and paths stay out — that is
+ * DLP's job"): the floor takes the four shapes precise enough to refuse on.
+ */
+export declare const SECRET_CONTENT_PATTERNS: readonly GuardPattern[];
+/**
+ * Writes and edits targeting the agent-skill surface — `.agents/skills/**`
+ * and `.claude/skills/**`.
+ *
+ * TD-358 (updated 2026-08-18): these two entries stay `warn` and stay
+ * compiled into {@link staticFloorPatterns} — that part of the original
+ * decision is unchanged. What changed is what that tier assignment now
+ * *means*: it is the DEGRADED-MODE baseline, not the intended steady state.
+ * The steady state, everywhere a valid policy snapshot has landed, is `block`
+ * — shipped as `skill_surface.*.tier` entries through
+ * `services/sync-daemon/src/lib/policySnapshot.ts`'s `buildSnapshotRules`,
+ * gated behind `SKILL_SURFACE_TIER_SEVERITY`. See that constant's doc comment
+ * for why skill-directory *path* writes no longer sit behind the same
+ * false-positive-rate justification skill-CONTENT scanning still does — this
+ * entry only covers the half that stayed at `warn`.
+ *
+ * The two design choices below are for different reasons and worth
+ * separating:
+ *
+ * - **Why the FLOOR copy stays `warn`:** a compiled-in rule ships on every
+ *   machine at once and can only be changed by a release — no one-sync-cycle
+ *   undo if it turns out wrong. That is exactly the property a degraded-mode
+ *   baseline needs (safe to run forever, unconditionally, on a machine that
+ *   has never talked to the control plane) and exactly the property the
+ *   steady-state decision does not need to have, since it lives in the
+ *   snapshot and can be retracted in a cycle. Blocking here as well would
+ *   collapse that distinction and reintroduce the un-retractable blast radius
+ *   the snapshot channel exists to avoid.
+ * - **Why a floor copy exists at all, unlike `DESTRUCTIVE_COMMAND_PATTERNS`:**
+ *   this pattern set is NOT content-conditional — it does not run
+ *   `scanSkillContent` or judge what a skill file says, only WHERE a write
+ *   targets. That is a deterministic, zero-ambiguity match (a write's target
+ *   path either is or is not under `.agents/skills/` or `.claude/skills/`),
+ *   so a workspace with no control-plane connectivity (offline, pre-`connect`,
+ *   or a snapshot that failed its digest/workspace check) still gets an
+ *   advisory signal from the moment the gate is written, rather than falling
+ *   back to nothing.
+ *
+ * `subject: 'target'` deliberately, not `'any'`: this matches the tool's own
+ * path argument (`file_path`/`path`/…, the same extraction every Write/Edit
+ * gate already does), not a bare mention in a shell command. A `cat` or `grep`
+ * of a skill file is a read, not a write, and is not what this pattern
+ * exists to flag — narrower than `UNIVERSAL_PROTECTED_PATHS`'s "any mention"
+ * rule on purpose, since that rule blocks and this one only advises.
+ *
+ * A future promotion to `block` on skill CONTENT (not path) is a different,
+ * later, and still-open decision — it needs the corpus measurement TD-358
+ * describes, which this change does not supply. It should ship through the
+ * same policy-snapshot channel the way this path-tier promotion and
+ * `DESTRUCTIVE_COMMAND_PATTERNS` both do, so it too is retractable in a sync
+ * cycle rather than a release if the measurement turns out wrong.
+ */
+export declare const SKILL_SURFACE_PATTERNS: readonly GuardPattern[];
+/**
+ * Commands that destroy the machine or its data irrecoverably.
+ *
+ * TD-309: none of these were blocked by any harness. They are shipped through
+ * the policy snapshot rather than compiled into the gate, and at `warn` before
+ * `block` — see the note on `severity` below.
+ *
+ * ## What is deliberately allowed
+ *
+ * `rm -rf ./`, `rm -rf .`, `rm -rf *`, `rm -rf build/`, `rm -rf node_modules`
+ * and `rm -rf /home/…` are all ordinary developer commands and all pass. That
+ * is not an oversight to tighten later. A guard that blocks routine work
+ * teaches the developer to run `chflags nouchg` on the hook — the exact bypass
+ * `GOVERNANCE_BYPASS_PATTERNS` exists to stop. Blocking too much manufactures
+ * the adversary the rest of this file defends against.
+ *
+ * ## What no pattern here catches
+ *
+ * Shell redirection to a raw device (`cat /dev/zero > /dev/sda`), obfuscation
+ * (`eval "$(printf cm0gLXJmIC8= | base64 -d)"`), anything reached through a
+ * script file rather than typed as a command, and any of these run by a process
+ * the agent spawns rather than by the agent. This tier is a speed bump against
+ * accident and casual bypass. Containment is the proxy and OS permissions.
+ */
+export declare const DESTRUCTIVE_COMMAND_PATTERNS: readonly GuardPattern[];
+export declare function protectedPathShellPatterns(): readonly GuardPattern[];
+/** Every compiled-in guard: the static floor. Destructive patterns are **not**
+ *  here — they ship through the policy snapshot so they can be retracted
+ *  without a release. `SKILL_SURFACE_PATTERNS` IS here, deliberately, despite
+ *  also being new: unlike the destructive tier it is a deterministic path
+ *  match with no content judgement to get wrong, so there is no measurement
+ *  risk to hold it back from — see its own doc comment. As of TD-358's
+ *  block-tier promotion these two entries are the DEGRADED-MODE baseline
+ *  only: the steady state is `block`, delivered through the policy snapshot
+ *  (`SKILL_SURFACE_TIER_SEVERITY` in `lib/policySnapshot.ts`) and additive on
+ *  top of these, exactly the way the destructive tier layers on top of this
+ *  same floor. */
+export declare function staticFloorPatterns(): readonly GuardPattern[];
+//# sourceMappingURL=protectedPaths.d.ts.map

package/dist/harness/protectedPaths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protectedPaths.d.ts","sourceRoot":"","sources":["../../src/harness/protectedPaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AAIH,iEAAiE;AACjE,eAAO,MAAM,yBAAyB,EAAE,SAAS,MAAM,EAiEtD,CAAA;AAMD;;;;;;;GAOG;AACH;;;;;;;;;GASG;AACH;;0DAE0D;AAC1D,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,KAAK,CAAA;AAEvF,MAAM,WAAW,YAAY;IAC3B;4EACwE;IACxE,EAAE,EAAE,MAAM,CAAA;IACV,uCAAuC;IACvC,MAAM,EAAE,MAAM,CAAA;IACd;;;;;6BAKyB;IACzB,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB;;;;;;;;;;;;;;OAcG;IACH,QAAQ,EAAE,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,CAAA;IAC9C;wDACoD;IACpD,MAAM,EAAE,MAAM,CAAA;IACd;;2BAEuB;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,gCAAgC;IAChC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IAC1B;;;yCAGqC;IACrC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAoCD,eAAO,MAAM,kBAAkB;IAC7B;;;;;;OAMG;iBACqD,CAAC,CAAC,EAAE,OAAO,KAAK,MAAM;IAE9E,oEAAoE;;IAGpE;;;;;;;;;;;;;OAaG;IACH,8DAA8D;;IAM9D;;;;;;;;;;;OAWG;;CASK,CAAA;AAEV;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI,CA2BlE;AA0CD;;;;;;GAMG;AACH,eAAO,MAAM,0BAA0B,EAAE,SAAS,YAAY,EAyD5D,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,uBAAuB,EAAE,SAAS,YAAY,EAyG1D,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmDG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,YAAY,EA+CxD,CAAA;AAEF;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,4BAA4B,EAAE,SAAS,YAAY,EAmJ/D,CAAA;AA2CD,wBAAgB,0BAA0B,IAAI,SAAS,YAAY,EAAE,CAEpE;AAED;;;;;;;;;;kBAUkB;AAClB,wBAAgB,mBAAmB,IAAI,SAAS,YAAY,EAAE,CAO7D"}