vitna.ai/docs/cli/keys Machine view
Raw .md llms.txt
> Source: https://vitna.ai/docs/cli/keys
> Raw Markdown: https://vitna.ai/docs/cli/keys.md
> Corpus index: https://vitna.ai/llms.txt

# Push keys

Who may land a reading over the network, per org, minted and revoked at the
prompt. The web process authenticates against these and cannot mint one. With
console keys on, an owner can revoke one from the console, and can mint a
platform key there through a separate minter (below).

## Minting

```bash
npm run org:key:create -- --org convexity --label "runtime, box 1"
```

The token is printed once and stored nowhere: the record holds its sha256,
by the same constraint that keeps a session token out of the nightly dump. It
goes in `VITNA_PUSH_KEY` on the box whose [`runtime:push`](../runtime/pushing.md)
will use it, and authenticates `POST /api/v1/usage` for that org's workloads
only.

`--label` is required and is for the operator: with three boxes pushing,
"which key is this" has to be answerable at the prompt. A reading's own
provenance carries the key's id rather than its label, so a relabel cannot
rewrite history.

The command ends by listing the org's keys, so what exists is visible at the
moment one is added.

## Revoking

```bash
npm run org:key:revoke -- <id> --reason "box decommissioned"
```

Revocation is a date and a reason on the row, never a delete: which keys
existed and when they stopped is part of how a pushed reading's provenance is
audited, and the row holds a hash, so keeping it keeps no secret. It applies
on the key's next push, which is refused with the date and the words "mint
another", so a forgotten pusher learns to stop rather than retrying forever.

Losing a token means revoking and minting again. Nothing can recover one,
because nothing holds one.

## Seeing what exists

The console lists them, per org, under **Push keys** on
[the settings page](https://vitna.ai/console/settings): the label, when the key
was minted, whether it is live or revoked and why, and whether any reading the
register currently holds arrived on it.

Push and router keys are minted only at the prompt, because both need the
migrate credential, which is strictly more privilege than a push key
grants. The role the page reads with is granted every column of the table
except the hash, so the page cannot show a token and no later query written
against it could either.

## Platform keys from the console

On an instance with `VITNA_CONSOLE_KEYS=on`, an org owner can mint a platform
key on the settings page and revoke any of the org's keys there. The web
process still cannot mint one. The page files a request, the owner confirms it
with a passkey, and `vitna-mint` (`npm run org:key:minter`, as `vitna_minter`)
mints the key and seals it to a key the owner's browser made for that request.
The page opens it, shows it once, and forgets it.

On the box the minter is `vitna-mint.service`, reading `/etc/vitna/env.minter`.
By hand it needs `DATABASE_MINT_URL`, `VITNA_SITE_ORIGIN` and `WEBAUTHN_RP_ID`,
and refuses to start without all three:

```bash
npm run org:key:minter
```

The minter mints only when every one of these holds:

- the request is less than ten minutes old and names an org the requester owns;
- its passkey assertion answers a challenge that is a digest of the request
  itself, so it cannot be spent on another request or another sealing key;
- the passkey belongs to the requester, verified the person (a PIN or a
  biometric), and is approved for minting with the same key it holds now;
- the org has minted fewer than 10 console keys in a day, and the owner fewer
  than 5 in an hour.

An operator approves a passkey once, after its owner reads back the fingerprint
the settings page shows beside it:

```bash
npm run org:passkey:approve -- --github <login>
npm run org:passkey:approve -- --github <login> --passkey <id> --by "<who checked, and how>"
npm run org:passkey:approve -- --github <login> --passkey <id> --withdraw
```

This is what keeps a compromised web process from minting on its own: it can
add a passkey to an account, but not approve one. What it can still do is serve
a page that asks the owner for a passkey touch and binds that touch to a
request of its choosing, because an authenticator shows the site and not the
request. So the guarantee is no key without a live touch of an approved
passkey, not no key the owner did not mean.

Revoking from the page writes the revocation's date, reason and who revoked;
a trigger keeps a revoked key revoked for every role. Every request and its
answer stay in `site.key_request`, which nothing rewrites.

One column is easy to over-read. **Named by a reading** is not "last used": the
register keeps the newest reading per workload, so a hand-run export landing on
top of a runtime's window makes that column go quiet while the key is still
pushing, and a key that pushed once in June still shows if nothing has landed
since. It is evidence a key reached the record, never evidence of when it last
did.
Human Machine Shift+M