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

# KYC Courier

> Move KYC files from your verifier to your bank as ciphertext only the bank can open.

The KYC courier moves an investor's KYC file from your verifier to your bank as ciphertext that only the bank can open. Trusset relays the sealed envelope and never holds a key that opens it.

`trusset-kyc` is the command line tool for [sealed KYC records](https://docs.trusset.org/protocol/infrastructure/sealed-kyc-records.md). It runs on your own machine and has two sides:

* **The verifier** seals the KYC file of an investor so that only the bank can read it, signs it, and posts it to the bank's inbox on Trusset.
* **The bank** downloads the sealed envelope, verifies and decrypts it locally, files the record, and proves to Trusset that it opened it. Trusset then deletes the ciphertext.

Banks follow the [bank walkthrough](https://docs.trusset.org/tools/kyc-courier/bank-walkthrough.md). Fintechs and other verifiers follow the [verifier walkthrough](https://docs.trusset.org/tools/kyc-courier/verifier-walkthrough.md). [Trusset for banks](https://docs.trusset.org/protocol/banks.md) and [Trusset for fintechs](https://docs.trusset.org/protocol/fintechs.md) show where KYC fits in each path.

## Who uses it

| Role | What they do with the tool |
| - | - |
| Bank | Creates the record key, pins each verifier's signing key, opens the records that arrive, and can verify a filed record again offline at any time |
| Verifier | Creates a signing key, stores the bank's invite, seals and sends records, follows their status, and revokes a record when needed |
| Auditor | Runs `trusset-kyc verify` on a filed record directory with the verifier's fingerprint, which the bank gives it (`--fingerprint`). Needs no network and no private key |

Approving a record and listing its wallet on a whitelist are not part of the tool. The bank does that in the Issuer Portal or through the [API](https://docs.trusset.org/endpoints/customers/approve-kyc-record.md), and its own wallet signs.

## What Trusset sees

* The envelope header: envelope ID, source ID, wallet address, profile key, recipient key ID, two digests and three timestamps.
* The size of the ciphertext and the time of delivery.
* Whether and when the bank opened, approved or rejected a record, and whether the verifier revoked it.

## What Trusset cannot do

* **Read a record.** Records are encrypted to the bank's X25519 key with HPKE (RFC 9180). The private key never leaves the bank's keystore.
* **Forge or alter a record.** Each record is signed twice with the verifier's Ed25519 key: once inside the ciphertext, once over the header and the ciphertext. The bank's tool checks both against a key the bank pinned itself.
* **Move a record to another wallet, source or profile.** Those fields are in the signed header, the header is bound into the encryption, and the same fields are repeated inside the signed record.
* **Claim that a record was opened.** Opening is proven with a random value that exists only inside the ciphertext.

## The two pinning rules

These two rules are what make the list above hold even if Trusset were compromised:

1. **The verifier pins the bank's key from the invite.** The tool never encrypts to a key that Trusset reports. If Trusset reports a different key than the invite holds, `send` refuses.
2. **The bank pins each verifier's signing key in its own keystore.** The signing key Trusset reports is shown as a hint and is never used to verify a record.

> [!WARNING]
>
> The invite itself is issued through Trusset. Compare fingerprints over a channel that does not run through Trusset, for example by phone, before the first record is sent:
>
> * The bank reads the verifier the fingerprint of its recipient key from `trusset-kyc key show` on its own machine, never from the Trusset app, which is served by Trusset like the invite. The verifier passes it to `invite add --fingerprint`, which stores the invite only when the key in it has exactly this fingerprint. `seal` and `send` refuse an invite that was never checked this way.
> * The verifier reads the bank the fingerprint of its signing key before the bank runs `source add`, and the bank compares it with what `source add` prints.
>
> A fingerprint is the first 32 hex characters of SHA-256 over the raw public key, in 8 groups of 4, for example `b961 9d9b e69e d903 c31c 6f1a f3c6 a7d2`. A key pinned without this comparison is only the key Trusset relayed.

A compromised relay could still drop or delay envelopes, replay an old valid envelope, report wrong status values and report wrong key hints. It could not make the bank accept a record the pinned verifier did not sign, and it could not read anything.

When a verifier changes its signing key, the bank's tool holds the records signed with the new key. It neither opens nor rejects them, and it prints both fingerprints. The bank first opens every record still waiting under the old key, then compares the new fingerprint with the verifier and pins the new key with `source add --replace --former-key retire`, or `--former-key revoke` when the old key was exposed. A former key never opens a new record, whatever date the envelope claims. A retired key keeps the records filed under it verifying; a revoked key does not, and it can never be pinned again, not even after `source remove`.

`verify` checks a filed record against a key the person running it trusts: the pin in the local keystore, one of its retired keys, or the key or fingerprint given on the command line. Without one of these the record does not verify, because the key that comes with the folder proves nothing on its own.

## What the tool does not decide

The tool moves a file and proves where it came from. It does not judge whether the verification behind it is sufficient. Whether a bank may rely on a verifier's KYC, and how personal data may pass between the two, is governed by the agreements between the bank and the verifier.

The tool does not check what a verifier seals. A record with wrong content is still validly signed, so the review of the file stays with the bank.

## Getting the tool

The tool is not published to a package registry. Trusset provides it during onboarding.

It needs Node.js 18 or newer and has no runtime dependencies. All cryptography uses the `crypto` module built into Node.js. From the folder you received:

```bash theme={null}
npm install -g .
trusset-kyc --version
```

Or run it without installing: `node bin/trusset-kyc.js --help`.

File modes are not enforced on Windows. Use a directory there that only your account can read.

Version 1.2.0. Apache-2.0 license.

> [card] [Bank walkthrough](https://docs.trusset.org/tools/kyc-courier/bank-walkthrough.md)
>
> From the record key to an opened and filed record

> [card] [Verifier walkthrough](https://docs.trusset.org/tools/kyc-courier/verifier-walkthrough.md)
>
> From the invite to a delivered record, its status and a revocation

> [card] [CLI reference](https://docs.trusset.org/tools/kyc-courier/cli-reference.md)
>
> Every command, option, environment variable and exit code

> [card] [Keys and files](https://docs.trusset.org/tools/kyc-courier/keys-and-files.md)
>
> What is written to disk, how keys are protected, what to back up


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