encryptTinSensitiveField — Encrypt sensitive field

Encrypt a TIN-sensitive field locally with a signature-derived AES-GCM key and return its authorization hash.

What it does

This function encrypts a sensitive TIN field using a key derived from the TIN, field type, and user signature. It also returns a hash of the signature for registry binding.

How the flow works

1. Caller invokes the function

   The caller provides the TIN, field type, plaintext value, and user signature.
2. Validation

   The SDK requires WebCrypto AES-GCM support and uses the exact field type and signature bytes for key derivation.
3. Main work

   It generates or accepts a nonce, encrypts the value, and hashes the signature bytes.
4. Result

   It returns { nonce, ciphertext, userAuthorizationHash } for the sensitive-field instruction.

Signature

export async function encryptTinSensitiveField(params: {
  tin: bigint | number | string; fieldType: string; value: string;
  userSignature: Uint8Array | string; nonce?: Uint8Array;
}): Promise<{ nonce: Uint8Array; ciphertext: Uint8Array; userAuthorizationHash: Uint8Array }>

tin · bigint | number | string · required

TIN key input.

fieldType · string · required

Field namespace bound into the key.

value · string · required

Plaintext field value.

userSignature · Uint8Array | string · required

Authorization material used for key derivation and hashing.

nonce · Uint8Array

Optional AES-GCM nonce.

Result and errors

Returns ciphertext, nonce, and a 32-byte authorization hash. WebCrypto failures are propagated.

const encrypted = await encryptTinSensitiveField({ tin, fieldType: "phone", value, userSignature });

Source: tins.ts:1362-1379