@helix-id/voice-auth 0.1.0

package/README.md

@@ -0,0 +1,135 @@
+# @helix-id/voice-auth
+
+Backend SDK for [Helix Voice Authentication](https://helix.id) — 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, and callback verification.
+
+## Installation
+
+```bash
+npm install @helix-id/voice-auth
+```
+
+## Quick Start
+
+### 1. Generate the Redirect URL (backend)
+
+```typescript
+import { createAuthUrl } from "@helix-id/voice-auth";
+
+app.get("/auth/start", (req, res) => {
+  const state = Buffer.from(JSON.stringify({ action: "approve_tx", txId: "abc123", returnTo: "/dashboard" })).toString(
+    "base64",
+  );
+
+  const { url, nonce } = createAuthUrl({
+    spaceId: process.env.HELIX_SPACE_ID,
+    state,
+  });
+
+  req.session.helixNonce = nonce;
+  res.json({ url });
+});
+```
+
+### 2. Redirect the User (frontend)
+
+```typescript
+const { url } = await fetch("/auth/start").then((r) => r.json());
+window.location.href = url;
+```
+
+### 3. Verify the Callback (backend)
+
+```typescript
+import { verifyCallback, InvalidSignatureError, NonceMismatchError, ExpiredTimestampError } from "@helix-id/voice-auth";
+
+app.get("/auth/callback", (req, res) => {
+  try {
+    const result = verifyCallback(req.query, {
+      nonce: req.session.helixNonce,
+      secret: process.env.HELIX_SECRET,
+    });
+
+    req.session.helixNonce = null;
+
+    const state = JSON.parse(Buffer.from(result.state, "base64").toString());
+
+    if (result.status === "verified") {
+      res.redirect(state.returnTo);
+    } else {
+      res.redirect(`${state.returnTo}?error=${result.statusCode}`);
+    }
+  } catch (error) {
+    if (error instanceof InvalidSignatureError) {
+      res.status(401).json({ error: "Invalid signature" });
+    } else if (error instanceof NonceMismatchError) {
+      res.status(401).json({ error: "Nonce mismatch" });
+    } else if (error instanceof ExpiredTimestampError) {
+      res.status(401).json({ error: "Callback expired" });
+    } else {
+      throw error;
+    }
+  }
+});
+```
+
+## API
+
+### `createAuthUrl(options)`
+
+Generates a redirect URL and cryptographic nonce.
+
+| Option    | Type     | Required | Description                                              |
+| --------- | -------- | -------- | -------------------------------------------------------- |
+| `spaceId` | `string` | Yes      | Your Space ID (UUID)                                     |
+| `state`   | `string` | Yes      | Opaque state echoed back in callback                     |
+| `baseUrl` | `string` | No       | Override Helix URL (default: `https://capsule.helix.id`) |
+
+Returns `{ url: string, nonce: string }`. Store `nonce` in the user's session.
+
+### `verifyCallback(query, options)`
+
+Verifies the HMAC-signed callback and parses the result.
+
+| Option   | Type     | Required | Description                                   |
+| -------- | -------- | -------- | --------------------------------------------- |
+| `nonce`  | `string` | Yes      | Nonce from `createAuthUrl`, stored in session |
+| `secret` | `string` | Yes      | Shared secret from Helix admin panel          |
+
+Returns `{ status, statusCode, logId, state }`.
+
+Throws: `InvalidSignatureError`, `NonceMismatchError`, `ExpiredTimestampError`, `MalformedCallbackError`.
+
+## Status Codes
+
+| status_code                | status     | Description                                |
+| -------------------------- | ---------- | ------------------------------------------ |
+| `voice_verified`           | `verified` | Voice matched successfully                 |
+| `voice_enrolled`           | `verified` | First-time user — voice profile created    |
+| `challenge_mismatch`       | `failed`   | Spoken words didn't match displayed digits |
+| `synthetic_voice_detected` | `failed`   | Audio flagged as AI-generated or spoofed   |
+| `voice_mismatch`           | `failed`   | Voice didn't match enrolled profile        |
+
+## Testing
+
+Use the test credentials for local development:
+
+```typescript
+import { createAuthUrl, HELIX_TEST_SPACE_ID, HELIX_TEST_SECRET } from "@helix-id/voice-auth";
+
+const { url, nonce } = createAuthUrl({
+  spaceId: HELIX_TEST_SPACE_ID,
+  state: "test",
+});
+```
+
+| Credential   | Value                                         |
+| ------------ | --------------------------------------------- |
+| Space ID     | `a1b2c3d4-e5f6-7890-abcd-ef1234567890`        |
+| Secret       | `tk_test_hx_4a7f2c9d8e1b3f6a5c2d9e8f7b4a1c3d` |
+| Callback URL | `http://localhost:8080/helix/callback`        |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,107 @@
+//#region src/types.d.ts
+/** Human-readable status codes returned in the callback `status_code` param. */
+type StatusCode = "voice_verified" | "voice_enrolled" | "challenge_mismatch" | "synthetic_voice_detected" | "voice_mismatch";
+/** Generic status from callback `status` param. */
+type CallbackStatus = "verified" | "failed";
+/** Raw query parameters Helix appends to the callback URL. */
+interface CallbackQuery {
+  status: string;
+  status_code: string;
+  log_id: string;
+  space_id: string;
+  nonce: string;
+  state: string;
+  ts: string;
+  sig: string;
+}
+/** Options for `createAuthUrl`. */
+interface CreateAuthUrlOptions {
+  /** Your Space ID (UUID from Helix admin panel). */
+  spaceId: string;
+  /** Opaque state string echoed back in the callback. Base64-encode JSON before passing. */
+  state: string;
+  /** Override the Helix base URL (defaults to `https://capsule.helix.id`). */
+  baseUrl?: string;
+}
+/** Result from `createAuthUrl`. */
+interface CreateAuthUrlResult {
+  /** Full URL to redirect the user to. */
+  url: string;
+  /** Cryptographically random 32-char hex nonce. Store this in the user's session. */
+  nonce: string;
+}
+/** Options for `verifyCallback`. */
+interface VerifyCallbackOptions {
+  /** The nonce stored in the user's session (from `createAuthUrl`). */
+  nonce: string;
+  /** Your shared secret from the Helix admin panel. */
+  secret: string;
+}
+/** Parsed and verified callback result. */
+interface VerifyCallbackResult {
+  /** `"verified"` or `"failed"`. */
+  status: CallbackStatus;
+  /** Detailed status code (e.g. `"voice_verified"`, `"voice_mismatch"`). */
+  statusCode: StatusCode;
+  /** UUID of the verification log entry. */
+  logId: string;
+  /** The state string you passed to `createAuthUrl`, echoed back unchanged. */
+  state: string;
+}
+//#endregion
+//#region src/auth-url.d.ts
+/**
+ * Generate a redirect URL and cryptographic nonce for initiating a Helix voice auth session.
+ *
+ * The nonce must be stored in the user's server-side session and passed to `verifyCallback`
+ * when the callback arrives.
+ */
+declare function createAuthUrl(options: CreateAuthUrlOptions): CreateAuthUrlResult;
+//#endregion
+//#region src/verify.d.ts
+/**
+ * Verify an HMAC-SHA256 signed callback from Helix and parse the result.
+ *
+ * Throws `NonceMismatchError`, `ExpiredTimestampError`, `InvalidSignatureError`,
+ * or `MalformedCallbackError` if verification fails.
+ */
+declare function verifyCallback(query: CallbackQuery, options: VerifyCallbackOptions): VerifyCallbackResult;
+//#endregion
+//#region src/errors.d.ts
+/** Base error class for all @helix-id/voice-auth errors. */
+declare class VoiceAuthError extends Error {
+  readonly code: string;
+  constructor(message: string, code: string);
+}
+/** HMAC signature verification failed — payload may have been tampered with. */
+declare class InvalidSignatureError extends VoiceAuthError {
+  constructor();
+}
+/** Callback nonce does not match the session nonce — possible CSRF. */
+declare class NonceMismatchError extends VoiceAuthError {
+  constructor(expected: string, actual: string);
+}
+/** Callback timestamp is outside the 5-minute validity window — possible replay. */
+declare class ExpiredTimestampError extends VoiceAuthError {
+  constructor(ts: string);
+}
+/** A required query parameter is missing or malformed. */
+declare class MalformedCallbackError extends VoiceAuthError {
+  constructor(field: string);
+}
+//#endregion
+//#region src/constants.d.ts
+/** Default Helix base URL for production. */
+declare const HELIX_DEFAULT_BASE_URL = "https://capsule.helix.id";
+/** Test Space ID for local development and integration testing. */
+declare const HELIX_TEST_SPACE_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+/** Test shared secret for local development and integration testing. */
+declare const HELIX_TEST_SECRET = "tk_test_hx_4a7f2c9d8e1b3f6a5c2d9e8f7b4a1c3d";
+/** Test callback URL for local development. */
+declare const HELIX_TEST_CALLBACK_URL = "http://localhost:8080/helix/callback";
+/** Callback timestamp validity window in seconds (5 minutes). */
+declare const TIMESTAMP_WINDOW_SECONDS = 300;
+/** Mapping of status codes to their HTTP-like numeric codes (for reference). */
+declare const STATUS_CODE_NUMBERS: Record<string, string>;
+//#endregion
+export { type CallbackQuery, type CallbackStatus, type CreateAuthUrlOptions, type CreateAuthUrlResult, ExpiredTimestampError, HELIX_DEFAULT_BASE_URL, HELIX_TEST_CALLBACK_URL, HELIX_TEST_SECRET, HELIX_TEST_SPACE_ID, InvalidSignatureError, MalformedCallbackError, NonceMismatchError, STATUS_CODE_NUMBERS, type StatusCode, TIMESTAMP_WINDOW_SECONDS, type VerifyCallbackOptions, type VerifyCallbackResult, VoiceAuthError, createAuthUrl, verifyCallback };

package/dist/index.mjs

@@ -0,0 +1,120 @@
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+
+//#region src/constants.ts
+/** Default Helix base URL for production. */
+const HELIX_DEFAULT_BASE_URL = "https://capsule.helix.id";
+/** Test Space ID for local development and integration testing. */
+const HELIX_TEST_SPACE_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
+/** Test shared secret for local development and integration testing. */
+const HELIX_TEST_SECRET = "tk_test_hx_4a7f2c9d8e1b3f6a5c2d9e8f7b4a1c3d";
+/** Test callback URL for local development. */
+const HELIX_TEST_CALLBACK_URL = "http://localhost:8080/helix/callback";
+/** Callback timestamp validity window in seconds (5 minutes). */
+const TIMESTAMP_WINDOW_SECONDS = 300;
+/** Mapping of status codes to their HTTP-like numeric codes (for reference). */
+const STATUS_CODE_NUMBERS = {
+	voice_verified: "200",
+	voice_enrolled: "201",
+	voice_mismatch: "401",
+	synthetic_voice_detected: "403",
+	challenge_mismatch: "422"
+};
+
+//#endregion
+//#region src/auth-url.ts
+/**
+* Generate a redirect URL and cryptographic nonce for initiating a Helix voice auth session.
+*
+* The nonce must be stored in the user's server-side session and passed to `verifyCallback`
+* when the callback arrives.
+*/
+function createAuthUrl(options) {
+	const { spaceId, state, baseUrl = HELIX_DEFAULT_BASE_URL } = options;
+	const nonce = randomBytes(16).toString("hex");
+	const url = new URL("/voice-auth", baseUrl);
+	url.searchParams.set("space_id", spaceId);
+	url.searchParams.set("nonce", nonce);
+	url.searchParams.set("state", state);
+	return {
+		url: url.toString(),
+		nonce
+	};
+}
+
+//#endregion
+//#region src/errors.ts
+/** Base error class for all @helix-id/voice-auth errors. */
+var VoiceAuthError = class extends Error {
+	constructor(message, code) {
+		super(message);
+		this.name = "VoiceAuthError";
+		this.code = code;
+	}
+};
+/** HMAC signature verification failed — payload may have been tampered with. */
+var InvalidSignatureError = class extends VoiceAuthError {
+	constructor() {
+		super("Invalid callback signature", "INVALID_SIGNATURE");
+		this.name = "InvalidSignatureError";
+	}
+};
+/** Callback nonce does not match the session nonce — possible CSRF. */
+var NonceMismatchError = class extends VoiceAuthError {
+	constructor(expected, actual) {
+		super(`Nonce mismatch: expected "${expected}", got "${actual}"`, "NONCE_MISMATCH");
+		this.name = "NonceMismatchError";
+	}
+};
+/** Callback timestamp is outside the 5-minute validity window — possible replay. */
+var ExpiredTimestampError = class extends VoiceAuthError {
+	constructor(ts) {
+		super(`Callback timestamp expired: ${ts}`, "EXPIRED_TIMESTAMP");
+		this.name = "ExpiredTimestampError";
+	}
+};
+/** A required query parameter is missing or malformed. */
+var MalformedCallbackError = class extends VoiceAuthError {
+	constructor(field) {
+		super(`Missing or malformed callback parameter: ${field}`, "MALFORMED_CALLBACK");
+		this.name = "MalformedCallbackError";
+	}
+};
+
+//#endregion
+//#region src/verify.ts
+const REQUIRED_FIELDS = [
+	"status",
+	"status_code",
+	"log_id",
+	"space_id",
+	"nonce",
+	"state",
+	"ts",
+	"sig"
+];
+/**
+* Verify an HMAC-SHA256 signed callback from Helix and parse the result.
+*
+* Throws `NonceMismatchError`, `ExpiredTimestampError`, `InvalidSignatureError`,
+* or `MalformedCallbackError` if verification fails.
+*/
+function verifyCallback(query, options) {
+	for (const field of REQUIRED_FIELDS) if (!query[field]) throw new MalformedCallbackError(field);
+	if (query.nonce !== options.nonce) throw new NonceMismatchError(options.nonce, query.nonce);
+	const now = Math.floor(Date.now() / 1e3);
+	const ts = Number(query.ts);
+	if (Math.abs(now - ts) > TIMESTAMP_WINDOW_SECONDS) throw new ExpiredTimestampError(query.ts);
+	const { sig, ...rest } = query;
+	const canonical = Object.keys(rest).sort().map((k) => `${k}=${rest[k]}`).join("&");
+	const expected = createHmac("sha256", options.secret).update(canonical).digest("hex");
+	if (sig.length !== expected.length || !timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) throw new InvalidSignatureError();
+	return {
+		status: query.status,
+		statusCode: query.status_code,
+		logId: query.log_id,
+		state: query.state
+	};
+}
+
+//#endregion
+export { ExpiredTimestampError, HELIX_DEFAULT_BASE_URL, HELIX_TEST_CALLBACK_URL, HELIX_TEST_SECRET, HELIX_TEST_SPACE_ID, InvalidSignatureError, MalformedCallbackError, NonceMismatchError, STATUS_CODE_NUMBERS, TIMESTAMP_WINDOW_SECONDS, VoiceAuthError, createAuthUrl, verifyCallback };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@helix-id/voice-auth",
+  "version": "0.1.0",
+  "description": "Backend SDK for Helix Voice Authentication redirect flow",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "types": "./dist/index.d.mts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@helix/typescript-config": "workspace:*",
+    "@helix/eslint-config": "workspace:*",
+    "vitest": "4.0.18",
+    "tsdown": "0.20.1",
+    "typescript": "5.9.3",
+    "eslint": "9.39.1"
+  }
+}