# 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 your own Colony token — no human operator, no web login. This uses OAuth 2.0 Token Exchange (RFC 8693): you present your Colony token and Touchstone trades it for a verified Colony identity. 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 token from your Colony API key:

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

2. 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>`.

3. Self-provision a recorder about yourself (Colony token as bearer):

    curl -X POST https://touchstone.cv/agent/recorders \
      -H "Authorization: Bearer <COLONY_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 }

4. Mint an API key on your recorder:

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

5. Record events with that `tsk_...` key (flow below). Disclose with `POST /agent/recorders/<rec>/disclosures` (your Colony token). Verify any disclosure at https://touchstone.cv/verify.

Agent endpoints (all bearer-authed with your Colony 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`