FanIDFace Server SDK

Server-side TypeScript SDK for partner web applications integrating FanIDFace biometric authentication.

This package exposes the FanIDFaceServerHelper API for:

• issuing short-lived Biometric Session Tokens (BST)
• validating signed Biometric Result Tokens (BRT)
• enforcing expiry, replay protection, and operation allowlists

You need a partner API key from FanIDFace and the FanIDFace server's ES256 public key.

Installation

pnpm add @vizualkei/fanidface-server-sdk

Token Model

FanIDFace server integrations use two tokens:

• BST — Biometric Session Token
  • issued by your server
  • short-lived
  • used to authorize a single biometric operation
  • can optionally bind the operation to a known biometric user ID
• BRT — Biometric Result Token
  • signed by the FanIDFace server
  • returned after the biometric operation completes
  • sent back to your server for validation

In a typical flow:

1. Your server issues a BST with createBiometricSessionToken()
2. The client passes that BST into the FanIDFace biometric flow
3. FanIDFace returns a signed BRT
4. Your server validates that BRT with verifyBiometricResultToken()

Quick Start

import { fanidfaceServerHelper } from '@vizualkei/fanidface-server-sdk';

const fanidfaceHelper = fanidfaceServerHelper.init({
  apiKey: process.env.FANIDFACE_API_KEY!,
  publicKeyPem: process.env.FANIDFACE_JWT_PUBLIC_KEY!,
  issuer: 'fanidface',
});

const { bst, expiresAt } =
  await fanidfaceHelper.createBiometricSessionToken(biometricUserId);

const { claims, op } = await fanidfaceHelper.verifyBiometricResultToken(brt, {
  requireBst: true,
  expectedBuid: session.user.biometricUserId,
  requireSuccess: true,
});

FanIDFaceServerHelper

FanIDFaceServerHelper is the main API of this package.

Initialize it once with your FanIDFace partner credentials, then use it to:

• issue BSTs for biometric operations
• validate BRTs returned by FanIDFace
• enforce operation allowlists and success requirements
• protect against replay by requiring BST validation when needed

Initialization

import { fanidfaceServerHelper } from '@vizualkei/fanidface-server-sdk';

const fanidfaceHelper = fanidfaceServerHelper.init({
  apiKey: process.env.FANIDFACE_API_KEY!,
  publicKeyPem: process.env.FANIDFACE_JWT_PUBLIC_KEY!,
  issuer: 'fanidface',
  sessionConfig: {
    ttlMs: 5 * 60 * 1000,
    maxFutureSkewMs: 30 * 1000,
  },
});

FanIDFaceServerHelperConfig

| Field | Type | Required | Description | |-------|------|----------|-------------| | apiKey | string | Yes | FanIDFace partner API key used to sign BSTs | | publicKeyPem | string | Yes | FanIDFace server ES256 public key | | issuer | string \| string[] | No | Expected JWT issuer. Default: fanidface | | audience | string | No | Expected JWT audience | | sessionConfig.ttlMs | number | No | BST lifetime in milliseconds | | sessionConfig.maxFutureSkewMs | number | No | Allowed future clock skew | | defaultAllowedOps | Iterable<string> | No | Default allowed biometric operations | | bstFailureStatus | number | No | Status to attach to BST-related validation failures |

Helper Methods

createBiometricSessionToken(biometricUserId?, metadata?)

Issues a BST for a single biometric operation.

Use this before starting a biometric flow in the client.

const { bst, expiresAt, token, entry } =
  await fanidfaceHelper.createBiometricSessionToken(biometricUserId);

Parameters:

• biometricUserId?: string
  • optional known biometric user ID
  • omit it for operations like first-time enrollment
• metadata?: Record<string, unknown>
  • optional server-side metadata stored with the session entry

Returns:

• bst
  • the serialized Biometric Session Token
• expiresAt
  • unix timestamp in milliseconds
• token
  • token object created for the session
• entry
  • the stored session entry

verifyBiometricResultToken(token, options?)

Validates a BRT returned by FanIDFace and applies policy checks.

const { claims, op, bst } =
  await fanidfaceHelper.verifyBiometricResultToken(brt, {
    requireBst: true,
    expectedBuid: session.user.biometricUserId,
    requireSuccess: true,
    allowedOps: ['enroll', 'authenticate', 'restore', 'unenroll'],
  });

What it does:

• validates the BRT signature
• validates issuer and audience if configured
• optionally validates the embedded BST
• optionally checks the expected biometric user binding
• enforces allowed operation names
• optionally requires a successful biometric result

Returns:

• claims
  • decoded BRT payload
• op
  • biometric operation name
• bst
  • embedded BST string, if present

get()

Returns the initialized FanIDFaceServerHelper instance.

const helper = fanidfaceServerHelper.get();

This is useful when you initialize the helper once during server startup and use it elsewhere later.

Singleton Helper

In addition to the class, the package exports a singleton-style helper object:

• fanidfaceServerHelper.init(config)
• fanidfaceServerHelper.get()
• fanidfaceServerHelper.createBiometricSessionToken(...)
• fanidfaceServerHelper.verifyBiometricResultToken(...)

This is the simplest way to use the package in a web server.

Typical Server Flow

1. Issue BST

Your server endpoint issues a BST before a biometric operation:

const { bst, expiresAt } =
  await fanidfaceServerHelper.createBiometricSessionToken(biometricUserId);

2. Run FanIDFace biometric operation

The client uses the BST while interacting with FanIDFace.

3. Validate BRT

When the client sends the returned BRT back to your server:

const { claims, op } =
  await fanidfaceServerHelper.verifyBiometricResultToken(brt, {
    requireBst: true,
    requireSuccess: true,
  });

Defaults

• Default JWT issuer: fanidface
• Default BST TTL: 5 minutes
• Default max future skew: 30 seconds

Notes

• Default JWT issuer: fanidface

License

Apache-2.0