feat: attestation system — design, claim taxonomy, CLI, and seven-tier TDD

Background

Attestations are the trust layer of the Muse ecosystem. An attestation is a cryptographically-signed statement by one identity about another identity — non-forgeable, tamper-evident, and anchored to the same Ed25519 keypair that signs commits. Because every identity's key traces back to a shared HD wallet root, an attestation is as strong as the signing identity itself.

This makes Muse attestations fundamentally different from social endorsements. They are closer to W3C Verifiable Credentials, but native to the ecosystem: the same key that signs `muse commit --sign` signs `muse hub attestation create`.

Canonical message (domain-separated, replay-resistant): ``` ATTEST {attester} {subject} {claim_json} {issued_at_iso} ```

The `ATTEST` prefix domain-separates this from MSign auth headers and MPay payment messages, preventing cross-protocol replay attacks.

Design Questions (resolve before implementation)

1. Open vs. closed claim type registry

Option A — Open schema: any valid JSON object is a claim; `claim_type` is the top-level key. Maximum composability. No registry needed. Hard to enumerate, hard to render in UI without knowing the schema.

Option B — Closed registry: claim types must be declared in a registry (DB table or code constant). Unknown types rejected at write time. Enables indexed search, typed UI rendering, and forward-compatible schema evolution.

Option C — Hybrid (recommended): a `type` field from a well-known enum is required; an optional `metadata` object is freeform. The registry defines the semantics; metadata carries domain-specific payload.

2. Scope: identity-only or referenceable?

Current model: attestation is always `attester → subject (handle)`.

Future option: attestation can reference a specific commit, repo, or symbol: `attester → subject::repo_id::commit_id`. This enables per-artifact claims like `stems:verified` on a specific commit, not just on a handle.

3. Expiry / TTL

Current model: permanent until explicitly revoked by attester.

Option: optional `expires_at` field. Useful for time-bounded trust grants (e.g. a contractor relationship that lapses). Default: no expiry (current behavior preserved).

4. Transitivity

If Gabriel attests agentx as `trusted`, and agentx attests agent-y as `spawned-by`, does that create a verifiable trust chain? The current `TrustChainEntry` model suggests yes, but the chain is implicit.

Design question: should transitivity be declared (attester opts in to chain propagation) or computed (hub derives trust graphs from attestation DAG)?

5. On-chain anchoring (ERC-8004 trajectory)

Long-term: attestation hashes anchored to Avalanche L1 via the ERC-8004 agent identity contract. The attestation_id (SHA-256 of canonical message) is the natural on-chain anchor. Out of scope for this issue — flagged for Phase 3.

Claim Type Taxonomy (proposed)

Registry is additive: new types can be declared without migration.

Implementation Plan

Phase 1 — Claim type registry + schema hardening

• Add `musehub_attestation_claim_types` table (or in-code registry constant): `type_key`, `category`, `description`, `introduced_at`
• Add DB CHECK constraint on `musehub_attestations.claim` validating `type` key is in the registry (enforced at application layer; soft constraint at DB)
• Add optional `expires_at` column with NULL default (non-breaking)
• Add optional `scope` column (`identity` | `repo` | `commit`) with default `identity` (non-breaking)
• Alembic migration; backwards-compatible

Phase 2 — `muse hub attestation` CLI commands

```bash muse hub attestation create \ --subject <handle> \ --type <claim_type> \ [--metadata '{"key":"val"}'] \ [--expires-in 90d] \ --json

muse hub attestation list [--subject <handle>] [--attester <handle>] \ [--type <claim_type>] [--json]

muse hub attestation revoke <attestation_id> --json ```

The `create` command:

1. Resolves attester handle from `muse auth whoami`
2. Fetches attester public key from `~/.muse/identity.toml`
3. Constructs canonical message
4. Signs with Ed25519 private key
5. POSTs `AttestationRequest` to `POST /api/profiles/{subject}/attestations`
6. Returns `AttestationResponse` as JSON

Phase 3 — Trust graph + transitivity (future)

• `GET /api/trust-graph/{handle}` — DAG of attestations reachable from handle
• Transitivity declarations: opt-in chain propagation
• On-chain anchoring prep (ERC-8004)

Test Plan — Seven Tiers

All tests written RED first before implementation.

Tier 1 — Unit

• `verify_attestation_signature`: valid sig passes; tampered claim fails; wrong key fails; cross-protocol message (MSign prefix) fails
• `_canonical_message`: output is deterministic; field order is fixed; ATTEST prefix present; newline separators correct
• `compute_attestation_id`: same inputs → same ID; different issued_at → different ID
• Claim type registry: known type passes; unknown type raises `ValueError`; registry is additive (adding new type doesn't break existing)
• `AttestationRequest` / `AttestationBadge` Pydantic validation: required fields, type coercion, datetime handling

Tier 2 — Integration

• `issue_attestation`: valid sig → persisted; invalid sig → `ValueError`; duplicate → idempotent (returns existing, no second row)
• `revoke_attestation`: attester can revoke own attestation; wrong revoker → 403; non-existent → 404; revoked row has `revoked_at` set
• `get_attestations_for_subject`: returns only active (non-revoked) by default; `include_revoked=True` returns all; filters by claim type; paginates correctly
• `get_attestations_by_attester`: same filter/pagination coverage
• `issue_attestation` with `expires_at`: expired attestation excluded from `get_attestations_for_subject` live results; included with `include_expired=True`
• Scope field: `identity`-scoped attestation stored and retrieved correctly
• API route `POST /api/profiles/{handle}/attestations`: 201 on success; 400 on invalid sig; 409 on duplicate (idempotent); 404 unknown subject

Tier 3 — End-to-End

• Full CLI round-trip: `muse hub attestation create` signs → posts → hub stores → `muse hub attestation list` retrieves; profile page renders the badge
• Revoke round-trip: create → revoke → profile page no longer shows badge
• Expires round-trip: create with `--expires-in 1s` → wait → list returns empty
• Cross-identity: human attests agent; agent attests human (both directions work)
• Unknown claim type: `muse hub attestation create --type nonsense` → CLI error before any HTTP call

Tier 4 — Stress

• 1,000 concurrent `issue_attestation` calls for the same canonical payload → exactly 1 row in DB (idempotency under concurrent writes)
• 10,000 attestations for a single subject → `get_attestations_for_subject` returns in < 200ms with index
• 100 concurrent revocations of different attestations → all succeed without deadlock or row contention

Tier 5 — Data Integrity

• Attestation row survives DB restart (durability)
• `revoked_at` is set atomically with the revocation UPDATE; no partial-revoke state possible
• `attestation_id` is unique; duplicate insert on same ID raises `IntegrityError` (not silently overwritten)
• Deleting an identity (soft-delete) does not cascade-delete attestations — historical record is immutable
• `claim` JSON is stored verbatim; no normalization that would change `claim_type` derivation

Tier 6 — Performance

• `GET /api/profiles/{handle}` (profile page) renders attestation section in < 50ms with 500 attestations for subject (index coverage verified by EXPLAIN)
• Bulk `get_attestations_for_subject` with pagination: page 1 of 1,000-row result in < 20ms
• `issue_attestation` write path: p99 < 50ms under 50 concurrent writers
• Index coverage: `(subject, revoked_at)` and `(attester, revoked_at)` confirmed in query plan

Tier 7 — Security

• Signature replay: posting the same `AttestationRequest` twice is idempotent, not a double-write (content-addressed ID prevents it)
• Cross-protocol replay: an MSign auth header cannot be submitted as an attestation signature (domain separation test: prepend `MUSE-SIGN-V1` instead of `ATTEST`)
• Attester impersonation: posting a request with `attester=gabriel` but signing with a different key → 400 invalid signature
• Revoker impersonation: `DELETE` with wrong authenticated identity → 403
• Claim injection: claim JSON with `proto` or SQL meta-characters stored verbatim without execution (parameterized query coverage)
• Key rotation: attestations issued under old key remain verifiable after key rotation (attester_public_key stored per attestation, not looked up live)
• Expired attestation: `expires_at` in the past is excluded from default queries even if not explicitly revoked

Acceptance Criteria

• All 7 test tiers pass GREEN before any code merges
• `muse hub attestation create/list/revoke` commands work end-to-end on staging
• Profile page renders received/given attestations with correct claim types
• Claim type registry is code-level (Phase 1); DB-level registry is Phase 2
• Strong docstrings on all public functions and CLI commands
• Alembic migration for `expires_at` and `scope` columns
• No git, no GitHub, no backwards-compat shims