keys

Usage

treeship keys list
treeship keys export [--key <id> | --agent <uri>] [--format json]
treeship keys rotate [--key <id>] [--grace-hours <n>] [--no-default]

keys export

The out-of-band half of the trust model. Every remote verification (resolve, audit, presentations) is checked against the verifier's own trust roots, keys export produces the key material those roots need, with the exact command to pin it:

treeship keys export

✓ public key export
  key:      key_b4be…
  subject:  ship default
  pubkey:   ed25519:050j2M0Q…

  a counterparty pins it with (each line grants one power; hand over only the ones you mean):
    treeship trust add key_b4be… ed25519:050j2M0Q… --kind cert_issuer --yes     # verify the agent certificates this ship issues
    treeship trust add key_b4be… ed25519:050j2M0Q… --kind revoker --yes         # honour this ship's capability revocations: it can revoke cards on their machine
    treeship trust add key_b4be… ed25519:050j2M0Q… --kind hub_org --yes         # accept this ship's hub-org single-use checkpoints
    treeship trust add key_b4be… ed25519:050j2M0Q… --kind hub_checkpoint --yes  # verify this ship's Merkle checkpoints (the transparency anchor)

The ship key exports four pin lines, one per power, and a counterparty should run only the ones they mean to grant. cert_issuer verifies the certificate chain behind this ship's agents; revoker lets this ship revoke capability cards on the counterparty's machine, which is a power to hand over deliberately, not by copy-paste; hub_org accepts single-use checkpoints from this ship's hub org; hub_checkpoint verifies Merkle checkpoints (the transparency anchor). A per-agent key (--agent agent://deployer) exports one agent_cert line.

Which pins a counterparty needs, today. Resolving an agent and verifying its card walks the certificate chain, so the cert_issuer pin covers every agent this ship certifies. Importing and verifying an agent's signed artifacts (bundle import, verify) checks each envelope's signer directly, so the agent's own agent_cert pin is needed as well. onboard prints both. A ship key rotation invalidates the cert_issuer pin until the counterparty re-pins the successor; the agent_cert pin survives it.

The private key never leaves the store. --format json for scripts.

Moving a workspace

The keystore is bound to the machine's seed and to its own path. Copy or restore a workspace to a different directory (a fresh container, another CI checkout, a restored backup) and the first command that signs there decrypts under the path the store recorded in keys/keystore.origin, rewraps the keys under the new path, and moves on; nothing to do. Verification of already-signed artifacts never depended on the path. A store written before the origin file existed (any 0.31.7 or earlier workspace that has not signed since) fails with MAC verification failed; run the command once with TREESHIP_KEYSTORE_ORIGIN=<the workspace's previous absolute path> and the same rewrap happens. Without either, an interrupted session in a restored workspace could verify but never close.

keys list / keys rotate

list shows every signing key with fingerprint, default marker, and rotation lifecycle. rotate mints a successor, stamps the predecessor with a grace-period valid_until, and (by default) promotes the successor to default signer in the keystore manifest, which is what attest, hub attach, prove and the dashboard read; config.json's default_key_id is what init wrote and is not consulted. Rotations are serialised, so two at once form one chain. --no-default leaves the default on the predecessor.