@coo-quack/sensitive-canary 0.4.6 → 0.5.0

package/.claude-plugin/marketplace.json

@@ -14,7 +14,7 @@
         "repo": "coo-quack/sensitive-canary"
       },
       "description": "Blocks secrets and PII before they reach the Anthropic API",
-      "version": "0.4.6",
+      "version": "0.5.0",
       "license": "MIT",
       "keywords": ["security", "secrets", "pii", "hooks"]
     }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "sensitive-canary",
   "description": "Blocks secrets and PII before they reach the Anthropic API",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "author": {
     "name": "coo-quack"
   },

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## v0.5.0 (2026-03-14)
+
+### Features
+
+- Add Google Cloud API Key (`gcp-api-key`) detection rule
+- Add npm Access Token (`npm-token`) detection rule
+
+### Fixes
+
+- Prevent `openai-key` (legacy) rule from overlapping with `openai-project-key` and `anthropic-key` via negative lookahead
+- Use nullish coalescing (`??`) in `entropy()` for correct semantics under `noUncheckedIndexedAccess`
+- Remove unreachable `unique` filter in `user-prompt-submit-hook`
+- Consolidate `randomBird()` calls in `block()` for consistent emoji across terminal and JSON output
+- Fix fd leaks in file read and `/dev/tty` write paths with `try/finally`
+- Use `bytesRead` return value from `fs.readSync` to avoid NUL-filled buffer tails
+- Scan text prefix before first NUL byte in binary files instead of skipping entirely
+
+### Performance
+
+- Read only the last 64 KB of transcript files for allow-tag resolution
+- Skip binary content after first NUL byte to avoid pointless regex scanning
+
+### Documentation
+
+- Unify documentation site structure with Getting Started and Troubleshooting pages
+- Symlink `docs/contributing.md` to root `CONTRIBUTING.md`
+
+---
+
 ## v0.4.6 (2026-03-12)
 
 ### Security

package/README.md

@@ -25,7 +25,7 @@ Claude Code is a powerful development tool, but file reads and command execution
 | `echo $API_KEY` with live key ❌ | Env var value scanned and blocked ✅ |
 
 - **Two hooks** — `UserPromptSubmit` and `PreToolUse` cover both directions of risk
-- **29 detection rules** — sourced from gitleaks and TruffleHog detector definitions
+- **31 detection rules** — sourced from gitleaks and TruffleHog detector definitions
 - **Entropy filtering** — reduces false positives on low-entropy values
 - **Luhn validation** — credit card numbers are validated, not just pattern-matched
 - **Local only** — all scanning runs in your terminal; nothing is sent anywhere
@@ -188,9 +188,9 @@ To allow it through, add the suggested tag:
 ```
 > Read .env
 
-📄 sensitive-canary: blocked — /path/to/.env
+🐤 sensitive-canary: blocked — /path/to/.env
 
-🐤  Blocked: .env and .env.* files contain secrets and must not be read into the conversation.
+🚫 Blocked: .env and .env.* files contain secrets and must not be read into the conversation.
 
 To allow this, the user must add an allow tag to their next prompt:
   [allow-secret]  — allow secrets
@@ -207,9 +207,9 @@ Non-`.env` files are also blocked if their contents contain secrets or PII.
 ```
 > Read config.yaml
 
-📄 sensitive-canary: blocked — /path/to/config.yaml
+🐤 sensitive-canary: blocked — /path/to/config.yaml
 
-🐤  Blocked: file contains sensitive data
+🚫 Blocked: file contains sensitive data
 
   [Secret] AWS Access Key ID (aws-access-key): AKIA****MPLE
 ```
@@ -230,15 +230,17 @@ To intentionally bypass a block, include the appropriate tag in your **current p
 
 ## Detection rules
 
-### Secrets (22 rules)
+### Secrets (24 rules)
 
 | Rule ID | Description |
 |---|---|
 | `aws-access-key` | AWS Access Key ID |
+| `gcp-api-key` | Google Cloud API Key |
 | `private-key` | PEM Private Key (RSA / EC / DSA / PGP / OpenSSH) |
 | `github-pat` | GitHub Personal Access Token |
 | `github-fine-grained` | GitHub Fine-Grained Token |
 | `gitlab-pat` | GitLab Personal Access Token |
+| `npm-token` | npm Access Token |
 | `slack-token` | Slack Token |
 | `slack-webhook` | Slack Webhook URL |
 | `discord-webhook` | Discord Webhook URL |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coo-quack/sensitive-canary",
-  "version": "0.4.6",
+  "version": "0.5.0",
   "description": "Claude Code hooks that block secrets and PII before they reach the Anthropic API",
   "homepage": "https://coo-quack.github.io/sensitive-canary/",
   "type": "module",

package/src/__tests__/pre-tool-use-hook.test.ts

@@ -245,6 +245,73 @@ describe("pre-tool-use-hook — sensitive content blocking", () => {
   });
 });
 
+// ── binary file handling ─────────────────────────────────────────────────────
+
+describe("pre-tool-use-hook — binary file handling", () => {
+  it("blocks when a secret appears before the first NUL byte", () => {
+    const content = Buffer.concat([
+      Buffer.from("key=AKIAIOSFODNN7EXAMPLE\n"),
+      Buffer.from([0x00]),
+      Buffer.from("binary data"),
+    ]);
+    const p = join(tmpDir, "binary-secret-before-nul.bin");
+    writeFileSync(p, content);
+    const { exitCode, decision } = runHook("Read", p);
+    expect(exitCode).toBe(2);
+    expect(decision).toBe("block");
+  });
+
+  it("allows a binary file when no secret appears before the first NUL byte", () => {
+    const content = Buffer.concat([
+      Buffer.from("clean text\n"),
+      Buffer.from([0x00]),
+      Buffer.from("AKIAIOSFODNN7EXAMPLE"),
+    ]);
+    const p = join(tmpDir, "binary-secret-after-nul.bin");
+    writeFileSync(p, content);
+    const { exitCode } = runHook("Read", p);
+    expect(exitCode).toBe(0);
+  });
+
+  it("allows a binary file that starts with NUL", () => {
+    const content = Buffer.concat([
+      Buffer.from([0x00]),
+      Buffer.from("AKIAIOSFODNN7EXAMPLE"),
+    ]);
+    const p = join(tmpDir, "binary-nul-start.bin");
+    writeFileSync(p, content);
+    const { exitCode } = runHook("Read", p);
+    expect(exitCode).toBe(0);
+  });
+});
+
+// ── transcript tail read ────────────────────────────────────────────────────
+
+describe("pre-tool-use-hook — transcript tail read (64 KB)", () => {
+  it("[allow-all] in a large transcript (>64KB) is respected when near the end", () => {
+    // Build a transcript larger than 64KB with the allow tag in the last message
+    const filler = JSON.stringify({
+      type: "user",
+      message: { role: "user", content: "x".repeat(1024) },
+    });
+    const fillerLines = Array.from({ length: 70 }, () => filler).join("\n");
+    const allowLine = JSON.stringify({
+      type: "user",
+      message: { role: "user", content: "[allow-all] read everything" },
+    });
+    const transcriptContent = `${fillerLines}\n${allowLine}\n`;
+    const tp = join(tmpDir, "large-transcript.jsonl");
+    writeFileSync(tp, transcriptContent, "utf8");
+
+    const p = writeFixture(
+      "large-transcript-test.txt",
+      "key=AKIAIOSFODNN7EXAMPLE\n",
+    );
+    const { exitCode } = runHook("Read", p, { transcriptPath: tp });
+    expect(exitCode).toBe(0);
+  });
+});
+
 // ── Bash tool — env var expansion ────────────────────────────────────────────
 
 describe("pre-tool-use-hook — Bash tool (env var expansion)", () => {

package/src/lib/__tests__/rules.test.ts

@@ -68,6 +68,26 @@ describe("scan — secrets", () => {
     expect(findings.some((f) => f.ruleId === "aws-access-key")).toBe(true);
   });
 
+  it("detects a GCP API key", () => {
+    const findings = scan(`key=AIzaSyC${"A".repeat(32)}`);
+    expect(findings.some((f) => f.ruleId === "gcp-api-key")).toBe(true);
+  });
+
+  it("does not flag a string starting with AIza but too short", () => {
+    const findings = scan("AIzaSyC_short");
+    expect(findings.some((f) => f.ruleId === "gcp-api-key")).toBe(false);
+  });
+
+  it("detects an npm access token", () => {
+    const findings = scan(`npm_${"A".repeat(36)}`);
+    expect(findings.some((f) => f.ruleId === "npm-token")).toBe(true);
+  });
+
+  it("does not flag npm_ with insufficient length", () => {
+    const findings = scan("npm_shorttoken");
+    expect(findings.some((f) => f.ruleId === "npm-token")).toBe(false);
+  });
+
   it("detects a PEM private key header (RSA)", () => {
     const findings = scan("-----BEGIN RSA PRIVATE KEY-----");
     expect(findings.some((f) => f.ruleId === "private-key")).toBe(true);
@@ -154,6 +174,16 @@ describe("scan — secrets", () => {
     expect(findings.some((f) => f.ruleId === "openai-key")).toBe(true);
   });
 
+  it("does not flag sk-proj-* as openai-key (legacy)", () => {
+    const findings = scan("sk-proj-Xk9mP2qR7vL4nW1sYj3cBz8dEf5gHiKoNpQuTxMn");
+    expect(findings.some((f) => f.ruleId === "openai-key")).toBe(false);
+  });
+
+  it("does not flag sk-ant-* as openai-key (legacy)", () => {
+    const findings = scan(`sk-ant-${"A".repeat(95)}`);
+    expect(findings.some((f) => f.ruleId === "openai-key")).toBe(false);
+  });
+
   it("detects an OpenAI project API key", () => {
     const findings = scan("sk-proj-Xk9mP2qR7vL4nW1sYj3cBz8dEf5gHiKoNpQuTxMn");
     expect(findings.some((f) => f.ruleId === "openai-project-key")).toBe(true);

package/src/lib/rules.ts

@@ -37,7 +37,7 @@ export function luhn(str: string): boolean {
 export function entropy(str: string): number {
   if (str.length === 0) return 0;
   const freq: Record<string, number> = {};
-  for (const ch of str) freq[ch] = (freq[ch] || 0) + 1;
+  for (const ch of str) freq[ch] = (freq[ch] ?? 0) + 1;
   let h = 0;
   const n = str.length;
   for (const count of Object.values(freq)) {
@@ -64,6 +64,12 @@ const SECRET_RULES: Rule[] = [
       /\b(A3T[A-Z0-9]|AKIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASIA)[A-Z0-9]{16}\b/g,
     category: "secret",
   },
+  {
+    id: "gcp-api-key",
+    description: "Google Cloud API Key",
+    regex: /AIza[0-9A-Za-z_-]{35}/g,
+    category: "secret",
+  },
   {
     id: "private-key",
     description: "PEM Private Key",
@@ -92,6 +98,14 @@ const SECRET_RULES: Rule[] = [
     category: "secret",
   },
 
+  // Package registries
+  {
+    id: "npm-token",
+    description: "npm Access Token",
+    regex: /npm_[A-Za-z0-9]{36}/g,
+    category: "secret",
+  },
+
   // Communication
   {
     id: "slack-token",
@@ -164,7 +178,7 @@ const SECRET_RULES: Rule[] = [
   {
     id: "openai-key",
     description: "OpenAI API Key (legacy)",
-    regex: /sk-[A-Za-z0-9]{48}/g,
+    regex: /sk-(?!proj-|ant-)[A-Za-z0-9]{48}/g,
     category: "secret",
   },
   {

package/src/pre-tool-use-hook.ts

@@ -25,6 +25,11 @@ interface TranscriptLine {
   message?: Message;
 }
 
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+// Maximum bytes to read from the tail of a transcript file.
+const MAX_TRANSCRIPT_TAIL_BYTES = 65_536; // 64 KB
+
 // ── Transcript ────────────────────────────────────────────────────────────────
 
 // Returns true when the message contains at least one text content block
@@ -42,7 +47,25 @@ function hasTextContent(msg: Message): boolean {
 function loadAllowTagsFromTranscript(transcriptPath: string): Set<string> {
   let raw: string;
   try {
-    raw = fs.readFileSync(transcriptPath, "utf8");
+    const stat = fs.statSync(transcriptPath);
+    if (stat.size <= MAX_TRANSCRIPT_TAIL_BYTES) {
+      raw = fs.readFileSync(transcriptPath, "utf8");
+    } else {
+      const buf = Buffer.alloc(MAX_TRANSCRIPT_TAIL_BYTES);
+      const fd = fs.openSync(transcriptPath, "r");
+      try {
+        const bytesRead = fs.readSync(
+          fd,
+          buf,
+          0,
+          MAX_TRANSCRIPT_TAIL_BYTES,
+          stat.size - MAX_TRANSCRIPT_TAIL_BYTES,
+        );
+        raw = buf.subarray(0, bytesRead).toString("utf8");
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
   } catch {
     return new Set();
   }
@@ -173,9 +196,10 @@ function block(
   detectionLines: string[],
   allowHints: string[],
 ): never {
+  const bird = randomBird();
   const terminalMessage = [
     "",
-    `${randomBird()} sensitive-canary: blocked — ${source}`,
+    `${bird} sensitive-canary: blocked — ${source}`,
     "",
     ...detectionLines,
     "",
@@ -183,13 +207,15 @@ function block(
 
   try {
     const fd = fs.openSync("/dev/tty", "w");
-    fs.writeSync(fd, terminalMessage);
-    fs.closeSync(fd);
+    try {
+      fs.writeSync(fd, terminalMessage);
+    } finally {
+      fs.closeSync(fd);
+    }
   } catch {
     process.stderr.write(terminalMessage);
   }
 
-  const bird = randomBird();
   const reasonLines = [
     `${bird} sensitive-canary blocked: ${source}`,
     "",
@@ -218,7 +244,7 @@ function scanFile(filePath: string, allowTags: Set<string>): void {
     block(
       filePath,
       [
-        `${randomBird()}  Blocked: .env and .env.* files contain secrets and must not be read into the conversation.`,
+        "🚫 Blocked: .env and .env.* files contain secrets and must not be read into the conversation.",
       ],
       buildAllowHints(`please read ${filePath}`, [], true),
     );
@@ -226,7 +252,13 @@ function scanFile(filePath: string, allowTags: Set<string>): void {
 
   let content: string;
   try {
-    content = fs.readFileSync(filePath, "utf8");
+    const raw = fs.readFileSync(filePath);
+    // Binary files: scan only the text prefix before the first NUL byte
+    const nulIndex = raw.indexOf(0);
+    content = (nulIndex === -1 ? raw : raw.subarray(0, nulIndex)).toString(
+      "utf8",
+    );
+    if (content.length === 0) return;
   } catch {
     return;
   }
@@ -237,7 +269,7 @@ function scanFile(filePath: string, allowTags: Set<string>): void {
   block(
     filePath,
     [
-      `${randomBird()}  Blocked: file contains sensitive data`,
+      "🚫 Blocked: file contains sensitive data",
       "",
       ...findingsToLines(findings),
     ],
@@ -281,7 +313,7 @@ process.stdin.on("end", () => {
       block(
         `bash command: ${command.slice(0, 80)}`,
         [
-          `${randomBird()}  Blocked: environment variable $${varName} contains sensitive data`,
+          `🚫 Blocked: environment variable $${varName} contains sensitive data`,
           "",
           ...findingsToLines(findings),
         ],
@@ -297,7 +329,7 @@ process.stdin.on("end", () => {
       block(
         `bash command: ${command.slice(0, 80)}`,
         [
-          `${randomBird()}  Blocked: bash command contains sensitive data`,
+          "🚫 Blocked: bash command contains sensitive data",
           "",
           ...findingsToLines(cmdFindings),
         ],

package/src/user-prompt-submit-hook.ts

@@ -76,22 +76,14 @@ process.stdin.on("end", () => {
     process.exit(2);
   }
 
-  const unique: Finding[] = afterAllow.filter(
-    (f) =>
-      !(f.category === "secret" && effectiveMask.has("secret")) &&
-      !(f.category === "pii" && effectiveMask.has("pii")),
-  );
-
-  if (unique.length === 0) process.exit(0);
-
-  const hasSecret = unique.some((f) => f.category === "secret");
-  const hasPii = unique.some((f) => f.category === "pii");
+  const hasSecret = afterAllow.some((f) => f.category === "secret");
+  const hasPii = afterAllow.some((f) => f.category === "pii");
 
   const blockLines = [
     "",
     `${randomBird()} sensitive-canary: sensitive data detected — blocked`,
     "",
-    ...findingsToLines(unique),
+    ...findingsToLines(afterAllow),
     "",
     "To allow, add a tag to your prompt:",
     ...(hasSecret ? ["  [allow-secret]  — allow secrets"] : []),