public-surface-audit

Files (2)

• SKILL.md
• SKILL_detail.md

SKILL.md (first lines)

# public-surface-audit — Operator-Private Token Leak Scan

Scans the git-tracked file set (the public surface) for operator-private tokens that were supposed
to stay in gitignored files (e.g. `CLAUDE.local.md`, companion store). After a public/private split,
a front-door fix is not enough — a leaked username or absolute home path anywhere in the tracked set
breaks the "public repo = model-agnostic methodology only" invariant.

> While `marketplace-gate` Check 5 answers "is this repo broadly safe to publish?" (API keys, internal
> domains, license), `public-surface-audit` answers a narrower question: "did any operator-private
> token survive the public/private split into a tracked file?" It scans `git ls-files` only — gitignored
> files like `CLAUDE.local.md` are intentionally out of scope (they are the *correct* home for these tokens).

## Triggers

- `/public-surface-audit`
- `/public-surface-audit --target <repo path>`
- `/public-surface-audit --json` (machine-parseable verdict for hook-gating — see Step 5)
- "Did I leak anything into the public repo?", "public surface audit", "private token scan"
- "Check tracked files for private tokens", "is my public/private split clean?"
- "Did any operator-private token survive into a tracked file?", "scan before publish"

---

## Scope — Tracked Files Only

This skill scans **only `git ls-files`** (committed/staged tracked files). Gitignored files are
deliberately excluded — `CLAUDE.local.md`, the companion store, and local session data are the
*correct* home for operator-private tokens, so finding them there is not a leak.

```bash
ARGS="${ARGUMENTS//--json/}"            # strip flags first — "--json" alone must not become the path
REPO_PATH="${ARGS#--target }"
REPO_PATH="$(printf '%s' "$REPO_PATH" | xargs)"
REPO_PATH="${REPO_PATH:-$(pwd)}"
git -C "$REPO_PATH" rev-parse --is-inside-work-tree >/dev/null 2>&1 \
  || { echo "Not a git repo — public-surface-audit scans git-tracked files only. Aborting."; exit 1; }
echo "Target: $REPO_PATH"
git -C "$REPO_PATH" ls-files | wc -l | xargs echo "Tracked files:"
```

---

## Step 1. Pattern List (configurable)

The pattern source is **two layers, matching the mechanical scan layer** (`scripts/psa_scan_lib.sh`,
shared with the pre-commit/pre-push/pre-publish hooks — this skill must render the same verdict the
hooks would, or the same repo state gets two answers):

1. **`.claude/rules/.public-surface-patterns.defaults`** — committed, universal placeholder-grade
   patterns (safe to publish; carries no operator literal).
2. **`.claude/rules/.public-surface-patterns`** — **gitignored, operator literals** (or `PSA_PATTERNS`
   env override). Your real username and employer name live *only* here — hardcoding them in a tracked
   file would leak exactly what this skill hunts. One `severity<TAB>regex` per line.

The scan reads the **union of both layers**. This SKILL.md carries only placeholders; the skill
dogfoods its own rule.

| # | Token class | Severity | Placeholder (real value goes in the gitignored source) | Why private |
|:-:|---|:-:|---|---|
| 1 | Real username | HIGH | `<your-unix-username>` | Personal identity — must not appear on public surface |
| 2 | Company / employer asset name | HIGH | `<company-asset>` (alternation OK) | Company-confidential, leak-forbidden |
| 3 | Operator absolute home path | MED | `/Users/[a-z0-9_-]+/` (generic — carries no literal name) | Machine-bound, leaks username + local layout |
| 4 | Companion-store name | LOW | `<companion-store-name>` | Private companion store — methodology should not name it |
| 5 | Operator-private script / handoff name | LOW | `<private-script>`, `<private-dir>/` | Operator-specific wiring, belongs in `CLAUDE.local.md` |

**Severity meaning**:
- **HIGH** — real name or company asset. A leak is a confidentiality / identity exposure. Block publish.
- **MED** — absolute home path. Leaks username + local filesystem layout; also a portability bug.
- **LOW** — companion-store / private-wiring name. Methodology should be model-agnostic; naming a private
  store is drift, not a confidentiality breach.

> **Setup**: put your real values in the gitignored override (one `severity<TAB>regex` per line).
> Degrade states, by layer — never collapse them:
> - **Neither layer present** → **NOT CONFIGURED** — *not* CLEAN. A missing pattern source must never
>   masquerade as a clean bill of health ("nothing scanned" misread as "nothing leaked").
> - **Defaults only** (override absent) → scan runs, but the verdict carries the label
>   `operator literals NOT CONFIGURED — universal patterns only; identity/company classes UNSCANNED`.
>   This mirrors what the hooks scan in the same state, instead of reporting NOT CONFIGURED while the
>   hook path quietly scans defaults (two verdicts for one repo state — the divergence this line closes).
> - To declare "I genuinely have no private tokens", create the override **empty** — an empty file is
>   an explicit declaration, an absent file is unconfigured.

---

## Step 2. Allowlist (legitimate references)

Some tracked files legitimately reference otherwise-private tokens — the scan must not flag these as
leaks. Maintain an allowlist of `file path :: token` pairs. A match is suppressed only when **both**
the file and the token are on the allowlist row.

**Where the filled allowlist lives**: a populated allowlist row *names private tokens*, so it belongs
in a **gitignored** source beside the pattern override (`.claude/rules/.public-surface-allowlist`, or a
section of `CLAUDE.local.md`) — never in a tracked file. The table below shows generic shapes only; a
tracked copy of your real allowlist would itself be the leak this skill scans for.

| Tracked file | Allowed tokens | Reason |
|---|---|---|
| `.gitignore` | companion-store name, sync-script name | Must name what it ignores |
| your sync script (e.g. `scripts/<sync-script>`) | companion-store name, operator-dir names, home path | The sync script's whole job is the companion store |
| an install-template rules file | home path, companion-store name | Install template — the install path is its content |
| a doc describing the companion-store *pattern* | the `*-be` pattern (no literal store name) | Documents the pattern generically |

**Allowlist rule**: a hit on file F matching token T is **suppressed** iff a row exists with file == F
and T in that row's allowed tokens. Everything else is reported. Keep the allowlist tight — when in
doubt, report and let the user confirm. Genuinely model-agnostic mentions (the `*-be` companion
*pattern* without the literal store name) should not require allowlisting because they do not match a
literal private token.

---

## Step 3. Scan

For each pattern in Step 1, grep the tracked set, then drop allowlisted hits. Do this for **every**
pattern row before producing the report — do not stop at the first HIT.

**Binary / generated carve-out**: skip binaries. Additionally note (do not auto-suppress) hits inside
generated artifacts (e.g. `paper/*.html` exported from a private source) — these are real leaks on the
public surface and must be reported, but the fix is "regenerate from a sanitized source," not "edit the
HTML by hand." Flag them with a `(generated artifact)` note.

From chrono-meta/forge-harness, MIT.

More from chrono-meta/forge-harness