@hasna/hooks 0.11.7 → 0.12.0

package/hooks/hook-signed-link-guard/README.md

@@ -0,0 +1,228 @@
+# signed-link-guard
+
+PreToolUse guard for shell commands, installed as `hooks run signed-link-guard`
+with the matcher `^(Bash|Monitor)$`. It judges Claude Code's `Bash` tool and its
+`Monitor` tool (Monitor runs a shell command and streams each stdout line to the
+model), and Codex's `Bash`. The bundled native safety entry
+(`hooks safety install trash-guard`) also evaluates it for every Bash and
+Monitor command, whatever capability name the registration uses.
+
+Composite GitHub content (bodies, comments, reviews, commit messages, check
+links and check details) carries third-party signed action links: URLs with a
+signature parameter, a multi-week expiry and no revoke path. A tool result stays
+in the agent's transcript, so a printed link is an exposed capability. This
+guard refuses a command before it runs when any `gh` invocation in it would
+print that content. The refusal reason is always exactly:
+
+```
+composite output withheld: signed-link shape; use bounded scalar projections per class disposition 799310
+```
+
+## What it refuses
+
+1. `gh pr view`, `gh issue view`, `gh release view`, `gh discussion view`:
+   - without `--json` (the human view prints the body), so a plain
+     `gh pr view <n>` is refused;
+   - with `--comments` / `-c`;
+   - with a `--json` field outside the scalar list below, unless a `--jq`
+     projection provably prints only bounded scalars.
+   `--web` / `-w` is allowed: it opens a browser and prints nothing. A flag's
+   last occurrence wins and `--web=false`, `-w=false` or `--web=0` is not set,
+   as gh's own flag parser reads them.
+2. `gh pr checks` without `--json` (the table prints check links, and so does
+   `--watch`), or with a `--json` field other than `bucket, completedAt, event,
+   name, startedAt, state, workflow` (`link` and `description` are refused)
+   unless a scalar `--jq` projection selects from them.
+3. `gh api` on REST endpoints that return bodies, comments, reviews, commit
+   messages, check runs or suites, statuses, events, deployment payloads or
+   issue and pull request objects:
+   - `repos/<o>/<r>/{pulls,issues,commits,check-runs,check-suites,statuses,
+     comments,releases,compare,events,discussions,deployments,milestones}`
+     (issue labels excepted);
+   - a single branch `repos/<o>/<r>/branches/<b>` (it carries the head
+     commit's message; the branch list, protection and rename endpoints do
+     not);
+   - `…/git/{commits,tags}`, `…/actions/{runs,jobs}` (logs excepted, see
+     below), `…/actions/workflows/<id>/runs`, webhook deliveries;
+   - `issues`, `user/issues`, `orgs/<o>/issues`, `search/{issues,commits}`,
+     user, org and network events, project items and cards, team
+     discussions.
+
+   The endpoint is normalised as the request reaches GitHub first: an
+   `https://api.github.com/` or GHES `/api/v3/` origin, the query string and
+   fragment are stripped, `%2F` and other escapes are decoded, `.` and `..`
+   are resolved and letters are lower-cased. Any other absolute URL (a
+   github.com page, a raw `.patch`) cannot be classified and is refused.
+4. `gh api graphql` queries selecting `body`, `bodyText`, `bodyHTML`,
+   `comments`, `reviews`, `reviewThreads`, commit `message*`,
+   `autoMergeRequest { commitBody commitHeadline }`, `summary`, `text`,
+   `description`, `annotations`, `payload`, `url` or any `*Url` / `*HTML`
+   field, and a check run's or status context's `title`. The query is read
+   with a GraphQL tokenizer, so strings, block strings and `#` comments are
+   not selections; an unbalanced query counts as sensitive.
+5. `gh api` writes whose response echoes the object: `PATCH` of an issue,
+   pull request, review or comment, and other writes on the families above.
+   Writes whose documented response is empty or scalar pass (GitHub REST
+   OpenAPI description 1.1.4): deleting a comment, reaction, label, release,
+   asset, run, deployment or milestone; re-running, cancelling or approving a
+   run or job; `PUT pulls/<n>/merge` (it returns `sha`, `merged` and a GitHub
+   status message) and `update-branch`; setting, adding or removing issue
+   labels; locking an issue. For the others use `--silent` or a scalar `--jq`.
+6. `gh api` reads of a sensitive family without `--silent` or a `--jq` / `-q`
+   projection the guard can prove prints only bounded scalars (see below).
+7. Other composite reads: `gh status` (it prints comment and mention
+   excerpts), `gh pr diff --patch` (each commit's full message), `gh project
+   item-list --format json` without a scalar `--jq`, and `--json` lists with a
+   composite field on `gh pr list`, `gh issue list`, `gh pr status`,
+   `gh issue status`, `gh search prs|issues|commits`, `gh release list` and
+   `gh discussion list`.
+8. Traffic logging. `GH_DEBUG` (any value except empty, `0`, `false` and `no`;
+   gh's legacy `DEBUG` for `1`, `true`, `yes` and `api`) and `gh api
+   --verbose` make gh log the raw HTTP responses whatever `--jq` or `--silent`
+   print. Under them a call passes only when it provably fetches no link field:
+   a view, list, status or search whose `--json` fields are all scalar, or a
+   `gh api` call on an endpoint outside the families above (logs endpoints
+   excepted). Every other gh command is refused under `GH_DEBUG`, writes and
+   `gh run` included; `gh pr checks` is always refused under it, because its
+   query fetches every check's `detailsUrl` whatever `--json` selects. The
+   variable is read from assignments in the command (`GH_DEBUG=api gh …`,
+   `export GH_DEBUG=1; gh …`, `env GH_DEBUG=1 gh …`).
+9. Fail closed: an endpoint, field list or query built from an expansion
+   (`$VAR`, `$( )`, a glob or brace list), a GraphQL query read from a file or
+   stdin, an unknown `gh` command (it may be an alias for a read above), an
+   unknown subcommand of `pr`, `issue`, `release`, `discussion` or `search`, a
+   read whose arguments `xargs` appends from stdin (`… | xargs gh pr view`),
+   and a command that cannot be parsed to its end while it mentions `gh`.
+
+## Scalar `--json` fields
+
+- Pull requests: `additions, assignees, author, baseRefName, baseRefOid,
+  changedFiles, closed, closedAt, createdAt, deletions, files, fullDatabaseId,
+  headRefName, headRefOid, headRepository, headRepositoryOwner, id,
+  isCrossRepository, isDraft, labels, maintainerCanModify, mergeCommit,
+  mergeStateStatus, mergeable, mergedAt, mergedBy, number,
+  potentialMergeCommit, reactionGroups, reviewDecision, reviewRequests, state,
+  title, updatedAt, url`.
+- Issues: `assignees, author, closed, closedAt, createdAt, id, isPinned,
+  labels, number, reactionGroups, state, stateReason, subIssuesSummary, title,
+  updatedAt, url`.
+- Releases: `apiUrl, author, createdAt, databaseId, id, isDraft, isImmutable,
+  isLatest, isPrerelease, name, publishedAt, tagName, tarballUrl,
+  targetCommitish, uploadUrl, url, zipballUrl`.
+
+The object's own `url` is allowed: GitHub generates it from the owner,
+repository and number, and it has no query string that could carry a
+signature. Labels are allowed because a label description is a repository
+setting capped at 100 characters. Refused composite fields include `body,
+comments, reviews, latestReviews, statusCheckRollup, commits,
+autoMergeRequest, closingIssuesReferences, closedByPullRequestsReferences,
+blockedBy, blocking, parent, subIssues, milestone, projectCards,
+projectItems, issueType, category, assets`, and any field a future gh adds.
+
+## `--jq` projections
+
+A `--jq` / `-q` filter admits a command when every output provably ends at a
+scalar, non-free-text field. This applies to `gh api`, to `gh project
+item-list --format json`, and to the `--json` commands above, where it admits
+a composite field: `gh pr view 12 --json body --jq '.body | length'` passes.
+Accepted examples: `.head.sha`, `.[] | .name`, `[.number, .title]`,
+`{number, state}`, `"\(.number) \(.title)"`, `.check_runs[] | [.name,
+.conclusion] | @tsv`, `.body | length`, `map(.name) | join(",")`,
+`.[] | select(.user.login == "x") | .id`, and on a single pull request or
+issue the counts `.commits`, `.comments` and `.review_comments`.
+
+Scalar leaves are identifiers, numbers, counts, booleans, enums, refs, object
+ids, timestamps and short names (`id`, `number`, `state`, `conclusion`,
+`name`, `login`, `sha`, `title`, `created_at`, `digest`, `size_in_bytes`,
+`run_started_at`, `date`, `wait_timer`, `ahead_by`, `behind_by`,
+`total_commits`, …) and `html_url`. `html_url` is admitted because in every
+response the guard refuses it is a GitHub-generated `github.com/<owner>/<repo>/…`
+page address with at most an anchor or a GitHub filter query; the schemas where
+someone else sets it (license, Pages site, dependency-snapshot job) are not
+among them. Other URL fields (`url`, `details_url`, `target_url`) stay refused.
+
+Refused: anything outside the supported jq subset (`..`, `if`, `reduce`,
+variables, `$ENV`, `input`, dynamic object keys, regular-expression functions
+with a non-literal pattern, `#` comments, which gojq continues across a
+backslash-newline), any whole object (`.`, `.head`, `.[]`), any free-text leaf
+(`.body`, `.output.summary`), anything projected out of a free-form container
+(`payload`, `inputs`, check `output`, `config`, …), and anything projected out
+of an object or array the filter built from a composite field
+(`{name: .body} | .name`, `[.body] | .[0]`). `--verbose` and `--template` void
+a projection.
+
+## Where commands can hide
+
+Command position is honoured (only a `gh` word in command position counts,
+after assignments, keywords and `env`, `sudo`, `timeout`, `nice`, `command`,
+`exec`, `nohup`, `time` and similar wrappers), and the guard follows:
+
+- pipelines, `&&`, `||`, `;`, subshells, `{ …; }` groups and `function`
+  bodies;
+- `$( … )` and backticks, also inside double quotes and unquoted
+  here-documents; a here-document body inside `$( )` is data, so the default
+  write spelling `gh pr comment 1 --body "$(cat <<'EOF' … EOF)"` passes
+  whatever the body says (apostrophes, an unbalanced `)`, nested quotes, or
+  the text of a refused command);
+- `bash|sh|zsh -c`, also when the string is built by `$(cat <<EOF …)` or
+  `$(echo …)`, `eval`, `env -S`, `su|runuser|script|flock -c`, `ssh <host>
+  <command>`, `gh codespace ssh … -- <command>` and `watch`;
+- text a shell reads as its script: literal `echo`, `printf` or `cat <<EOF`
+  output piped into `bash` or `sh`, here-documents and here-strings fed to a
+  shell, `source <(…)`, `. <(…)` and `. /dev/stdin`;
+- `xargs … gh …` and `find … -exec gh … ;`;
+- runners that pass a bare `gh` word on (`secrets exec … -- gh`, `op run --
+  gh`, `unbuffer gh`, `npx`, `bun x`, `docker`, …).
+
+A command word built by expansion is judged by its literal basename when it
+has one: `"$HOME/.bun/bin/tool" status` is not gh, `"$HOME/bin/gh" pr view 1`
+is. A word with no readable name (`$GH`, `"$(command -v gh)"`) is judged as gh.
+Any other program's `gh` argument is data: `node x.js gh pr view 1` is not a
+gh call.
+
+## Always allowed
+
+`gh pr diff` (without `--patch`), `gh pr list` / `gh issue list` tables,
+`gh pr view --json` with scalar fields, every `gh` write subcommand (`create`,
+`comment`, `edit`, `merge`, `review`, …; `--body` and `--body-file` are input,
+not output), `gh run`, `gh repo`, `gh workflow`, `gh release download`, `gh
+api` on other endpoints, `--help`, and every command that does not run `gh`.
+
+Workflow logs are allowed: `gh run view --log`, `--log-failed` and `gh api
+…/actions/runs/<id>/logs` or `…/actions/jobs/<id>/logs` print the
+repository's own step output, not the composite objects of this class, and
+the two routes are treated the same. They are downloads through a redirect to
+a signed storage URL that gh follows without printing; `--verbose` and
+`GH_DEBUG` print that redirect, so under them the logs endpoints are refused.
+
+## Scalar alternatives
+
+| Instead of | Use |
+|---|---|
+| `gh pr view 12` | `gh pr view 12 --json number,title,state,headRefOid,url` |
+| reading a body | `gh pr view 12 --json body --jq '.body \| length'`, or `gh pr view 12 --web` |
+| `gh pr checks 12` | `gh pr checks 12 --json name,state,bucket` |
+| failing checks | `gh pr checks 12 --json name,bucket --jq '.[] \| select(.bucket == "fail") \| .name'` |
+| `gh pr checks 12 --watch` | `gh run watch <run-id> --exit-status`, or poll `gh pr checks 12 --json bucket --jq '[.[] \| select(.bucket == "pending")] \| length'` |
+| `gh api repos/o/r/pulls/12` | `gh api repos/o/r/pulls/12 --jq .head.sha` |
+| `gh api -X PATCH repos/o/r/issues/12 -f state=closed` | the same with `--silent` |
+
+gh refuses `--watch` together with `--json`, so a scalar watch is a polling
+loop or `gh run watch`.
+
+## Limits
+
+- It judges the command text. A script file, a shell alias or function
+  defined in an earlier command or a startup file, a program that runs `gh`
+  itself (Python, Node, Perl, awk, `make`, a git alias) and a `gh` extension's
+  own output are not visible to it.
+- `GH_DEBUG` set in the harness's own environment, rather than in the
+  command, is not visible to it.
+- `curl`, `wget` and other HTTP clients calling `api.github.com` directly,
+  and `git log` or `git show` of a commit message, are outside its scope.
+- It is not the only exposure path: workflow logs, `gh pr diff`, file
+  contents and other tools can print a link that someone wrote there. The
+  optional `signed-link-output` PostToolUse hook is the backstop for output.
+- Codex's interactive terminal input (`write_stdin` into a running unified
+  exec session) has not been verified to pass through PreToolUse; a command
+  typed into a running shell that way may not be judged.

package/hooks/hook-signed-link-guard/package.json

@@ -0,0 +1,12 @@
+{
+  "name": "signed-link-guard",
+  "version": "0.1.0",
+  "description": "PreToolUse Signed Link Guard hook for @hasna/hooks",
+  "type": "module",
+  "main": "./src/hook.ts",
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "author": "Hasna",
+  "license": "Apache-2.0"
+}