saphan trust
Creates and manages the keys and signed records that establish who may instruct and approve work in an installation: the root key, delegations, the deployment record and edition, the owner's presence
Creates and manages the keys and signed records that establish who may instruct and approve work in an installation: the root key, delegations, the deployment record and edition, the owner's presence key, the seat-issuing key and the gateway's server certificate. saphan trust doctor checks their health.
saphan trust author-epoch
Groups the commands for an author epoch: the point from which a kind of record, such as review notes or status reports, must carry its author's signature.
saphan trust author-epoch propose
Prints the proposed epoch declaration for each kind named with --cut — the boundary, how many records it freezes and the digest the owner's touch would sign — without signing or writing anything. Declaring the epoch is a separate owner act; a proposal alone is never accepted by a verifier.
| flag | type | default | what it does |
|---|---|---|---|
--cut | stringArray | Repeatable kind=<RFC 3339 time>: freeze every record of that kind captured at or before the time. Kinds are actor-turn, exec-status, master-verify, review-notes, review-status and round. | |
--writer-landed | stringArray | Repeatable: a kind whose signing writer is installed and confirmed working; a --cut for a kind not named here is refused. |
saphan trust delegate
Signs a grant letting another key act for a limited scope, set of streams and period, and records it in the signed identity store; the delegations section of the actor roster file is regenerated from it. Scopes are order signing (the default), seat issuing and owner presence; for the last two the command only previews what it would sign until you add --yes. ⚠ This is an owner act: for an order-signing grant, and for the other two scopes once you add --yes, it prints a one-time code on this terminal and waits for you to type it back. It is refused when no terminal is attached (for example from a script or a CI job), and in the console's browser terminal it is refused in favour of the console's passkey prompt.
| flag | type | default | what it does |
|---|---|---|---|
--delegate-actor | string | The name of the actor receiving the grant (required). | |
--delegate-key-id | string | The receiving key's apk- key id (required). | |
--delegate-pub | string | The receiving key's public key, base64-encoded (required). | |
--exp | string | When the grant expires, as an RFC 3339 time (required for every scope). For seat-issuing and owner-presence it must also be later than --nbf and later than now. | |
--nbf | string | When the grant becomes valid, as an RFC 3339 time (required). | |
--registry | string | The actor registry file; defaults to <workspace>/bridge/registry/ACTORS.md. Any other path is refused. | |
--root-key | string | The root private key to sign with; defaults to ~/.saphan/trust/root.key. For an order-signing grant: If you leave it out and an identity-signing delegate that the root granted is installed beside the default root key (identity-delegate.key), the delegate signs instead, and a delegate key there with no grant covering it is refused; a key you name always signs. | |
--scope | string | order-signing | ⚠ What the grant allows: order-signing (the default), seat-issuing (signing the grants that admit agent seats) or owner-presence (signing the owner's presence proof at the gateway). The last two are powerful and sign only with --yes. |
--stream | stringSlice | For an order-signing grant, a stream the grant covers (repeatable); * covers every stream. ⚠ If you leave it out, the grant covers every stream. Refused for seat-issuing and owner-presence grants, which are not limited to streams. | |
--ts | string | The grant's timestamp, as an RFC 3339 time; defaults to now. | |
--yes | bool | false | For seat-issuing and owner-presence grants, actually sign; without it the command prints exactly what it would sign. |
saphan trust deployment
Groups the commands for the deployment record: the root-signed record naming the installation's ids, edition, owners and server identity.
saphan trust deployment set
Root-signs the installation's deployment record: the first one, or a change to the one in force. The first record needs --deployment-id, --workspace-id, --org-id, --edition and at least one --owner; a change keeps the ids and replaces only the parts you name. It prints the exact record and signs nothing until you add --yes.
| flag | type | default | what it does |
|---|---|---|---|
--clear-server-identity | bool | false | Remove the server identity from the record. |
--deployment-id | string | The deployment id, 32 lowercase hex digits; required on the first record. | |
--edition | string | The edition: solo, team or enterprise. | |
--org-id | string | The organisation id; required on the first record. | |
--owner | stringSlice | An owner's actor handle (repeatable); when given, it replaces the list of owners. | |
--root-key | string | The root private key to sign with; defaults to ~/.saphan/trust/root.key. | |
--rp-from-config | bool | false | Record the passkey relying party the configuration names (webauthn_rp_id and webauthn_origins under [act_authority]), against which every person's passkey assertion is re-verified. |
--server-identity | stringSlice | A seat-issuing key id (apk-…) of the server's own unix user (repeatable; team and enterprise only); when given, it replaces the list. ⚠ Once the list is set, a seat grant dated after the record and signed by any key not on it is refused, the root key included. | |
--ts | string | The record's time, as an RFC 3339 time; defaults to now. | |
--workspace-id | string | The workspace id, 32 lowercase hex digits; required on the first record. | |
--yes | bool | false | Sign the record; without it the command only prints what it would sign. |
saphan trust doctor
Checks the installation's trust material: the root public key is present and its file custody is sound, the root private key passes the same checks if it is on this host, the trust.enforce setting is valid, and the gateway's server certificate is not expired (a warning within 14 days of expiry). On team and enterprise editions it also checks that the seat-issuing key is not owned by, or readable to, the user agents run as; on solo it states that agents can read that key, so agent attribution rests on seat signatures alone. It changes nothing, and it is not a full check of every signature in the registry.
| flag | type | default | what it does |
|---|---|---|---|
--root-pub | string | The root public key to check; defaults to ~/.saphan/trust/root.key.pub. |
saphan trust edition
Prints the edition (solo, team or enterprise) recorded in the installation's root-signed deployment record, who signed it and when, or why it cannot be read. It reads only that signed record, never a local setting, and changes nothing.
saphan trust edition set
Records the installation's edition in a root-signed deployment record, an owner act. The first record also names the organisation and the owners; a later call amends that one record and keeps everything else. The command reads no clock, so you give the signing time with --at; rehearse it with saphan dry-run trust edition set ….
| flag | type | default | what it does |
|---|---|---|---|
--actor | string | The actor handle recorded as writing the record (required). | |
--at | string | The RFC 3339 time the owner signs at (required; no clock is read). | |
--org | string | The organisation name; required on the first record and kept from it afterwards. | |
--owner | stringSlice | An owner's actor handle (repeatable), first record only; defaults to --actor. | |
--root-key | string | Absolute path of the owner's root private key (required); it must match the root key this installation pins, or the record is refused before it is written. |
saphan trust gate-epoch
Groups the commands for the person epoch for gates: the point after which every gate decision must be signed by the person or seat that made it.
saphan trust gate-epoch declare
Declares the person epoch for gates with the owner's touch. By default it opens the console's epoch page (Touch ID or a phone) and waits for the declaration to be recorded; --cli takes the touch on this terminal with a FIDO2 security key. ⚠ An epoch is declared once and its boundary never moves, so run propose first and compare the digest with the one on your screen.
| flag | type | default | what it does |
|---|---|---|---|
--cli | bool | false | Take the touch on this terminal with a FIDO2 security key instead of the console page; required when this installation reads its record through a gateway. |
saphan trust gate-epoch propose
Prints the declaration the owner would approve — the boundary (the newest gate decision at this moment), how many decisions it freezes and the digest the touch signs — without signing or writing anything.
saphan trust init
Creates the installation's root key pair at ~/.saphan/trust/root.key and prints its apk- key id; the private key is never printed. ⛔ It never overwrites an existing key, because a new root would invalidate every signature the old one made. ⚠ This is an owner act: it prints a one-time code on this terminal and waits for you to type it back. It is refused when no terminal is attached (for example from a script or a CI job), and in the console's browser terminal it is refused in favour of the console's passkey prompt.
| flag | type | default | what it does |
|---|---|---|---|
--root-key | string | Where to write the root private key; defaults to ~/.saphan/trust/root.key. |
saphan trust owner-key
Groups the commands for the owner's presence key: a passphrase-sealed key that the root delegates to, used to prove the owner is present.
saphan trust owner-key init
Creates the owner's presence key, sealed under a passphrase you type twice at the terminal, and writes it to ~/.saphan/trust/owner.key without overwriting an existing one. The key does nothing until the root delegates to it; the command prints the complete saphan trust delegate --scope owner-presence … line to run on the machine that holds the root key. ⚠ This is an owner act: it prints a one-time code on this terminal and waits for you to type it back. It is refused when no terminal is attached (for example from a script or a CI job), and in the console's browser terminal it is refused in favour of the console's passkey prompt.
| flag | type | default | what it does |
|---|---|---|---|
--owner-key | string | Where to write the sealed key; defaults to ~/.saphan/trust/owner.key. | |
--root-workspace | string | The workspace root on the machine that holds the root key, used in the printed delegation line; defaults to --workspace. |
saphan trust seat-issuer
Groups the commands for the seat-issuing key, which signs the grants that admit agent seats.
saphan trust seat-issuer init
Creates the seat-issuing key at <state dir>/seat-issuer.key (mode 0600, never overwritten) and prints its apk- id and public key. On team and enterprise editions it refuses unless run as the server's own unix user, the one that owns the state directory; on solo it states the weaker separation. Without --yes it only prints what it would create. It is refused until the deployment record exists (saphan trust deployment set), because the edition decides who may create the key.
| flag | type | default | what it does |
|---|---|---|---|
--yes | bool | false | Create the key; without it the command only prints what it would do. |
saphan trust server-cert
Issues a TLS server key and certificate for the gateway from the fleet's intermediate certificate authority, an owner act, writing the files the gateway's --tls-key, --tls-cert and optionally --client-ca options read. At least one --dns or --ip name and an explicit --ttl are required (refusals server-cert-no-san and server-cert-ttl-required). To renew, use --reuse-key; otherwise an existing key file is refused with server-cert-key-exists.
| flag | type | default | what it does |
|---|---|---|---|
--cert-out | string | Where to write the certificate, as PEM (required); this is the gateway's --tls-cert. | |
--client-ca-out | string | Optionally also write the fleet's intermediate certificate here as PEM, for the gateway's --client-ca; the fleet's own copy is DER, which that option cannot read. | |
--dns | stringSlice | A DNS name the certificate must cover (repeatable); at least one --dns or --ip is required. | |
--intermediate-cert | string | The issuing intermediate certificate; defaults to ~/.saphan/trust/intermediate.crt. | |
--intermediate-key | string | The issuing intermediate private key; defaults to ~/.saphan/trust/intermediate.key. | |
--ip | stringSlice | An IP address the certificate must cover (repeatable); at least one --dns or --ip is required. | |
--key-out | string | Where to write the private key, as PKCS#8 PEM with mode 0600 (required); this is the gateway's --tls-key. | |
--name | string | The certificate's common name, the identity this server is called by in reports (required). | |
--reuse-key | bool | false | Renew: issue a new certificate over the existing key at --key-out, which is only read, never rewritten. |
--ttl | duration | 0s | ⚠ How long the certificate is valid, for example 720h (required; there is no default). When the gateway's certificate expires, every machine in the fleet loses its connection at once. |
saphan trust vendor-key
Groups the command for the vendor key, which signs the product canon (the governing documents shipped inside the binary). Used when producing Saphan Studio releases; not needed to operate an installation.
saphan trust vendor-key init
Creates the vendor key pair, writing the private key only to --out and printing the public key and its id. ⛔ It refuses a relative path, a path inside any git work tree, and an existing file; rehearse with saphan dry-run trust vendor-key init --out <path>. Used when producing Saphan Studio releases; not needed to operate an installation.
| flag | type | default | what it does |
|---|---|---|---|
--out | string | Absolute path for the private key, outside any git work tree (required). |
Global options apply to every command — see Every command.
saphan train
Shows and maintains trains: a train is a planned series of related work items, called wagons, declared in a train order and identified by its track name; each wagon is dispatched as its own stream.
saphan verify
Checks a signed instruction — a law document by path, or a registered order by reference — against the installation's trust chain (root key, actor registry, laws manifest and delegations) and prints o