npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@helix-id/node

v0.7.0

Published

Server-side SDK for Helix Voice Authentication and Reference List management (Web Crypto, holds the secret)

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/node

Quick 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.