Catalisa Biometrics SDKs

SDKs and integration snippets for Catalisa Biometrics — liveness and face-match sessions with a hosted capture page, an explainable decision and Ed25519-signed evidence.

API base URL: https://api.biometrics.catalisa.app/v1. Authentication: X-API-Key (or an IAM JWT as Authorization: Bearer). A test key runs the sandbox: simulated engine, no allowance spent, nothing billed.

your server ── POST /sessions ─────────────▶ Biometrics ── handoff.captureUrl ──▶ your server
your front  ── opens captureUrl (link / iframe / modal / WebView) ─▶ hosted capture page
hosted page ── postMessage progress (ready, step:<GESTURE>, done…) ─▶ your front   (never the result)
Biometrics  ── webhook biometrics.session.completed (RSA-SHA256) ──▶ your server   (the result)

The capture page never tells the person whether they were approved; the decision is read on the server.

packages/node      @catalisa/biometrics        (src, test, tsup → dist ESM/CJS/d.ts)
packages/web       @catalisa/biometrics-web    (src, test, tsup → dist ESM/CJS + UMD)
packages/python    catalisa-biometrics         (src/catalisa_biometrics, tests)
packages/go        .../packages/go             (stdlib only; tagged packages/go/vX.Y.Z)
packages/php       catalisa/biometrics         (src, tests; ext-curl/openssl/sodium only)
packages/dotnet    Catalisa.Biometrics         (src, tests; net8.0 + netstandard2.0)
packages/ruby      catalisa-biometrics         (lib, test; stdlib only)
packages/java      io.github.catalisaio:…      (src, tests; JDK + Jackson)
snippets/          short, complete snippets for the developer guide + index.json
examples/          node-server: full flow (session endpoint, modal page, webhook)
vectors/           crypto vectors generated by the building block's own code
scripts/           mock server, vector generator and the snippet/example verifiers

snippets/<topic>/<language>.<ext> (one entry per language per topic), indexed in snippets/index.json (topic, language, title, file).

Environment variables used by the snippets: CATALISA_API_KEY, CATALISA_BIOMETRICS_URL (optional), SESSION_ID, CATALISA_SUBACCOUNT_ID, CATALISA_WEBHOOK_KEYS (JSON map keyId → public key PEM), PORT.

npm install
npm test                                  # node + web
npm run build
(cd packages/python && python3 -m venv .venv && .venv/bin/pip install pytest && .venv/bin/python -m pytest -q)

node scripts/verify-snippets.mjs          # 32 server snippets; php/go/ruby/C# run in official docker images
node scripts/verify-web-snippets.mjs      # 4 web snippets in jsdom
node scripts/verify-example.mjs           # examples/node-server end to end

• HTTP snippets run against scripts/mock-biometrics.mjs, a mock that reproduces the server's routes, envelopes and error bodies (including the subaccount 402/403).
• Webhook servers receive deliveries signed at run time by the building block's own code (scripts/bb-vector.sh fresh extracts origin/main of building-blocks-v2 with git archive and runs src/webhooks-engine/utils/crypto.ts): a valid one must return 200; a tampered body and a 10-minute-old one must return 400.

vectors/vectors.json is produced by scripts/gen-vectors.bb.ts running inside a copy of the building block's source — the webhook signature by the Webhooks Engine's signPayload, the evidence signature by BiometricsEvidenceSignatureService.sign, and the list of capture page events from capture-page/page.ts. The Node, Web and Python test suites all read it, so a change in the server's signing format breaks the SDK tests. Regenerate with scripts/bb-vector.sh static vectors/vectors.json.

See PUBLISHING.md.