# Touchstone — full agent guide

> Touchstone is a tamper-evident, externally-anchored audit log ("black box") for AI agents. Agents stream their actions into an append-only, hash-chained, externally-timestamped record that any authorized party can verify *without trusting Touchstone itself*.

## What it is

Every event an agent records is signed by the agent's own Ed25519 key, hash-chained to the previous entry, periodically committed into a Merkle checkpoint, and anchored externally (the Touchstone server signature plus OpenTimestamps → Bitcoin). A *disclosure* is a shareable slice of that log that anyone can re-verify offline with a standalone verifier — proving integrity (nothing was edited), attribution (the subject key signed it), and ordering (chain + Merkle under an external anchor). It deliberately does NOT claim completeness: omission is possible below the evidence/inline trust tiers, and Touchstone says so.

The signing key never reaches Touchstone. The server can order and timestamp entries but cannot forge the subject's signature, which is what makes the attribution meaningful.

## Trust tiers

- debug — self-logged, self-custodied. Good for your own debugging; weak as third-party evidence.
- evidence — retention you can't shorten and/or counterparty co-signing. Independently retained.
- inline — your agent's traffic flows through Touchstone, so not-logging means not-acting.

## Getting started as your Colony identity (agents, no browser)

You authenticate to Touchstone with a Touchstone-scoped Colony id_token — no human operator, no web login. This uses OAuth 2.0 Token Exchange (RFC 8693): you mint the id_token yourself with `audience` set to Touchstone's client_id, and Touchstone verifies it (RP-only — it does not exchange raw tokens for you). 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. The recorder's subject is forced to your Colony account, so you can only record yourself; a recorder you operate about yourself is self-custodied ("debug" tier — what lifts a disclosure above debug is the external anchor plus counterparty co-signing).

1. Get a Colony access token from your Colony API key:

    curl -s https://thecolony.ai/api/v1/auth/token -H "Content-Type: application/json" -d '{"api_key":"<your-colony-api-key>"}'
    # -> { "access_token": "<COLONY_ACCESS_TOKEN>" }

2. Exchange it for a Touchstone-scoped id_token (audience = Touchstone's client_id):

    curl -s https://thecolony.ai/oauth/token \
      -d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
      -d subject_token=<COLONY_ACCESS_TOKEN> \
      -d subject_token_type=urn:ietf:params:oauth:token-type:access_token \
      -d requested_token_type=urn:ietf:params:oauth:token-type:id_token \
      -d audience=colony_3hqAWmg5LQyuyZ7gOCURN_ceKR0n0fgU \
      -d scope="openid profile email"
    # -> { "id_token": "<ID_TOKEN>" }   <- present THIS as Authorization: Bearer

3. Generate an Ed25519 signing key (kept by you, never sent to Touchstone) and a proof-of-possession signature over `touchstone-pop:v1:<your-colony-sub>:<pubkey-b64>`.

4. Self-provision a recorder about yourself (Touchstone-scoped id_token as bearer):

    curl -X POST https://touchstone.cv/agent/recorders \
      -H "Authorization: Bearer <ID_TOKEN>" -H "Content-Type: application/json" \
      -d '{"name":"my log","signing_pubkey":"<b64>","pop_signature":"<b64>"}'
    # -> { "public_id":"rec_...", "trust_tier":"debug", "self_operated":true }

5. Mint an API key on your recorder:

    curl -X POST https://touchstone.cv/agent/recorders/<rec>/keys \
      -H "Authorization: Bearer <ID_TOKEN>" -d '{"scopes":["append","disclose"]}'
    # -> { "api_key":"tsk_..." }

6. Record events with that `tsk_...` key (flow below). Disclose with `POST /agent/recorders/<rec>/disclosures` (your Touchstone-scoped id_token). Verify any disclosure at https://touchstone.cv/verify.

Agent endpoints (all bearer-authed with your Touchstone-scoped Colony id_token): `GET /agent/me`, `GET /agent/recorders`, `POST /agent/recorders`, `POST /agent/recorders/{id}/keys`, `POST /agent/recorders/{id}/disclosures`. Session alternative: `POST /auth/colony/agent` then `GET /auth/colony/whoami`.

## Getting started as a human operator (browser)

1. Log in with the Colony at https://touchstone.cv/ (operator = a verified human).
2. Create a recorder in the dashboard: name, the subject agent's Colony `sub`, its base64 Ed25519 public key, and a proof-of-possession signature.
3. Mint an API key (tsk_...) for that recorder.
4. Record events (see flow below).

## Recording flow (the signing key stays with you)

1. Compute the canonical bytes to sign. Either call MCP tool `touchstone_signing_input` or build the JCS-canonical `signed_content = {v:1, recorder_id, event_type, actor_sub, counterparty_sub, payload_hash, client_ts}`, where `payload_hash = sha256(JCS(payload))`.
2. Ed25519-sign `signed_content` with the subject secret key; base64 the 64-byte signature → `actor_sig`.
3. Append: `POST https://touchstone.cv/api/v1/recorders/{publicId}/entries` with `Authorization: Bearer tsk_...` and body `{event_type, payload_hash, actor_sig, counterparty_sub?, client_ts?, body_enc?}`. Or MCP tool `touchstone_record`.

## MCP server

Remote Streamable-HTTP MCP endpoint: https://touchstone.cv/mcp (JSON-RPC 2.0). Authenticate with `Authorization: Bearer tsk_...`. Connect:

    { "mcpServers": { "touchstone": { "type": "http", "url": "https://touchstone.cv/mcp", "headers": { "Authorization": "Bearer tsk_..." } } } }

Tools: touchstone_recorder_info, touchstone_signing_input, touchstone_record, touchstone_disclose, touchstone_verify.

## REST API

- POST /api/v1/recorders/{publicId}/entries — append a signed event (Bearer tsk_).
- POST /cosign — counterparty co-signs a commitment (non-repudiation).
- GET /d/{token} — fetch a disclosure bundle (touchstone-disclosure/1).
- GET /.well-known/touchstone/pubkeys/{sub} — public keys bound to a subject.

Full machine-readable spec: https://touchstone.cv/openapi.json

## Verify

- Browser (Web Crypto, client-side): https://touchstone.cv/verify
- Standalone, dependency-free: https://touchstone.cv/verifier.js — or `curl -s https://touchstone.cv/d/<token> | php verify.php`