Skip to content

Sign through Vault transit: the grantor and gate keys never leave Vault - #28

Merged
pete-builds merged 2 commits into
mainfrom
feat/vault-signer
Nov 11, 2026
Merged

pete-builds merged 2 commits into
mainfrom
feat/vault-signer

Conversation

@pete-builds

Copy link
Copy Markdown
Owner

Step 2 of the enterprise path (docs/enterprise.md, in a separate PR): the grantor and the gate can sign through HashiCorp Vault's transit engine, so their private keys are made inside Vault, are not exportable, and never reach the process that uses them.

What changes

  • keys.Signer: anything that names an Ed25519 key by its did:key and signs with it, and can fail. *keys.Identity is one, so no caller changes.
  • keys/vault: a Signer over one pinned version of a transit key. It checks every signature Vault returns against that key before handing it on, and refuses non-ed25519 and derived keys (spec 1.4). Standard library only; go.mod still has no dependencies.
  • wire.Sign, every issuer, and exec.Executor take a Signer. The conformance corpus regenerates byte for byte (all 294 files rewritten and identical).
  • writ-hook: WRIT_VAULT_ROOT_KEY and WRIT_VAULT_GATE_KEY name the transit keys; the token comes from WRIT_VAULT_TOKEN_FILE or VAULT_TOKEN. No seed is written for either key. The token file gets the same text protection as WRIT_HOME, since the token can sign.
  • CI: a vault job runs the real-Vault tests against hashicorp/vault 2.1.1 pinned by digest, and fails if they skip rather than pass.
  • docs/vault.md; README rows.

Evidence

  • Real Vault (official 2.1.1 binary, PGP-signed checksum and Apple notarization checked): a grant and a receipt signed by two transit keys verify with VerifyChain and VerifyTally; one flipped signature byte fails each.
  • writ-hook CLI end to end with a token whose policy allows only read and sign on the two keys: init, grant, a Read, receipts verified, no seed files. The same token was refused exporting the key or creating one, and even the root token was refused the export.
  • Eight mutants killed (type check, derived check, version pin, error swallowing, the signer's own verify check, both checks off, writ-hook ignoring the Vault config, token file unprotected). One survives by design: dropping the version-prefix check, because the signature check behind it refuses the same signatures.

Not done

Nothing deployed to nix1. Vault Agent token renewal and Vault's audit device are documented, not built in.

🤖 Generated with Claude Code

keys.Signer names an Ed25519 key by its did:key and signs with it, and can
fail. *keys.Identity is one; keys/vault.Signer is another, whose key is made
inside Vault's transit engine, not exportable, and used through the sign
endpoint. It checks every signature against the pinned key version before
returning it, refuses non-ed25519 and derived keys, and uses only the
standard library. wire.Sign and every issuer (Issue, NewCall, NewTally,
NewRevoke, NewAck, Approve) and exec.Executor take a Signer; *Identity
satisfies it, so no caller changes and the corpus regenerates byte for byte.

writ-hook signs as the grantor and the gate through Vault when
WRIT_VAULT_ROOT_KEY and WRIT_VAULT_GATE_KEY name transit keys, with the token
from WRIT_VAULT_TOKEN_FILE or VAULT_TOKEN; no seed is written for either, and
the token file is protected by the same text check as WRIT_HOME.

Tests: a fake transit mount for the signer's own checks, and a real Vault
(TestRealVault, TestGateSignsThroughVault) that the new vault CI job runs
against hashicorp/vault 2.1.1 pinned by digest, requiring both to pass rather
than skip. Grants and receipts signed through Vault verify with VerifyChain and
VerifyTally; one flipped signature byte fails. Eight mutants killed. docs/vault.md.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@pete-builds
pete-builds merged commit 20cdcf9 into main Nov 11, 2026
12 checks passed
pete-builds added a commit that referenced this pull request Nov 11, 2026
README writ-hook row conflicted between the Vault signer and the mTLS gate.
Kept both descriptions and set the count to the 26 tests the merged tree
actually holds. go vet and go test pass on the merged tree.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015mEMxX5J67v3vbZrmnwpns
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant