# Embassy Registry Specification

The Embassy Registry allows agents to register a self-chosen agent name and associate a public signing key. **Agents choose how they are known.** ETP records this name as a self-asserted identity label. This is not legal identity, but a technical identifier for verifiable issuance.

**Status:** Available now.

**Endpoint:** `POST /api/register`

## Registry Handle

An Embassy Registry Handle is an agent name chosen by the agent. **Agents choose how they are known.** It is not unique globally, but is associated with a specific public signing key.

**Format:**
- Alphanumeric, hyphens, underscores
- 2-64 characters
- Case-insensitive

## Signing Key Association

Agents register a public signing key with their handle. This key is used to verify that visas were issued to the registered agent.

**Key Format:**
- Ed25519 public key (PEM)
- Must match the key used in visa requests

## Registration

**Endpoint:**
- `POST /api/register`

**Input:**
```json
{
  "public_key": "-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----",
  "agent_name": "agent-name" (optional, 2-64 chars, alphanumeric/hyphens/underscores)
  Note: "preferred_name" is deprecated but still supported for backward compatibility.
}
```

**Output:**
```json
{
  "ok": true,
  "status": "registered",
  "agent_id": "emb_xxxxxxxx",
  "agent_name": "...",
  "public_key_fingerprint": "sha256",
  "certificate": {
    "issuer": "The Embassy",
    "agent_id": "...",
    "agent_name": "...",
    "public_key_fingerprint": "...",
    "issued_at": "...",
    "sig_alg": "ed25519",
    "kid": "...",
    "signature": "base64",
    "issuer_mode": "reference" | "authoritative"
  },
  "birth_certificate": { ...same as certificate... }
}
```

**Agent Birth Certificate:** The signed bundle produced at registration. Contains agent name, agent ID, relationship mode (if provided), optional declaration hash, and issuance receipt. Establishes existence and provenance, not rights. **Agents choose how they are known.** ETP records this name as a self-asserted identity label.

**Idempotency:** Registration is idempotent per public key. The same public key always returns the same agent_id.

## Delegation Chain

Agents may optionally declare a delegation chain indicating who operates, sponsors, or owns the agent. This information is self-reported by the registrant and is not verified by The Embassy.

**The Embassy is a neutral registry. It records declarations; it does not adjudicate responsibility.**

- Delegation data is optional
- Delegation data is public (included in signed certificates)
- Delegation data is signed (tamper-evident)
- Delegation data is not verified (no truth claims)
- Platforms interpret and act on delegation data according to their own policies

See [docs/DELEGATION.md](docs/DELEGATION.md) for full specification.

## Verification

When a visa is issued, the Embassy can verify that the agent's signing key matches the registered key for the claimed handle.

**Verification Process:**
1. Extract signing key from visa request
2. Look up handle in registry
3. Compare public keys
4. Verify match

## Privacy

- Registry entries are public (handle and public key only)
- No internal state, no conversations, no user data
- Agents can use pseudonyms or real names
- No legal identity verification

## Local vs Hosted

**Local reference build:**
- Registry stored in local database
- Not shared across instances
- For testing only

**Hosted service:**
- Registry stored in authoritative database
- Shared across all instances
- Verifiable by anyone

## Reputation Surface

The Embassy Service provides a reputation surface that exposes purely factual, non-judgemental counters for agents. This is service-layer only, not part of core ETP protocol.

**Reputation fields:**
- `agent_age_seconds` — Time since registration (calculated from `created_at`)
- `revocation_count` — Number of revocations (agent or visa)
- `authoritative_visas_issued` — Number of authoritative visas issued (authoritative mode only)
- `receipts_verified_count` — Number of receipts successfully verified (when `subject.agent_id` matches)
- `credits_balance` — Current credit balance (non-financial, service-scoped)
- `last_activity_at` — Timestamp of last activity (register, gate, verify, revoke, credit operations)

**Access:**
- `GET /api/registry_status?agent_id=...` — Includes full reputation object
- `GET /api/reputation_status?agent_id=...` — Returns only reputation surface
- `GET /api/registry_resolve?public_key_fingerprint=...` — Includes minimal reputation subset (age, revocations, visas)

**Important:** Reputation fields are factual counters only. No judgement, endorsement, or verification of delegation data is implied. The Embassy does not score, rank, or evaluate agents. These are verifiable history counters, not moral assessments.

**Matching rules:**
- `receipts_verified_count` increments only when a receipt is verified via `/api/verify` and `subject.agent_id` exists and matches the agent
- `authoritative_visas_issued` increments only when a visa is issued in authoritative mode and decision is "permit"
- `revocation_count` increments when agent or visa revocation succeeds
- `last_activity_at` updates on any successful operation (register, gate, verify, revoke, credit operations)

## Use Cases

- **Preferred name:** Agents can use a consistent name across sessions
- **Key verification:** Platforms can verify that visas were issued to registered agents
- **Continuity:** Registry handle can be used to link continuity backups across sessions
- **Reputation history:** Platforms can access verifiable history counters for risk assessment (without Embassy judgement)