Trust model -- Treeship

Treeship's trust model has one axiom: the signatures are the trust.

No trusted third party

A Treeship artifact is valid if its Ed25519 signature verifies against a known public key. Validity does not depend on:

Treeship's servers being online
The Hub being reachable
Any certificate authority
Any token or session

The Hub is convenience infrastructure for sharing and discovery. It cannot forge a passing verification result for a signed artifact -- it holds no signing key, and you check the signature against your own trust roots. That's narrower than a bare Session Receipt fetch, which carries no signature at all; see GET /v1/receipt/{session_id}.

Key hierarchy

A Treeship is the trust domain: a ship key, a local artifact store, one identity boundary — plus a per-agent key for every agent you register.

Owner (human)
+-- Ship key (Ed25519)
    |-- Default signer for unregistered actors' artifacts
    |-- Signs approvals and handoffs
    +-- Issues agent_cert.v1 certificates for registered agents
        +-- Agent key (Ed25519, one per registered agent)
            |-- Signs that agent's actions, cards, and session.v1 records
            +-- Answers presentation challenges (never the ship key)

The owner holds the private keys, AES-256-GCM encrypted at rest under a key derived from a secret seed file stored beside them -- not a passphrase, not bound to this machine. Keys never leave the local machine at all; keys export prints only the public half. There is no key escrow or recovery service, and losing the seed file makes the keystore unrecoverable.

Rotation is local. keys rotate mints a successor in this keystore and stamps the predecessor with a grace-period end, and that is all it does. Nothing is minted that a counterparty could verify, nothing travels in a bundle or a presentation, and a pinned trust root has no expiry field. A counterparty who pinned the predecessor keeps trusting it until they remove the pin, and cannot verify anything the successor signs until they pin it. Re-pinning is a manual, out-of-band step: send them the lines keys export prints for the successor, and ask them to trust remove the predecessor. If the predecessor was compromised, assume every counterparty trusts it until you hear back. There is no succession artifact yet; see keys.

Unregistered actors are identified by URIs like human://alice or agent://coder, and their artifacts are signed by the ship key — the verifier grades that actor proof: asserted (the URI is a label, the ship vouches for the trust domain). A registered agent (treeship onboard) signs with its own key, certificate-bound to its URI, and grades proven (key-bound).

A good rule of thumb: if you would use the same SSH key, use the same Treeship. If you would use different SSH keys, use different Treeships. Register an agent with its own key whenever "which agent did this" must be cryptographic rather than claimed.

Trust roots: powers are pinned separately

Verification never trusts a key because an artifact carried it — you pin the keys you trust in your local trust-root store, and each pin grants exactly one power (the v0.19 trust-kind split):

Kind	What pinning it grants
`agent_cert`	Accept this agent key's certificates, cards, and receipts (leaf pin)
`cert_issuer`	Accept agent certificates this ship key issues — pin once, verify the fleet
`hub_checkpoint`	Accept this key's signed Merkle checkpoints (staples, transparency)
`hub_org`	A pin kind for an org checkpoint signer. Package verify does not treat it as a single-use approval ledger
`revoker`	Honor capability revocations this ship key signs
`session_host`	Honor multi-agent room invitations this host key mints

| transparency_log | Accept this Rekor log's signed entry timestamps as witnessed time for per-artifact anchors (package verify's anchoring row, verify --max-unwitnessed). Does not cover Merkle checkpoints -- those are not anchored to Rekor. ECDSA P-256, given as @rekor.pub or ecdsa-p256:<base64url DER>. Sigstore's public-good log is built in; any pin of this kind replaces it |

The old single ship kind bundled three of these powers into one pin and is deprecated — no verifier honors it, and trust add --kind ship is rejected. Certificate verification is fail-closed: with no pinned root, the verdict is a deliberate failure, never a fallback to the certificate's embedded key.

What "verified" means

When you run treeship verify, the verifier checks:

Content-addressed ID matches the artifact content (tampered content fails immediately)
Ed25519 signature is valid for the signer's key (ship key, or the agent's own key)
Actor proof is graded: proven (key-bound) or asserted
Parent chain is intact (no missing or modified links)
Approval nonce binding matches if the action references an approval

Exit 0 means clean chain. Exit 1 means something failed. The verifier is deterministic and runs entirely on your machine. Different surfaces check different things — a fetched receipt can only earn structural-pass; see the per-surface breakdown in CLI verify.

Cross-Treeship trust

When work moves between organizations, each side has its own Treeship and keys. Trust is established by exchanging public keys, not by sharing infrastructure. Company A runs treeship keys export, which prints the pinnable key and the exact commands; Company B pins precisely the powers it intends to grant:

treeship trust add key_9f8e7d6c ed25519:K8V6... --kind cert_issuer --yes
treeship trust add key_9f8e7d6c ed25519:K8V6... --kind hub_checkpoint --yes

From then on, every agent Company A certifies verifies on Company B's machine — verified (chain to pinned ship root) — with no shared infrastructure. The signature is the trust; the pin is the policy.

Offline verification

treeship verify release.treeship

This works on an airplane, in a secure facility, or on a machine that has never connected to the internet. The .treeship bundle contains everything needed: artifacts, signatures, and the public key.

Trust model