npm altcha-lib 2.9.0
v2.9.0

47 minutes ago

This release adds support for ALTCHA Sentinel v2 to remote verification (verifyServer) and makes local and remote verification of server-signed payloads return the same result shape. Sentinel v1 still works without changes.

Highlights

Sentinel v2 remote verification

verifyServer and every framework plugin's verifyServer option now work with Sentinel v2's POST /v2/verify/signature. Authenticate with a restricted or full API key through the new apiKey option. It is sent as Authorization: Basic base64(id:secret).

import { verifyServer } from 'altcha-lib';

const result = await verifyServer({
  payload,
  url: 'https://sentinel.example.com/v2/verify/signature',
  apiKey: { id: API_KEY_ID, secret: API_KEY_SECRET },
});

Framework plugins (Express, Fastify, NestJS, Next.js, Nuxt/H3, SvelteKit, Hono):

const altcha = create({
  verifyServer: {
    url: 'https://sentinel.example.com/v2/verify/signature',
    apiKey: { id: API_KEY_ID, secret: API_KEY_SECRET },
  },
});

Sentinel v1 (/v1/verify/signature, with the optional secret) works as before.

verifyServerSignature accepts the raw payload string

verifyServerSignature now takes the base64-encoded JSON string the widget submits, as well as the decoded object (payload: string | ServerSignaturePayload). You no longer need to decode it yourself.

const result = await verifyServerSignature({ payload: req.body.altcha, hmacSecret });

Behavior changes

Check these before upgrading if your code relies on the old behavior:

  • Malformed payloads no longer throw in verifyServerSignature. A payload that can't be decoded, or one without algorithm, now returns verified: false with invalidSolution: true. An unsupported algorithm still throws.
  • 4xx responses from Sentinel are no longer retried. Previously only 400 returned at once, and other 4xx statuses such as 401, 403 and 404 were retried. Now only network errors, timeouts and 5xx responses are retried.
  • Error reason comes from Sentinel's error body. reason is the code from the error body (for example UNAUTHORIZED). If there is no code, it is the body's error field, and otherwise HTTP_<status>. Previously, 4xx responses other than 400 always gave HTTP_<status>.
  • verificationData has the same shape for local and remote verification. Sentinel v2 returns nested verificationData ({ device: { browser } }). verifyServer flattens it to the dotted keys that verifyServerSignature returns (data['device.browser']). Data from Sentinel v1 is already flat and doesn't change.
  • secret is not sent when apiKey is set. secret is only for Sentinel v1. Sentinel v2 rejects it on /v2.
  • Headers you pass override apiKey. A custom Authorization value in headers replaces the one built from apiKey.

Documentation

  • The README, docs/server-signatures.md and every framework guide now show remote verification for both Sentinel v2 and v1, and include a new section on errors and retries.
  • The README says that the default export provides the v2 form verifyServerSignature({ payload, hmacSecret }), and that the v1 form (payload, hmacKey) comes from altcha-lib/v1.

New types

  • VerifyServerApiKey: { id: string; secret: string }
  • VerifyServerOptions.apiKey?: VerifyServerApiKey

Don't miss a new altcha-lib release

NewReleases is sending notifications on new releases.