elizaos--eliza/.github/certification

Certification trust anchor

certification-public-key.pem is the Ed25519 public key that the develop→main promotion gate trusts. A certification.json (produced by bun run --cwd packages/evidence certify:sign) is a signed claim that a holder of the matching private key reviewed a specific evidence bundle for a specific commit. Verification logic lives in packages/evidence/src/certify/sign.ts; the CI workflow must stay a thin caller of certify:verify and perform no verification logic of its own (#14546 / #14547).

Trusted key fingerprint: 3ac9e3e625a9ed2f (first 16 hex of sha256 over the SPKI DER). packages/evidence/src/certify/committed-key.test.ts asserts the committed PEM matches this fingerprint, so an accidental or malicious pem swap fails the test suite as well as review. This key was provisioned during the epic #14541 bootstrap; its private half lives in the ELIZA_CERT_SIGNING_KEY repo secret. Rotation (procedure below) is cheap and may be performed at any time by the repo owner — merging a PR that replaces the pem and this fingerprint is the act of trusting a new key. There is deliberately no default trust anchor in code: certify:verify requires an explicit --pubkey.

Trust model — binding rules for the CI gate (#14547)

• Read the public key from the BASE branch (main), never from the PR head. The gate must check out main's copy of this file (e.g. git show origin/main:.github/certification/certification-public-key.pem) and pass it via --pubkey. If the gate read the key from the PR head, an attacker could swap the key and a matching self-signed certification in a single PR and the gate would happily verify their own signature. Key changes only become trusted after they land on main through review.
• The private key is never in the repo. It lives only in the ELIZA_CERT_SIGNING_KEY secret (PEM or base64-wrapped PEM) on the signing runner, and in the local env/keychain of authorized certifiers. No tool in this repo writes a private key to disk; certify:keygen prints it only under the explicit --print-private-key flag.
• What a valid signature proves: a keyholder signed exactly these verdicts over exactly this bundle manifest (bundleSha) for exactly this commit. What it does not prove: that the review was diligent. That is why the reviewer identity ({kind, id, model?}) is part of the signed payload and must be surfaced in the gate's check summary.

Verify contract (what the workflow calls)

bun run --cwd packages/evidence certify:verify -- \
  --cert <path/to/certification.json> \
  --bundle <bundle-dir> \
  --pubkey <base-branch-checkout>/.github/certification/certification-public-key.pem \
  --expected-commit <cert.commit> \
  --max-age-hours 72 \
  --required-tier full \
  [--requirements <requirements.json>] \
  --json

Exit 0 iff valid. --json prints the full report on stdout, including failures: [{code, message, context}] with distinct codes (schema-invalid | unsigned | bad-signature | wrong-key | stale | commit-mismatch | bundle-tampered | verdict-failures | verdict-incomplete | tier-insufficient); all detectable failures are reported together, not first-failure-only.

For the required develop→main gate, --bundle is mandatory. Without the bundle, verification can only prove that the JSON was signed by the trusted key; it cannot prove the signed bundleSha matches real artifacts, that every mechanically-derived lane/analysis subject was reviewed, or that verdict evidence paths actually exist. Omitting --bundle is only for detached signature inspection, never for promotion. With a bundle, verification also re-runs the mechanical rollup: mechanically non-pass subjects may be signed as fail or waived with notes, but never omitted or signed as pass.

Key rotation

1. An authorized engineer runs bun run --cwd packages/evidence certify:keygen -- --print-private-key on a trusted machine (never in CI logs).
2. Open a PR replacing certification-public-key.pem and the fingerprint in this README. The PR must be reviewed and merged to main like any other change — merging it is the act of trusting the new key.
3. Update the ELIZA_CERT_SIGNING_KEY repo secret (and any local certifier copies) to the new private key.
4. Certifications signed by the old key stop verifying the moment the new public key is on main (wrong-key). Re-certify in-flight promotions.

Compromise response is the same procedure, performed immediately; the old key needs no explicit revocation because the gate trusts exactly one key — the one on main.

The CI gate (#14547): certification-verify.yml

.github/workflows/certification-verify.yml runs on every non-draft PR targeting main and is the promotion gate. What it does, in order:

1. Checks out the PR head commit (not the synthetic merge ref) and reads the trusted public key from the base branch per the trust model above.
2. Locates the certification and bundle: certification.json committed at the repo root of the promotion branch and the signed evidence bundle committed at evidence/bundle/. Missing either file = red, with remediation instructions in the check summary. The gate always passes --bundle evidence/bundle so artifact integrity, rollup completeness, and signed evidence-path membership are re-derived from the committed bundle.
3. Runs scripts/certification/check-commit-drift.mjs: the certified commit must equal the PR head, or be an ancestor whose diff to head touches only the docs/template allowlist — docs/**, packages/docs/**, any *.md, plus the certification artifacts themselves (certification.json, evidence/bundle/** — those necessarily land after the signed commit and are protected by the signature and bundleSha, not by the drift rule). Any other source, workflow, policy, or config drift = re-certify.
4. Runs certify:verify (the contract above) with --expected-commit <cert.commit> --max-age-hours 72 --required-tier full.
5. Writes a check summary with the reviewer identity, tier, age, signed verdict table (waived rows surfaced with notes), drifted paths, trusted key fingerprint, and every failure code verbatim. Verification only — the gate never performs evidence review.

Branch protection (admins)

Add the required status check verify-certification (the job name in certification-verify.yml) to main's branch protection. This is a manual admin step — the workflow does not (and must not) edit branch protection. Keep the name stable; renaming the job orphans the required check and blocks every promotion. The companion certification-verify-selftest job is CI for the gate's own plumbing (runs only on PRs touching it) and must not be made a required check.

Bootstrap: until this directory's public key and packages/evidence exist on main, the gate fails closed on every promotion PR ("no trusted public key on main"). The first promotion that carries the certification stack to main needs a one-time admin bypass; every promotion after it is fully gated.

Residual risk (accepted): pull_request-triggered workflows execute the PR's own merged workflow definition, so a promotion PR that edits the gate files could neuter the check. The drift check refuses to allowlist those paths, the diff is plainly visible to the human merger, and promotion PRs are human-reviewed by definition. Hardening to pull_request_target (base branch runs the workflow) is a possible follow-up.

Remediation runbook (gate is red)

1. Preferred: dispatch the vast certification workflow for the promoted commit; it produces the bundle, review, and signed certification.json.

2. Local fallback (requires a certifier holding ELIZA_CERT_SIGNING_KEY):

   bun run --cwd packages/evidence bundle:create -- --tier full
   bun run --cwd packages/evidence certify:rollup -- --bundle <bundle-dir> --out verdicts.json
   # review verdicts.json by hand — waivers require notes
   bun run --cwd packages/evidence certify:sign -- --bundle <bundle-dir> \
     --verdicts verdicts.json --reviewer-id <you> --reviewer-kind human
   cp <bundle-dir>/certification.json ./certification.json  # commit on the promotion branch
   rm -rf evidence/bundle && mkdir -p evidence && cp -R <bundle-dir> evidence/bundle
   

3. stale (>72h) or commit-mismatch/drift failures always mean the same thing: re-run certification at the current head. There is no override flag by design.

Break-glass (emergencies)

Push to main is a production deploy, so the gate must be watertight — but it must not brick emergencies. The break-glass path is not a code path: a repository admin bypasses the required certification-verify check via branch-protection admin override. Every such bypass is visible in the GitHub audit log; there is deliberately no in-repo flag, env var, or alternate verification mode that skips signature checks. The required check being bypassed is verify-certification (see the CI gate section above) — that is the exact string admins bypass and auditors grep for.