feat(peek): verify_audit_log MCP tool + peek audit bundle evidence archive

[harry-harish]

Summary

Makes peek's hash-chained action audit log verifiable in-loop by the agent and shareable as a portable evidence archive — extending the shipped audit log (#113).

• verify_audit_log (new, 17th MCP tool, read-only, no params): verifies ~/.peek/audit.log's hash chain and returns { logPresent, status, entriesVerified, …, summary } — status ∈ intact / broken / truncated / tail-tampered / prefix-tampered / incomplete-final / gaps / head-missing. verifyAuditChain was ported verbatim from @peekdev/cli into @peekdev/mcp's deliberately-duplicated native-host/audit-chain.ts (importing AuditHead, not re-declaring); the pinned known-answer vector test guards drift.
• peek audit bundle (new CLI): packages audit.log + audit.head.json into a portable *.peekaudit gzipped-tar archive with a SHA-256 integrity manifest + chain head. peek audit verify --bundle <file>: a receiver verifies archive integrity + the chain in one step.

Honesty / guardrails

Read-only, 100% local, no new egress/telemetry. Integrity is a SHA-256 manifest, not a signature, and there's no external timestamp anchor — messaging says "append-only, tamper-evident, not tamper-proof" everywhere. The audit log is value-free by design (verbs/selectors/prompts/timestamps, never values); the archive caveat says exactly what it does/doesn't contain.

Docs ripple (17th tool)

Skill 16→17 + verify_audit_log entry, re-copied to the plugin (byte-identical; check-plugin enforces), peek-mcp/peek-cli READMEs + recipe count sweep, and a new recipe verify-and-share-a-tamper-evident-audit-trail.

Test plan

• peek-mcp 382 + peek-cli 226 tests pass (new: verify cases, verify_audit_log tool, audit-bundle round-trip/tamper/formatVersion/head-sha, bundle + verify --bundle commands)
• full recursive pnpm test + build + lint + typecheck green
• verify-recipes (STRICT) + verify:plugin + claude plugin validate ./plugins/peek pass
• ported verifyAuditChain diff'd byte-identical vs the CLI; plugin SKILL.md byte-identical
• After merge: manual peek-docs Vercel redeploy (new recipe); optional hero asset for the recipe

Changesets: @peekdev/mcp minor + @peekdev/cli minor.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a new audit bundle command to package evidence into a portable archive and verify received archives.
  • Added a new read-only audit log integrity check tool for confirming whether the local audit chain is intact, broken, truncated, or incomplete.
  • Expanded the MCP tool surface from 16 to 17 tools.

• Documentation

  • Updated setup guides, CLI help text, and skill docs to reflect the new audit capabilities and tool count.

[harry-harish]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[harry-harish]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[harry-harish]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Caution

Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted.

Error details

{}

[harry-harish]

@coderabbitai full review

[coderabbitai]

✅ Action performed

Full review finished.

[coderabbitai]

Warning

Review limit reached

@harry-harish, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 55 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: c47b1054-414f-4ddf-baa7-23c70aa3228e

📥 Commits

Reviewing files that changed from the base of the PR and between 853b377 and 97dece0.

📒 Files selected for processing (10)

• apps/peek-docs/src/content/recipes/verify-and-share-a-tamper-evident-audit-trail.md
• packages/peek-cli/skills/peek-skill.md
• packages/peek-cli/src/commands/audit-verify.ts
• packages/peek-cli/src/lib/audit-bundle.ts
• packages/peek-cli/test/audit-verify.test.ts
• packages/peek-mcp/src/mcp/server.ts
• packages/peek-mcp/test/audit-chain.test.ts
• packages/peek-mcp/test/server.test.ts
• packages/peek-mcp/test/verify-audit-log.test.ts
• plugins/peek/skills/peek/SKILL.md

📝 Walkthrough

Walkthrough

Adds a hash-chain audit-log verification library (verifyAuditChain), a new read-only MCP tool verify_audit_log, CLI commands peek audit bundle and peek audit verify --bundle for creating/verifying portable *.peekaudit archives, plus tests and documentation updates reflecting the expanded 17-tool surface.

Changes

Audit verification and bundling

Layer / File(s)	Summary
Audit chain verification core packages/peek-mcp/src/native-host/audit-chain.ts, packages/peek-mcp/test/audit-chain.test.ts	Implements verifyAuditChain and verifySummary, validating prelude hashes, prev-hash chaining, gap tracking, and tail integrity, returning statuses like intact/broken/truncated/tail-tampered/gaps/incomplete-final/head-missing.
MCP verify_audit_log tool packages/peek-mcp/src/mcp/server.ts, packages/peek-mcp/test/{server,stdio-smoke,verify-audit-log}.test.ts	Registers a read-only tool that reads the audit log and stored head, verifies the chain, and returns JSON status; updates PEEK_MCP_TOOLS to 17 entries with corresponding test updates.
Portable .peekaudit archive library packages/peek-cli/src/lib/audit-bundle.ts, packages/peek-cli/test/audit-bundle.test.ts	Adds packAuditBundle, unpackAuditBundle, and verifyAuditBundleIntegrity building gzipped tar archives with SHA-256 manifest checksums and optional chain-head metadata.
CLI bundle and verify --bundle commands packages/peek-cli/src/commands/{audit-bundle,audit-verify,audit}.ts, packages/peek-cli/test/{audit-verify,audit}.test.ts	Adds runAuditBundle command and a --bundle <file> flag for runAuditVerify, wires bundle subcommand dispatch and usage text into audit.ts.
Documentation, changesets, and tool-count updates .changeset/*.md, apps/peek-docs/src/content/recipes/*, packages/peek-cli/README.md, packages/peek-cli/skills/peek-skill.md, packages/peek-mcp/README.md, plugins/peek/README.md, plugins/peek/skills/peek/SKILL.md	Adds changesets, a new recipe on verifying/sharing audit trails, and updates tool counts from 16 to 17 across READMEs and skill docs.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant CLI
  participant AuditBundleLib
  participant FileSystem

  User->>CLI: peek audit bundle --dir --out
  CLI->>FileSystem: read audit.log / audit.head.json
  CLI->>AuditBundleLib: packAuditBundle(outPath, input)
  AuditBundleLib-->>CLI: .peekaudit archive written

  User->>CLI: peek audit verify --bundle file
  CLI->>AuditBundleLib: unpackAuditBundle(bundlePath)
  AuditBundleLib-->>CLI: logBuf, headBuf
  CLI->>AuditBundleLib: verifyAuditBundleIntegrity
  CLI->>CLI: verifyAuditChain(logBuf, head)
  CLI-->>User: verification result

Loading

sequenceDiagram
  participant Client
  participant MCPServer
  participant FileSystem
  participant AuditChain

  Client->>MCPServer: call verify_audit_log
  MCPServer->>FileSystem: check audit.log exists
  FileSystem-->>MCPServer: logPresent status
  MCPServer->>FileSystem: read audit.log and head
  MCPServer->>AuditChain: verifyAuditChain(logBuf, head)
  AuditChain-->>MCPServer: VerifyResult
  MCPServer-->>Client: JSON result + summary

Loading

Possibly related PRs

• Cubenest/rrweb-stack#113: Builds on the same hash-chained audit-log verification primitives used by the new peek audit verify and verify_audit_log flows.
• Cubenest/rrweb-stack#133: Both PRs edit packages/peek-cli/skills/peek-skill.md's tool-surface documentation and tool count listings.

Poem

A rabbit checked its chain of hops,
No broken link, no gaps, no drops! 🐇
Bundled logs in a tidy sack,
SHA-256 seals the pack.
Seventeen tools now hop in a row—
Verified trails, wherever they go!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 42.86% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the two main additions: the verify_audit_log MCP tool and the peek audit bundle archive flow.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/peek-verify-audit-log

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 11

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In
`@apps/peek-docs/src/content/recipes/verify-and-share-a-tamper-evident-audit-trail.md`:
- Around line 77-80: The fenced block in the recipe content is missing a
language identifier, which causes markdownlint to fail. Update the markdown
fence around the audit trail output so it uses a valid language such as text or
console, keeping the existing content unchanged. Locate the fenced snippet in
the verify-and-share-a-tamper-evident-audit-trail.md recipe and adjust the fence
syntax only.
- Around line 75-80: The sample output in the audit verification recipe does not
match the actual CLI output from `peek audit verify --bundle`, so update this
block to use the literal wording emitted by the verifier or clearly mark it as
schematic. Locate the documentation snippet under the audit trail recipe and
adjust the displayed result to match the current human summary text produced by
the verification command.

In `@packages/peek-cli/skills/peek-skill.md`:
- Around line 84-88: The audit tool guidance in the peek skill incorrectly
suggests using verify_audit_log after receiving a bundle, but that tool only
checks the local audit log and cannot validate a .peekaudit file. Update the
wording around verify_audit_log in the skill docs so it is only described for
~/.peek/audit.log, and route bundle verification to the CLI flow via peek audit
verify --bundle <file> instead of the current “or after receiving one” phrasing.

In `@packages/peek-cli/src/commands/audit-verify.ts`:
- Around line 106-108: The bundled audit head parsing in audit-verify.ts can
throw before the integrity check handles failures. Update the head parsing
around unpacked.headBuf/JSON.parse in the verify flow so malformed bundled
audit.head.json is caught and converted into the same deterministic verify
failure behavior used by the --dir path. Keep the change scoped to the bundle
verification path and preserve the existing AuditHead handling.
- Around line 96-113: The `audit-verify` bundle path is mixing human text with
JSON output, breaking the `--bundle --json` contract. Update the
`verifyAuditBundle` flow in `audit-verify.ts` so `write('archive integrity
ok...')` and the `archive integrity FAILED...` message are only emitted for
non-JSON mode, and make the `verifyAuditBundleIntegrity`/`verifyAuditChain`
result path produce a single JSON document when `values.json` is set. Keep the
behavior consistent across the `values.bundle`, `values.json`,
`unpackAuditBundle`, and `verifyAuditChain` branches.

In `@packages/peek-cli/src/lib/audit-bundle.ts`:
- Around line 14-19: The current AUDIT_CAVEAT overstates the security guarantees
of the archive because the SHA-256 manifest is stored inside the same unsigned
bundle it verifies. Update AUDIT_CAVEAT in audit-bundle.ts to describe this as
internal corruption detection only, not tamper-evidence or proof of
authorship/time, and align any related messaging in verifyAuditBundleIntegrity
and audit bundle documentation/comments to reflect that a true integrity root
must come from outside the archive.

In `@packages/peek-cli/test/audit-verify.test.ts`:
- Around line 261-295: Add a regression test in audit-verify.test.ts that
exercises runAuditVerify with both --bundle and --json, so the bundle-specific
JSON output path is covered alongside the existing human-readable cases. Use the
existing helpers like chainLog, packAuditBundle, and runAuditVerify, then assert
the emitted JSON contains the expected archive/integrity status for a good
bundle and/or tampered bundle. Keep the new case near the current bundle tests
so the separate JSON branch in the audit verify command stays protected.

In `@packages/peek-mcp/src/mcp/server.ts`:
- Around line 999-1010: The audit status handler in mcp/server.ts is
short-circuiting on a missing log file before checking the head file. Update the
callback in the audit lookup path so it always reads audit.head.json and invokes
verifyAuditChain when audit.head.json exists, even if audit.log is missing. Use
the existing symbols defaultAuditLogPath, auditHeadPath, readHead, and
verifyAuditChain to return a tamper-detected result instead of the benign “no
audit log yet” response.

In `@packages/peek-mcp/test/audit-chain.test.ts`:
- Around line 61-119: Extend the verifyAuditChain coverage in
audit-chain.test.ts to hit the remaining branches: add a case that builds a
chain with a genuine gap so verifyAuditChain returns the gaps status, and add a
benign lagging-head case where the log has valid extra entries beyond the
supplied AuditHead and should still be reported as intact. Use the existing
chainLog and verifyAuditChain helpers to keep the tests aligned with the current
verifier behavior and assert the relevant status/metadata fields.

In `@packages/peek-mcp/test/server.test.ts`:
- Line 155: Update the test description in server.test.ts for the suite around
the documented tool surface so it matches the actual asserted count. The current
title on the it(...) block omits get_page_view and get_element_detail, so revise
the breakdown string to include those two read tools and reflect 17 total tools,
keeping the assertion and the named tool surface in sync.

In `@plugins/peek/skills/peek/SKILL.md`:
- Around line 84-88: The audit tool guidance in the Peek skill incorrectly tells
users to call verify_audit_log after receiving a bundle, but that tool only
checks the local audit log and cannot validate a .peekaudit file. Update the
text near the verify_audit_log entry in SKILL.md to remove the “or after
receiving one” wording and instead direct bundle checks to the CLI flow via peek
audit verify --bundle <file>, keeping the tool description accurate to its
scope.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: b15a5ffa-2fb2-476f-9f5a-fc1edb3e1826

📥 Commits

Reviewing files that changed from the base of the PR and between f9fc8c3 and 853b377.

📒 Files selected for processing (23)

• .changeset/peek-audit-bundle.md
• .changeset/peek-verify-audit-log.md
• apps/peek-docs/src/content/recipes/set-up-peek-with-claude-code.md
• apps/peek-docs/src/content/recipes/using-peek-with-your-agent.md
• apps/peek-docs/src/content/recipes/verify-and-share-a-tamper-evident-audit-trail.md
• packages/peek-cli/README.md
• packages/peek-cli/skills/peek-skill.md
• packages/peek-cli/src/commands/audit-bundle.ts
• packages/peek-cli/src/commands/audit-verify.ts
• packages/peek-cli/src/commands/audit.ts
• packages/peek-cli/src/lib/audit-bundle.ts
• packages/peek-cli/test/audit-bundle.test.ts
• packages/peek-cli/test/audit-verify.test.ts
• packages/peek-cli/test/audit.test.ts
• packages/peek-mcp/README.md
• packages/peek-mcp/src/mcp/server.ts
• packages/peek-mcp/src/native-host/audit-chain.ts
• packages/peek-mcp/test/audit-chain.test.ts
• packages/peek-mcp/test/server.test.ts
• packages/peek-mcp/test/stdio-smoke.test.ts
• packages/peek-mcp/test/verify-audit-log.test.ts
• plugins/peek/README.md
• plugins/peek/skills/peek/SKILL.md