Skip to main content
trusset-kyc has a bank side and a verifier side. Every command accepts the common options.

Common options

Environment variables

The API address must use https. Plain http is accepted only for localhost, 127.0.0.1 and [::1].

Bank commands

keygen

Creates an X25519 record key pair and stores it in the keystore. Prints the public key, the key ID and the fingerprint. Running it again adds a key and keeps the earlier ones.

key show

Lists the record keys in the keystore, public parts only, and marks the newest.

source add, source revoke-key, source list, source remove

source add pins the signing key of a source. Records from that source are accepted only when signed by this key. A source that is already pinned is refused unless --replace is given, and --replace needs a decision about the former key. --former-key retire is a planned rotation: the former key opens no new record, and records filed while it was pinned still verify. --former-key revoke is for a key that was lost or exposed: it opens no new record, and records filed under it no longer verify. --former-key without --replace is refused. Run open --all before you pin a new key, because a former key never opens a record again, whatever date the envelope claims. source revoke-key revokes a retired key that later turned out to be exposed. The current key cannot be revoked this way; pin the new key with --replace --former-key revoke instead. A revoked key can never be pinned again, for this or any other source. source list shows how many retired and revoked keys a source has. source remove deletes the pin and its retired keys. Its revoked keys stay in the keystore, so removing a source and adding it again does not undo a revocation.

pull

Lists the records Trusset holds for your instance. Nothing is decrypted. --status takes one of the eight record statuses and defaults to RECEIVED. Each line says whether the record’s source is pinned and whether the record key it is sealed to is in this keystore.

open

Downloads, verifies, decrypts and files one record, or every record in status RECEIVED, then acknowledges each to Trusset. --out is required. Give either one record ID or --all. The bank walkthrough lists the outcomes.

verify

Verifies a filed record directory offline. The key in the folder’s source.json must match a key you trust: the source’s pin in this keystore, one of its retired keys for a record sealed before that key was retired, or the key or fingerprint given with --key or --fingerprint. A revoked key anchors nothing. Without one of these the record does not verify. The envelope signature is always checked, so a receipt without a valid sealedDigest or a missing envelope.sig makes the record fail. Exits 0 when it verifies and 2 when it does not.

Verifier commands

source-keygen

Creates the Ed25519 signing key pair and prints the public key and its fingerprint. A keystore holds one signing key, and the command refuses to overwrite it.

invite add, invite confirm, invite list, invite remove

invite add requires --fingerprint: the fingerprint of the bank’s recipient key as the bank read it out from trusset-kyc key show over a channel that does not run through Trusset. The tool checks that the key in the invite has exactly this fingerprint. When it does not, nothing is stored and the command exits with 2 (FINGERPRINT_MISMATCH). Without --fingerprint nothing is stored and it exits with 1 (FINGERPRINT_REQUIRED). When it matches, the invite is stored as confirmed and the tool asks the inbox for the bank’s key as a consistency check; when that check fails, the invite stays stored and the command exits with an error that says so. --replace is needed to replace a stored invite for the same source. invite confirm confirms an invite stored by version 1.1.0 or earlier, which seal and send refuse until then (INVITE_NOT_CONFIRMED). A wrong fingerprint leaves the invite stored but not confirmed. invite list never shows the token, and shows the recipient key, its key ID and its fingerprint only for a confirmed invite.

seal

Seals and signs a record for the bank named in the stored invite and writes <envelopeId>.envelope.json. The invite must be confirmed against the bank’s fingerprint. Works offline unless --send is given, which checks the bank’s key and delivers in the same run. When the delivery fails, the envelope file is kept and can be sent later.

send

Delivers a sealed envelope. Before it posts, it checks that the envelope is sealed to the key the invite pins, that the timing rules hold, and that the inbox reports the same recipient key. When the keystore holds the signing key, it also checks that the envelope is signed by it.

status

Shows what happened to a delivered record.

revoke

Signs and posts a revocation for a delivered record.

Exit codes

Errors are written to stderr as one line starting with error:, warnings as lines starting with warning:.

JSON output

With --json the tool prints one JSON object on one line of stdout. It carries ok and command plus the result fields of the command. On failure ok is false and an error object holds code and message. The exit code is the same as without --json.

Network behaviour

Every call has a timeout of 60 seconds, and 300 seconds for uploading and downloading an envelope. Network failures and the status codes 502, 503 and 504 are retried, up to 3 attempts in total, for calls that are safe to repeat. A 429 RATE_LIMIT_EXCEEDED answer is waited out and retried, also up to 3 attempts. INBOX_FULL is not retried. Redirects are not followed.