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 consentPoint 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()}'},);const sdk = new BiometrySDK({ baseUrl: 'https://app.example.com/biometry', // Called before every request, so a refreshed token is picked up. headers: () => ({ Authorization: `Bearer ${getAppSessionToken()}` }),});If the proxy is on another origin and authenticates with cookies, also pass
credentials: 'include'. The proxy must then answer CORS with your page’s
exact origin and Access-Control-Allow-Credentials: true.
Do not pass apiKey together with baseUrl: the SDK would then send your
Biometry API key to the baseUrl host on every request.
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 key | Flutter method | Web method | Default path on your backend | Forwards to |
|---|---|---|---|---|
startSession | initialize() | startSession() | POST /sessions (?warmup=true when asked) | POST /api-gateway/v2/sessions |
endSession | endSession() | endSession() | POST /sessions/{session_id}/end | POST /api-gateway/v2/sessions/{session_id}/end |
liveness | livenessCheck() | liveness() | POST /liveness | POST /api-gateway/v2/liveness |
faceVerify | faceVerify() | faceVerify() | POST /face-verify | POST /api-gateway/v2/face-verify |
voiceVerify | voiceVerify() | voiceVerify() | POST /voice-verify | POST /api-gateway/v2/voice-verify |
faceMatch | faceMatch() | matchFaces() | POST /face-match | POST /api-gateway/v2/face-match |
enrollFace | enrolFace() | enrollFace() | POST /enrollments/face | POST /api-gateway/v2/enrollments/face |
enrollVoice | enrolVoice() | enrollVoice() | POST /enrollments/voice | POST /api-gateway/v2/enrollments/voice |
checkDocument | docAuth() | checkDocAuth() | POST /documents/check | POST /api-gateway/v2/documents/check |
deepfakeCheck | deepfakeCheck() | (none) | POST /deepfake/checks | POST /api-gateway/v2/deepfake/checks |
approveConsent | approveConsent() | (none) | POST /consents/{consent_id}/approve/{user_id} | POST /api-gateway/v2/consents/{consent_id}/approve/{user_id} |
getConsentApprovals | getConsentApprovals(), 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.
import { BiometrySDK } from 'biometry-sdk';
const sdk = new BiometrySDK({ baseUrl: 'https://app.example.com', paths: { liveness: '/kyc/liveness', endSession: '/biometry-sessions/{session_id}/finish', },});The keys are typed as ProxyOperation. An unknown key or an invalid path
makes the constructor throw.
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:
-
Authenticate your own user with your normal session, cookie or JWT. Reject unauthenticated calls with
401. User ids must be 3 to 128 characters ofA-Za-z0-9._:@-(the consent endpoint requires it). -
Accept only the paths the SDKs call, and refuse everything else. These are the default paths from the table above (or your
pathsoverrides):Method Path What to forward POST/sessionsNo body; ?warmup=trueonly. Record the returnedsession_idas owned by this user, with an expiry. Rate-limit per userPOST/sessions/{session_id}/endsession_idmust be owned by the user; JSON body withphone_numberonly. Forget the session afterwardsPOST/liveness,/voice-verifyrequestpart:session_id(required),triggerandservices(liveness);phraseset to this session’s challenge andvocabularyset toen_digits; filevideo(voicefor voice-verify)POST/face-verifyrequestpart:session_id; nophrase(face recognition only, no challenge); filevideoPOST/face-matchrequestpart:session_id,use_session_video; filesreference_image,videoPOST/enrollments/face,/enrollments/voicerequestpart:is_document(face) orphrase,vocabulary(voice); fileface, or up to 4voicefilesPOST/documents/checkrequestpart:session_id,provider,mrz_provider; filedocumentPOST/deepfake/checksrequestpart:session_id; filevideoPOST/consents/{consent_id}/approve/{user_id}Custom consent templates only. No body; path user_idmust be the signed-in userGET/consents/my-approvals/{user_id}Custom consent templates only. Path user_idmust be the signed-in userRemove 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}/consentswith or without the/api-gateway/v2prefix). In proxy mode the Web SDK’s consent methods throw, and so do the Flutter SDK’sgiveConsent,getConsentStatusandrevokeConsent. -
Never pass the client’s body through: rebuild it. Parse the JSON
requestpart, build a new object from the fields allowed for that path (exact key names, expected types), setuser_idto the signed-in user, keep asession_idonly if it was started for that user (otherwise403), 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: answer403unless 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. -
Drop the query string (keep only
warmup=trueon session start). The gateway also reads form values such asphraseandvocabularyfrom the query. -
Add
Authorization: Bearer <your API token>and send the rebuilt request tohttps://api.biometrysolutions.com/api-gateway/v2plus 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 withpaths. Do not forward the caller’s ownAuthorizationheader or cookies to Biometry. -
Return Biometry’s status code, body and safe headers (
content-type,x-request-id,retry-after) so the SDK’s error handling keeps working.
Onboarding: record consent before enrollment
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}/consentswith{"authorization": true, "storage": true}. Theuser_idis the same value the proxy sets on every request, and must be 3 to 128 characters ofA-Za-z0-9._:@-. Repeating the call is a no-op,falsewithdraws a consent, andGETon the same path returns both states. The example answers400for an id outside that range and502if Biometry refuses. - Pass the user’s
user-agentand IP, so Biometry’s record of the consent shows the user’s client rather than your server. Behind a load balancer, take the IP fromx-forwarded-foronly for the hops you trust (the example’strustProxy). - Take the
user_idfrom your own session, never from the request. - Do not forward the SDKs’ consent calls (
giveConsentin Flutter,giveAuthorizationConsentandgiveStorageConsentin 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 /challengewith asession_idin 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’sCHALLENGE_LENGTHandgenerateChallenge(), 8 digits from1-9by 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:
livenessandvoice-verifycan each use the challenge once, so one recording can go to both. Setrequest.phraseto it andvocabularytoen_digits, ignoring whatever the device sent. A second use on the same route, another session’s challenge, or an expired one gets409and 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 on2xx, 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) gets409. A failed liveness verdict comes back as200, so it still uses the challenge. face-verifyneeds 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 withHSETNX <key> <route> pending, commit withHSET <key> <route> used, release withHDEL <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 tox-forwarded-for(default0, 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,0turns it off).upstreamTimeoutMs: how long a Biometry call may take before the proxy answers504(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; makereserveatomic (for exampleHSETNX).
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);// 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.