@intutic/shared-types 1.10.0 → 1.10.1

package/dist/guardrailIr.js

@@ -0,0 +1,301 @@
+"use strict";
+/**
+ * Guardrail IR — the only thing a policy compiler may say (LLD #71).
+ *
+ * An LLM reading corporate policy prose is allowed to propose exactly two
+ * things: a verbatim quote anchored to a passage it was shown, and a clause in
+ * this closed IR. Everything after that is deterministic code: the validator
+ * (`services/control-plane/src/lib/guardrailValidator.ts`) checks the quote by
+ * containment and the IR against the grammar the proxy and the harness gates
+ * already enforce, the renderers in `./guardrailRender.ts` turn it into the
+ * exact bytes those enforcers read, and cross-language parity fixtures prove
+ * the renderers and the Rust / gate-script parsers agree.
+ *
+ * The grammar is a subset of what a human may author, on purpose:
+ *
+ * - `hook_rule` — a per-call condition on a tool and its arguments, enforced
+ *   by the sync daemon's emitted harness gate scripts. Regexes are never model
+ *   output: the tool pattern is rendered from literal tool tokens and the
+ *   argument pattern from literal substrings (`argContains` / `argNotContains`),
+ *   escaped and composed as lookaheads — the dialect JS `RegExp` and Python
+ *   `re` share, so the bash gates' `python3` clause and the JS gates agree.
+ * - the six union-safe SOP front-matter keys the Rust proxy enforces
+ *   (`deny_tools`, `review_before`, `requires_before`, `forbid_after`,
+ *   `max_calls`, `forbid_with`). `~>` adjacency is not offered; `->` only.
+ * - `wasm_predicate` — the existing closed predicate DSL, verdict 3 (reask)
+ *   only. A generated rule can never originate a block.
+ * - `none` — "this passage contains no enforceable rule", so the corpus can
+ *   measure over-generation.
+ *
+ * Deliberately absent: the three allowlist keys (`allow_harnesses`,
+ * `plan_steps`, `scope_paths` — intersection-composed, empty-means-unrestricted;
+ * a generated allowlist can silently deny everything), raw regexes, raw
+ * AssemblyScript, `BLOCK:` titles, DLP patterns, SSL graphs, verdict 1, OR.
+ *
+ * Structural impossibilities match the Rust parser's own refusals: a token with
+ * whitespace (a shell command) cannot exist, a `forbid_with` taint is an enum,
+ * and an ordering rule is one pair.
+ *
+ * @module
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FRONT_MATTER_KINDS = exports.IR_KINDS = exports.GuardrailIrSchema = exports.MAX_CALLS_LIMIT = exports.MAX_RATIONALE_CHARS = exports.MAX_TITLE_CHARS = exports.MAX_ROLES = exports.MAX_LITERAL_CHARS = exports.MAX_LITERALS = exports.MAX_LIST_TOKENS = exports.MAX_HOOK_TOOLS = exports.TOOL_TOKEN_RE = exports.ACTION_TOKENS = void 0;
+exports.isActionToken = isActionToken;
+exports.isFrontMatterIr = isFrontMatterIr;
+exports.validateGuardrailIr = validateGuardrailIr;
+exports.canonicalizeIr = canonicalizeIr;
+exports.irTokens = irTokens;
+const zod_1 = require("zod");
+const rulePredicateDsl_js_1 = require("./rulePredicateDsl.js");
+/**
+ * The eight `action:` tokens the proxy's classifier synthesises from tool
+ * calls. Moved here from `services/control-plane/src/services/learnedHoldService.ts`
+ * so the IR, the validator and the hold miner read one list; that file
+ * re-exports it. A token outside this set and outside the observed tool names
+ * compiles into a control that can never fire.
+ */
+exports.ACTION_TOKENS = [
+    'action:deploy',
+    'action:publish',
+    'action:release',
+    'action:db_write',
+    'action:secret_read',
+    'action:http_post',
+    'action:pii_export',
+    'action:run_tests',
+];
+function isActionToken(value) {
+    return exports.ACTION_TOKENS.includes(value);
+}
+/**
+ * A tool name the harness could plausibly call: `Bash`, `run_command`,
+ * `mcp__github__create_issue`, `developer__shell`. No whitespace, so a shell
+ * command can never be mistaken for a tool (sops.rs `parse_ordering` refuses
+ * the same shape for the same reason). `.`, `:` and `-` are allowed because
+ * namespaced harness tools carry them.
+ */
+exports.TOOL_TOKEN_RE = /^[A-Za-z][A-Za-z0-9_.:-]{0,63}$/;
+exports.MAX_HOOK_TOOLS = 8;
+exports.MAX_LIST_TOKENS = 16;
+exports.MAX_LITERALS = 4;
+exports.MAX_LITERAL_CHARS = 64;
+exports.MAX_ROLES = 8;
+exports.MAX_TITLE_CHARS = 80;
+exports.MAX_RATIONALE_CHARS = 480;
+exports.MAX_CALLS_LIMIT = 1000;
+const Token = zod_1.z
+    .string()
+    .min(1)
+    .max(64)
+    .refine((v) => isActionToken(v) || exports.TOOL_TOKEN_RE.test(v), {
+    message: 'a token is a tool name (`Bash`, `mcp__github__create_issue`) or one of the eight `action:` tokens — never a command',
+});
+/**
+ * A literal substring of the serialised tool input. No tab or newline (the
+ * `.rules` snapshot is line- and tab-delimited), and no `"` or `\` — those
+ * are JSON-escaped in the haystack the gates match against, so a literal
+ * containing them could never match the bytes it was written for.
+ */
+const Literal = zod_1.z
+    .string()
+    .min(1)
+    .max(exports.MAX_LITERAL_CHARS)
+    .refine((v) => !/[\t\r\n"\\]/.test(v), {
+    message: 'a literal may not contain a tab, newline, double quote or backslash',
+});
+const Roles = zod_1.z
+    .array(zod_1.z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/, 'a role is lower-case: `deployer`, `reviewer`'))
+    .max(exports.MAX_ROLES)
+    .optional();
+const Title = zod_1.z.string().min(1).max(exports.MAX_TITLE_CHARS);
+const Rationale = zod_1.z.string().max(exports.MAX_RATIONALE_CHARS);
+const HookRuleSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal('hook_rule'),
+    title: Title,
+    tools: zod_1.z.array(Token).min(1).max(exports.MAX_HOOK_TOOLS),
+    argContains: zod_1.z.array(Literal).max(exports.MAX_LITERALS).optional(),
+    argNotContains: zod_1.z.array(Literal).max(exports.MAX_LITERALS).optional(),
+    roles: Roles,
+})
+    .strict();
+const DenyToolsSchema = zod_1.z
+    .object({ kind: zod_1.z.literal('deny_tools'), tools: zod_1.z.array(Token).min(1).max(exports.MAX_LIST_TOKENS), roles: Roles })
+    .strict();
+const ReviewBeforeSchema = zod_1.z
+    .object({ kind: zod_1.z.literal('review_before'), tokens: zod_1.z.array(Token).min(1).max(exports.MAX_LIST_TOKENS), roles: Roles })
+    .strict();
+const orderingShape = {
+    first: Token,
+    then: Token,
+    roles: Roles,
+};
+// Discriminated-union members must be plain objects, so the two cross-field
+// rules (ordering tokens differ; a wasm predicate validates) are applied in
+// `validateGuardrailIr` after the shape parse rather than as refinements here.
+const RequiresBeforeSchema = zod_1.z.object({ kind: zod_1.z.literal('requires_before'), ...orderingShape }).strict();
+const ForbidAfterSchema = zod_1.z.object({ kind: zod_1.z.literal('forbid_after'), ...orderingShape }).strict();
+const MaxCallsSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal('max_calls'),
+    token: Token,
+    limit: zod_1.z.number().int().min(1).max(exports.MAX_CALLS_LIMIT),
+    roles: Roles,
+})
+    .strict();
+const ForbidWithSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal('forbid_with'),
+    taint: zod_1.z.enum(['secrets()', 'pii()']),
+    token: Token,
+    roles: Roles,
+})
+    .strict();
+const WasmPredicateSchema = zod_1.z
+    .object({
+    kind: zod_1.z.literal('wasm_predicate'),
+    title: Title,
+    rationale: Rationale,
+    predicate: zod_1.z.unknown(),
+    verdict: zod_1.z.literal(3),
+    roles: Roles,
+})
+    .strict();
+const NoneSchema = zod_1.z.object({ kind: zod_1.z.literal('none'), reason: Rationale }).strict();
+exports.GuardrailIrSchema = zod_1.z.discriminatedUnion('kind', [
+    HookRuleSchema,
+    DenyToolsSchema,
+    ReviewBeforeSchema,
+    RequiresBeforeSchema,
+    ForbidAfterSchema,
+    MaxCallsSchema,
+    ForbidWithSchema,
+    WasmPredicateSchema,
+    NoneSchema,
+]);
+/** Every kind, in one place, for the lint gate (`check-guardrail-ir-keys.js`). */
+exports.IR_KINDS = [
+    'hook_rule',
+    'deny_tools',
+    'review_before',
+    'requires_before',
+    'forbid_after',
+    'max_calls',
+    'forbid_with',
+    'wasm_predicate',
+    'none',
+];
+/** The kinds that render to a SOP front-matter key the Rust proxy reads. */
+exports.FRONT_MATTER_KINDS = [
+    'deny_tools',
+    'review_before',
+    'requires_before',
+    'forbid_after',
+    'max_calls',
+    'forbid_with',
+];
+function isFrontMatterIr(ir) {
+    return exports.FRONT_MATTER_KINDS.includes(ir.kind);
+}
+/**
+ * Parse an untrusted value into the IR, or say why it is not one. Never
+ * throws. This — not `GuardrailIrSchema.parse` — is the entry point: the
+ * shape parse cannot express "the two ordering tokens differ" or "the wasm
+ * predicate is in the closed DSL", so both are checked here.
+ */
+function validateGuardrailIr(value) {
+    const parsed = exports.GuardrailIrSchema.safeParse(value);
+    if (!parsed.success) {
+        const first = parsed.error.issues[0];
+        const where = first?.path?.length ? `${first.path.join('.')}: ` : '';
+        return { ok: false, reason: `${where}${first?.message ?? 'not a guardrail IR'}` };
+    }
+    const ir = parsed.data;
+    if ((ir.kind === 'requires_before' || ir.kind === 'forbid_after') && ir.first === ir.then) {
+        return { ok: false, reason: `${ir.kind}: an ordering rule needs two different tokens` };
+    }
+    if (ir.kind === 'wasm_predicate') {
+        try {
+            (0, rulePredicateDsl_js_1.validatePredicate)(ir.predicate);
+        }
+        catch (err) {
+            return { ok: false, reason: `predicate: ${err instanceof Error ? err.message : String(err)}` };
+        }
+    }
+    return { ok: true, ir };
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort();
+}
+/**
+ * The identity of a control, as a stable string.
+ *
+ * Two proposals that name the same control from the same passage are one
+ * proposal — `policy_clauses` is unique on `(passage_hash, ir_canonical)` —
+ * so the title and rationale, which change nothing about what is enforced,
+ * are not part of it. Lists are sorted and deduplicated; roles are lower-case
+ * (the proxy lowercases them too); tool tokens keep their case (the proxy
+ * matches `Bash` case-sensitively).
+ */
+function canonicalizeIr(ir) {
+    const roles = ir.kind === 'none' ? undefined : ir.roles && ir.roles.length ? uniqueSorted(ir.roles.map((r) => r.toLowerCase())) : undefined;
+    let core;
+    switch (ir.kind) {
+        case 'hook_rule':
+            core = {
+                tools: uniqueSorted(ir.tools),
+                argContains: uniqueSorted(ir.argContains ?? []),
+                argNotContains: uniqueSorted(ir.argNotContains ?? []),
+            };
+            break;
+        case 'deny_tools':
+            core = { tools: uniqueSorted(ir.tools) };
+            break;
+        case 'review_before':
+            core = { tokens: uniqueSorted(ir.tokens) };
+            break;
+        case 'requires_before':
+        case 'forbid_after':
+            core = { first: ir.first, then: ir.then };
+            break;
+        case 'max_calls':
+            core = { token: ir.token, limit: ir.limit };
+            break;
+        case 'forbid_with':
+            core = { taint: ir.taint, token: ir.token };
+            break;
+        case 'wasm_predicate':
+            core = { predicate: ir.predicate, verdict: ir.verdict };
+            break;
+        case 'none':
+            core = {};
+            break;
+    }
+    return JSON.stringify({ kind: ir.kind, ...core, ...(roles ? { roles } : {}) }, sortedKeys);
+}
+function sortedKeys(_key, value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+    }
+    return value;
+}
+/** Every token (tool or action) an IR names — the set a validator must find in the cited passage. */
+function irTokens(ir) {
+    switch (ir.kind) {
+        case 'hook_rule':
+        case 'deny_tools':
+            return [...ir.tools];
+        case 'review_before':
+            return [...ir.tokens];
+        case 'requires_before':
+        case 'forbid_after':
+            return [ir.first, ir.then];
+        case 'max_calls':
+        case 'forbid_with':
+            return [ir.token];
+        case 'wasm_predicate':
+        case 'none':
+            return [];
+    }
+}
+//# sourceMappingURL=guardrailIr.js.map

package/dist/guardrailIr.js.map

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

package/dist/guardrailRender.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Guardrail renderers and their parsers (LLD #71).
+ *
+ * Two artifacts come out of the IR, and both are read by code this package
+ * does not own:
+ *
+ * - **Hook rules** become `{toolPattern, argPattern, reason}` — the shape
+ *   `services/sync-daemon/src/lib/policySnapshot.ts` turns into a
+ *   `policy-snapshot.rules` line and the emitted gate scripts match with
+ *   `new RegExp(toolPattern)` / `new RegExp(argPattern)` against the tool name
+ *   and `JSON.stringify(tool_input)`. The tool pattern must be portable ERE
+ *   (the daemon's `assertPortableEre` refuses `\s`, `(?`, anchors, …); the
+ *   argument pattern is exempt from that but must mean the same thing to JS
+ *   `RegExp` and Python `re`, because the bash gates delegate it to `python3`.
+ * - **Front-matter lines** become the YAML-ish block `packages/proxy/src/sops.rs`
+ *   parses with `parse_front_matter`. `parseFrontMatterEnforcing` below is a
+ *   line-for-line mirror of that parser's split semantics so a render can be
+ *   re-parsed and compared to the IR it came from — and so the cargo fixture
+ *   test can prove the Rust side reads the same fields.
+ *
+ * Every renderer is byte-stable: the same IR always yields the same bytes, so
+ * a rendered artifact is content-addressable and a reviewer diffing two
+ * versions sees only what changed.
+ *
+ * @module
+ */
+import { type GuardrailIr, type HookRuleIr, type FrontMatterIr } from './guardrailIr.js';
+export interface HookRuleCitation {
+    /** Verbatim quote from the cited passage. */
+    quote: string;
+    /** Deep link to the upstream document, or null when the provider has none. */
+    sourceUrl: string | null;
+}
+export interface RenderedHookRule {
+    toolPattern: string;
+    argPattern?: string;
+    reason: string;
+}
+/** Longest reason the gates print and the hook-events route accepts with margin (its cap is 512). */
+export declare const MAX_REASON_CHARS = 300;
+/** Longest quote embedded in a reason; truncated with an ellipsis beyond it. */
+export declare const MAX_QUOTE_IN_REASON = 200;
+/**
+ * Escape a literal for a regex that both JS `RegExp` (no flags) and Python
+ * `re` compile identically: every non-alphanumeric ASCII character is
+ * backslash-escaped, alphanumerics never are (`\d`-style escapes would mean
+ * something else). Non-ASCII characters are left alone — neither engine
+ * treats them as syntax.
+ */
+export declare function escapeRegexLiteral(literal: string): string;
+/**
+ * The tool half of a hook rule. Tokens are alternated inside one group; the
+ * only character a token may contain that is regex syntax is `.`, and it is
+ * escaped. Anchored, because two of the three consumers (`matchSopRule` and
+ * the MCP proxy's `matchRule`) test the pattern unanchored against the bare
+ * tool name — `Bash` would match `BashHistory` there. The daemon strips the
+ * anchors and wraps the pattern for whole-token matching itself, so all three
+ * read it as "exactly this tool".
+ */
+export declare function renderToolPattern(tools: readonly string[]): string;
+/**
+ * The argument half: one positive lookahead per required literal, one
+ * negative lookahead per forbidden literal, over the whole serialised input.
+ * `[\s\S]*` rather than `.*` so a multi-line argument (a heredoc in a Bash
+ * command) is still searched end to end. Undefined when there is nothing to
+ * say about the arguments.
+ */
+export declare function renderArgPattern(contains?: readonly string[], notContains?: readonly string[]): string | undefined;
+/**
+ * A whole SOP file around rendered front-matter lines: the shape the control
+ * plane projects a front-matter guardrail into `GET /api/v1/workspace/
+ * sops-policy` with, and the shape the parity fixtures under
+ * `fixtures/guardrail-ir/` are generated in — one function, so the cargo
+ * fixture test covers the projection byte for byte. `source:` and `cite:`
+ * are informational lines the proxy ignores; `mode: shadow` is the one it
+ * reads.
+ */
+export interface GuardrailSopFileInput {
+    /** The enforcing lines, as `renderFrontMatterLines` produced them. */
+    lines: string;
+    title: string;
+    /** Markdown body under the H1; the cited passage usually goes here as a quote. */
+    body: string;
+    sourceUrl?: string | null;
+    /** The passage hash the rule stands on. */
+    cite?: string | null;
+    shadow: boolean;
+}
+export declare function renderGuardrailSopFile(input: GuardrailSopFileInput): string;
+/** Tabs and newlines would break the `.rules` projection; collapse them. */
+export declare function scrubReason(text: string): string;
+/**
+ * The reason a developer sees on stderr when the rule fires:
+ * `<title> — policy: "<quote>" (<url>)`. The citation travels into the block
+ * message itself, which is the whole point of a grounded guardrail.
+ */
+export declare function renderHookReason(title: string, citation: HookRuleCitation): string;
+export declare function renderHookRule(ir: HookRuleIr, citation: HookRuleCitation): RenderedHookRule;
+/**
+ * The front-matter lines for a set of IRs — no fences, no `mode:`; the
+ * projection that ships them adds those. One line per rule for the pair
+ * keys (the Rust parser splits `requires_before:`/`forbid_after:`/`max_calls:`
+ * on commas but `forbid_with:` deliberately not, so one-per-line is the only
+ * shape that is right for all four), and one comma-joined line for the list
+ * keys. Deterministic: sorted, deduplicated, fixed key order.
+ */
+export declare function renderFrontMatterLines(irs: readonly FrontMatterIr[]): string;
+export interface ParsedFrontMatter {
+    roles: string[];
+    allowHarnesses: string[];
+    denyTools: string[];
+    planSteps: string[];
+    scopePaths: string[];
+    reviewBefore: string[];
+    /** `[first, then, adjacent]` — `adjacent` is true for `~>`. */
+    requiresBefore: Array<[string, string, boolean]>;
+    forbidAfter: Array<[string, string, boolean]>;
+    maxCalls: Array<[string, number]>;
+    forbidWith: Array<[string, string]>;
+    mode: 'shadow' | 'enforce';
+    /** Rules that failed to parse, in the Rust parser's own wording. */
+    errors: string[];
+}
+/**
+ * Split a document into the text between its `---` fences and the body,
+ * with the Rust parser's fallback contract: no fence, or an unterminated
+ * one, means the whole document is body and there is no front matter.
+ */
+export declare function splitFrontMatter(raw: string): {
+    front: string;
+    body: string;
+};
+/**
+ * Parse the text between the fences exactly as `parse_front_matter` in
+ * sops.rs does: a key is a line prefix, list keys split on commas and strip
+ * quotes/brackets, `requires_before`/`forbid_after` parse `A -> B`,
+ * `max_calls` parses `A <= N` (comma-split), `forbid_with` parses
+ * `taint(), token` (never comma-split), unknown keys are ignored, and an
+ * unparseable rule is reported rather than dropped.
+ */
+export declare function parseFrontMatterEnforcing(front: string): ParsedFrontMatter;
+/** Mirror of `is_enforceable`: does this front matter declare anything the proxy can act on? */
+export declare function isEnforceableFrontMatter(fm: ParsedFrontMatter): boolean;
+/**
+ * The IRs a parsed front matter expresses — the inverse of
+ * {@link renderFrontMatterLines} for the six generated keys. Allowlist keys
+ * (`allow_harnesses`, `plan_steps`, `scope_paths`) have no IR and are not
+ * returned; adjacency (`~>`) rules are returned as plain ordering rules,
+ * which is the only shape the IR offers.
+ */
+export declare function frontMatterToIrs(fm: ParsedFrontMatter): FrontMatterIr[];
+/** Render a mixed IR list's front-matter half; non-front-matter kinds are ignored. */
+export declare function frontMatterIrsOf(irs: readonly GuardrailIr[]): FrontMatterIr[];
+//# sourceMappingURL=guardrailRender.d.ts.map

package/dist/guardrailRender.d.ts.map

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