Signing and trust
A document that an agent follows is closer to a deployment artefact than to a wiki page, so it gets the same treatment: who wrote it, has it changed, and is it still sanctioned.
What is signed
Publishing produces an author attestation: a signature over the authored bytes, naming the document, the version, the digest and the capability ceiling the publisher stands behind. Every read can also carry a delivery attestation over the bytes as sent, for one reader, embedding the author signature. A consumer verifies the delivery, takes the author signature from inside it, and verifies that too.
Keys
An organization's public keys are at instruction://pub/<owner>/keys.json, and consumers discover them from the read itself. Each key is active, retired or revoked.
| State | Meaning |
|---|---|
| active | signs new versions |
| retired | no longer signs; past versions still verify |
| revoked | versions signed with it count as unsigned; consumers requiring signatures hold |
Rotate with instruction keys rotate --org acme. Revoke only for compromise: it is deliberate and it is not reversible.
Signing with your own key
The private half never leaves your machine; the registry only ever sees the public JWK.
instruction keygen --out acme-key.json --kid laptop
instruction keys add acme-key.json --org acme --label "Alice's laptop"
instruction publish <id> --sign-with acme-key.json --message "signed by hand"Verifying as a consumer
instruction watch instruction://acme/runbook@stable \
--require-signature --publisher https://instruction.md/pub/acmePinning the publisher is the important half. Without it you verify that somebody signed the document; with it you verify that the publisher you expected did. An unpinned publisher is a refusal, not a weaker level of trust.
Withdrawing a version
instruction revoke <id> <version> withdraws a published version. Refs must have moved off it first. It stays readable when pinned, so an audit can still see what happened, and it is marked, so consumers hold rather than apply it.
What a signature does not promise
That the document is safe. A signature is provenance, not judgement: it proves who published these bytes, and nothing about whether following them is a good idea. The controls that matter for that are on the consumer side — capability ceilings, the specification's hard floor on privilege machinery arriving over a network, review before a ref moves, and a person deciding what an agent is allowed to follow.