@helix-id/voice-auth 0.1.0 → 0.1.2

package/README.md

@@ -43,10 +43,19 @@ window.location.href = url;
 
 ```typescript
 import { verifyCallback, InvalidSignatureError, NonceMismatchError, ExpiredTimestampError } from "@helix-id/voice-auth";
+import type { CallbackQuery } from "@helix-id/voice-auth";
 
 app.get("/auth/callback", (req, res) => {
   try {
-    const result = verifyCallback(req.query, {
+    // verifyCallback expects every field to be a plain string.
+    // Frameworks like Express can parse duplicate query params as arrays
+    // (e.g. ?status=verified&status=failed → { status: ["verified","failed"] }).
+    // Normalize req.query before passing it in:
+    const query: CallbackQuery = Object.fromEntries(
+      Object.entries(req.query).map(([k, v]) => [k, Array.isArray(v) ? v[0] : String(v)]),
+    ) as CallbackQuery;
+
+    const result = verifyCallback(query, {
       nonce: req.session.helixNonce,
       secret: process.env.HELIX_SECRET,
     });
@@ -101,6 +110,8 @@ Returns `{ status, statusCode, logId, state }`.
 
 Throws: `InvalidSignatureError`, `NonceMismatchError`, `ExpiredTimestampError`, `MalformedCallbackError`.
 
+> **Important:** `query` must be a flat `Record<string, string>`. Some frameworks (Express, Koa) can parse duplicate query parameters as arrays. Normalize the query object before passing it to `verifyCallback` — see the callback example above.
+
 ## Status Codes
 
 | status_code                | status     | Description                                |
@@ -116,7 +127,8 @@ Throws: `InvalidSignatureError`, `NonceMismatchError`, `ExpiredTimestampError`,
 Use the test credentials for local development:
 
 ```typescript
-import { createAuthUrl, HELIX_TEST_SPACE_ID, HELIX_TEST_SECRET } from "@helix-id/voice-auth";
+import { createAuthUrl } from "@helix-id/voice-auth";
+import { HELIX_TEST_SPACE_ID, HELIX_TEST_SECRET } from "@helix-id/voice-auth/testing";
 
 const { url, nonce } = createAuthUrl({
   spaceId: HELIX_TEST_SPACE_ID,

package/dist/constants-Bq_R93HE.d.mts

@@ -0,0 +1,13 @@
+//#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;
+//#endregion
+export { TIMESTAMP_WINDOW_SECONDS as a, HELIX_TEST_SPACE_ID as i, HELIX_TEST_CALLBACK_URL as n, HELIX_TEST_SECRET as r, HELIX_DEFAULT_BASE_URL as t };

package/dist/constants-CVQVsNWb.mjs

@@ -0,0 +1,14 @@
+//#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;
+
+//#endregion
+export { TIMESTAMP_WINDOW_SECONDS as a, HELIX_TEST_SPACE_ID as i, HELIX_TEST_CALLBACK_URL as n, HELIX_TEST_SECRET as r, HELIX_DEFAULT_BASE_URL as t };

package/dist/index.d.mts

@@ -1,3 +1,5 @@
+import { a as TIMESTAMP_WINDOW_SECONDS, t as HELIX_DEFAULT_BASE_URL } from "./constants-Bq_R93HE.mjs";
+
 //#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";
@@ -79,7 +81,7 @@ declare class InvalidSignatureError extends VoiceAuthError {
 }
 /** Callback nonce does not match the session nonce — possible CSRF. */
 declare class NonceMismatchError extends VoiceAuthError {
-  constructor(expected: string, actual: string);
+  constructor();
 }
 /** Callback timestamp is outside the 5-minute validity window — possible replay. */
 declare class ExpiredTimestampError extends VoiceAuthError {
@@ -90,18 +92,4 @@ 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 };
+export { type CallbackQuery, type CallbackStatus, type CreateAuthUrlOptions, type CreateAuthUrlResult, ExpiredTimestampError, HELIX_DEFAULT_BASE_URL, InvalidSignatureError, MalformedCallbackError, NonceMismatchError, type StatusCode, TIMESTAMP_WINDOW_SECONDS, type VerifyCallbackOptions, type VerifyCallbackResult, VoiceAuthError, createAuthUrl, verifyCallback };

package/dist/index.mjs

@@ -1,26 +1,6 @@
+import { a as TIMESTAMP_WINDOW_SECONDS, t as HELIX_DEFAULT_BASE_URL } from "./constants-CVQVsNWb.mjs";
 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.
@@ -60,8 +40,8 @@ var InvalidSignatureError = class extends VoiceAuthError {
 };
 /** 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");
+	constructor() {
+		super("Nonce mismatch", "NONCE_MISMATCH");
 		this.name = "NonceMismatchError";
 	}
 };
@@ -99,15 +79,17 @@ const REQUIRED_FIELDS = [
 * 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);
+	for (const field of REQUIRED_FIELDS) if (query[field] == null || query[field] === "") throw new MalformedCallbackError(field);
 	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();
+	const expectedBuf = Buffer.from(expected, "hex");
+	const sigBuf = Buffer.from(sig, "hex");
+	if (sigBuf.length !== expectedBuf.length || !timingSafeEqual(sigBuf, expectedBuf)) throw new InvalidSignatureError();
+	if (query.nonce !== options.nonce) throw new NonceMismatchError();
+	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);
 	return {
 		status: query.status,
 		statusCode: query.status_code,
@@ -117,4 +99,4 @@ function verifyCallback(query, options) {
 }
 
 //#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 };
+export { ExpiredTimestampError, HELIX_DEFAULT_BASE_URL, InvalidSignatureError, MalformedCallbackError, NonceMismatchError, TIMESTAMP_WINDOW_SECONDS, VoiceAuthError, createAuthUrl, verifyCallback };

package/dist/testing.d.mts

@@ -0,0 +1,2 @@
+import { i as HELIX_TEST_SPACE_ID, n as HELIX_TEST_CALLBACK_URL, r as HELIX_TEST_SECRET } from "./constants-Bq_R93HE.mjs";
+export { HELIX_TEST_CALLBACK_URL, HELIX_TEST_SECRET, HELIX_TEST_SPACE_ID };

package/dist/testing.mjs

@@ -0,0 +1,3 @@
+import { i as HELIX_TEST_SPACE_ID, n as HELIX_TEST_CALLBACK_URL, r as HELIX_TEST_SECRET } from "./constants-CVQVsNWb.mjs";
+
+export { HELIX_TEST_CALLBACK_URL, HELIX_TEST_SECRET, HELIX_TEST_SPACE_ID };

package/package.json

@@ -1,25 +1,22 @@
 {
   "name": "@helix-id/voice-auth",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Backend SDK for Helix Voice Authentication redirect flow",
   "type": "module",
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
       "types": "./dist/index.d.mts"
+    },
+    "./testing": {
+      "import": "./dist/testing.mjs",
+      "types": "./dist/testing.d.mts"
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
-  "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",
@@ -29,11 +26,19 @@
     "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"
+    "eslint": "9.39.1",
+    "@helix/typescript-config": "0.0.1",
+    "@helix/eslint-config": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint"
   }
-}
+}