@intutic/sync-daemon 1.10.0 → 1.10.1

package/dist/lib/policySnapshot.d.ts

@@ -0,0 +1,224 @@
+/**
+ * policySnapshot.ts — ships workspace policy *to* the machine, so the gate does
+ * not have to ship the decision off it.
+ *
+ * # Why
+ *
+ * TD-307: `POST /api/v1/hook-gate` was called by two of thirteen gates, so DLP,
+ * `BLOCK:` SOPs, SSO policy and promoted findings reached two of thirteen. The
+ * obvious repair — route the other eleven through the gate — is the wrong one:
+ * those eleven enforce locally and **fail closed**, the two network callers were
+ * the only ones that **fail open**, and the gate's allow path is five or six
+ * sequential Postgres round-trips. Routing everyone through it would trade
+ * fail-closed for fail-open and put a control-plane outage on every `Bash`.
+ *
+ * Almost none of that decision needs the network. So the daemon resolves policy
+ * once per sync cycle and writes it here; every gate reads a local file.
+ *
+ * # Two tiers, one invariant
+ *
+ * The **static floor** (`staticFloorPatterns()`) is compiled into each gate and
+ * always enforced. The **dynamic tier** is this file, and it is *additive only*:
+ *
+ * > For every harness and every snapshot state, the set of calls blocked after
+ * > this change is a superset of the set blocked before.
+ *
+ * That is what makes the failure modes tractable. A missing or corrupt snapshot
+ * costs only rules that, for eleven of the thirteen gates, did not exist at all
+ * before — so degrading returns to yesterday's behaviour rather than opening a
+ * new hole. It is also why an absent snapshot does **not** fail closed: that
+ * would brick every agent on every machine at install time, to replace
+ * protection the floor already provides.
+ *
+ * # Where it lives, and why that matters
+ *
+ * `~/.intutic/hooks/policy-snapshot.{json,rules}`. The directory is load-bearing:
+ * `.intutic/hooks` is already in `UNIVERSAL_PROTECTED_PATHS`, so all thirteen
+ * gates refuse an agent's attempt to write the snapshot on day one, with no new
+ * entry and no new code.
+ *
+ * # The ` WHERE ` clause survives this pipeline now
+ *
+ * A SOP titled `BLOCK:^shell$ WHERE kubectl\s+apply(?!.*@sha256:):reason`
+ * resolves to `{toolPattern, argPattern}` at `GET /api/v1/policy/resolve`
+ * (the demo doctor's "argPattern served" check proves that half). This module
+ * used to be where the other half died: `ResolvedPolicy` did not declare
+ * `argPattern`, `toGuardPattern` did not carry it, and the rule reached all
+ * twelve tool-call gates as "block `shell` unconditionally" — simultaneously
+ * failing to enforce the argument condition and re-manufacturing the exact
+ * over-blocking (`make test` refused) the WHERE grammar was invented to
+ * eliminate. It now travels: verbatim in the JSON's `sopRules` and `rules`,
+ * base64-encoded in the `.rules` projection's seventh column (see
+ * `RULES_COLUMNS` in gateBody.ts for the encoding contract), and every gate
+ * family conditions a name-matched rule on it before firing.
+ *
+ * @module
+ */
+import { type GuardPattern } from '../harness/protectedPaths.js';
+/** Directory every gate looks in. Inside `.intutic/hooks`, which is already
+ *  protected — see the module note. */
+export declare const DEFAULT_SNAPSHOT_DIR: string;
+export declare const SNAPSHOT_JSON = "policy-snapshot.json";
+export declare const SNAPSHOT_RULES = "policy-snapshot.rules";
+/**
+ * Whether the destructive tier ships as `block` or as `warn`.
+ *
+ * `warn`. These seven patterns qualify for `block` on the merits — every one is
+ * unrecoverable without a reinstall or a backup — but they have never run
+ * against real developer traffic, and they would land on thirteen harnesses at
+ * once. A false positive here does not merely annoy: the fastest workaround
+ * available to a blocked developer is `chflags nouchg` on the hook, which is the
+ * exact bypass `GOVERNANCE_BYPASS_PATTERNS` exists to stop. Shipping too hard
+ * manufactures our own adversary.
+ *
+ * So they ride the advisory tier first and earn promotion from
+ * `tool_flagged` telemetry — the same discipline `sslGateEvaluator.ts` follows
+ * for SSL enforcement, and the same one `packages/proxy/src/plugins/anomaly`
+ * states as the promotion rule. Flipping this constant is the promotion, and it
+ * belongs in a commit alongside the measurement that licenses it.
+ *
+ * Shipping them *through the snapshot* rather than compiling them into the gate
+ * is the other half: the set we are least sure about is the set we can retract
+ * in one sync cycle instead of one release.
+ */
+export declare const DESTRUCTIVE_TIER_SEVERITY: 'block' | 'warn';
+/**
+ * Whether the skill-directory-write tier ships as `block` or as `warn`.
+ *
+ * `block` — deliberately not following `DESTRUCTIVE_TIER_SEVERITY`'s warn-first
+ * ramp, because the thing that ramp is buying time for does not exist on this
+ * surface. `DESTRUCTIVE_COMMAND_PATTERNS` rides at `warn` because those seven
+ * families are unmeasured against real developer traffic and a false positive
+ * has a real cost (see that constant's own comment). `SKILL_SURFACE_PATTERNS`
+ * is not that kind of rule: it does not run `scanSkillContent` or judge
+ * anything about what a skill file says, only WHERE a write's target path
+ * points — `.agents/skills/**` or `.claude/skills/**`, a deterministic,
+ * zero-ambiguity match. TD-358 (`docs/TECH_DEBT.md`) says this about exactly
+ * that distinction: "Path-matching is the one exception, and it is not
+ * actually an exception to the measurement requirement — it never needed
+ * one." There is no false-positive rate to earn a promotion by measuring,
+ * because there is nothing probabilistic here to measure in the first place.
+ *
+ * The second half of the argument is what `warn` actually buys on this
+ * surface, and the answer is nothing. `SECRET_CONTENT_PATTERNS`
+ * (`harness/protectedPaths.ts`) skips the warn-first ramp for the same reason
+ * and states the principle this constant now follows: "A warn that lets the
+ * write proceed IS the incident." A poisoned skill file written under
+ * warn-only is not a near-miss sitting in telemetry waiting for a human to
+ * notice — it is a file on disk that the very next agent session loads and
+ * trusts as instructions, the same way it trusts its own system prompt. Warn
+ * logs the write and lets it land anyway, so there is no window in which the
+ * advisory tier protected anything. That is what makes this different from
+ * `DESTRUCTIVE_COMMAND_PATTERNS`: a destructive *command*'s warn tier buys a
+ * chance for a human to notice before the damage is done; a skill file, once
+ * written, already is the damage.
+ *
+ * Shipped *through the snapshot* rather than promoted in place in
+ * `staticFloorPatterns()`, for the same operational reason
+ * `DESTRUCTIVE_TIER_SEVERITY` is: the rollout, not the mechanism, is the thing
+ * still short on field time, and the snapshot channel is what makes it
+ * retractable in one sync cycle instead of one release if that turns out
+ * wrong. `staticFloorPatterns()` keeps its two `SKILL_SURFACE_PATTERNS`
+ * entries at `warn` — unchanged by this constant — as the degraded-mode
+ * baseline for a workspace with no snapshot, or an invalid one; this constant
+ * is what promotes the steady state to `block` everywhere a valid snapshot has
+ * landed. Flipping it back to `'warn'` is the retraction, exactly as it is for
+ * `DESTRUCTIVE_TIER_SEVERITY`.
+ */
+export declare const SKILL_SURFACE_TIER_SEVERITY: 'block' | 'warn';
+/** Rules the control plane resolved for this workspace. Mirrors the
+ *  `GET /api/v1/policy/resolve` response — including `argPattern`, the
+ *  ` WHERE ` clause of a SOP title. This type is where that field used to
+ *  fall on the floor: resolve served it, the type did not declare it, and the
+ *  gates enforced the rule as an unconditional tool-name block. */
+export interface ResolvedPolicy {
+    workspaceId: string;
+    sopRules: Array<{
+        id: string;
+        toolPattern: string;
+        argPattern?: string;
+        action: string;
+        reason: string;
+        /**
+         * LLD #71: `'guardrail'` on rules the control plane projects from a cited
+         * policy guardrail. The only origin for which `action: 'warn'` is shipped
+         * (at severity `warn`, report-only); every other warn rule is still
+         * dropped, the HIGH/CRITICAL catch-all included.
+         */
+        origin?: string;
+    }>;
+    interventionMode: string;
+    /**
+     * Per-server MCP allowlist, absorbed verbatim from `allowedServers` on
+     * `GET /api/v1/policy/resolve` (confirmed against `evaluate.ts` and
+     * `lib/mcpCuration.ts` — both the daemon-mode and stdio-mode routes read
+     * this same field name off `workspaces.settings`, so this is not a new
+     * name invented for the snapshot). Absent/empty means unrestricted — the
+     * MCP proxy already reads it that way (`packages/mcp-proxy/src/policy.ts`),
+     * and the gate-side `#mcpservers` header this field feeds
+     * (`writePolicySnapshot` below) preserves the same convention: an empty
+     * list omits the header entirely rather than shipping a deny-everything one.
+     */
+    mcpAllowedServers: string[];
+    /**
+     * Wave 7 (audit-remediation): promotes `destructive.sql_drop` from `warn`
+     * to `block` in `buildSnapshotRules` below — a per-rule override, not a
+     * flip of `DESTRUCTIVE_TIER_SEVERITY`. Absent/wrongly-typed degrades to
+     * `false` (stays `warn`), the same fail-safe direction every other field
+     * here degrades in.
+     */
+    sqlDropStrictBlock: boolean;
+}
+export interface PolicySnapshotOptions {
+    controlPlaneUrl: string;
+    apiKey: string;
+    workspaceId: string;
+    /** Override the directory (tests). */
+    snapshotDir?: string;
+    /**
+     * `review_before:` tokens from the workspace's local SOPs and settings
+     * (`parseSopConstraints(...).reviewBefore`). Each becomes a `hold` rule,
+     * `sop.local.review_before.<token>`, so every gate holds on them — not only
+     * the Claude Code hook that used to bake them in (TD-474 item 4).
+     */
+    localHoldTokens?: readonly string[];
+}
+/**
+ * Decides whether a control-plane rule is safe to put on a blocking path.
+ *
+ * Returns the reason for rejection, or `null` if the rule is fine. Rejections
+ * are logged rather than thrown: one bad SOP must not cost the workspace every
+ * other rule.
+ */
+export declare function validateRule(toolPattern: string, ruleId: string): string | null;
+/** Fetches resolved policy for the workspace. Returns null on any failure —
+ *  the caller keeps the previous snapshot rather than replacing it with nothing. */
+export declare function fetchResolvedPolicy(opts: PolicySnapshotOptions): Promise<ResolvedPolicy | null>;
+/** Builds the rule set a snapshot would carry, without writing it. Exported so
+ *  a test can assert the contents rather than re-deriving them. */
+export declare function buildSnapshotRules(policy: ResolvedPolicy, localHoldTokens?: readonly string[]): GuardPattern[];
+/**
+ * Writes the snapshot atomically.
+ *
+ * Two artifacts from one source: the canonical JSON, and a tab-separated
+ * `.rules` projection so the five bash gates need no JSON parser on the decision
+ * path. Both carry the same digest, so a test — and the gate — can tell that the
+ * projection really came from the JSON.
+ */
+export declare function writePolicySnapshot(policy: ResolvedPolicy, snapshotDir?: string, localHoldTokens?: readonly string[]): Promise<{
+    digest: string;
+    ruleCount: number;
+}>;
+/**
+ * Fetch and write in one call. Safe to run on every sync cycle.
+ *
+ * Never throws: policy refresh must not be able to take down the sync loop. A
+ * failed fetch leaves the previous snapshot in place, which is the correct
+ * degradation — stale rules stay enforced. If they expired into permissiveness,
+ * "kill the daemon and wait" would be a supported way to disarm governance.
+ */
+export declare function refreshPolicySnapshot(opts: PolicySnapshotOptions): Promise<{
+    digest: string;
+    ruleCount: number;
+} | null>;
+//# sourceMappingURL=policySnapshot.d.ts.map

package/dist/lib/policySnapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policySnapshot.d.ts","sourceRoot":"","sources":["../../src/lib/policySnapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAQH,OAAO,EAIL,KAAK,YAAY,EAClB,MAAM,8BAA8B,CAAA;AAIrC;uCACuC;AACvC,eAAO,MAAM,oBAAoB,QAA+C,CAAA;AAChF,eAAO,MAAM,aAAa,yBAAyB,CAAA;AACnD,eAAO,MAAM,cAAc,0BAA0B,CAAA;AAErD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,GAAG,MAAe,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,eAAO,MAAM,2BAA2B,EAAE,OAAO,GAAG,MAAgB,CAAA;AAEpE;;;;mEAImE;AACnE,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,KAAK,CAAC;QACd,EAAE,EAAE,MAAM,CAAA;QACV,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,CAAC,EAAE,MAAM,CAAA;QACnB,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;QACd;;;;;WAKG;QACH,MAAM,CAAC,EAAE,MAAM,CAAA;KAChB,CAAC,CAAA;IACF,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;;;;;;;;OAUG;IACH,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B;;;;;;OAMG;IACH,kBAAkB,EAAE,OAAO,CAAA;CAC5B;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,EAAE,MAAM,CAAA;IACvB,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;OAKG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACpC;AAgDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmD/E;AA4FD;oFACoF;AACpF,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CA4ChC;AAyDD;mEACmE;AACnE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,cAAc,EAAE,eAAe,GAAE,SAAS,MAAM,EAAO,GAAG,YAAY,EAAE,CAwDlH;AA+BD;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,WAAW,GAAE,MAA6B,EAC1C,eAAe,GAAE,SAAS,MAAM,EAAO,GACtC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAmHhD;AAaD;;;;;;;GAOG;AACH,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAAC,CASvD"}