# Voice-Auth Integration Guide

Server-side setup, callback verification, and SDK reference for @helix-id/node — everything your engineers need to go live.

The `@helix-id/node` package provides a lightweight backend SDK for integrating Helix Biometric MFA into any Node.js application.

The SDK is built on the universal Web Crypto API — it uses no `node:` builtins, so the same code runs on Node, Bun, Deno and serverless runtimes such as Vercel or Cloudflare Workers. It runs server-side only\: it holds your shared secret and must never be bundled into browser JavaScript.

## How the flow works

Authentication follows a redirect-based flow\: your server generates a signed URL, the user is sent to the Helix portal to speak a short numeric challenge, and Helix redirects back with an HMAC-signed callback result. Both legs are signed with your shared secret — the outbound URL carries a `sig` query param, and the callback carries its own signature. The nonce stored in the user session prevents replay attacks.

The redirect flow in the [Quickstart](https://docs.helix.id/quickstart.md) needs nothing but this server SDK. [Prompt mode](https://docs.helix.id/prompt-mode.md) has a prompt that builds it in one shot with a coding agent, and the optional `@helix-id/browser` widget wires the same flow to a button — see the [Browser SDK](https://docs.helix.id/browser-sdk.md).

## What's included

A single integration of `@helix-id/node` gives you one redirect, one callback, and one verdict. Your servers never receive or store audio — the user speaks on the Helix portal, and the outcome reaches your callback as a single HMAC-signed `statusCode`.

### Biometric MFA

Voice-ID enrollment and passwordless re-authentication. The user speaks a short numeric challenge displayed on the Helix portal; Helix matches the audio against the enrolled voice profile and returns a signed verdict to your callback.

| Characteristic            | Typical      |
| ------------------------- | ------------ |
| Enrollment time           | ~6s          |
| Re-auth time              | ~2s          |
| Replay protection         | nonce + HMAC |
| Auth URL integrity        | HMAC-SHA256  |
| Callback freshness window | 300s         |

### What you receive on the callback

The verdict is exposed as a high-level `status` plus a specific `statusCode` on the result returned by `verifyCallback()`\:

| Verdict    | What it means                                                                                                                                                                                                                                                       |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verified` | The speaker matched their enrolled voice profile, or a profile was enrolled during this session. Codes\: `voice_verified`, `voice_enrolled`.                                                                                                                         |
| `failed`   | The attempt did not produce a match, or the space's age gate rejected it. Codes\: `challenge_mismatch`, `voice_mismatch`, `synthetic_voice_detected`, `age_requirement_not_met`, `age_inconclusive`. All seven codes are listed under [Status codes](https://docs.helix.id/status-codes.md). |

Service-level commitments (latency, availability) are governed by your Helix order form. Targets above describe typical observed performance, not contractual SLAs.

## Next steps

* [Install the package](https://docs.helix.id/installation.md) and set your Space ID and shared secret.
* Follow the [Quickstart](https://docs.helix.id/quickstart.md) to wire the redirect and the callback.
* Keep the [API reference](https://docs.helix.id/api.md) and [Status codes](https://docs.helix.id/status-codes.md) open while you build.