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
key show
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
--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
RECEIVED, then acknowledges each to Trusset. --out is required. Give either one record ID or --all. The bank walkthrough lists the outcomes.
verify
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
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
<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
status
revoke
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 codes502, 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.