createTinV1IdentityEnvelope — Encrypt a TIN identity

Create the keyed lookup commitment and encrypted identity envelope accepted by the TIN V1 registry instruction.

What it does

This SDK helper derives a keyed lookup commitment from the supplied TIN and protected resolver secret, encrypts the display name and TIN with AES-GCM, and returns the ciphertext envelope. It does not create an on-chain TIN account. Call it only in a trusted backend that can access the lookup secret; never send that secret to Receiver.

How the flow works

1. Caller invokes the function

   The trusted issuer supplies the random TIN, display name, and protected lookup secret.
2. Validation

   The function requires at least 16 bytes of resolver secret material.
3. Main work

   It derives the lookup commitment, generates a random AES-GCM nonce, and encrypts the JSON identity payload.
4. Result

   It returns lookupCommitment and an envelope containing nonce bytes followed by ciphertext bytes.

Signature

export async function createTinV1IdentityEnvelope(params: {
  tin: bigint | number | string;
  displayName: string;
  lookupSecret: Uint8Array | string;
}): Promise<{ lookupCommitment: Uint8Array; encryptedIdentityEnvelope: Uint8Array }>

tin · bigint | number | string · required

TIN lookup material.

displayName · string · required

Name placed inside the encrypted JSON payload.

lookupSecret · Uint8Array | string · required

Protected resolver secret; keep it on the trusted XP backend and TSN Node only.

Result and errors

The helper returns a 32-byte lookup commitment and AES-GCM envelope. It throws if the runtime does not expose WebCrypto AES-GCM support.

This invocation is illustrative; the caller provides a generated TIN and a configured secret. Use the complete source-derived signature for runtime validation requirements.

const envelope = await createTinV1IdentityEnvelope({
  tin: generatedTin,
  displayName: "Example",
  lookupSecret: process.env.TINS_LOOKUP_SECRET!,
});

Source: tins.ts