> Source: https://vitna.ai/docs/routing/signing > Raw Markdown: https://vitna.ai/docs/routing/signing.md > Corpus index: https://vitna.ai/llms.txt # Signing an artifact without an operator `aperture:sign` answers a queue of asks for signed artifacts, rebuilding each one from the record rather than signing what it was handed, so that a config or a policy can reach a customer without somebody standing at a prompt. ```bash DATABASE_SIGNER_URL=... VITNA_POLICY_SIGNING_KEY=... npm run aperture:sign ``` ## The problem it solves, which is not convenience [`aperture:policy`](policy.md) and [`aperture:config`](config.md) both sign, and both need a key the web process deliberately cannot see: one environment file, one reader, and a test that fails if anything a page can import so much as names the variable. That boundary is worth keeping. Its consequence was that a signed artifact existed only when a person ran a command, which is not something a customer can be given. So the site writes a row saying what it wants, and a timer unit answers it. The site still cannot sign, and now it does not have to. ## A request is an ask, and never a draft The row names an organisation and a decision. It carries no bytes at all. That is the whole security argument. A signer that signed the document it was handed would be an oracle: any bug upstream of it becomes a file with Vitna's signature on it, and the signature would be perfectly valid. Instead the signer re-reads the accepted decisions, rebuilds the artifact itself through the same code [`aperture:policy`](policy.md) runs, and the only thing a caller influences is which org and which decision the ask claims to be about. A caller who gets either wrong receives a refusal, not a signature. ## Four ways an ask is refused | Refusal | What it means | |---|---| | Out of scope | The named decision belongs to a different organisation | | Not accepted | The named decision is proposed or rejected, so nothing routes under it | | Superseded | The record has moved past it, so an artifact built now is not the one asked for | | Stale | The ask waited more than twelve hours, and the record may have changed underneath it | | Partial | A lane does not resolve, which the emitter already refuses to write around | Out of scope is checked before anything else about the decision, so an ask that names another organisation's decision learns only that it is not theirs. Superseded is why a request names a decision at all. The caller is saying "as of this one", and if the standing set has changed, the honest answer is to ask again rather than to receive a document that is quietly behind. An ask that names no decision means whatever stands right now, and cannot be superseded. ## A refusal is a row Every answered ask writes to `aperture.artifact`, which is append-only. A signed row carries the canonical bytes, their digest, the decisions that went into them, the key that signed and the signature. A refused row carries the reason and nothing that could be mistaken for an artifact. Refusals are stored for the reason the record stores everything else: a table of successes answers what was signed and not what was asked and declined, and the second question is the one an incident asks. ## The key that signs this is not the key that signs the record Until this existed, one Ed25519 key signed both each day's Merkle root and every config and policy emitted for a customer. While both ran from a timer nobody outside could reach, that was untidy. The moment signing happens on a customer's ask it is a category error: a compromise of the customer-facing signer would forge the public record's roots rather than one customer's routing. So there are two keys, in two files, with one reader each, and no unit reads both. `aperture:sign` refuses to start if its own key is not registered with the record to sign policies, so an artifact a customer could not verify is never produced in the first place. ## Registering a key, and the order that matters ```bash npm run witness:key:register -- --purpose policy --key <public half> npm run witness:key:register -- --list npm run witness:key:retire -- --key <public half> --reason "rotated 2026-09-01" ``` Registering publishes a key. It does not start signing with it, and the difference is an outage: 1. register the incoming key, so the record acknowledges and publishes it 2. operators add it to their runtime's `VITNA_PUBLIC_KEY`, beside the key they already pin, and restart 3. only then does the private half go where the signer reads it `VITNA_PUBLIC_KEY` accepts a comma-separated set from `vitna-runtime` 0.1.2 onwards, which is what makes step 2 a restart nobody has to hurry. This page said 0.2.0 until 2026-09-13; the set was released in 0.1.2, and `platform/runtime/policy-store.mjs` in that package is what parses it. Doing 3 before 2 signs policies every deployed runtime refuses, and each operator has to edit a file before their lanes come back. The whole order, retirement and a compromise included, is [rotating a signing key](../operations/key-rotation.md). What is registered at any moment is published at [`GET /api/v1/keys`](../api/v1/verification/keys.md), purpose first, and on `/witness`. Retiring is a date and a reason, never a delete. An artifact signed last year has to stay checkable against the key that signed it, and a verifier that could not tell a retired key from a key that was never Vitna's would have to call both of them forgeries. ## What it does not do **It is not an endpoint and must not become one.** It is a timer unit reading a table. Nothing in a request path calls it, nothing waits on it, and a customer collects what it wrote afterwards. An inference request still never calls vitna.ai. **Collecting it is a separate page.** The artifact sits in the table, and an owner asks for one at `/console/deployment`. Anybody signed in to the organisation downloads it from the same page, which prints beside each signed policy the two lines a runtime needs, with the key that signed that file. A machine with no session uses [Collecting a signed artifact](../api/v1/engine/artifacts.md), an authenticated read with the organisation's own key. **It ordinarily answers within about six minutes.** `deploy/vitna-sign.timer` fires every five minutes, on the twos and sevens, with up to thirty seconds of jitter, so an ask made just after a run waits for the next one. A refusal lands on the same schedule, with its reason. That is the schedule, not a promise: an attempt that fails is retried after five minutes and then twenty five, so an ask can wait half an hour or more and end refused. The console says so beside an ask that has waited longer than six minutes. **It signs nothing until a key is registered to sign policies.** The signer starts only with a key the register lists for that purpose, so on an instance where [`GET /api/v1/keys`](../api/v1/verification/keys.md) answers `"policyKey": null` nothing is signed, the console says so instead of the six minutes, and it takes no ask: one would answer nothing, block the next ask for that organisation, and be refused as stale if the signer started more than twelve hours later. vitna.ai was in that state on 2026-09-13. A registered key is what signing needs rather than proof that it runs; the signer also needs the private half and its database login on the box, which no page can see. **It signs policies only.** A config is a kind the queue accepts and this refuses by name, so an ask for one is answered rather than left pending.