> ## Documentation Index
> Fetch the complete documentation index at: https://vitruvio.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Signing and trust roots

> Integrity versus authenticity, a governed genesis, explicit signing, and rotating or revoking keys.

Integrity and authenticity answer different questions. `brain verify` proves that the blocks match their hashes and
module roots. `auth status` also asks whether valid, authorized SSH signatures support the claimed head. A brain may
therefore be intact and still be unsigned, unpinned or signed by a key outside its trust root.

Vitruvio never reads a private key. Signing uses an Ed25519 key already offered by `ssh-agent`:

```console theme={null}
ssh-add ~/.ssh/id_ed25519
vitruvio auth keys
vitruvio auth status
vitruvio auth trust-root
```

The fingerprint printed by `auth keys` is the identifier accepted by `--sign-with` and `auth sign`.

## Start governed

Governance must be in the genesis; it cannot be asserted retroactively over an existing history. The concise path
synthesizes revision 1 from one or more agent keys, gives them every signing scope and associates them with the
configured actor:

```console theme={null}
vitruvio --actor maintainer@example.org brain init ./brain \
  --governed --sign-with SHA256:REPLACE_WITH_FINGERPRINT
```

Repeat `--sign-with` and set `--govern-quorum 2` when two independent keys must approve a trust-root change. For
separate scopes or subjects, author a TOML or JSON `TrustRoot` document and pass `--trust-root root.toml`. The root
travels in the snapshot; the consumer pins its digest, not a mutable list maintained elsewhere.

Signing is always explicit:

```console theme={null}
vitruvio auth sign SHA256:REPLACE_WITH_FINGERPRINT
vitruvio auth status
vitruvio auth attribution
```

`auth trust-root` is the human-readable governance inventory: the root digest and revision, consumer pin, quorum,
each public-key fingerprint, its canonical subject, scopes and whether it is active at the inspected snapshot. Pass
`--snapshot` to audit an earlier version. It prints an explicit ungoverned result when no root exists; an unsigned
ungoverned brain is not thereby corrupt.

Choosing between a governed and an ungoverned brain is the first decision of the [onboarding](/docs/onboarding/governed-or-ungoverned); this page is what the governed choice commits you to afterwards.

## Rotation and revocation

For a distributed rotation, create the exact document once, send that immutable plan to the quorum, collect detached
records, and commit the same bytes:

```console theme={null}
vitruvio auth plan-rotate next-root.toml --output rotation.json
vitruvio auth countersign rotation.json SHA256:KEY_A --output key-a.json
vitruvio auth countersign rotation.json SHA256:KEY_B --output key-b.json
vitruvio auth rotate --plan rotation.json --record key-a.json --record key-b.json
```

A local quorum can use `auth rotate --trust-root next-root.toml --sign-with ...`. `auth revoke` distinguishes
prospective retirement (`--retired-from`) from compromise at an already published snapshot
(`--compromised-from`); they are intentionally not interchangeable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.