Skip to content

wshobson/agents / plugins/protect-mcp/skills/protect-mcp-setup

protect-mcp-setup

Verified

Configure Cedar policy enforcement and Ed25519 signed receipts for Claude Code tool calls. Use when setting up projects that need cryptographic audit trails, policy-gated tool execution, or compliance-ready evidence of agent actions.

FileKindSize
SKILL.mdskill md8.7 KB
references/receipt-format.mdmarkdown4.2 KB

references/receipt-format.md

View on GitHub
# Receipt format written by protect-mcp 0.32.4

The hook appends one JSON object per line to the configured `receipts.jsonl`.
The signer uses a payload/signature envelope:

```json
{
  "payload": {
    "type": "protectmcp:decision",
    "tool_name": "Read",
    "decision": "allow",
    "reason": "post_execution_receipt",
    "policy_digest": "none",
    "request_id": "tu-example",
    "scope": "tu-example",
    "mode": "enforce",
    "spec": "draft-farley-acta-signed-receipts-03",
    "issuer_certification": "self-signed",
    "public_key": "<64-hex-public-key>",
    "issuer_name": "protect-mcp",
    "issued_at": "2026-11-03T00:00:00.000Z",
    "issuer_id": "generated"
  },
  "signature": { "alg": "EdDSA", "kid": "generated", "sig": "<128-hex-signature>" }
}
```

This is illustrative; the placeholders are not a valid signature. Ed25519
signs the RFC 8785 JCS-canonical **payload**, not the surrounding envelope.
Pass the signer's public key independently with `--key`; the signed
`payload.public_key` does not establish its own trustworthiness.

The hook passes only the tool name. It does not include raw input, output,
an input digest, or transcript metadata. `decision: allow` records a
post-execution observation; it does not prove which Cedar policy ran, the
arguments, the result, or successful execution. With no signer configuration
in `protect-mcp.json`, `policy_digest` is `none`.

## Chain coverage and migration

After the first receipt, `payload.previousReceiptHash` links to the previous
signed receipt: `sha256:` followed by the lowercase SHA-256 of the JCS of
that **whole receipt, signature included**. `@veritasacta/verify@0.11.1
--replay-chain` checks signatures and those links. Deleting or reordering an
interior linked receipt breaks the chain.

A truncated tail still verifies: no surviving successor names the missing
last receipt. The chain also cannot establish that every tool call was
recorded. Keep an externally retained checkpoint or copy to check completeness.

Existing 0.7.4 JSON keys remain usable; keep their identity and set their mode
to 0600. New receipts have `payload.tool_name`, `payload.reason`,
`payload.issued_at`, and an object `signature`; legacy receipts used a
`v: 2` envelope, `payload.tool`, `payload.reason_code`, and a string signature.
Update consumers to support both formats. Do not rewrite or re-sign old lines.

The verifier accepts mixed logs. The first new receipt can link to the last
legacy receipt, but earlier legacy lines have no links. Deletion or reordering
within that legacy portion can go undetected; the chain does not retrofit
integrity links onto it. Editing a legacy receipt's signed contents still
fails its own signature check. For a clear boundary between formats, move the
old log to an archive before upgrading and verify it with its original public key.

## Rotating the signing key

Move the old signing key and active receipt log to a secure archive before
creating a new key. Start a fresh `receipts.jsonl` for the new key. Verify
each log with its original public key and distribute the new public key
through a trusted channel. Never commit the private key.

Missing or unusable keys can make the CLI append an unsigned diagnostic line
and return `signed: false`. The hook reports that as an error with empty
stdout. Confirmation checks the persisted receipt's `request_id`, tool name,
and signature format; it does not verify the signature's cryptographic validity.
Independent verification with the trusted public key is required. The hook
preserves a failed signer's exit status and stderr. A PostToolUse error cannot
undo the completed tool call. Inspect the log to establish what was written,
and verify its receipts with the trusted public key.

Receipt confirmation reads backwards in 64 KiB chunks from one file-size
snapshot and stops at the matching receipt. A recent match therefore avoids
scanning the historical prefix; an absent match can still scan the whole
snapshot. This bounds the common confirmation path, not the signer's own
work. Bytes appended after the snapshot are ignored. The signer writes an
LF after each receipt, so an unterminated trailing fragment is not confirmed;
a complete matching receipt before that fragment can still be found.
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall