Skip to content

Backend proxy for client SDKs

Your project API token must stay on your backend (see Integration architecture). The Flutter SDK (2.1.0+) and the Web SDK (3.1.0+) support this with proxy mode: you give the SDK a baseUrl pointing at your own backend, and leave the token out. Your backend checks who is calling, rebuilds the request for that user, adds the token and sends it to Biometry. It also does two jobs the device must never do: it records the user’s consent and it owns the liveness challenge.

App (SDK, no token) ──> Your backend proxy ──> api.biometrysolutions.com
1. authenticate your user
2. allow only SDK paths
3. rebuild the request: SET user_id,
keep only owned session_ids,
SET phrase = this session's challenge
4. add Authorization: Bearer <API token>
5. send it to /api-gateway/v2 + the same path
Onboarding (once per user, server-to-server):
record authorization + storage consent

Point the SDK at your backend

In proxy mode each SDK call goes to baseUrl plus a short path of its own: the API v2 path without Biometry’s /api-gateway/v2 prefix. With baseUrl: 'https://app.example.com/biometry', a session start goes to https://app.example.com/biometry/sessions, which your proxy sends on to https://api.biometrysolutions.com/api-gateway/v2/sessions. Your backend owns these routes and their names; Biometry never sees them.

Without a token, the SDKs send no Authorization header of their own. Use headers (or a function that returns them) to send your app’s own credentials to the proxy.

final biometry = await Biometry.initialize(
baseUrl: 'https://app.example.com/biometry',
userId: 'user-123',
// Called before every request, so a refreshed token is picked up.
headersProvider: () async =>
{'Authorization': 'Bearer ${await auth.currentToken()}'},
);

The SDK methods still take a user id and, for liveness and voice-verify, a phrase. Pass your backend’s id for the signed-in user as userId (the proxy sets user_id from your session anyway), and pass the challenge you displayed as phrase. The proxy overwrites the phrase with its own copy, but the Web SDK still requires a non-empty value:

await sdk.liveness(video, currentUser.id, displayedChallenge, { sessionId });

Default paths

Each backend route forwards to the Biometry path with the same name under /api-gateway/v2. For example, POST <baseUrl>/liveness on your backend goes to POST https://api.biometrysolutions.com/api-gateway/v2/liveness.

Operation keyFlutter methodWeb methodDefault path on your backendForwards to
startSessioninitialize()startSession()POST /sessions (?warmup=true when asked)POST /api-gateway/v2/sessions
endSessionendSession()endSession()POST /sessions/{session_id}/endPOST /api-gateway/v2/sessions/{session_id}/end
livenesslivenessCheck()liveness()POST /livenessPOST /api-gateway/v2/liveness
faceVerifyfaceVerify()faceVerify()POST /face-verifyPOST /api-gateway/v2/face-verify
voiceVerifyvoiceVerify()voiceVerify()POST /voice-verifyPOST /api-gateway/v2/voice-verify
faceMatchfaceMatch()matchFaces()POST /face-matchPOST /api-gateway/v2/face-match
enrollFaceenrolFace()enrollFace()POST /enrollments/facePOST /api-gateway/v2/enrollments/face
enrollVoiceenrolVoice()enrollVoice()POST /enrollments/voicePOST /api-gateway/v2/enrollments/voice
checkDocumentdocAuth()checkDocAuth()POST /documents/checkPOST /api-gateway/v2/documents/check
deepfakeCheckdeepfakeCheck()(none)POST /deepfake/checksPOST /api-gateway/v2/deepfake/checks
approveConsentapproveConsent()(none)POST /consents/{consent_id}/approve/{user_id}POST /api-gateway/v2/consents/{consent_id}/approve/{user_id}
getConsentApprovalsgetConsentApprovals(), assertConsent()(none)GET /consents/my-approvals/{user_id}GET /api-gateway/v2/consents/my-approvals/{user_id}

The defaults are available in code as Biometry.defaultProxyPaths (Flutter) and the exported DEFAULT_PROXY_PATHS (Web). Without baseUrl (direct mode) nothing changes: the SDKs call https://api.biometrysolutions.com/api-gateway/v2 paths directly.

Use your own route names

If your backend already has a naming scheme, pass paths with the operations you want to move. The others keep their defaults.

final biometry = await Biometry.initialize(
baseUrl: 'https://app.example.com',
userId: 'user-123',
paths: {
ProxyOperation.liveness: '/kyc/liveness',
ProxyOperation.endSession: '/biometry-sessions/{session_id}/finish',
},
);

The keys are the ProxyOperation enum. An invalid path makes initialize() throw an ArgumentError before any request.

Each path must start with /, must not contain ? or #, and must contain exactly the placeholders of its default path, once each ({session_id}, {consent_id}, {user_id}). The SDK fills them in URI-encoded. paths only applies with baseUrl; without it, it is ignored with a warning. If you move a route, serve the new path on your backend too, and keep forwarding it to the default Biometry path in the table above. In the reference proxy, change only the first path of that route’s ROUTES entry and keep its upstream, for example route('POST', '/kyc/liveness', { upstream: '/liveness', ... }) for the /kyc/liveness path above. A path parameter is written :session_id in ROUTES and {session_id} in the SDK’s paths.

What the proxy must do

A proxy that adds your token to anything it receives is as dangerous as shipping the token: anyone could use it to act as any of your users. It must:

  1. Authenticate your own user with your normal session, cookie or JWT. Reject unauthenticated calls with 401. User ids must be 3 to 128 characters of A-Za-z0-9._:@- (the consent endpoint requires it).

  2. Accept only the paths the SDKs call, and refuse everything else. These are the default paths from the table above (or your paths overrides):

    MethodPathWhat to forward
    POST/sessionsNo body; ?warmup=true only. Record the returned session_id as owned by this user, with an expiry. Rate-limit per user
    POST/sessions/{session_id}/endsession_id must be owned by the user; JSON body with phone_number only. Forget the session afterwards
    POST/liveness, /voice-verifyrequest part: session_id (required), trigger and services (liveness); phrase set to this session’s challenge and vocabulary set to en_digits; file video (voice for voice-verify)
    POST/face-verifyrequest part: session_id; no phrase (face recognition only, no challenge); file video
    POST/face-matchrequest part: session_id, use_session_video; files reference_image, video
    POST/enrollments/face, /enrollments/voicerequest part: is_document (face) or phrase, vocabulary (voice); file face, or up to 4 voice files
    POST/documents/checkrequest part: session_id, provider, mrz_provider; file document
    POST/deepfake/checksrequest part: session_id; file video
    POST/consents/{consent_id}/approve/{user_id}Custom consent templates only. No body; path user_id must be the signed-in user
    GET/consents/my-approvals/{user_id}Custom consent templates only. Path user_id must be the signed-in user

    Remove the rows your app does not call. The last two are only needed if your app shows your own consent documents with the Flutter SDK’s approveConsent / getConsentApprovals; they do not record the consent Biometry needs (see Onboarding). Never forward a consent-recording call from the device (/api-consent/*, or /users/{user_id}/consents with or without the /api-gateway/v2 prefix). In proxy mode the Web SDK’s consent methods throw, and so do the Flutter SDK’s giveConsent, getConsentStatus and revokeConsent.

  3. Never pass the client’s body through: rebuild it. Parse the JSON request part, build a new object from the fields allowed for that path (exact key names, expected types), set user_id to the signed-in user, keep a session_id only if it was started for that user (otherwise 403), and build a new multipart body with only the expected file parts. Refuse a non-multipart body on a multipart path. Check IDs in the path the same way: answer 403 unless a {user_id} is the signed-in user and a {session_id} was started for that user, so nobody can end another user’s session or read their consent approvals.

  4. Drop the query string (keep only warmup=true on session start). The gateway also reads form values such as phrase and vocabulary from the query.

  5. Add Authorization: Bearer <your API token> and send the rebuilt request to https://api.biometrysolutions.com/api-gateway/v2 plus the default path for that call (the “Forwards to” column above), rebuilt from the ids you checked. This holds even if you renamed the route with paths. Do not forward the caller’s own Authorization header or cookies to Biometry.

  6. Return Biometry’s status code, body and safe headers (content-type, x-request-id, retry-after) so the SDK’s error handling keeps working.

Biometry needs the user’s authorization consent (before face and voice verification) and storage consent (before enrollment); see Consent. In proxy mode your backend records both, server-to-server with your API key, once the user has agreed in your app. This is a required onboarding step before the first enrollment.

  • Call PUT /api-gateway/v2/users/{user_id}/consents with {"authorization": true, "storage": true}. The user_id is the same value the proxy sets on every request, and must be 3 to 128 characters of A-Za-z0-9._:@-. Repeating the call is a no-op, false withdraws a consent, and GET on the same path returns both states. The example answers 400 for an id outside that range and 502 if Biometry refuses.
  • Pass the user’s user-agent and IP, so Biometry’s record of the consent shows the user’s client rather than your server. Behind a load balancer, take the IP from x-forwarded-for only for the hops you trust (the example’s trustProxy).
  • Take the user_id from your own session, never from the request.
  • Do not forward the SDKs’ consent calls (giveConsent in Flutter, giveAuthorizationConsent and giveStorageConsent in the Web SDK, and the v2 consents path). A device that can record consent could record it for anyone.

The /v2/consents endpoints are a different feature: custom consent templates (your own documents for users to approve). They are not checked by any biometric call and do not unlock enrollment or verification.

The example below does this in recordConsent(), exposed as POST /onboarding/consent with {"accepted": true} for your onboarding flow.

Decide who may enroll

The example lets any signed-in user call /enrollments/face and /enrollments/voice at any time. Add your own rule before production. A new enrollment changes the face or voice the user is checked against (voice enrollment adds to the existing voice print), so someone who steals a user’s app session could enroll their own face or voice for that user and then pass later checks as them.

Allow enrollment only where your product expects it, for example during onboarding, or after the user has signed in again or passed another check (a code sent to their phone). Answer 403 from the enrollment routes when your rule says no.

Liveness challenge

The digits the user reads aloud must come from your backend, not the device, or a replayed video can pass. Your proxy issues the challenge, keeps its own copy and writes it into phrase itself. See Liveness challenge for why and for the format.

  • Issue it from your own route (POST /challenge with a session_id in the example), bound to the signed-in user from your session and to a session that user started. Never key it by an id the client could swap.
  • Generate it with a CSPRNG (crypto.randomInt). Keep the format in one place (the example’s CHALLENGE_LENGTH and generateChallenge(), 8 digits from 1-9 by default) so you can change it.
  • Expire it after 5 minutes. A new challenge for the session replaces the old one. Rate-limit issuance per user.
  • Once per route, per session: liveness and voice-verify can each use the challenge once, so one recording can go to both. Set request.phrase to it and vocabulary to en_digits, ignoring whatever the device sent. A second use on the same route, another session’s challenge, or an expired one gets 409 and nothing is sent to Biometry. The phrase must never be empty: without one the gateway falls back to form values.
  • A use counts only when Biometry answers 2xx. Reserve the route before the call; commit it on 2xx, and release it on any other status or a network error so the user can retry with the same digits. While a route is reserved, a second request for it (a double submit) gets 409. A failed liveness verdict comes back as 200, so it still uses the challenge.
  • face-verify needs no challenge: it runs face recognition only and takes no phrase, so the proxy sends it without one.
  • The example keeps challenges in memory. In production use shared storage with atomic updates, for example a Redis hash per user and session with EXPIRE 300: reserve with HSETNX <key> <route> pending, commit with HSET <key> <route> used, release with HDEL <key> <route>.

In the app, fetch the challenge from your backend after starting the session and show those digits. In Flutter, pass it to Biometry.setChallenge(challenge) before showing the scanner (and Biometry.clearChallenge() when the user abandons the attempt), and make the recording window (scanTime) long enough for 8 digits, about 10 seconds. With the React or Angular face recorder, pass it as challengeDigits.

Minimal example (Node)

A runnable version with a README and a node --test suite is in the Web SDK repository under examples/proxy-server. The code below is that example’s server.mjs in full, the same code its tests run against. It has no dependencies and needs Node 18.8 or newer. Pass your own authenticate(), replace the in-memory stores with shared storage, and add rate limits to the other routes. Its ROUTES table serves the SDKs’ default paths. Each entry states the path your backend serves and, separately, the Biometry path it forwards to (upstream); the request goes to Biometry at /api-gateway/v2 plus upstream. The old prefixed paths (/api-gateway/v2/... on your backend) get 404. To rename a route, change only the first path of its entry, keep upstream, and pass the same new path to the SDK. For example, route('POST', '/kyc/liveness', { upstream: '/liveness', ... }) goes with paths: { liveness: '/kyc/liveness' } on the Web SDK or paths: {ProxyOperation.liveness: '/kyc/liveness'} on Flutter. Both paths of an entry must use the same :param names. Besides apiKey, authenticate, apiUrl and allowedOrigin, createProxy() takes:

  • allowedHeaders: extra request headers your page may send cross-origin (for example a CSRF header). A CORS preflight gets back only the requested headers that are on the allow list. They reach your proxy only, not Biometry.
  • trustProxy: how many proxies or load balancers in front of it append to x-forwarded-for (default 0, the socket address). Used for the client IP in the consent record, and for the scheme (x-forwarded-proto) in the origin check below when a load balancer terminates TLS. Never set it without such proxies.
  • sweepIntervalMs: how often expired sessions, challenges and rate-limit windows are dropped from memory (default one minute, 0 turns it off).
  • upstreamTimeoutMs: how long a Biometry call may take before the proxy answers 504 (default 120 seconds). Keep it above your slowest call.
  • sessions, challenges: the stores, to replace with shared storage. Their methods may return Promises, so a Redis-backed store works; make reserve atomic (for example HSETNX).

Browser requests whose Origin is neither allowedOrigin nor the proxy’s own origin (same scheme and host) get 403, and /challenge and /onboarding/consent need content-type: application/json, so another site cannot make a signed-in user’s browser call the proxy with their cookies. Requests without Origin (native apps, server-to-server) are allowed. On liveness, the proxy refuses a services value that skips active_speaker_detection or visual_speech_recognition (the services that check the spoken challenge) or face_liveness_detection (anti-spoofing). If authenticate() throws, for example on an expired token, the caller gets 401. A failed Biometry call answers 502, and a failure in your own stores answers 500.

Use it from your own code like this:

import { createProxy } from './server.mjs';
createProxy({
apiKey: process.env.BIOMETRY_API_KEY,
authenticate: (req) => yourSessionUserId(req), // your code: user_id or undefined
allowedOrigin: process.env.ALLOWED_ORIGIN, // only if your page is on another origin
trustProxy: 1, // one load balancer in front that appends x-forwarded-for
}).listen(3002);
examples/proxy-server/server.mjs
// Minimal backend proxy for Biometry client SDKs ("proxy mode").
//
// The browser or mobile app holds no Biometry token. It points the SDK at this
// server (`new BiometrySDK({ baseUrl })` or `Biometry.initialize(baseUrl: ...)`),
// and this server:
// 1. authenticates the caller as one of YOUR users,
// 2. only accepts the paths the SDKs call in proxy mode (the API v2 paths
// without the `/api-gateway/v2` prefix, for example `POST /liveness`),
// 3. never forwards the client's body: it rebuilds every request from an
// allow list of fields and files, SETS user_id to the signed-in user, and
// keeps a session_id only if this server started that session for them,
// 4. owns the liveness challenge: `POST /challenge` issues one for a session,
// and liveness / voice-verify send that stored copy as `phrase`, whatever
// the device sent,
// 5. adds `Authorization: Bearer <BIOMETRY_API_KEY>` and sends the rebuilt
// request to the Biometry API, at `/api-gateway/v2` plus the route's
// `upstream` path.
//
// It also records the user's authorization and storage consent server-side
// (`POST /onboarding/consent`, `recordConsent()`); the SDKs' own consent
// calls are not forwarded.
//
// Zero dependencies, Node 18.8 or newer. Pass your own `authenticate()` and
// replace the in-memory stores (sessions, challenges) with shared storage
// before using it. Store methods may return Promises; the proxy awaits them.
import http from 'node:http';
import { randomInt } from 'node:crypto';
import { isIP } from 'node:net';
import { pathToFileURL } from 'node:url';
const MAX_BODY_BYTES = 50 * 1024 * 1024;
/** How long a Biometry call may take before the proxy gives up with 504. */
const UPSTREAM_TIMEOUT_MS = 120 * 1000;
/** Path parameters (session ids, consent ids, user ids) must look like ids. */
const SAFE_ID = /^(?!\.{1,2}$)[A-Za-z0-9._:@-]{1,128}$/;
/** Biometry consent is keyed by user_id, which must be 3 to 128 of these characters. */
const CONSENT_USER_ID = /^[A-Za-z0-9._:@-]{3,128}$/;
/** How long this proxy remembers which user started a session. */
const SESSION_TTL_MS = 60 * 60 * 1000;
/** Session starts allowed per user per minute. */
const SESSION_START_LIMIT = 20;
// ---------------------------------------------------------------------------
// Liveness challenge. The format lives here only: change these lines if you
// need a different length or alphabet.
// ---------------------------------------------------------------------------
/** Number of digits in a challenge. */
export const CHALLENGE_LENGTH = 8;
/** Digits a challenge is drawn from. 0 is left out: it has several spoken forms. */
export const CHALLENGE_DIGITS = '123456789';
/** Speech-recognition vocabulary for digit challenges, pinned on challenge routes. */
export const CHALLENGE_VOCABULARY = 'en_digits';
const CHALLENGE_TTL_MS = 5 * 60 * 1000;
/** Challenges issued per user per minute. */
const CHALLENGE_RATE_LIMIT = 10;
const RATE_WINDOW_MS = 60 * 1000;
/**
* Returns CHALLENGE_LENGTH distinct digits from CHALLENGE_DIGITS, shuffled
* with a CSPRNG (crypto.randomInt), for example "48719352".
*/
export function generateChallenge() {
const digits = [...CHALLENGE_DIGITS];
for (let i = digits.length - 1; i > 0; i--) {
const j = randomInt(i + 1);
[digits[i], digits[j]] = [digits[j], digits[i]];
}
return digits.slice(0, CHALLENGE_LENGTH).join('');
}
/** Fixed-window counter: at most `limit` calls per key per window. */
class RateLimiter {
constructor(limit, windowMs, now) {
this.limit = limit;
this.windowMs = windowMs;
this.now = now;
this.windows = new Map(); // key -> { count, start }
}
allow(key) {
const now = this.now();
const w = this.windows.get(key);
if (!w || now - w.start >= this.windowMs) {
this.windows.set(key, { count: 1, start: now });
return true;
}
if (w.count >= this.limit) return false;
w.count += 1;
return true;
}
/** Drops windows that have ended, so the map does not grow with every user ever seen. */
sweep() {
const now = this.now();
for (const [key, w] of this.windows) {
if (now - w.start >= this.windowMs) this.windows.delete(key);
}
}
}
/**
* Which user started which Biometry session, with an expiry, and a per-user
* limit on session starts.
*
* DEMO ONLY: in production store ownership in shared storage with an expiry
* (for example Redis `SET session:<id> <user_id> EX 3600`).
*/
export class SessionStore {
constructor({ now = Date.now, ttlMs = SESSION_TTL_MS } = {}) {
this.now = now;
this.ttlMs = ttlMs;
this.owners = new Map(); // session_id -> { userId, expiresAt }
this.starts = new RateLimiter(SESSION_START_LIMIT, RATE_WINDOW_MS, now);
}
allowStart(userId) {
return this.starts.allow(userId);
}
add(sessionId, userId) {
this.owners.set(sessionId, { userId, expiresAt: this.now() + this.ttlMs });
}
/** The user who started `sessionId`, or undefined if unknown or expired. */
owner(sessionId) {
const entry = this.owners.get(sessionId);
if (!entry) return undefined;
if (entry.expiresAt <= this.now()) {
this.owners.delete(sessionId);
return undefined;
}
return entry.userId;
}
delete(sessionId) {
this.owners.delete(sessionId);
}
/** Drops expired sessions and ended rate-limit windows. createProxy() calls it every minute. */
sweep() {
const now = this.now();
for (const [id, entry] of this.owners) {
if (entry.expiresAt <= now) this.owners.delete(id);
}
this.starts.sweep();
}
}
/** Liveness services that check the spoken challenge. */
export const CHALLENGE_SERVICES = ['active_speaker_detection', 'visual_speech_recognition'];
/**
* Services `/liveness` always runs: the two that check the spoken challenge,
* plus face liveness detection (anti-spoofing). Without the last one a client
* could ask for a liveness check that never looks for a spoof.
*/
export const LIVENESS_REQUIRED_SERVICES = [...CHALLENGE_SERVICES, 'face_liveness_detection'];
/** Routes that consume the challenge. Each may use it once per session. */
const CHALLENGE_ROUTES = ['liveness', 'voice-verify'];
/**
* Liveness challenges, bound to the signed-in user AND one session. Valid for
* 5 minutes. Liveness and voice-verify can each use it once (so one recording
* can go to both); a new challenge for the session replaces the old one.
*
* A route's use is two steps: `reserve()` before the Biometry call, then
* `commit()` when Biometry answered 2xx, or `release()` when it did not (any
* other status, or a network error), so a failed upstream call does not burn
* the challenge. While a route is reserved, another request for it gets
* nothing, so a double submit can't use one challenge twice.
*
* DEMO ONLY: in production keep this in shared storage, for example a Redis
* hash per user+session with `EXPIRE 300`: reserve a route with an atomic
* `HSETNX <key> <route> pending`, commit with `HSET <key> <route> used`, and
* release with `HDEL <key> <route>` (only while it is still `pending`).
*/
export class ChallengeStore {
constructor({ now = Date.now, generate = generateChallenge } = {}) {
this.now = now;
this.generate = generate;
this.challenges = new Map(); // `${userId}\n${sessionId}` -> { value, expiresAt, used: Set, pending: Set }
this.issued = new RateLimiter(CHALLENGE_RATE_LIMIT, RATE_WINDOW_MS, now);
}
/** Issues a new challenge for this user and session. Returns undefined when rate-limited. */
issue(userId, sessionId) {
if (!this.issued.allow(userId)) return undefined;
const value = this.generate();
this.challenges.set(`${userId}\n${sessionId}`, {
value, expiresAt: this.now() + CHALLENGE_TTL_MS, used: new Set(), pending: new Set(),
});
return { value, expiresInSeconds: CHALLENGE_TTL_MS / 1000 };
}
/**
* Reserves the challenge for `route`. Returns `{ value, commit, release }`,
* or undefined if it is missing, expired, already used on that route, or
* reserved by a request still in flight. Call `commit()` when Biometry
* answered 2xx and `release()` otherwise; after the first of them, both do
* nothing.
*/
reserve(userId, sessionId, route) {
const key = `${userId}\n${sessionId}`;
const entry = this.challenges.get(key);
if (!entry) return undefined;
if (entry.expiresAt <= this.now()) {
this.challenges.delete(key);
return undefined;
}
if (entry.used.has(route) || entry.pending.has(route)) return undefined;
entry.pending.add(route);
let settled = false;
return {
value: entry.value,
commit: () => {
if (settled) return;
settled = true;
entry.pending.delete(route);
entry.used.add(route);
// Only delete it if a newer challenge has not replaced it meanwhile.
if (CHALLENGE_ROUTES.every((r) => entry.used.has(r)) && this.challenges.get(key) === entry) {
this.challenges.delete(key);
}
},
release: () => {
if (settled) return;
settled = true;
entry.pending.delete(route);
},
};
}
/** Reserves and commits at once. Returns the challenge, or undefined like reserve(). */
use(userId, sessionId, route) {
const reservation = this.reserve(userId, sessionId, route);
reservation?.commit();
return reservation?.value;
}
deleteSession(userId, sessionId) {
this.challenges.delete(`${userId}\n${sessionId}`);
}
/** Drops expired challenges and ended rate-limit windows. createProxy() calls it every minute. */
sweep() {
const now = this.now();
for (const [key, entry] of this.challenges) {
if (entry.expiresAt <= now) this.challenges.delete(key);
}
this.issued.sweep();
}
}
// ---------------------------------------------------------------------------
// Consent. Biometry needs the user's authorization and storage consent before
// enrollment. Record both from your backend with your API key, through
// PUT /api-gateway/v2/users/{user_id}/consents, keyed by the same user_id.
// ---------------------------------------------------------------------------
/**
* Records authorization and storage consent for `userId`. Call it from your
* onboarding flow after the user agreed in your app, before enrollment.
* Recording consent the user already gave is a no-op. `clientHeaders`
* (the user's `user-agent`, `x-forwarded-for`) go into Biometry's record of
* the consent instead of this server's.
* Returns the failing Response (its body already released; read `status`),
* or undefined when both were recorded. `signal` can abort the call.
*/
export async function recordConsent({ apiUrl, apiKey, userId, clientHeaders = {}, signal }) {
if (typeof userId !== 'string' || !CONSENT_USER_ID.test(userId)) {
throw new Error('user_id must be 3 to 128 characters of A-Za-z0-9._:@- for consent');
}
const headers = { ...clientHeaders, authorization: `Bearer ${apiKey}`, 'content-type': 'application/json' };
const res = await fetch(`${apiUrl}/api-gateway/v2/users/${encodeURIComponent(userId)}/consents`, {
method: 'PUT',
headers,
body: JSON.stringify({ authorization: true, storage: true }),
signal,
});
// Release the connection: only the status is used.
await res.body?.cancel();
return res.ok ? undefined : res;
}
// ---------------------------------------------------------------------------
// Routes
// ---------------------------------------------------------------------------
/**
* Fields of the JSON `request` part a route may carry, with their type. Any
* other key (including case variants such as `USER_ID`) is dropped. `user_id`
* is never taken from the client: it is set from the signed-in user.
*/
const FIELD_TYPES = {
session_id: 'string',
phrase: 'string',
vocabulary: 'string',
trigger: 'string',
use_session_video: 'boolean',
is_document: 'boolean',
provider: 'string',
mrz_provider: 'string',
services: 'services',
phone_number: 'string',
};
/** Biometry's API v2 prefix: every route is forwarded to this plus its `upstream` path. */
const UPSTREAM_PREFIX = '/api-gateway/v2';
const paramNames = (path) => [...path.matchAll(/:(\w+)/g)].map((m) => m[1]);
/**
* Builds a route. `template` is the path the client calls; `options.upstream`
* (required) is the Biometry API v2 path it is forwarded to, without the
* `/api-gateway/v2` prefix. Both must use the same `:param` names, which are
* mapped by name.
*/
export function route(method, template, options = {}) {
const { upstream, ...rest } = options;
if (typeof upstream !== 'string' || !upstream.startsWith('/')) {
throw new Error(`route ${method} ${template}: options.upstream (the Biometry path) is required`);
}
const params = paramNames(template);
const upstreamParams = paramNames(upstream);
const sorted = (names) => [...names].sort().join(',');
if (new Set(params).size !== params.length || sorted(params) !== sorted(upstreamParams)) {
throw new Error(
`route ${method} ${template}: path params (${params.join(', ')}) must match upstream ${upstream} (${upstreamParams.join(', ')})`,
);
}
const pattern = new RegExp(`^${template.replace(/:(\w+)/g, '([^/]+)')}$`);
return { method, template, upstream, upstreamTemplate: `${UPSTREAM_PREFIX}${upstream}`, params, pattern, ...rest };
}
/** The Biometry path a route forwards to, with its params filled in by name. */
export function upstreamPath(route, values) {
return route.upstreamTemplate.replace(/:(\w+)/g, (_, name) => encodeURIComponent(values[name]));
}
/**
* The only calls the client SDKs make. Everything else gets 404.
*
* The first path is the one the SDKs call in proxy mode (their default paths:
* the API v2 path without `/api-gateway/v2`). `upstream` is the Biometry API v2
* path the rebuilt request goes to, at `/api-gateway/v2` plus `upstream`. To
* rename a route, change the first path only and keep `upstream`, then pass
* the same new path to the SDK (`paths` in the web SDK). Both ROUTES paths
* must use the same `:param` names. Keep `:name` in ROUTES, but write the
* SDK's `paths` with `{name}` placeholders, e.g. ROUTES
* `/kyc/:session_id/finish` with `paths: { endSession: '/kyc/{session_id}/finish' }`.
*
* - `body`: 'none' (nothing is forwarded), 'json' or 'multipart' (rebuilt).
* - `setUser`: add `user_id` = signed-in user to the rebuilt request part.
* - `challenge`: this route's name for the challenge; `phrase` is set to the
* session's stored challenge and `vocabulary` to CHALLENGE_VOCABULARY.
* - `fields`: request-part fields copied from the client.
* - `files`: file parts copied from the client, with the most allowed of each.
* - `query`: query parameters kept, with the only value allowed for each.
*/
export const ROUTES = [
route('POST', '/sessions', { upstream: '/sessions', body: 'none', startsSession: true, query: { warmup: 'true' } }),
route('POST', '/sessions/:session_id/end', {
upstream: '/sessions/:session_id/end', body: 'json', fields: ['phone_number'], endsSession: true,
}),
route('POST', '/liveness', {
upstream: '/liveness',
body: 'multipart', setUser: true, challenge: 'liveness',
fields: ['session_id', 'trigger', 'services'], files: { video: 1 },
// The client may not skip the challenge checks or anti-spoofing.
requiredServices: LIVENESS_REQUIRED_SERVICES,
}),
route('POST', '/face-verify', {
upstream: '/face-verify',
body: 'multipart', setUser: true, fields: ['session_id'], files: { video: 1 },
}),
route('POST', '/voice-verify', {
upstream: '/voice-verify',
body: 'multipart', setUser: true, challenge: 'voice-verify', fields: ['session_id'], files: { voice: 1 },
}),
route('POST', '/face-match', {
upstream: '/face-match',
body: 'multipart', setUser: true, fields: ['session_id', 'use_session_video'],
files: { reference_image: 1, video: 1 },
}),
route('POST', '/enrollments/face', {
upstream: '/enrollments/face',
body: 'multipart', setUser: true, fields: ['is_document'], files: { face: 1 },
}),
route('POST', '/enrollments/voice', {
upstream: '/enrollments/voice',
// Up to 4 recordings of the phrase (the gateway's RequiredUtterances).
body: 'multipart', setUser: true, fields: ['phrase', 'vocabulary'], files: { voice: 4 },
}),
route('POST', '/documents/check', {
upstream: '/documents/check',
body: 'multipart', fields: ['session_id', 'provider', 'mrz_provider'], files: { document: 1 },
}),
route('POST', '/deepfake/checks', {
upstream: '/deepfake/checks',
body: 'multipart', setUser: true, fields: ['session_id'], files: { video: 1 },
}),
// Custom consent templates only (Flutter approveConsent / getConsentApprovals).
// They do not record the consent enrollment needs. Remove them if unused.
route('POST', '/consents/:consent_id/approve/:user_id', {
upstream: '/consents/:consent_id/approve/:user_id', body: 'none',
}),
route('GET', '/consents/my-approvals/:user_id', { upstream: '/consents/my-approvals/:user_id', body: 'none' }),
];
/**
* Request headers a cross-origin page may send (CORS preflight). Add your own
* auth headers, for example `x-csrf-token`, with createProxy({ allowedHeaders })
* or ALLOWED_HEADERS. This only lets the browser send them to this server;
* they are not forwarded to Biometry.
*/
export const CORS_ALLOWED_HEADERS = ['authorization', 'content-type', 'x-client-app', 'x-client-app-version'];
/** Client request headers passed on to Biometry. The caller's Authorization and cookies are not. */
const FORWARDED_REQUEST_HEADERS = ['x-client-app', 'x-client-app-version'];
/** Biometry response headers passed back to the client. */
const FORWARDED_RESPONSE_HEADERS = /^(content-type|x-request-id|retry-after|x-ratelimit-[a-z-]+|ratelimit(-[a-z]+)?)$/i;
class HttpError extends Error {
constructor(status, message, headers = {}) {
super(message);
this.status = status;
this.headers = headers;
}
}
/**
* DEMO ONLY, enabled with ALLOW_DEMO_AUTH=1: maps the bearer token
* `demo-app-token` to the user `user-123`. Use your real session or JWT check.
*/
function demoAuthenticate(req) {
const demoUsers = { 'demo-app-token': 'user-123' };
const match = /^Bearer (.+)$/.exec(req.headers.authorization ?? '');
return match ? demoUsers[match[1]] : undefined;
}
async function readBody(req) {
const chunks = [];
let size = 0;
for await (const chunk of req) {
size += chunk.length;
if (size > MAX_BODY_BYTES) throw new HttpError(413, 'body too large');
chunks.push(chunk);
}
return Buffer.concat(chunks);
}
function checkType(name, value) {
const type = FIELD_TYPES[name];
const ok = type === 'services'
? value !== null && typeof value === 'object' && !Array.isArray(value)
&& Object.keys(value).every((k) => k === 'include' || k === 'exclude')
&& Object.values(value).every((v) => Array.isArray(v) && v.every((s) => typeof s === 'string'))
: typeof value === type;
if (!ok) throw new HttpError(400, `invalid ${name}`);
}
function parseJson(text, what) {
try {
const value = JSON.parse(text);
if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error();
return value;
} catch {
throw new HttpError(400, `${what} must be a JSON object`);
}
}
/**
* Builds a NEW request object from the route's allowed fields. Exact,
* lower-case key names only, so `USER_ID` or `uſer_id` never get through.
*/
async function rebuildRequestPart(route, clientPart, ctx) {
const { userId, sessions, challenges } = ctx;
const part = {};
for (const name of route.fields ?? []) {
if (!Object.hasOwn(clientPart, name) || clientPart[name] === null) continue;
checkType(name, clientPart[name]);
part[name] = clientPart[name];
}
if (part.services && route.requiredServices) {
const { include, exclude = [] } = part.services;
for (const name of route.requiredServices) {
if (exclude.includes(name) || (include && !include.includes(name))) {
throw new HttpError(400, `services may not skip ${name}`);
}
}
}
if (part.session_id !== undefined && (await sessions.owner(part.session_id)) !== userId) {
throw new HttpError(403, 'session does not belong to the signed-in user');
}
if (route.challenge) {
if (part.session_id === undefined) throw new HttpError(400, 'session_id is required for a challenge');
// Never empty: without a phrase the gateway falls back to form values.
// Reserved, not used: the handler commits it only when Biometry answers 2xx.
const reservation = await challenges.reserve(userId, part.session_id, route.challenge);
if (!reservation) {
throw new HttpError(409, 'no valid liveness challenge for this session (missing, expired, used, or in use by another request): request one from POST /challenge');
}
ctx.reservation = reservation;
part.phrase = reservation.value;
part.vocabulary = CHALLENGE_VOCABULARY;
}
if (route.setUser) part.user_id = userId;
return part;
}
/** Returns the body to send upstream, rebuilt from the client's body. */
async function rebuildBody(route, req, ctx) {
if (route.body === 'none') return undefined;
const contentType = req.headers['content-type'] ?? '';
if (route.body === 'multipart' && !/^multipart\/form-data;/i.test(contentType)) {
throw new HttpError(415, 'expected multipart/form-data');
}
const raw = await readBody(req);
if (route.body === 'json') {
const clientBody = raw.length ? parseJson(raw.toString('utf8'), 'body') : {};
const body = await rebuildRequestPart(route, clientBody, ctx);
return Object.keys(body).length ? JSON.stringify(body) : undefined;
}
let form;
try {
form = await new Request('http://local/', {
method: 'POST', headers: { 'content-type': contentType }, body: raw,
}).formData();
} catch {
throw new HttpError(400, 'invalid multipart/form-data body');
}
const requestPart = form.get('request');
const clientPart = typeof requestPart === 'string' ? parseJson(requestPart, 'request part') : {};
const out = new FormData();
out.append('request', JSON.stringify(await rebuildRequestPart(route, clientPart, ctx)));
for (const [name, max] of Object.entries(route.files)) {
const files = form.getAll(name).filter((f) => typeof f !== 'string').slice(0, max);
for (const file of files) out.append(name, file, file.name);
}
return out;
}
/** Checks the path parameters and returns the path to forward, rebuilt from them. */
async function checkedPath(route, pathname, userId, sessions) {
const match = route.pattern.exec(pathname);
const values = {};
route.params.forEach((name, i) => {
let value;
try {
value = decodeURIComponent(match[i + 1]);
} catch {
throw new HttpError(400, `invalid ${name}`);
}
if (!SAFE_ID.test(value)) throw new HttpError(400, `invalid ${name}`);
values[name] = value;
});
if (values.user_id !== undefined && values.user_id !== userId) {
throw new HttpError(403, 'user_id does not belong to the signed-in user');
}
if (values.session_id !== undefined && (await sessions.owner(values.session_id)) !== userId) {
throw new HttpError(403, 'session does not belong to the signed-in user');
}
return { path: upstreamPath(route, values), values };
}
/** Keeps only the route's allowed query parameters with their allowed value. */
function rebuildQuery(route, searchParams) {
const out = new URLSearchParams();
for (const [name, allowed] of Object.entries(route.query ?? {})) {
if (searchParams.get(name) === allowed) out.set(name, allowed);
}
const query = out.toString();
return query ? `?${query}` : '';
}
/** Returns `value` without trailing `/` characters. No regex, so no backtracking. */
function trimTrailingSlashes(value) {
let end = value.length;
while (end > 0 && value[end - 1] === '/') end -= 1;
return value.slice(0, end);
}
/**
* The caller's IP address. With `trustProxy` 0 it is the socket address.
* Behind N proxies or load balancers that each append to `x-forwarded-for`,
* set `trustProxy` to N to use the address the outermost one saw. Never set
* it without such proxies: clients can write `x-forwarded-for` themselves.
*/
export function clientAddress(req, trustProxy = 0) {
const socketAddress = req.socket.remoteAddress;
const header = req.headers['x-forwarded-for'];
if (!trustProxy || typeof header !== 'string') return socketAddress;
const hops = header.split(',').map((h) => h.trim()).filter(Boolean);
// Fewer entries than trusted proxies: the request skipped one of them, so
// the leftmost entry may have been written by the client. Same for non-IPs.
if (hops.length < trustProxy) return socketAddress;
const hop = hops[hops.length - trustProxy];
return isIP(hop) ? hop : socketAddress;
}
/**
* The scheme the browser used to reach this server: `https:` or `http:`.
* Without trusted proxies it is the socket's own. Behind a load balancer that
* terminates TLS (`trustProxy` 1 or more), it is the `x-forwarded-proto` the
* proxies set, read the same way as `x-forwarded-for` in `clientAddress`.
* Clients can write that header themselves, so it is only read when
* `trustProxy` says a proxy is there.
*/
export function requestScheme(req, trustProxy = 0) {
const own = req.socket.encrypted ? 'https:' : 'http:';
const header = req.headers['x-forwarded-proto'];
if (!trustProxy || typeof header !== 'string') return own;
const hops = header.split(',').map((p) => p.trim().toLowerCase()).filter(Boolean);
// Proxies that append: the outermost trusted one wrote the entry trustProxy
// places from the end (entries left of it may be client-written). Proxies
// that overwrite leave fewer entries; then the nearest one's value stands.
const proto = hops.length >= trustProxy ? hops[hops.length - trustProxy] : hops[hops.length - 1];
return proto === 'https' || proto === 'http' ? `${proto}:` : own;
}
/**
* Browser requests carry `Origin`. Accept only your app's origin
* (`allowedOrigin`) or this server's own origin (same scheme and host), so
* another site cannot make a signed-in user's browser call the proxy with
* their cookies (a form or `text/plain` POST needs no CORS preflight). The
* scheme matters: `http://example.com` is a different site from
* `https://example.com`, and a plain-http page there must not pass. Requests
* without `Origin` (native apps, server-to-server) are allowed.
*/
function originAllowed(req, allowedOrigin, trustProxy) {
const origin = req.headers.origin;
if (origin === undefined) return true;
if (allowedOrigin && origin === allowedOrigin) return true;
try {
const url = new URL(origin);
return url.protocol === requestScheme(req, trustProxy) && url.host === req.headers.host;
} catch {
return false; // includes "null"
}
}
const UPSTREAM = Symbol('upstream');
/** Rethrows an error from the Biometry call, marked so it is answered 502. */
function fromUpstream(err) {
if (err !== null && typeof err === 'object') err[UPSTREAM] = true;
throw err;
}
function requireJson(req) {
const type = (req.headers['content-type'] ?? '').split(';')[0].trim().toLowerCase();
if (type !== 'application/json') throw new HttpError(415, 'content-type must be application/json');
}
function sendJson(res, status, body, headers = {}) {
res.writeHead(status, { 'content-type': 'application/json', ...headers });
res.end(JSON.stringify(body));
}
/**
* Creates the proxy server.
*
* @param {object} options
* @param {string} options.apiKey - Your Biometry project API key.
* @param {(req: http.IncomingMessage) => string | undefined | Promise<string | undefined>} options.authenticate -
* Returns the user_id the caller may act as, from YOUR session, or undefined. If it throws
* (as most JWT verifiers do on a bad or expired token), the caller gets 401 as well.
* @param {string} [options.apiUrl] - Where requests go. Defaults to the Biometry API.
* @param {string} [options.allowedOrigin] - Your web app's origin, for CORS.
* @param {string[]} [options.allowedHeaders] - Extra request headers a cross-origin page may
* send (for example your CSRF header), added to CORS_ALLOWED_HEADERS.
* @param {number} [options.trustProxy] - How many proxies or load balancers in front of this
* server append to `x-forwarded-for`. 0 (default) uses the socket address. See clientAddress().
* @param {SessionStore} [options.sessions] - Session ownership. Use shared storage in production.
* @param {ChallengeStore} [options.challenges] - Liveness challenges. Use shared storage in production.
* @param {number} [options.sweepIntervalMs] - How often expired entries are dropped from the
* stores (calls their `sweep()` if they have one). 0 turns it off.
* @param {number} [options.upstreamTimeoutMs] - How long a Biometry call may take before the
* proxy answers 504. Keep it above your slowest call.
*
* Store methods (`owner`, `allowStart`, `add`, `delete`, `issue`, `reserve`,
* `commit`, `release`, `deleteSession`) may be synchronous or return Promises.
*/
export function createProxy({
apiKey,
authenticate,
apiUrl = 'https://api.biometrysolutions.com',
allowedOrigin,
allowedHeaders = [],
trustProxy = 0,
sessions = new SessionStore(),
challenges = new ChallengeStore(),
sweepIntervalMs = 60 * 1000,
upstreamTimeoutMs = UPSTREAM_TIMEOUT_MS,
}) {
if (!apiKey) throw new Error('apiKey is required');
if (typeof authenticate !== 'function') throw new Error('authenticate is required');
if (!Number.isInteger(trustProxy) || trustProxy < 0) {
throw new Error('trustProxy must be a whole number of proxies, 0 or more');
}
const upstreamBase = trimTrailingSlashes(apiUrl);
const corsHeaders = new Set([...CORS_ALLOWED_HEADERS, ...allowedHeaders.map((h) => h.toLowerCase())]);
/** The preflight's requested headers that are on the allow list, or the whole list. */
function corsAllowHeaders(req) {
const requested = req.headers['access-control-request-headers'];
if (typeof requested !== 'string') return [...corsHeaders].join(', ');
return requested.split(',').map((h) => h.trim().toLowerCase()).filter((h) => corsHeaders.has(h)).join(', ');
}
async function issueChallenge(req, userId) {
requireJson(req);
const raw = await readBody(req);
const body = raw.length ? parseJson(raw.toString('utf8'), 'body') : {};
const sessionId = body.session_id;
if (typeof sessionId !== 'string') throw new HttpError(400, 'session_id is required');
if ((await sessions.owner(sessionId)) !== userId) throw new HttpError(403, 'session does not belong to the signed-in user');
const issued = await challenges.issue(userId, sessionId);
if (!issued) throw new HttpError(429, 'too many challenges, try again later', { 'retry-after': String(RATE_WINDOW_MS / 1000) });
// The device shows these digits; the proxy keeps its own copy.
return { challenge: issued.value, expires_in: issued.expiresInSeconds };
}
async function onboardingConsent(req, userId) {
requireJson(req);
const raw = await readBody(req);
const body = raw.length ? parseJson(raw.toString('utf8'), 'body') : {};
if (body.accepted !== true) throw new HttpError(400, 'accepted must be true');
if (!CONSENT_USER_ID.test(userId)) {
throw new HttpError(400, 'user_id must be 3 to 128 characters of A-Za-z0-9._:@- for consent');
}
const clientHeaders = {};
if (req.headers['user-agent']) clientHeaders['user-agent'] = req.headers['user-agent'];
const address = clientAddress(req, trustProxy);
if (address) clientHeaders['x-forwarded-for'] = address;
const failed = await recordConsent({
apiUrl: upstreamBase, apiKey, userId, clientHeaders, signal: AbortSignal.timeout(upstreamTimeoutMs),
});
if (failed) throw new HttpError(502, `consent was not recorded (Biometry answered ${failed.status})`);
return { consent: 'recorded' };
}
const OWN_ROUTES = { 'POST /challenge': issueChallenge, 'POST /onboarding/consent': onboardingConsent };
const server = http.createServer(async (req, res) => {
if (allowedOrigin) {
// Credentials allowed, so the page can use cookies (`credentials: 'include'`
// in the web SDK) or an Authorization header for your own session.
res.setHeader('access-control-allow-origin', allowedOrigin);
res.setHeader('access-control-allow-credentials', 'true');
res.setHeader('vary', 'Origin, Access-Control-Request-Headers');
const allowHeaders = corsAllowHeaders(req);
if (allowHeaders) res.setHeader('access-control-allow-headers', allowHeaders);
res.setHeader('access-control-allow-methods', 'GET, POST');
if (req.method === 'OPTIONS') return res.writeHead(204).end();
}
// Carries the liveness challenge reservation, if this route takes one.
const ctx = { userId: undefined, sessions, challenges, reservation: undefined };
let upstreamSignal; // set once the Biometry call starts
try {
const url = new URL(req.url, 'http://local');
const own = OWN_ROUTES[`${req.method} ${url.pathname}`];
const route = own ? undefined : ROUTES.find((r) => r.method === req.method && r.pattern.test(url.pathname));
if (!own && !route) return sendJson(res, 404, { error: 'not found' });
if (!originAllowed(req, allowedOrigin, trustProxy)) return sendJson(res, 403, { error: 'origin not allowed' });
let userId;
try {
userId = await authenticate(req);
} catch {
// A failed check is a refusal, not an outage: the app should ask the user to sign in.
userId = undefined;
}
if (typeof userId !== 'string' || !userId) return sendJson(res, 401, { error: 'sign in first' });
ctx.userId = userId;
if (own) return sendJson(res, 200, await own(req, userId));
const { path, values } = await checkedPath(route, url.pathname, userId, sessions);
if (route.startsSession && !(await sessions.allowStart(userId))) {
throw new HttpError(429, 'too many sessions, try again later', { 'retry-after': String(RATE_WINDOW_MS / 1000) });
}
const body = await rebuildBody(route, req, ctx);
const headers = { authorization: `Bearer ${apiKey}` };
if (typeof body === 'string') headers['content-type'] = 'application/json';
for (const name of FORWARDED_REQUEST_HEADERS) {
if (req.headers[name]) headers[name] = req.headers[name];
}
// Covers reading the response body too.
upstreamSignal = AbortSignal.timeout(upstreamTimeoutMs);
// fetch sets the multipart content-type (with a fresh boundary) for FormData.
const upstream = await fetch(`${upstreamBase}${path}${rebuildQuery(route, url.searchParams)}`, {
method: req.method,
headers,
body,
signal: upstreamSignal,
}).catch(fromUpstream);
// Biometry handled it, so the challenge is used. On any other status, or
// if fetch threw, the finally block below releases it for a retry.
if (upstream.ok) {
try {
await ctx.reservation?.commit();
} catch (err) {
// Not read below, so free the upstream connection now.
await upstream.body?.cancel().catch(() => {});
throw err;
}
}
const responseBody = Buffer.from(await upstream.arrayBuffer().catch(fromUpstream));
if (route.startsSession && upstream.ok) {
let sessionId;
try {
sessionId = JSON.parse(responseBody.toString('utf8'))?.data?.session_id;
} catch {
// Not JSON: nothing to record. The response is passed back as is.
}
if (typeof sessionId === 'string') await sessions.add(sessionId, userId);
}
if (route.endsSession && upstream.ok) {
await sessions.delete(values.session_id);
await challenges.deleteSession(userId, values.session_id);
}
const responseHeaders = {};
upstream.headers.forEach((value, name) => {
if (FORWARDED_RESPONSE_HEADERS.test(name)) responseHeaders[name] = value;
});
res.writeHead(upstream.status, responseHeaders);
res.end(responseBody);
} catch (err) {
if (err instanceof HttpError) return sendJson(res, err.status, { error: err.message }, err.headers);
// Some Node versions report a timeout while reading the body as AbortError.
if (err?.name === 'TimeoutError' || (err?.name === 'AbortError' && upstreamSignal?.aborted)) {
return sendJson(res, 504, { error: 'upstream timeout' });
}
console.error(err);
// 502 only when the Biometry call failed; a failing store or bug is ours.
if (err?.[UPSTREAM]) sendJson(res, 502, { error: 'upstream error' });
else sendJson(res, 500, { error: 'internal error' });
} finally {
try {
await ctx.reservation?.release(); // does nothing once committed
} catch (err) {
console.error(err);
}
}
});
// The in-memory stores only drop an expired entry when it is read again;
// sweep them so users who never come back do not hold memory forever.
if (sweepIntervalMs > 0) {
// A shared store's sweep may be async; a rejection must not crash the proxy.
const sweep = (store) => {
try {
Promise.resolve(store.sweep?.()).catch((err) => console.error(err));
} catch (err) {
console.error(err);
}
};
const timer = setInterval(() => {
sweep(sessions);
sweep(challenges);
}, sweepIntervalMs);
timer.unref();
server.on('close', () => clearInterval(timer));
}
return server;
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
const apiKey = process.env.BIOMETRY_API_KEY;
if (!apiKey) {
console.error('BIOMETRY_API_KEY environment variable is required');
process.exit(1);
}
if (process.env.ALLOW_DEMO_AUTH !== '1') {
console.error('No authenticate() configured. Import createProxy() and pass your own, '
+ 'or set ALLOW_DEMO_AUTH=1 to try the demo token (never in production).');
process.exit(1);
}
console.warn('ALLOW_DEMO_AUTH=1: "Bearer demo-app-token" signs in as user-123. Demo only.');
const port = Number(process.env.PORT ?? 3002);
createProxy({
apiKey,
authenticate: demoAuthenticate,
apiUrl: process.env.BIOMETRY_API_URL,
allowedOrigin: process.env.ALLOWED_ORIGIN,
allowedHeaders: (process.env.ALLOWED_HEADERS ?? '').split(',').map((h) => h.trim()).filter(Boolean),
trustProxy: Number(process.env.TRUST_PROXY ?? 0),
upstreamTimeoutMs: Number(process.env.UPSTREAM_TIMEOUT_MS ?? UPSTREAM_TIMEOUT_MS),
}).listen(port, () => {
console.log(`Biometry proxy on http://localhost:${port}`);
});
}

Limits of proxy mode

Proxy mode keeps the token off the device, but your proxy is now an endpoint that spends your Biometry quota on behalf of signed-in users. Apply the same rate limits and abuse checks you use for the rest of your API.