Skip to main content
The KYC Inbox is how a bank’s designated KYC verifier delivers KYC files to that bank. You seal the KYC file of an investor so that only the bank can read it, sign it, and post it to the bank’s inbox. Trusset stores the sealed envelope and relays it. It holds no key that opens it. The bank’s side of the same flow, including approving a record and listing the wallet, is under Customers. There are two ways to use the inbox:
  • The command line tool. trusset-kyc seals, signs, sends and revokes for you. See the verifier walkthrough.
  • Your own implementation. The envelope uses HPKE as standardised in RFC 9180 and Ed25519 signatures. This page specifies the format completely, so a stock HPKE library is enough.

Base Path

sourceId and the API address both come from the invite the bank gave you. Each source has its own inbox, and one inbox delivers to one bank instance.

Authentication

Every request carries the token from the invite as a bearer token:
No API key is used here. The token identifies you to the inbox. It does not authenticate a record: every delivery and every revocation is also signed with your Ed25519 signing key, and the bank verifies those signatures itself. A missing, malformed or wrong token answers 401 UNAUTHORIZED. So does an unknown sourceId and a source the bank removed, with the same message, so the answer does not reveal which of them applies. When the bank issues a new invite, the old token stops working at once.

The invite

The bank creates your source and hands you one string:
Treat the invite as a secret. It holds your token.Seal only to the recipientKey from the invite. The inbox reports the bank’s current key as well, but that report passes through Trusset, so use it only as a check: when it differs from the key in your invite, send nothing and ask the bank for a new invite.The invite itself is also issued through Trusset. Before your first delivery, have the bank read you the fingerprint of its recipient key from trusset-kyc key show on its own machine, over a channel that does not run through Trusset, for example by phone. Check the invite’s recipientKey against it and seal nothing if they differ: trusset-kyc invite add --fingerprint does this, and in code assertInviteFingerprint from trusset-kyc-courier. Never take the value to compare from the invite or from anything Trusset serves. Give the bank the fingerprint of your signing key the same way.

Keys

A key ID is the first 16 hex characters of SHA-256 over the raw public key bytes. A fingerprint is the first 32 hex characters of the same hash, in 8 groups of 4 separated by a space, for example b961 9d9b e69e d903 c31c 6f1a f3c6 a7d2. You send the bank your signing public key once. The bank registers it on your source and pins it in its own tool. Trusset never needs your private key, and no endpoint accepts one.

Envelope format

An envelope has four parts: a clear header, the HPKE encapsulated key, the ciphertext and a signature. Build them in this order.

1. The record document

The record document is what the bank reads after decryption. It is a JSON object serialised to UTF-8 bytes, called P below:
An attachment name is a plain file name of at most 120 characters: no path separator, no leading dot, unique within the record in any letter case. mediaType is a lowercase type/subtype. From P you derive three values:

2. The header

The header is the only part Trusset can read. It carries exactly these 13 keys and no other. Write them in this order:
Every value except v is a string, and each one has a fixed form. The header has no free-text key and none can be added. A header with a missing or an extra key is refused. Compact JSON. The header bytes are the UTF-8 bytes of the JSON with no whitespace and no duplicate keys. They must equal what JavaScript produces with JSON.stringify(JSON.parse(text)). Anything else is refused with VALIDATION_ERROR. In Python, json.dumps(header, separators=(',', ':'), ensure_ascii=False) produces this form. In Go, disable HTML escaping in the encoder. The header bytes are used three times, always the exact same bytes: as the HPKE associated data, inside the signature, and on the wire as base64url without padding. They are at most 2,048 bytes.

3. Sealing

Seal with HPKE, RFC 9180, base mode, single shot: The result is enc, the 32-byte encapsulated key, and ciphertext, the AES-256-GCM output with its 16-byte tag appended. One message is sealed per context, so the sequence number is 0.

4. The signature

Both hashes enter as their 32 raw bytes. The signature is 64 bytes. It binds the header to the sealed bytes, so neither can be exchanged without breaking it.

The delivery body

The ciphertext limit covers the whole record document with its attachments. Attachments are base64 inside the document, so about 4.5 MiB of files fit in one record. Describe Inbox reports the limit as limits.maxCiphertextBytes.

Timestamps

Every timestamp has exactly the form YYYY-MM-DDTHH:mm:ss.sssZ, in UTC with milliseconds, as JavaScript’s toISOString() writes it. On delivery the header must satisfy all of these, measured against Trusset’s clock, which Describe Inbox returns as serverTime:

What Trusset checks

On delivery Trusset checks the header’s form and timing, the sizes, that sourceId names your inbox, that profileKey is the one the bank set for you, that recipientKeyId names the bank’s current key, and the signature against the signing key the bank registered for your source. Trusset cannot check anything inside the ciphertext. The bank’s tool does that after decryption: it verifies the signature on the envelope and innerSignature against the key the bank pinned, and compares the record document with recordDigest, openCommitment, the fields repeated in the header and every attachment hash. An envelope that fails there is rejected by the bank with BAD_SIGNATURE, DIGEST_MISMATCH or UNDECRYPTABLE, which you read from Get Delivery Status.

Sending twice

Posting the exact same envelope again is safe. It answers 200 with replayed: true and the record it already created, and stores nothing new. Two other cases are refused: A record that has to be delivered again, for example after the bank rejected it, is sealed again with a new envelopeId, openProof and nonce. That also gives it a new recordDigest.

Revocations

You revoke a record you delivered with a signed statement. Its header carries exactly these 8 keys, as compact JSON under the same rules:
revocationId is 16 random bytes as 32 lowercase hex characters. reason is EXPIRED, WITHDRAWN, SUPERSEDED, INVALID or OTHER. issuedAt follows the same rule as on a delivery.
The body is { "header": "<base64url>", "signature": "<base64>" }. See Revoke Record.

What happens to a record

Trusset deletes the ciphertext when the bank opens or rejects the record, when you revoke it, when validUntil passes, and after 30 days uncollected. The header stays.

Response envelope

Every answer carries both data and error, with the unused one null. On failure, error carries code and message, and details.field where one field is at fault. Responses are sent with Cache-Control: no-store.

Errors every route can return

Rate limits

Requests without an API key count against the per-IP limit of 100 requests per minute described on Rate Limits. The inbox adds two of its own: 240 requests per minute for each source, and 20 failed authentications per 10 minutes for each IP address, after which a further failed attempt answers 429 instead of 401. A delivery is also refused with 429 INBOX_FULL while too many of your records wait unopened at the bank. That is not a rate limit: retrying does not help until the bank opens records. See Deliver Record.

What Trusset does not do

Trusset relays and stores ciphertext. It does not verify an investor, does not read or assess a KYC file, and takes no part in the bank’s decision to accept a record. Whether the bank may rely on your verification, and how personal data may pass between you, is governed by the agreements between you and the bank.