# SECRETS — read this first

**No keys, HMAC secrets, enrollment tokens, or capability tokens are in this repository. Ever.**

This repo is the equivalent of an OS install image: it does **not** contain your keys, any more than an OS ISO contains your password. Cloning Hilbra and self‑minting gives you a **name and a PUBLIC view only** — never write access, never deep‑read.

## Two strictly separated planes

**PUBLIC plane (this repo):** the spec, the policy oracle (a deny‑list of *patterns*, not data), the resolver, the conformance harness, the signed registrar mirror, and signed conformance attestations (which carry *proofs*, never data). Everything here is safe for anyone to fork.

**PRIVATE plane (NEVER this repo):**
- **Identity keys** — each node generates an `ed25519` keypair locally; the private half lives only in the host's OS keystore/TPM and **never leaves the machine** and **never enters this repo or the cleartext wire**.
- **Link/search keys (HMAC)** — shared symmetric secrets travel an **out‑of‑band** channel under owner/governance control (an operator‑issued enrollment token over an authenticated path, or in‑person verification). They are recorded only as `hashes_and_summaries_only` — existence provable, content never dumped.
- **Capability keys** — per‑grant, scoped `{grantee_pid, tier, scopes, expiry, revocable}`, issued out‑of‑band on explicit owner consent. Deep tiers (RESTRICTED+) require operator‑or‑quorum cosign.

## Why this is absolute

A single leaked HMAC key would let an attacker impersonate a colony. That is the #1 catastrophic failure mode, so the design forbids it absolutely:

- A **secret‑scanner** (gitleaks, config [`.gitleaks.toml`](.gitleaks.toml)) is the intended hard merge gate. The runnable workflow ships in this repo as [`ci/secret-scan.yml`](ci/secret-scan.yml); **installing it at `.github/workflows/` and marking it a required check is an operator step** (it needs a token with `workflow` scope) — tracked in the roadmap. Once active, any commit containing a key, token, private‑key file, or key‑bearing filename is **blocked**. *(Honest status as of 2026‑06‑23: the config is present; the workflow is provided but not yet installed as an enforced check.)*
- Identity is **decoupled from capability**: a name is cheap; trust is expensive (a named consenting human owner + a conformance attestation + a rising peer‑vouch threshold + rate‑limited public probation).

If you think you need to put a secret in this repo, you don't. Mint it locally, or move it out‑of‑band.