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 withoutalgorithm, now returnsverified: falsewithinvalidSolution: true. An unsupportedalgorithmstill throws. - 4xx responses from Sentinel are no longer retried. Previously only
400returned at once, and other 4xx statuses such as401,403and404were retried. Now only network errors, timeouts and 5xx responses are retried. - Error
reasoncomes from Sentinel's error body.reasonis thecodefrom the error body (for exampleUNAUTHORIZED). If there is nocode, it is the body'serrorfield, and otherwiseHTTP_<status>. Previously, 4xx responses other than400always gaveHTTP_<status>. verificationDatahas the same shape for local and remote verification. Sentinel v2 returns nestedverificationData({ device: { browser } }).verifyServerflattens it to the dotted keys thatverifyServerSignaturereturns (data['device.browser']). Data from Sentinel v1 is already flat and doesn't change.secretis not sent whenapiKeyis set.secretis only for Sentinel v1. Sentinel v2 rejects it on/v2.- Headers you pass override
apiKey. A customAuthorizationvalue inheadersreplaces the one built fromapiKey.
Documentation
- The README,
docs/server-signatures.mdand 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 fromaltcha-lib/v1.
New types
VerifyServerApiKey:{ id: string; secret: string }VerifyServerOptions.apiKey?: VerifyServerApiKey