@hasna/hooks 0.11.7 → 0.12.0

package/hooks/hook-signed-link-guard/src/hook.ts

@@ -0,0 +1,72 @@
+#!/usr/bin/env bun
+
+/**
+ * PreToolUse hook: signed-link-guard
+ *
+ * Refuses a shell command — Claude Code's `Bash` and `Monitor` tools (Monitor
+ * streams a command's stdout to the model) — when any `gh` invocation in it
+ * would print composite
+ * GitHub content — bodies, comments, reviews, commit messages, check links and
+ * details, raw issue/pull request/check objects — where third-party signed
+ * action links appear. The refusal happens before the command runs, so the
+ * content never reaches the agent's transcript. Bounded scalar reads pass:
+ * `gh pr view <n> --json number,state,headRefOid`, `gh pr checks <n> --json
+ * name,state,bucket`, `gh api … --jq <scalar projection>`, `gh pr diff`,
+ * `gh pr list`, and every write (`create`, `comment`, `merge`, …).
+ *
+ * The rules and the field classes live in ./classify.ts; the `--jq` proof in
+ * ./jq.ts. The reason string is fixed by the engineering decision for this
+ * class and is emitted verbatim.
+ *
+ * Output contract (the same narrow shape the native safety entry accepts):
+ *   - allowed  -> nothing on stdout
+ *   - refused  -> { hookSpecificOutput: { hookEventName: "PreToolUse",
+ *                  permissionDecision: "deny", permissionDecisionReason } }
+ *
+ * Fail-closed on its own defects: if classification throws, a command that
+ * mentions `gh` as a word is refused with the same reason, and any other
+ * command is left alone. Nothing about the command is written to stderr.
+ */
+
+import { getCommand, readInput, respond, type CodewithHookInput, type CodewithHookOutput } from "../../codewith-native-common";
+import { classifyCommand, SIGNED_LINK_REFUSAL } from "./classify";
+
+export { classifyCommand, SIGNED_LINK_REFUSAL } from "./classify";
+
+const GH_WORD = /(?:^|[^A-Za-z0-9_.-])gh(?:$|[^A-Za-z0-9_.-])/;
+
+function deny(): CodewithHookOutput {
+  return {
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: SIGNED_LINK_REFUSAL,
+    },
+  };
+}
+
+/** Tools whose `tool_input.command` is a shell command whose output reaches the model. */
+export const SHELL_TOOLS: ReadonlySet<string> = new Set(["Bash", "Monitor"]);
+
+/** Verdict for one hook input. `{ continue: true }` means "no decision". */
+export function evaluate(input: CodewithHookInput): CodewithHookOutput {
+  if (input?.hook_event_name !== "PreToolUse" || !SHELL_TOOLS.has(input.tool_name ?? "")) return { continue: true };
+  const command = getCommand(input);
+  if (!command.trim()) return { continue: true };
+  try {
+    return classifyCommand(command).refused ? deny() : { continue: true };
+  } catch {
+    return GH_WORD.test(command) ? deny() : { continue: true };
+  }
+}
+
+export async function run(): Promise<void> {
+  const verdict = evaluate(readInput());
+  // Silence is the documented no-op for Claude and Codex; emit only a decision.
+  if (!("continue" in verdict && verdict.continue === true)) respond(verdict);
+}
+
+if (import.meta.main) {
+  await run();
+  process.exit(0);
+}

package/hooks/hook-signed-link-guard/src/jq.ts

@@ -0,0 +1,545 @@
+/**
+ * Proof that a `--jq` / `-q` projection prints only bounded scalars.
+ *
+ * `gh api --jq <filter>` prints only what the filter selects, so a filter that
+ * provably ends every output at a scalar, non-free-text field keeps a
+ * composite response (a pull request, a comment list, a check run) out of the
+ * transcript. This module decides whether a filter is such a projection.
+ *
+ * It is a proof, not a guess: it accepts a deliberately small subset of the
+ * jq language and answers `false` for anything outside it. A `false` makes the
+ * guard refuse the command, so every unsupported construct fails closed.
+ *
+ * The analysis tracks the SHAPE of what each expression outputs:
+ *
+ *   - "safe"    literals, numbers, booleans, and values built only from
+ *               safe parts (an array or object whose members are all safe);
+ *   - leaf name the value of a field called `name` in the API response. It
+ *               is safe to print only when `name` is in SCALAR_FIELDS;
+ *   - "root"    the whole response. Like "unknown", but a field listed in the
+ *               caller's `rootScalars` (a count on a single pull request) is
+ *               safe when read directly from it;
+ *   - "unknown" arbitrary response JSON (the elements of an iteration, a whole
+ *               sub-object). Never safe to print;
+ *   - "tainted" a value the filter itself built from unsafe parts, or a
+ *               free-form container (`payload`, `inputs`, check `output`, …).
+ *               Its field names no longer describe its content, so nothing
+ *               projected out of it is safe: `{name: .body} | .name` is not.
+ *   - a union   the separate outputs of `,` and `//`.
+ *
+ * The final output of the filter must be safe. Field access on response data
+ * yields the named leaf, so `.[] | .name` is safe while `.`, `.[]`, `.head`
+ * and `.body` are not.
+ *
+ * Comments are refused: gojq continues a `#` comment across a
+ * backslash-newline, which a line-based reading would get wrong.
+ *
+ * Errors: a filter that errors prints gojq's error text, which carries at most
+ * a short fixed-length preview of the offending value (gojq truncates value
+ * previews), too short to hold a signed link. Functions whose error text can
+ * echo a whole string (regular-expression functions given a non-literal
+ * pattern) only accept literal arguments.
+ */
+
+export type Shape = "safe" | "unknown" | "root" | "tainted" | { leaf: string } | { union: Shape[] };
+
+export interface ProjectionOptions {
+  /** Fields that are plain scalars when read directly from the response root. */
+  rootScalars?: ReadonlySet<string>;
+}
+
+/**
+ * Field names whose values are scalars that are not free text: identifiers,
+ * numbers, counts, booleans, enums, refs, object ids, timestamps and short
+ * names. A title is single-line user text; it is admitted because the
+ * signed-link class is carried by bodies, comments, reviews, commit messages
+ * and check output, and a bounded title read is the documented alternative.
+ * URL-valued fields are NOT admitted: in a raw API response a field called
+ * `url` belongs to whatever object the path lands on, and some objects hold
+ * third-party URLs under generic names.
+ */
+export const SCALAR_FIELDS: ReadonlySet<string> = new Set([
+  "id", "node_id", "databaseId", "fullDatabaseId", "number", "state", "state_reason", "stateReason",
+  "status", "conclusion", "bucket", "name", "login", "sha", "oid", "abbreviatedOid", "ref",
+  "headRefName", "baseRefName", "headRefOid", "baseRefOid", "head_sha", "headSha", "head_branch", "headBranch",
+  "merged", "mergeable", "mergeable_state", "mergeStateStatus", "draft", "isDraft", "locked", "isLocked",
+  "title", "displayTitle", "display_title",
+  "created_at", "updated_at", "closed_at", "merged_at", "started_at", "completed_at", "submitted_at", "pushed_at", "published_at",
+  "createdAt", "updatedAt", "closedAt", "mergedAt", "startedAt", "completedAt", "submittedAt", "pushedAt", "publishedAt",
+  "tag_name", "tagName", "total_count", "totalCount", "count", "additions", "deletions", "changes",
+  "changed_files", "changedFiles", "filename", "path", "event", "workflow", "workflowName", "workflow_id",
+  "workflowDatabaseId", "run_id", "run_number", "run_attempt", "attempt", "check_suite_id",
+  "default_branch", "defaultBranch", "full_name", "fullName", "nameWithOwner", "private", "isPrivate",
+  "visibility", "archived", "isArchived", "fork", "isFork", "isRequired", "is_required", "required",
+  "context", "type", "__typename", "role", "permission", "size", "reviewDecision",
+  "author_association", "authorAssociation", "isCrossRepository", "maintainerCanModify", "maintainer_can_modify",
+  "commentsCount", "language",
+  // Artifacts, runs, deployments and comparisons (all numbers, booleans, digests or timestamps).
+  "digest", "size_in_bytes", "run_started_at", "date", "wait_timer", "ahead_by", "behind_by", "total_commits",
+  "expired", "current_user_can_approve", "environment",
+  // A GitHub-generated page address. In every response the guard refuses it is
+  // github.com/<owner>/<repo>/… with at most an anchor or a GitHub filter query
+  // (REST OpenAPI description 1.1.4); the schemas where someone else sets
+  // html_url (license, Pages site, dependency-snapshot job) are not among them.
+  "html_url",
+]);
+
+/** Containers whose keys are chosen by users or apps, so a key name says nothing about the value. */
+const FREEFORM: ReadonlySet<string> = new Set([
+  "payload", "client_payload", "inputs", "config", "metadata", "output", "properties", "custom_properties", "variables",
+]);
+
+/** Functions whose output carries no text from their input (numbers, booleans, nothing). */
+const OPAQUE_RESULT = new Set([
+  "length", "utf8bytelength", "not", "type", "any", "all", "isempty", "empty",
+  "test", "startswith", "endswith", "contains", "inside", "has", "in", "index", "rindex", "indices",
+  "floor", "ceil", "round", "fabs", "sqrt", "isinfinite", "isnan", "isnormal", "infinite", "nan",
+  "true", "false", "null",
+]);
+
+/** Functions whose output is (a re-encoding of) their input. */
+const PASSTHROUGH = new Set([
+  "tostring", "tojson", "ascii_downcase", "ascii_upcase", "ltrimstr", "rtrimstr", "trim", "ltrim", "rtrim",
+  "sort", "unique", "reverse", "first", "last", "min", "max", "add", "flatten", "join", "split",
+  "values", "nulls", "strings", "numbers", "booleans", "arrays", "objects", "iterables", "scalars",
+  "sort_by", "group_by", "unique_by", "min_by", "max_by", "select", "limit", "to_entries", "from_entries",
+]);
+
+/** Arguments of these functions must be literals: their error text can echo a whole argument. */
+const LITERAL_ARGS = new Set([
+  "test", "startswith", "endswith", "contains", "inside", "has", "in", "index", "rindex", "indices",
+  "ltrimstr", "rtrimstr", "join", "split", "flatten", "limit",
+]);
+
+const FORMATS = new Set(["@text", "@json", "@csv", "@tsv", "@sh", "@base64", "@uri", "@html"]);
+
+type Token =
+  | { t: "dot" }
+  | { t: "field"; name: string }
+  | { t: "str"; parts: Array<string | { src: string }> }
+  | { t: "num" }
+  | { t: "ident"; name: string }
+  | { t: "fmt"; name: string }
+  | { t: "op"; v: string };
+
+class Unprovable extends Error {}
+
+const fail = (): never => { throw new Unprovable(); };
+
+function readString(src: string, start: number): { end: number; parts: Array<string | { src: string }> } {
+  // src[start] === '"'
+  const parts: Array<string | { src: string }> = [];
+  let text = "";
+  let i = start + 1;
+  while (i < src.length) {
+    const ch = src[i];
+    if (ch === '"') { if (text) parts.push(text); return { end: i + 1, parts }; }
+    if (ch === "\\") {
+      const next = src[i + 1];
+      if (next === "(") {
+        // Interpolation: find the matching ')' outside nested strings.
+        let depth = 1;
+        let j = i + 2;
+        while (j < src.length && depth > 0) {
+          const c = src[j];
+          if (c === '"') { j = readString(src, j).end; continue; }
+          if (c === "(") depth++;
+          else if (c === ")") depth--;
+          j++;
+        }
+        if (depth !== 0) fail();
+        if (text) { parts.push(text); text = ""; }
+        parts.push({ src: src.slice(i + 2, j - 1) });
+        i = j;
+        continue;
+      }
+      if (next === undefined) fail();
+      text += next;
+      i += 2;
+      continue;
+    }
+    text += ch;
+    i++;
+  }
+  return fail();
+}
+
+function tokenize(src: string): Token[] {
+  const out: Token[] = [];
+  let i = 0;
+  const ops = ["?//", "|=", "+=", "-=", "*=", "/=", "%=", "//=", "==", "!=", "<=", ">=", "//", "|", ",", "+", "-", "*", "/", "%", "<", ">", "=", "(", ")", "[", "]", "{", "}", ":", ";", "?"];
+  while (i < src.length) {
+    const ch = src[i];
+    if (/\s/.test(ch)) { i++; continue; }
+    if (ch === "#") fail(); // comments are not supported (see the header)
+    if (ch === '"') { const s = readString(src, i); out.push({ t: "str", parts: s.parts }); i = s.end; continue; }
+    if (ch === ".") {
+      if (src[i + 1] === ".") fail(); // `..` recursion prints everything
+      const m = /^[A-Za-z_][A-Za-z0-9_]*/.exec(src.slice(i + 1));
+      if (m) { out.push({ t: "field", name: m[0] }); i += 1 + m[0].length; continue; }
+      if (src[i + 1] === '"') {
+        const s = readString(src, i + 1);
+        if (s.parts.some((p) => typeof p !== "string")) fail();
+        out.push({ t: "field", name: s.parts.join("") });
+        i = s.end;
+        continue;
+      }
+      out.push({ t: "dot" });
+      i++;
+      continue;
+    }
+    if (ch === "$" || ch === "@") {
+      const m = /^[@$][A-Za-z_][A-Za-z0-9_]*/.exec(src.slice(i));
+      if (!m || ch === "$") fail(); // variables ($ENV, $__loc__, bindings) are not supported
+      out.push({ t: "fmt", name: m![0] });
+      i += m![0].length;
+      continue;
+    }
+    const num = /^[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(src.slice(i));
+    if (num) { out.push({ t: "num" }); i += num[0].length; continue; }
+    const id = /^[A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*/.exec(src.slice(i));
+    if (id) { out.push({ t: "ident", name: id[0] }); i += id[0].length; continue; }
+    const op = ops.find((o) => src.startsWith(o, i));
+    if (!op) fail();
+    out.push({ t: "op", v: op! });
+    i += op!.length;
+  }
+  return out;
+}
+
+type Node =
+  | { k: "dot" }
+  | { k: "field"; name: string; of?: Node }
+  | { k: "iter"; of: Node }
+  | { k: "index"; of: Node; key: Node }
+  | { k: "slice"; of: Node }
+  | { k: "opt"; of: Node }
+  | { k: "lit" }
+  | { k: "str"; parts: Node[]; text?: string }
+  | { k: "fmt"; name: string; str?: Node }
+  | { k: "array"; of?: Node }
+  | { k: "object"; entries: Array<{ key: "static"; value: Node }> }
+  | { k: "call"; name: string; args: Node[] }
+  | { k: "pipe"; a: Node; b: Node }
+  | { k: "comma"; a: Node; b: Node }
+  | { k: "alt"; a: Node; b: Node }
+  | { k: "bool"; a: Node; b: Node }
+  | { k: "arith"; a: Node; b: Node }
+  | { k: "neg"; of: Node };
+
+/** Constructs outside the supported subset: control flow, bindings, I/O, recursion and path rewriting. */
+const REJECTED_KEYWORDS = new Set(["if", "then", "elif", "else", "end", "as", "def", "reduce", "foreach", "try", "catch", "label", "import", "include", "and", "or", "__loc__", "error", "input", "inputs", "debug", "stderr", "env", "halt", "halt_error", "input_filename", "input_line_number", "recurse", "paths", "leaf_paths", "getpath", "setpath", "delpaths", "del", "path", "splits", "sub", "gsub", "capture", "match", "scan", "keys", "keys_unsorted", "map_values", "with_entries", "tostream", "fromstream", "truncate_stream", "walk", "tonumber", "implode", "explode", "ascii", "fromjson"]);
+
+class Parser {
+  private at = 0;
+  constructor(private readonly tokens: Token[]) {}
+
+  parse(): Node {
+    if (this.tokens.length === 0) fail();
+    const node = this.pipe();
+    if (this.at !== this.tokens.length) fail();
+    return node;
+  }
+
+  private peek(): Token | undefined { return this.tokens[this.at]; }
+  private isOp(v: string): boolean { const t = this.peek(); return !!t && t.t === "op" && t.v === v; }
+  private isIdent(v: string): boolean { const t = this.peek(); return !!t && t.t === "ident" && t.name === v; }
+  private expectOp(v: string): void { if (!this.isOp(v)) fail(); this.at++; }
+
+  pipe(): Node {
+    let node = this.comma();
+    if (this.isIdent("as")) fail();
+    if (this.isOp("|")) { this.at++; node = { k: "pipe", a: node, b: this.pipe() }; }
+    return node;
+  }
+
+  private comma(): Node {
+    let node = this.alt();
+    while (this.isOp(",")) { this.at++; node = { k: "comma", a: node, b: this.alt() }; }
+    return node;
+  }
+
+  private alt(): Node {
+    const node = this.or();
+    if (this.isOp("//")) { this.at++; return { k: "alt", a: node, b: this.alt() }; }
+    return node;
+  }
+
+  private or(): Node {
+    let node = this.and();
+    while (this.isIdent("or")) { this.at++; node = { k: "bool", a: node, b: this.and() }; }
+    return node;
+  }
+
+  private and(): Node {
+    let node = this.cmp();
+    while (this.isIdent("and")) { this.at++; node = { k: "bool", a: node, b: this.cmp() }; }
+    return node;
+  }
+
+  private cmp(): Node {
+    const node = this.add();
+    for (const v of ["==", "!=", "<=", ">=", "<", ">"]) {
+      if (this.isOp(v)) { this.at++; return { k: "bool", a: node, b: this.add() }; }
+    }
+    for (const v of ["=", "|=", "+=", "-=", "*=", "/=", "%=", "//=", "?//"]) if (this.isOp(v)) fail();
+    return node;
+  }
+
+  private add(): Node {
+    let node = this.mul();
+    while (this.isOp("+") || this.isOp("-")) { this.at++; node = { k: "arith", a: node, b: this.mul() }; }
+    return node;
+  }
+
+  private mul(): Node {
+    let node = this.unary();
+    while (this.isOp("*") || this.isOp("/") || this.isOp("%")) { this.at++; node = { k: "arith", a: node, b: this.unary() }; }
+    return node;
+  }
+
+  private unary(): Node {
+    if (this.isOp("-")) { this.at++; return { k: "neg", of: this.postfix() }; }
+    return this.postfix();
+  }
+
+  /** Object values: jq admits a term or a pipe of terms without commas. */
+  private objectValue(): Node {
+    let node = this.unary();
+    if (this.isOp("|")) { this.at++; node = { k: "pipe", a: node, b: this.objectValue() }; }
+    return node;
+  }
+
+  private postfix(): Node {
+    let node = this.primary();
+    for (;;) {
+      const t = this.peek();
+      if (!t) return node;
+      if (t.t === "field") { this.at++; node = { k: "field", name: t.name, of: node }; continue; }
+      if (t.t === "dot" && this.tokens[this.at + 1]?.t === "op" && (this.tokens[this.at + 1] as { v: string }).v === "[") {
+        this.at++;
+        continue; // `.[...]` after a term is the same as `[...]`
+      }
+      if (t.t === "op" && t.v === "?") { this.at++; node = { k: "opt", of: node }; continue; }
+      if (t.t === "op" && t.v === "[") { node = this.bracket(node); continue; }
+      return node;
+    }
+  }
+
+  private bracket(of: Node): Node {
+    this.expectOp("[");
+    if (this.isOp("]")) { this.at++; return { k: "iter", of }; }
+    if (this.isOp(":")) { this.at++; if (!this.isOp("]")) this.pipe(); this.expectOp("]"); return { k: "slice", of }; }
+    const key = this.pipe();
+    if (this.isOp(":")) { this.at++; if (!this.isOp("]")) this.pipe(); this.expectOp("]"); return { k: "slice", of }; }
+    this.expectOp("]");
+    return { k: "index", of, key };
+  }
+
+  private primary(): Node {
+    const t = this.peek();
+    if (!t) return fail();
+    this.at++;
+    switch (t.t) {
+      case "dot": return { k: "dot" };
+      case "field": return { k: "field", name: t.name };
+      case "num": return { k: "lit" };
+      case "str": return this.stringNode(t.parts);
+      case "fmt": {
+        if (!FORMATS.has(t.name)) fail();
+        const next = this.peek();
+        if (next?.t === "str") { this.at++; return { k: "fmt", name: t.name, str: this.stringNode(next.parts) }; }
+        return { k: "fmt", name: t.name };
+      }
+      case "ident": {
+        if (REJECTED_KEYWORDS.has(t.name)) fail();
+        if (t.name === "map" || OPAQUE_RESULT.has(t.name) || PASSTHROUGH.has(t.name)) {
+          const args: Node[] = [];
+          if (this.isOp("(")) {
+            this.at++;
+            args.push(this.pipe());
+            while (this.isOp(";")) { this.at++; args.push(this.pipe()); }
+            this.expectOp(")");
+          }
+          return { k: "call", name: t.name, args };
+        }
+        return fail();
+      }
+      case "op": {
+        if (t.v === "(") { const inner = this.pipe(); this.expectOp(")"); return inner; }
+        if (t.v === "[") {
+          if (this.isOp("]")) { this.at++; return { k: "array" }; }
+          const inner = this.pipe();
+          this.expectOp("]");
+          return { k: "array", of: inner };
+        }
+        if (t.v === "{") return this.object();
+        return fail();
+      }
+    }
+    return fail();
+  }
+
+  private stringNode(parts: Array<string | { src: string }>): Node {
+    const nodes: Node[] = [];
+    for (const part of parts) {
+      if (typeof part === "string") continue;
+      nodes.push(new Parser(tokenize(part.src)).parse());
+    }
+    return nodes.length === 0 ? { k: "str", parts: nodes, text: parts.join("") } : { k: "str", parts: nodes };
+  }
+
+  private object(): Node {
+    const entries: Array<{ key: "static"; value: Node }> = [];
+    if (this.isOp("}")) { this.at++; return { k: "object", entries }; }
+    for (;;) {
+      const t = this.peek();
+      if (!t) fail();
+      this.at++;
+      let shorthand: string | undefined;
+      if (t!.t === "ident") shorthand = t!.name;
+      else if (t!.t === "str") {
+        if (t!.parts.some((p) => typeof p !== "string")) fail(); // dynamic keys can carry values
+        shorthand = t!.parts.join("");
+      } else fail(); // `$var` and `(expr)` keys are not supported
+      if (this.isOp(":")) { this.at++; entries.push({ key: "static", value: this.objectValue() }); }
+      else entries.push({ key: "static", value: { k: "field", name: shorthand! } });
+      if (this.isOp(",")) { this.at++; continue; }
+      this.expectOp("}");
+      return { k: "object", entries };
+    }
+  }
+}
+
+export function isFinalSafe(shape: Shape): boolean {
+  if (typeof shape === "object" && "union" in shape) return shape.union.every(isFinalSafe);
+  return shape === "safe" || (typeof shape === "object" && SCALAR_FIELDS.has(shape.leaf));
+}
+
+/** A value built from parts: safe only when every part is. */
+const combine = (...shapes: Shape[]): Shape => (shapes.every(isFinalSafe) ? "safe" : "tainted");
+
+function union(...shapes: Shape[]): Shape {
+  const flat: Shape[] = [];
+  for (const shape of shapes) {
+    if (typeof shape === "object" && "union" in shape) flat.push(...shape.union);
+    else flat.push(shape);
+  }
+  return flat.length === 1 ? flat[0] : { union: flat };
+}
+
+/** Apply `f` to every member of a union. */
+function each(shape: Shape, f: (member: Shape) => Shape): Shape {
+  return typeof shape === "object" && "union" in shape ? union(...shape.union.map(f)) : f(shape);
+}
+
+const isFreeform = (shape: Shape) => typeof shape === "object" && "leaf" in shape && FREEFORM.has(shape.leaf);
+
+/** An element of `shape` (iteration, a numeric index, min/max/first/last). */
+const element = (shape: Shape): Shape => each(shape, (member) =>
+  member === "safe" ? "safe" : member === "tainted" || isFreeform(member) ? "tainted" : "unknown");
+
+function literalArg(node: Node): boolean {
+  return node.k === "lit" || (node.k === "str" && node.parts.length === 0) || (node.k === "call" && ["true", "false", "null"].includes(node.name) && node.args.length === 0);
+}
+
+interface Scope { rootScalars: ReadonlySet<string> }
+
+function field(shape: Shape, name: string, scope: Scope): Shape {
+  return each(shape, (member) => {
+    if (member === "safe" || member === "tainted") return member;
+    if (isFreeform(member)) return "tainted";
+    if (member === "root" && scope.rootScalars.has(name)) return "safe";
+    return { leaf: name };
+  });
+}
+
+function evaluate(node: Node, input: Shape, scope: Scope): Shape {
+  switch (node.k) {
+    case "dot": return input;
+    case "field": return field(node.of ? evaluate(node.of, input, scope) : input, node.name, scope);
+    case "iter": return element(evaluate(node.of, input, scope));
+    case "index": {
+      const base = evaluate(node.of, input, scope);
+      if (node.key.k === "str" && node.key.text !== undefined) return field(base, node.key.text, scope); // .["name"] is .name
+      if (node.key.k === "lit") return element(base);
+      evaluate(node.key, input, scope);
+      return "tainted"; // a computed key: which field is read is not known
+    }
+    case "slice": return each(evaluate(node.of, input, scope), (member) => (member === "root" ? "unknown" : isFreeform(member) ? "tainted" : member));
+    case "opt": return evaluate(node.of, input, scope);
+    case "lit": return "safe";
+    case "str": return combine(...node.parts.map((part) => evaluate(part, input, scope)));
+    case "fmt": return node.str ? evaluate(node.str, input, scope) : input;
+    case "array": return node.of ? combine(evaluate(node.of, input, scope)) : "safe";
+    case "object": return combine(...node.entries.map((entry) => evaluate(entry.value, input, scope)));
+    case "pipe": return evaluate(node.b, evaluate(node.a, input, scope), scope);
+    case "comma": return union(evaluate(node.a, input, scope), evaluate(node.b, input, scope));
+    case "alt": return union(evaluate(node.a, input, scope), evaluate(node.b, input, scope));
+    case "bool": evaluate(node.a, input, scope); evaluate(node.b, input, scope); return "safe";
+    case "arith": return combine(evaluate(node.a, input, scope), evaluate(node.b, input, scope));
+    case "neg": return evaluate(node.of, input, scope);
+    case "call": return evaluateCall(node, input, scope);
+  }
+}
+
+/** A function whose output re-encodes its input: the whole response stops being the root. */
+const passthrough = (input: Shape): Shape => each(input, (member) => (member === "root" ? "unknown" : isFreeform(member) ? "tainted" : member));
+
+function evaluateCall(node: Extract<Node, { k: "call" }>, input: Shape, scope: Scope): Shape {
+  const { name, args } = node;
+  if (LITERAL_ARGS.has(name) && name !== "limit" && !args.every(literalArg)) fail();
+  switch (name) {
+    case "map":
+      if (args.length !== 1) fail();
+      return combine(evaluate(args[0], element(input), scope));
+    case "select":
+      if (args.length !== 1) fail();
+      evaluate(args[0], input, scope);
+      return input;
+    case "limit":
+      if (args.length !== 2 || !literalArg(args[0])) fail();
+      return evaluate(args[1], input, scope);
+    case "first":
+    case "last":
+      if (args.length > 1) fail();
+      return args.length === 1 ? evaluate(args[0], input, scope) : element(input);
+    case "min":
+    case "max":
+      return element(input);
+    case "sort_by":
+    case "group_by":
+    case "unique_by":
+      if (args.length !== 1) fail();
+      evaluate(args[0], element(input), scope);
+      return passthrough(input);
+    case "min_by":
+    case "max_by":
+      if (args.length !== 1) fail();
+      evaluate(args[0], element(input), scope);
+      return element(input);
+    case "any":
+    case "all":
+    case "isempty":
+      for (const arg of args) evaluate(arg, "unknown", scope);
+      return "safe";
+  }
+  if (OPAQUE_RESULT.has(name)) return "safe";
+  if (PASSTHROUGH.has(name)) return passthrough(input);
+  return fail();
+}
+
+/**
+ * Whether `filter` provably prints only bounded scalars. Any construct outside
+ * the supported subset, and any parse failure, answers false.
+ */
+export function jqProjectionIsScalar(filter: string, options: ProjectionOptions = {}): boolean {
+  if (typeof filter !== "string" || !filter.trim() || filter.length > 4096) return false;
+  try {
+    const node = new Parser(tokenize(filter)).parse();
+    return isFinalSafe(evaluate(node, "root", { rootScalars: options.rootScalars ?? new Set() }));
+  } catch (error) {
+    if (error instanceof Unprovable) return false;
+    return false;
+  }
+}