@helix-id/node
v0.7.0
Published
Server-side SDK for Helix Voice Authentication and Reference List management (Web Crypto, holds the secret)
Keywords
Readme
@helix-id/node
Server-side SDK for Helix Voice Authentication — a redirect-based voice identity verification flow.
Your app redirects users to Helix, where they speak a short numeric challenge. Helix verifies their voice and redirects back with an HMAC-signed result. This package handles nonce generation, URL building, signing, callback verification, and server-side Reference List management.
Runs server-side only (backend / Next.js server / edge). It holds your shared secret and must never be bundled into browser JS. For the browser popup/embed/redirect widget, use @helix-id/browser.
Built on the universal Web Crypto API (crypto.subtle) — no node: builtins — so it runs on Node, edge runtimes, Bun, and Deno.
Installation
npm install @helix-id/nodeQuick Start
1. Generate the redirect URL (server)
import { createAuthUrl } from "@helix-id/node";
app.get("/helix/start", async (req, res) => {
const state = Buffer.from(JSON.stringify({ action: "approve_tx", txId: "abc123", returnTo: "/dashboard" })).toString(
"base64",
);
const { url, nonce } = await createAuthUrl({
spaceId: process.env.HELIX_SPACE_ID,
state,
origin: req.headers.origin, // the browser origin the SDK runs on
secret: process.env.HELIX_SECRET, // shared secret from the Helix admin panel
});
req.session.helixNonce = nonce; // store server-side; needed to verify the callback
res.json({ url });
});Choose the initial language
Pass locale when your backend creates the signed URL:
const { url, nonce } = await createAuthUrl({
spaceId,
state,
origin,
secret,
locale: "fr-CA",
});The initial language controls both the voice widget's text and its digit-STT model. Supported
languages are English (en), Spanish (es), and French (fr); regional tags such as fr-CA
resolve to their language. A supplied unsupported, malformed, or empty locale uses English.
When locale is omitted, Helix uses the saved manual language choice, then browser preferences,
then English. Users can change language in the widget; only manual choices are saved.
2. Verify the callback (server)
import { verifyCallback, InvalidSignatureError, NonceMismatchError } from "@helix-id/node";
app.get("/helix/callback", async (req, res) => {
try {
const result = await verifyCallback(req.query, {
nonce: req.session.helixNonce,
secret: process.env.HELIX_SECRET, // shared secret from the Helix admin panel
});
// { status, statusCode, logId, state, enrollmentId?, referenceList? }
if (result.enrollmentId) {
await db.users.update(userId, { helixEnrollmentId: result.enrollmentId });
}
res.json(result);
} catch (err) {
if (err instanceof InvalidSignatureError || err instanceof NonceMismatchError) {
return res.status(401).json({ error: err.code });
}
res.status(400).json({ error: "invalid_callback" });
}
});3. Verify a returning user (server)
If your Space has Voice MFA or Reference List enabled, verifyCallback returns an
enrollmentId — store it against the user. On their next voice-auth session, pass it back to
createAuthUrl so Helix verifies them against their existing enrollment instead of enrolling a
duplicate:
const { url, nonce } = await createAuthUrl({
spaceId: process.env.HELIX_SPACE_ID,
state,
origin: req.headers.origin,
secret: process.env.HELIX_SECRET,
enrollmentId: user.helixEnrollmentId, // omit on first-time users — Helix enrolls them
});4. Handle a Reference List match (server)
If your Space has Reference List enabled, every verified session — new enrollment or returning
user — comes back with result.referenceList ({ result, matchedEnrollmentId?, matchedCategory? }).
A match never blocks the user — the session completes — so the decision is yours, by the category you added the person with:
denied and vip are recommended client-defined conventions with no built-in behavior. Custom
labels are supported. Add people from your server before screening them.
if (result.referenceList?.result === "CONFIRMED_MATCH") {
const { matchedEnrollmentId, matchedCategory } = result.referenceList;
if (matchedCategory === "denied") await reviewQueue.add({ userId, matchedEnrollmentId });
}API
| Export | Description |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| createAuthUrl(options) | Build the /voice-auth redirect URL, sign it with HMAC-SHA256, and return a session nonce. Async. |
| verifyAuthUrlSignature(url, secret) | Verify the HMAC-SHA256 signature on an auth URL produced by createAuthUrl. Async. |
| verifyCallback(query, options) | Verify the HMAC-signed callback and parse the result. Async. |
| addToReferenceList(options) | Sign and send a Reference List addition. Async, server-side only. |
| removeFromReferenceList(options) | Sign and send a Reference List removal. Async, server-side only. |
| VoiceAuthError and subclasses | InvalidSignatureError, NonceMismatchError, ExpiredTimestampError, MalformedCallbackError, InvalidAuthUrlSignatureError, ReferenceListError. |
| STATUS_CODE_NUMBERS / STATUS_CODE_STRINGS | Status-code mappings (voice_verified ⇄ 200, etc.). |
| HELIX_DEFAULT_BASE_URL, HELIX_DEFAULT_API_URL, TIMESTAMP_WINDOW_SECONDS | Portal URL, API URL, and timestamp window. |
Test credentials for local development are exported from the @helix-id/node/testing subpath:
import { HELIX_TEST_SPACE_ID, HELIX_TEST_SECRET, HELIX_TEST_CALLBACK_URL } from "@helix-id/node/testing";Status codes
| status_code | Numeric | status |
| -------------------------- | ------- | -------- |
| voice_verified | 200 | verified |
| voice_enrolled | 201 | verified |
| voice_mismatch | 401 | failed |
| synthetic_voice_detected | 403 | failed |
| challenge_mismatch | 422 | failed |
| age_requirement_not_met | 451 | failed |
| age_inconclusive | 452 | failed |
Reference List results
| referenceList.result | Description |
| ---------------------- | ------------------------------------------------------------------------------ |
| CLEAR | No match on your Reference List. |
| CONFIRMED_MATCH | Matched a listed person — matchedEnrollmentId and matchedCategory say who. |
| UNSCOREABLE | Screening could not run. Treat as unscreened, not clear. |
| UNRESOLVED | Reserved, not returned yet. Handle like UNSCOREABLE, as any unknown value. |
Reference List management
Store enrollmentId from a verified callback against your user. Your server can then add that
person when your policy calls for it, or remove them after a review. Lists are separate for each
Space and environment. Adding requires Reference List enabled and an active server-side voice
template belonging to your client. An ID with only a device-held template returns
no_template_available. Removal works even when the feature is disabled.
import { addToReferenceList, ReferenceListError } from "@helix-id/node";
const options = {
spaceId: process.env.HELIX_SPACE_ID!,
secret: process.env.HELIX_SECRET!,
enrollmentId: user.helixEnrollmentId, // saved from verifyCallback
};
try {
const entry = await addToReferenceList({ ...options, category: "denied", reason: "manual_review" });
} catch (error) {
if (error instanceof ReferenceListError) console.error(error.status, error.code);
else throw error;
}After your appeal review succeeds, remove the person in a separate server action:
import { removeFromReferenceList, ReferenceListError } from "@helix-id/node";
try {
const removal = await removeFromReferenceList({
spaceId: process.env.HELIX_SPACE_ID!,
secret: process.env.HELIX_SECRET!,
enrollmentId: user.helixEnrollmentId,
reason: "APPEAL_UPHELD",
});
} catch (error) {
if (error instanceof ReferenceListError) console.error(error.status, error.code);
else throw error;
}Both helpers are async and perform a network call. Their baseUrl defaults to
https://api.helix.id (HELIX_DEFAULT_API_URL), the API origin. createAuthUrl uses the portal
https://capsule.helix.id. Set baseUrl to your local or alternate API when needed.
addToReferenceList(options): Promise<AddToReferenceListResult>
| addToReferenceList option | Type | Required | Description |
| ------------------------- | --------------------------- | -------- | ---------------------------------------------------------- |
| spaceId | string | yes | Space UUID. |
| secret | string | yes | This Space/environment's shared secret. Never transmitted. |
| enrollmentId | string | yes | Stored Enrollment ID: 64 lowercase hex characters. |
| env | "sandbox" \| "production" | no | Default production; use its secret. |
| baseUrl | string | no | API origin; default https://api.helix.id. |
| actor | string | no | Audit actor, 1–128 characters; default api. |
| category | string | no | Custom label matching [A-Za-z0-9_-]{1,64}. |
| reason | string | no | Add audit reason, 1–64 characters of free text. |
| customerRef | string | no | Case/reference, 1–256 characters; sent as customer_ref. |
| addToReferenceList result | Type | Required | Description |
| ------------------------- | ---------------- | -------- | ------------------------------------------------- |
| enrollmentId | string | yes | Listed person's ID. |
| category | string \| null | yes | Stored label; null if absent. |
| addedAt | string | yes | Original addition time, ISO 8601. |
| listSize | number | yes | Entries in the selected list. |
| alreadyListed | true | no | Present only for a duplicate addition (HTTP 200). |
Duplicate additions retain existing metadata. They still require the feature enabled and an active template.
removeFromReferenceList(options): Promise<RemoveFromReferenceListResult>
| removeFromReferenceList option | Type | Required | Description |
| ------------------------------ | --------------------------- | -------- | --------------------------------------------- |
| spaceId | string | yes | Space UUID. |
| secret | string | yes | This Space/environment's shared secret. |
| enrollmentId | string | yes | Listed ID: 64 lowercase hex characters. |
| env | "sandbox" \| "production" | no | Default production. |
| baseUrl | string | no | API origin; default https://api.helix.id. |
| actor | string | no | Audit actor, 1–128 characters; default api. |
| reason | ReferenceListRemoveReason | no | Optional fixed removal reason below. |
| removeFromReferenceList result | Type | Required | Description |
| ------------------------------ | ------ | -------- | ----------------------- |
| enrollmentId | string | yes | Removed person's ID. |
| removedAt | string | yes | Removal time, ISO 8601. |
| Removal reason | Description |
| ---------------- | ---------------------------------- |
| APPEAL_UPHELD | Appeal accepted after your review. |
| EXPIRED | Your listing period ended. |
| CUSTOMER_ERROR | You added the person by mistake. |
| OTHER | Other removal reason. |
Removal reasons are audit metadata; they do not schedule expiration.
Categories
Labels are optional and client-defined. These recommendations are not an enum and have no
built-in behavior; custom values are supported. On a match, matchedCategory echoes the stored
label. Your application decides whether to deny, review, or recognize someone; Helix never blocks
or grants privileges based on it.
| Recommended category | Description |
| -------------------- | ----------------------------------------------------------------- |
| denied | Your denial/review policy; enforcement stays in your application. |
| vip | Recognition or special handling in your application. |
Raw endpoint: POST /api/v1/reference-list
URL: https://api.helix.id/api/v1/reference-list. Send query parameters, no JSON body.
The helpers supply action, ts, and sig; unknown query parameters are rejected.
| Reference List parameter | Type | Required | Actions | Description |
| ------------------------ | --------------------------- | -------- | ------- | ------------------------------------------------------------ |
| space_id | string | yes | both | Space UUID. |
| env | "sandbox" \| "production" | yes | both | Required on the wire; SDK default production. |
| ts | string | yes | both | Decimal Unix seconds; within 300 seconds of server time. |
| sig | string | yes | both | HMAC-SHA256 signature, 64 lowercase hex characters. |
| action | "add" \| "remove" | yes | both | Selected operation. |
| enrollment_id | string | yes | both | Exactly 64 lowercase hex characters. |
| actor | string | no | both | 1–128 characters; default api. |
| category | string | no | add | [A-Za-z0-9_-]{1,64}. |
| reason | string | no | both | Add: free text, 1–64 characters. Remove: fixed reason above. |
| customer_ref | string | no | add | Customer reference, 1–256 characters. |
For raw clients, sign every transmitted parameter except sig with this Space/environment's
secret. Sort raw keys, percent-encode keys/values with encodeURIComponent, join as key=value
with &, then HMAC-SHA256 and append its lowercase hex digest as sig. This is the createAuthUrl
canonical encoding, not URLSearchParams.toString() (spaces differ). Generate a fresh timestamp
and signature for each request; use HTTPS and keep clocks synchronized.
| Reference List action | HTTP | Outcome | Description |
| --------------------- | ---- | ------------------------- | -------------------------------------------------------------------------- |
| add | 201 | added | Created. |
| add | 200 | already_listed | Returned existing metadata with alreadyListed: true. |
| remove | 200 | removed | Deleted. |
| both | 400 | VALIDATION_ERROR | Invalid query; nested { error: { code, message } }. |
| both | 401 | unauthorized | Authentication or timestamp failure; unavailable Space/environment/secret. |
| remove | 404 | not_listed | Absent from this list. |
| add | 409 | reference_list_disabled | Feature disabled. |
| add | 409 | no_template_available | No active server-side template for this client's ID. |
| add | 409 | reference_list_full | Configured capacity reached. |
These are actual HTTP statuses, separate from callback status codes. Success outcome labels are
descriptions, not JSON fields; responses contain the result fields above. Business/auth errors use
{ error: "code" } (no_template_available also has a message).
Any non-2xx response throws ReferenceListError extends VoiceAuthError with upstream .status
and backend .code. Missing/unusable codes or non-JSON error bodies use
REFERENCE_LIST_REQUEST_FAILED. Native transport and successful-response JSON parsing errors
propagate unchanged. The helpers do not retry, and absent removals throw 404 not_listed.
