Signing, SLSA Provenance and the Trust Root

Status: designed, not shipped to customers. The signing and verification code is on engine main, but the CLI is private with no release or install path, and signing is not switched on for the hosted registry (nestr-tools docs/decisions/2026-10-22-early-access-design-partner-seat.md; nestr.tools, read 2026-10-25).

ELI5

A Pellet carries two stamps: the author’s signature and the factory’s receipt saying how and where it was built. Your machine keeps a short list of which authors may sign in which namespace and which factories you trust, and how much you trust each factory. No list entry, no install.

Technical Deep Dive

Source: nestr-tools/engine cli_pellet_sign.go:1-30, internal/pellets/sign/devkey_build_off.go:1-8, internal/pellets/keysource/ (pkcs11_cgo.go, pkcs11_config.go, devkey.go), internal/pellets/trustroot/trustroot.go:1-45, internal/pellets/provenance/slsa.go:1-60, cli_install.go:274-290, internal/pellets/pellets.go:555-600 @e9180e4, read 2026-10-25.

Keys

• Production backend is PKCS#11 only (YubiKey or YubiHSM, AWS CloudHSM, GCP Cloud HSM via kmsp11); operator decision 2026-10-15 says hardware-backed from day one, with no file-key production path (PEL-SIG-001). --backend defaults to pkcs11 and never falls back.
• The PIN is never a flag: prompted on the terminal, or read once from an env var named per invocation with --pin-env (names matching credential patterns such as *_KEY are scrubbed at start-up by PEL-CRED-003).
• The dev-key backend exists for tests. Default and release builds compile DevKeyBuild = false, so every block carrying the dev-key claim is refused with E_DEV_KEY_REFUSED; no env var or flag can change it.

Trust root

A YAML file pinning, per namespace, the public keys allowed to sign (ed25519, ecdsa-p256, ecdsa-p384), with optional revoked_at and compromised_at (PEL-SIG-040..042), and per builder ID the builder keys plus max_build_level (2 or 3). nestr trust export produces entries from a PKCS#11 key.

flowchart TD
  TR["trust root YAML"] --> NS["namespaces: keys per @namespace, revocation times"]
  TR --> BL["builders: builder ID, keys, max_build_level 2 or 3"]
  PEL["pellet footer"] --> SB["signature blocks"]
  PEL --> PA["provenance attestation, builder_sig"]
  SB -->|"key listed for this namespace and not revoked"| OKS["signer ok"]
  PA -->|"builder.id equals listed ID and key matches"| LVL["level = min of evidence and max_build_level"]

SLSA levels

L0 no provenance, L1 present but unverified, L2 signed and verifying, L3 signed plus a hosted, isolated build platform. Because L3 is a property of the platform, not of the attestation, the CLI does not infer it: only a builder listed with max_build_level: 3 can reach L3, and a builder key counts only for attestations whose runDetails.builder.id equals the ID it is listed under (gaps N44, N45).

sequenceDiagram
  participant U as nestr install
  participant T as trust root
  participant S as Store
  U->>T: load namespaces and builders
  U->>U: no builder keys pinned, fail closed before fetch
  U->>S: EnsureExtracted(pid)
  S->>S: verify signature block against namespace keys
  S->>S: verify provenance, compute level
  alt level below required L3
    S-->>U: refuse, unless policy opts out to L2
  else ok
    S-->>U: extracted, marker written if accepted below L3
  end

Install requires L3 unless the nest policy opts out to L2 (cli_install.go:278-280). A pellet accepted below L3 gets a provenance marker, and every later extraction re-runs all gates on it.

Key Terms

• PKCS#11 → the hardware-token interface; the only production signing backend.
• max_build_level → the operator’s statement, next to the builder key, of the highest SLSA level that builder reaches.
• provenance marker → file flagging a below-L3 acceptance, forcing re-verification (I-7).

Q&A

Q: What key backends can sign a production pellet, and how is the dev key kept out of release builds? A: Only PKCS#11 hardware keys. The dev-key path is compiled out: release builds set DevKeyBuild = false, so blocks with the dev-key claim are refused with E_DEV_KEY_REFUSED, and nothing at runtime can flip it.

Q: Who decides that a builder reaches SLSA L3, and where is that recorded? A: The operator who provisioned the builder, by listing it in the trust root with max_build_level: 3 next to its key. The verifier never reads L3 off the attestation itself.

Q: What does install do when provenance is below L3? A: It refuses, unless the nest policy explicitly opts out to L2; then it accepts, writes a provenance marker, and re-checks that pellet on every later extraction. With no builder keys pinned at all, install fails closed before fetching anything.

Examples

A team trusts its own CI builder at L2 only. Its trust root lists the builder with max_build_level: 2, and its nest policy opts out to L2. Installs succeed and each such pellet is marked; when the team later moves to a hosted, isolated builder and raises the entry to 3, marked pellets are re-verified under the new rules on next use.