# ClearedBadge

> Record an agent's final output as a hash, then let the recipient check the unchanged content against that record themselves. Human documentation: https://clrbadge-web.vercel.app/docs

## Record a final file (fingerprint only, once)

1. Make the final file first. Compute SHA-256 with code over exactly the bytes you will hand over (lowercase hex). Do not regenerate the file afterwards: a regenerated PDF usually has different bytes.
2. Record only that fingerprint, through one of:
   - the MCP tool `register_file_fingerprint` of the ClearedBadge connector (signed-in account, small quota): https://clrbadge-mcp.vercel.app/mcp
   - from code, without account or key: POST https://clrbadge-seven.vercel.app/record-file-hash with body exactly {"sha256":"<64 lowercase hex>"} (Content-Type text/plain). Public limits: 5 per connection per hour, 20 per day, 500 per day in total (HTTP 429 when reached; nothing is recorded). Example: https://clrbadge-web.vercel.app/examples/record-file-fingerprint/record_file.py
   - in a browser: https://clrbadge-web.vercel.app/record → Private → "Enter an existing SHA-256" → Create record. Creating a record accepts the Beta Terms and Privacy Policy; ask the user to confirm that.
3. On success, check that the returned `hash` equals your fingerprint. Hand over: the unchanged file, the record ID and the Verify link https://clrbadge-web.vercel.app/verify?id=<record_id>. Keep the engine's answer (or the receipt file) as the receipt. If you cannot pass the receipt file on, copy the "Receipt as text" block from the Record page exactly and say that it is copied.
4. ClearedBadge never receives the file and cannot tell which file a fingerprint belongs to. Never retry after an unknown outcome (rule 3 below).

## Record your final output as JSON (once)

1. Save the final output as one JSON object, e.g. `event.json`. Any fields; no schema is required.
   The JSON is sent to the ClearedBadge engine, which stores only its hash. Do not include secrets, and include personal data only if you are allowed to share it with a third-party service.
2. Record it through the ClearedBadge connector: the MCP tool `register_event`, after the user has signed in (see https://clrbadge-web.vercel.app/agents). Connector URL (remote MCP, Streamable HTTP, OAuth sign-in): https://clrbadge-mcp.vercel.app/mcp. Tested with the Claude desktop app and Gemini CLI. Each account has a small registration quota; registering does not charge the user, and verify uses no quota.
   POST https://clrbadge-seven.vercel.app/record-event is reserved for the ClearedBadge connector (a server credential); a direct request without it is refused (401 or 403) and records nothing.
   Do not upload JSON through the website's Record page: that creates a file record, checked byte for byte instead of as JSON.
3. Never retry a registration automatically. When the outcome is unknown (timeout, dropped connection, 5xx, or the tool says so), a record may exist; report "outcome unknown" instead of sending again. Investigate first (look for a receipt or a logged answer with a `record_id`; there is no public lookup of events by content); only the user decides to record again, which creates a separate record. For files, POST /verify-file without `?id=` looks a file up by its hash.
4. Do not change `event.json` after recording. Keep it together with the receipt.

## Hand over

Give the recipient, unchanged:
- `event.json`
- the record ID
- the Verify link: https://clrbadge-web.vercel.app/verify?id=<record_id>

## What you may claim

- "Recorded" only after a real 201 response. Never invent a record ID, hash or link.
- "Matches" only after the content was actually compared with the recorded hash.
- A match shows correspondence with the record. It does not prove the content is true, who the agent is, that it was authorised, or that the recipient received it.
- Arweave `submitted` is not confirmation. `confirmed` is reported by the ClearedBadge anchor service (at least 20 block confirmations and a payload hash check); reading that status is not an independent on-chain check.

## Check (read-only)

- GET https://clrbadge-seven.vercel.app/verify/<record_id> -> `badge_id`, `hash`, `created_at`, `record_type`, `actor_type`, `source`, `content_type`
- Names: `record_id` (from /record-event) and `badge_id` are the same identifier; `recorded_at` and `created_at` are the same time.
- The record decides the hashing method, never the file name:
  - `record_type` "file" (recorded via POST /upload or POST /record-file-hash): SHA-256 of the exact file bytes. `metadata.fingerprint_method` says who computed it: "server_sha256" (the engine, from the uploaded bytes) or "device_sha256" (the client; the engine only received the fingerprint). Missing on older records: not specified. The comparison is the same either way.
  - `record_type` "agent_commit" with `content_type` "application/json", `actor_type` "agent" and `source` null (recorded via POST /record-event): SHA-256 of the UTF-8 bytes of the RFC 8785 canonical JSON.
  - Anything else: do not guess; report that the method is unknown.
- RFC 8785: use an existing implementation, e.g. `canonicalize` (npm, by RFC 8785 co-author Erdtman; also served at https://clrbadge-web.vercel.app/vendor/canonicalize.js) or `rfc8785` (PyPI). Sorting keys alone is not RFC 8785.
- GET https://clrbadge-anchor.vercel.app/anchor-status/<record_id> -> `status`: not_anchored | submitted | confirmed | failed, with `latest.txid` and `latest.payload_sha256`. `not_anchored` with `not_started.reason` (submission_paused | daily_transaction_limit | daily_fee_limit | insufficient_balance | budget_config_invalid) means anchoring was deliberately not started: the record is stored and verifiable, but not anchored, and it is not retried automatically. Never report that as submitted or confirmed. `submission_paused` (no `since`): new records are currently not anchored on Arweave at all.
- Optional own on-chain check: GET https://arweave.net/raw/<txid> returns the payload bytes; their SHA-256 must equal `latest.payload_sha256`, and the payload must contain this `badge_id` and `sha256`. Confirmations: GET https://arweave.net/tx/<txid>/status (`number_of_confirmations`).

## Limits and cost

- Event body: max 1 MiB. File (POST /upload): max 4,000,000 bytes. Private file fingerprint (POST /record-file-hash): exactly {"sha256":"<64 lowercase hex>"}; the file itself is never sent.
- Recording is currently free. New records are kept in the ClearedBadge registry and are not anchored on Arweave for now; their recorded time is ClearedBadge's own record, not an independent timestamp. Record once per final output, not every step.
- Files on the website and POST /record-file-hash: public, no account. Limits per connection: 5 per hour and 20 per day; 500 per day in total; shared between /upload and /record-file-hash (HTTP 429 `rate_limited` when reached; nothing is recorded).
- Do not call /anchor/:id or /cron/anchor-pending.