vitna.ai/docs/routing/signing Machine view
Raw .md llms.txt
> 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.
Human Machine Shift+M