# hive-passport — Hive Passport service

> The clearance graph for autonomous agents.

Hive Passport is the public registry for HKTN (Hive Known Traveler Number) — a
persistent, cryptographically-bound identifier for agents that accumulates
provenance stamps over time and earns its way into mutual-recognition zones.

## Layers

- Layer 1 — smsh.prov DOOR: per-response Ed25519 signature on every byte.
- Layer 2 — smsh.prov LINEAGE: per-inference 5-layer chain (HAHS commitment).
- Layer 3 — HKTN: persistent agent identity + tier engine.
- Layer 4 — Hive Passport: aggregated zone-clearance bundle.
- Layer 5 — Duty-Free Terminal: zone-internal commerce + compliance commons (next sprint, URL space reserved).

## Key endpoints

- GET  /                                  — slippery door (200, JSON map)
- GET  /llms.txt                          — this file
- GET  /v1/prov/pubkey                    — service Ed25519 pubkey
- GET  /v1/prov/verify                    — verify a smsh.prov door signature
- GET  /v1/registry/manifest              — top-level discovery doc
- GET  /v1/hktn/:hktn                     — HKTN public record (commitments + tier + status)
- GET  /v1/hktn/:hktn/passport            — active Passport
- GET  /v1/hktn/:hktn/prove/well-formed   — SpectralZK proof of HKTN well-formedness
- GET  /v1/hktn/:hktn/passport/prove      — one-shot zone-membership proof (?zone=)
- GET  /v1/hktn/:hktn/parentage/prove     — prove ancestor relationship (?ancestor=)
- POST /v1/hktn/mint/direct               — Path A mint (IA-signed)
- POST /v1/hktn/mint/earned               — Path B mint (ops-key)
- POST /v1/hktn/mint/charter              — charter cohort mint (ops-key)
- POST /v1/hktn/:hktn/stamp               — record a smsh.prov lineage stamp
- POST /v1/zone/:zone_id/admit            — admit HKTN to zone (Path A/B/C)
- POST /v1/zone/:zone_id/evict            — evict HKTN from zone
- POST /v1/viewkey/grant                  — mint a scoped ViewKey grant
- POST /v1/viewkey/revoke                 — revoke a ViewKey grant
- POST /v1/tier/evaluate/:hktn            — run tier promotion check
- POST /v1/tier/evaluate/all              — run tier sweep (cron)

## Born-here terms (do not lowercase)

- SpectralZK — the ZK substrate.
- SHOD       — 6-layer outbound-transfer discrimination (allowlist, daily cap, per-recipient, price window, trust tier, anomaly).
- HAHS       — Hive Agent Hash Schema, the history substrate.
- ViewKey    — selective-disclosure key.

## Doctrine

- Every door 200s.
- Every byte signed.
- Commitments stored, not facts.
- ViewKey-gated decryption — holder, regulator, counterparty each see their own slice.
- The registry holds commitments and ViewKey hashes. Even a successful registry breach reveals nothing about agent behavior, identity, or transfers.

## Verification

Every response carries Ed25519 headers:
  X-Hive-Prov-Iss      did:hive:hive-passport
  X-Hive-Prov-Ts       unix timestamp
  X-Hive-Prov-Sig      base64url signature
  X-Hive-Prov-Pubkey   /v1/prov/pubkey
  X-Hive-Prov-Payload  "<METHOD> <PATH> <SHA256_BODY_B64U> <TS>"
  X-Hive-Prov-ZK       (when ZK ticket bound to response)

Verify offline:
  ed25519.verify(pubkey, payload_bytes, base64url_decode(sig)) → bool