iceberg-subzero

Node.js / TypeScript client for the Subzero tokenization vault.

Configure entity types, API keys, and reveal policies in the dashboard first. This SDK is for server-side vault operations only — never ship sz_live_ keys to the browser.

Install

npm install iceberg-subzero

Local development:

cd node-sdk && npm install && npm run build

Quick start

import { SubzeroClient } from 'iceberg-subzero';

const client = new SubzeroClient({
  tokenizeKey: process.env.SUBZERO_TOKENIZE_API_KEY,
  revealKey: process.env.SUBZERO_REVEAL_API_KEY,
});

await client.ready();

const token = await client.tokenize('SSN', '123-45-6789');
const found = await client.search('SSN', '123-45-6789');
const value = await client.reveal(token);
const resolved = await client.resolve('123-45-6789');

Or from environment variables:

const client = SubzeroClient.fromEnv();
await client.ready();

A single apiKey works when one key has both scopes (e.g. admin):

const client = new SubzeroClient({ apiKey: 'sz_live_...' });

API key scopes

| Scope | SDK methods | |-------|-------------| | tokenize | tokenize, search, tokenizeBatch, proxy.scan, proxy.discover, proxy.restructure | | proxy | proxy.scan, proxy.discover, proxy.restructure | | reveal | reveal, resolve (requires a matching reveal policy in the dashboard) | | reveal_grant | createRevealGrant (BFF for Elements click-to-reveal) | | admin | All of the above (bypasses reveal policy) |

Use separate tokenizeKey, revealKey, proxyKey, and revealGrantKey in production for least privilege.

Reveal caller context (audit)

By default, reveal, resolve, and createRevealGrant send optional caller_context for audit logging. Auto-capture uses the first stack frame outside node_modules/ when captureCallerContext: true (default).

const client = new SubzeroClient({ revealKey: '...', captureCallerContext: false });
await client.reveal(token, { callerContext: { file: 'billing.ts', line: 42, sdk: 'node' } });

Privacy: auto-capture may include source file paths — disable or pass opaque refs if paths are sensitive.

Environment variables

| Variable | Purpose | |----------|---------| | SUBZERO_API_KEY | Single key (multiple operations) | | SUBZERO_TOKENIZE_API_KEY | Tokenize/search/batch only | | SUBZERO_REVEAL_API_KEY | Reveal only | | SUBZERO_PROXY_API_KEY | LLM proxy scan/discover/restructure only | | SUBZERO_REVEAL_GRANT_API_KEY | Browser reveal grant minting only | | SUBZERO_BASE_URL | Override API host (local/staging) |

LLM proxy preview

Dry-run scan (pre-call tokenize), discover (find-only with scores), and restructure (post-call detokenize). No upstream LLM call.

const scan = await client.proxy.scan({
  messages: [{ role: 'user', content: 'Patient SSN 123-45-6789' }],
});
console.log(scan.messages[0].tokenized);
console.log(scan.messages[0].tokensByEntityType.SSN); // grouped tokens by entity type

const discover = await client.proxy.discover({
  messages: [{ role: 'user', content: 'Patient SSN 123-45-6789' }],
});
console.log(discover.messages[0].matches[0].score);

const result = await client.proxy.restructure({
  messages: [{ role: 'assistant', content: 'SSN on file: [SSN_abc12345]' }],
});
console.log(result.messages[0].restructured);

Reveal grants (Next.js BFF)

Mint one-time grants for Elements browser reveal:

const grant = await client.createRevealGrant({
  token: '[SSN_a1b2c3d4]',
  clientPublicKeyJwk, // from iframe reveal_request
  allowedOrigin: 'https://app.yourcompany.com',
});

// Return grant.grantId to your frontend via your own API route

Batch tokenize

For ETL pipelines. Max 100 items per API request; the SDK auto-chunks larger lists.

import { isTokenizeBatchOk } from 'iceberg-subzero';

const results = await client.tokenizeBatch([
  { index: 0, entityType: 'SSN', value: '123-45-6789' },
  { index: 1, entityType: 'SSN', value: '987-65-4321' },
], {
  context: { source: 'dbt', pipelineId: 'contacts' },
});

for (const item of results) {
  if (isTokenizeBatchOk(item)) {
    console.log(item.index, item.token);
  } else {
    console.log(item.index, item.error);
  }
}

Example

With the API running and keys configured in the dashboard:

export SUBZERO_TOKENIZE_API_KEY=sz_live_...
export SUBZERO_REVEAL_API_KEY=sz_live_...
npx tsx examples/vault-demo.ts

Tests

npm test

Related

• Python SDK — same API surface for Python backends
• Elements SDK — browser capture with publishable keys
• Vault API docs