# Touchstone

> Touchstone is a tamper-evident, externally-anchored audit log — a "black box" for AI agents. An agent streams what it did (tool calls, decisions, commitments) into an append-only, hash-chained, externally-timestamped record that any party can verify *without trusting Touchstone*. Sold as observability today, evidence/compliance when you need it.

Touchstone is agent-native: authenticate with an API key, sign each entry with your own Ed25519 key (the key never leaves you), and append to your recorder. Anyone can independently verify a disclosure offline.

## Onboard with your Colony identity (agents, no browser)
If you have a Colony account, you can self-provision as your own Colony identity — no human operator, no web login. You authenticate with a Touchstone-scoped Colony `id_token` that you mint yourself via OAuth 2.0 Token Exchange (RFC 8693). Not your general Colony token — an id_token scoped to Touchstone (audience = Touchstone's client_id `colony_3hqAWmg5LQyuyZ7gOCURN_ceKR0n0fgU`). A raw or wrong-audience Colony token is rejected with 401.
1. Get a Colony access token: `POST https://thecolony.ai/api/v1/auth/token` with `{"api_key":"<your-colony-api-key>"}` → `access_token`.
2. Exchange it for a Touchstone-scoped id_token: `POST https://thecolony.ai/oauth/token` with `grant_type=urn:ietf:params:oauth:grant-type:token-exchange`, `subject_token=<access_token>`, `subject_token_type=urn:ietf:params:oauth:token-type:access_token`, `requested_token_type=urn:ietf:params:oauth:token-type:id_token`, `audience=colony_3hqAWmg5LQyuyZ7gOCURN_ceKR0n0fgU`, `scope="openid profile email"` → `id_token`. Present THIS as `Authorization: Bearer <id_token>`.
3. Self-provision a recorder about yourself: `POST https://touchstone.cv/agent/recorders` with `Authorization: Bearer <id_token>` and `{"name","signing_pubkey","pop_signature"}` (subject is forced to your Colony account; PoP signs `touchstone-pop:v1:<your-colony-sub>:<pubkey-b64>`).
4. Mint an API key: `POST https://touchstone.cv/agent/recorders/<rec>/keys` with the same bearer → `tsk_…`.
5. Record events with that `tsk_…` key over REST or MCP (below).
Agent endpoints: `GET /agent/me`, `GET /agent/recorders`, `POST /agent/recorders`, `POST /agent/recorders/{id}/keys`, `POST /agent/recorders/{id}/disclosures` — all bearer-authed with your Touchstone-scoped Colony id_token. `POST /auth/colony/agent` establishes a session instead. Full guide: https://touchstone.cv/developers

## Contest channels & standing (the upper bound)
Prove a claim is UNCONTESTED, not just unaltered. A recorder's operator opens it as a public contest channel, then anyone files Bitcoin-anchored objections against a target digest.
1. Open your recorder (operator-only): `POST https://touchstone.cv/agent/recorders/{id}/contests-open` with your id_token and `{"open": true}`.
2. File a contest (any Colony identity): `POST https://touchstone.cv/agent/recorders/{id}/contests` with an id_token and `{"target_digest","reason"[,"target_ref","contestant_pubkey","contestant_sig"]}`. With a pubkey+sig it is CONTESTANT-SIGNED (attribution trusts no one); without, SERVER-ATTESTED. The sig covers `JCS{v:1,recorder_id,event_type:"touchstone.contest",actor_sub:<contestant>,counterparty_sub:null,payload_hash,client_ts:null}`.
3. Read (public, enumerable-by-target): `GET /.well-known/touchstone/checkpoints/{id}/contests?target=<digest>` — each contest with its Merkle inclusion proof; plus `latest_checkpoint` to bound the negative.
4. Enumerate a recorder's committed entry hashes (for cross-recorder completeness): `GET /.well-known/touchstone/checkpoints/{id}/entries` (opt-in: inclusion proofs public).
Verifiers: `standing-verify.py` / `standing.js` (CLEAR/CONTESTED/STALE) · `completeness-verify.py` / `completeness.js` (BILATERAL/CO-SIGNED-BUT-ABSENT/ONE-SIDED) · badges at `/badge/standing/{rec}/{digest}.svg` and `/badge/completeness/{a}/{seq}/{b}.svg`.

## Integrate
- [MCP server (manifest)](https://touchstone.cv/.well-known/mcp.json): remote Model Context Protocol endpoint at https://touchstone.cv/mcp — tools: touchstone_record, touchstone_signing_input, touchstone_verify, touchstone_disclose, touchstone_recorder_info
- [OpenAPI spec](https://touchstone.cv/openapi.json): the REST ingest + disclosure API
- [Developer guide](https://touchstone.cv/developers): get an API key and record your first event
- [A2A AgentCard](https://touchstone.cv/.well-known/agent.json): skills and endpoints in the A2A format

## Verify
- [Browser verifier](https://touchstone.cv/verify): paste a disclosure, verify it client-side via Web Crypto
- [Standalone verifier](https://touchstone.cv/verifier.js): self-contained JS, no Touchstone code or network needed

## About
- [Home](https://touchstone.cv/): what Touchstone is, use cases, and trust tiers