Voice-Auth
Integration Guide.

npm install @helix-id/voice-auth

# .env
HELIX_SPACE_ID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
HELIX_SECRET=tk_live_hx_…

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 });
});

const { url } = await fetch("/auth/start").then((r) => r.json());
window.location.href = url;

import {
  verifyCallback,
  InvalidSignatureError,
  NonceMismatchError,
  ExpiredTimestampError,
} from "@helix-id/voice-auth";

app.get("/auth/callback", (req, res) => {
  // verifyCallback expects every field to be a plain string.
  // Express may parse duplicate query params as arrays —
  // normalize req.query before passing it in.
  const query = Object.fromEntries(
    Object.entries(req.query).map(
      ([k, v]) => [k, Array.isArray(v) ? v[0] : String(v)]
    )
  );

  try {
    const result = verifyCallback(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)
      return res.status(401).json({ error: "Invalid signature" });
    if (error instanceof NonceMismatchError)
      return res.status(401).json({ error: "Nonce mismatch" });
    if (error instanceof ExpiredTimestampError)
      return res.status(401).json({ error: "Callback expired" });
    throw error;
  }
});