altcha-lib 2.2.0 → 2.3.0

package/dist/cjs/v2/verify-server.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyServer = verifyServer;
+const helpers_js_1 = require("./helpers.js");
+/** Verifies a payload remotely via the ALTCHA Sentinel `/v1/verify/signature` API. */
+async function verifyServer(options) {
+    const { controller, fetch: fetchImpl = fetch, headers, payload, retries = 0, retryBackoff = 'exponential', retryDelay = 300, secret, timeout = 10_000, url, } = options;
+    const body = JSON.stringify({ payload, secret });
+    for (let attempt = 0; attempt <= retries; attempt++) {
+        if (controller?.signal.aborted) {
+            return { verified: false, reason: 'ABORTED' };
+        }
+        const attemptController = new AbortController();
+        const onAbort = () => attemptController.abort();
+        controller?.signal.addEventListener('abort', onAbort);
+        const timer = setTimeout(() => attemptController.abort(), timeout);
+        try {
+            const response = await fetchImpl(url, {
+                body,
+                headers: {
+                    'Content-Type': 'application/json',
+                    ...headers,
+                },
+                method: 'POST',
+                signal: attemptController.signal,
+            });
+            if (response.status === 400) {
+                const data = await response
+                    .json()
+                    .catch(() => null);
+                return {
+                    verified: false,
+                    reason: data?.error ?? `HTTP_${response.status}`,
+                };
+            }
+            if (!response.ok) {
+                throw new Error(`HTTP_${response.status}`);
+            }
+            return (await response.json());
+        }
+        catch (err) {
+            if (attempt >= retries) {
+                return {
+                    verified: false,
+                    reason: err instanceof Error ? err.message : 'NETWORK_ERROR',
+                };
+            }
+            const backoffDelay = retryBackoff === 'fixed' ? retryDelay : retryDelay * 2 ** attempt;
+            await (0, helpers_js_1.delay)(backoffDelay);
+        }
+        finally {
+            clearTimeout(timer);
+            controller?.signal.removeEventListener('abort', onAbort);
+        }
+    }
+    return { verified: false, reason: 'NETWORK_ERROR' };
+}

package/dist/esm/v2/frameworks/express.js

@@ -7,8 +7,11 @@ const asyncHandler = (fn) => (req, res, next) => {
     fn(req, res, next).catch(next);
 };
 export function create(options) {
-    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, } = options;
+    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, verifyServer: verifyServerOptions, } = options;
     const challengeHandler = asyncHandler(async (req, res) => {
+        if (!deriveKey || !createChallengeParameters) {
+            throw new Error('deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.');
+        }
         const challenge = await createChallenge({
             deriveKey,
             hmacSignatureSecret,
@@ -26,7 +29,7 @@ export function create(options) {
     });
     const verifyHandler = asyncHandler(async (req, res) => {
         const payload = await getPayloadFromRequest(req);
-        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         res.json(result);
     });
     const getPayloadFromRequest = async (req, cookieName) => {
@@ -39,7 +42,7 @@ export function create(options) {
         const { throwOnFailure = true } = options;
         return asyncHandler(async (req, res, next) => {
             const payload = await getPayloadFromRequest(req, setCookie?.name);
-            const { error, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             res.locals.altcha = {
                 error,
                 payload: resultPayload,

package/dist/esm/v2/frameworks/fastify.js

@@ -4,7 +4,7 @@ import { deriveHmacKeySecret, verify } from './shared.js';
 import { CappedMap } from '../capped-map.js';
 export { CappedMap, deriveHmacKeySecret, randomInt };
 export function create(options) {
-    const { createChallengeParameters, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, } = options;
+    const { createChallengeParameters, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, verifyServer: verifyServerOptions, } = options;
     const deleteCookie = (reply, name, path = '/') => {
         reply.header('Set-Cookie', `${name}=; Path=${path ?? '/'}; Max-Age=0`);
     };
@@ -28,6 +28,9 @@ export function create(options) {
         return request.body?.altcha;
     };
     const challengeHandler = async (request, reply) => {
+        if (!deriveKey || !createChallengeParameters) {
+            throw new Error('deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.');
+        }
         const challenge = await createChallenge({
             deriveKey,
             hmacSignatureSecret,
@@ -45,14 +48,14 @@ export function create(options) {
     };
     const verifyHandler = async (request, reply) => {
         const payload = await getPayloadFromRequest(request);
-        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         return reply.send(result);
     };
     const middleware = (options = {}) => {
         const { throwOnFailure = true } = options;
         return async (request, reply) => {
             const payload = await getPayloadFromRequest(request, setCookie?.name);
-            const { error, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             request.altcha = {
                 error,
                 payload: resultPayload,

package/dist/esm/v2/frameworks/h3.d.ts

@@ -22,7 +22,7 @@ export declare function create(options: AltchaOptions): {
     verifyHandler: import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
         error: string | null;
         payload: import("../types.js").Payload | import("../types.js").ServerSignaturePayload | null;
-        verification: import("../types.js").VerifySolutionResult | null;
+        verification: import("../types.js").VerifySolutionResult | import("../types.js").VerifyServerResult | null;
     }>>;
     getPayloadFromEvent: (event: H3Event, cookieName?: string) => Promise<string | undefined>;
     middleware: (options?: AltchaMiddlewareOptions) => import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<void>>;

package/dist/esm/v2/frameworks/h3.js

@@ -5,8 +5,14 @@ import { CappedMap } from '../capped-map.js';
 import { deriveHmacKeySecret, verify } from './shared.js';
 export { CappedMap, deriveHmacKeySecret, randomInt };
 export function create(options) {
-    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, } = options;
+    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, verifyServer: verifyServerOptions, } = options;
     const challengeHandler = defineEventHandler(async (event) => {
+        if (!deriveKey || !createChallengeParameters) {
+            throw new HTTPError({
+                message: 'deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.',
+                status: 500,
+            });
+        }
         setResponseHeader(event, 'Cache-Control', 'no-store');
         return {
             configuration: setCookie
@@ -23,7 +29,7 @@ export function create(options) {
         };
     });
     const verifyHandler = defineEventHandler(async (event) => {
-        return await verify(await getPayloadFromEvent(event), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        return await verify(await getPayloadFromEvent(event), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
     });
     const getPayloadFromEvent = async (event, cookieName) => {
         let payload = undefined;
@@ -54,7 +60,7 @@ export function create(options) {
     const middleware = (options = {}) => {
         const { throwOnFailure = true } = options;
         return defineEventHandler(async (event) => {
-            const { error, payload, verification } = await verify(await getPayloadFromEvent(event, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload, verification } = await verify(await getPayloadFromEvent(event, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             event.context.altcha = {
                 error,
                 payload,

package/dist/esm/v2/frameworks/hono.d.ts

@@ -84,6 +84,24 @@ export declare function create(options: AltchaOptions): {
             invalidSolution: boolean | null;
             time: number;
             verified: boolean;
+        } | {
+            apiKey?: string | null | undefined;
+            reason?: string | undefined;
+            verificationData?: {
+                [x: string]: import("hono/utils/types").JSONValue;
+                classification?: import("../types.js").ServerClassification | undefined;
+                email?: string | undefined;
+                expire?: number | undefined;
+                fields?: string[] | undefined;
+                fieldsHash?: string | undefined;
+                id?: string | undefined;
+                ipAddress?: string | undefined;
+                reasons?: string[] | undefined;
+                score?: number | undefined;
+                time?: number | undefined;
+                verified?: boolean | undefined;
+            } | null | undefined;
+            verified: boolean;
         } | null;
     }, import("hono/utils/http-status").ContentfulStatusCode, "json">>;
     getPayloadFromContext: (c: Context, cookieName?: string) => Promise<string | undefined>;

package/dist/esm/v2/frameworks/hono.js

@@ -6,8 +6,13 @@ import { CappedMap } from '../capped-map.js';
 import { deriveHmacKeySecret, verify } from './shared.js';
 export { CappedMap, deriveHmacKeySecret, randomInt };
 export function create(options) {
-    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, } = options;
+    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, verifyServer: verifyServerOptions, } = options;
     const challengeHandler = async (c) => {
+        if (!deriveKey || !createChallengeParameters) {
+            throw new HTTPException(500, {
+                message: 'deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.',
+            });
+        }
         c.header('Cache-Control', 'no-store');
         return c.json({
             configuration: setCookie
@@ -24,7 +29,7 @@ export function create(options) {
         });
     };
     const verifyHandler = async (c) => {
-        return c.json(await verify(await getPayloadFromContext(c), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store));
+        return c.json(await verify(await getPayloadFromContext(c), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions));
     };
     const getPayloadFromContext = async (c, cookieName) => {
         let payload = undefined;
@@ -48,7 +53,7 @@ export function create(options) {
     const middleware = (options = {}) => {
         const { throwOnFailure = true } = options;
         return async (c, next) => {
-            const { error, payload, verification } = await verify(await getPayloadFromContext(c, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload, verification } = await verify(await getPayloadFromContext(c, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             c.set('altcha', {
                 error,
                 payload,

package/dist/esm/v2/frameworks/nestjs.d.ts

@@ -22,13 +22,14 @@ export declare function createAltchaMiddleware(options?: AltchaMiddlewareOptions
     };
 };
 export declare class AltchaService {
-    private readonly hmacSignatureSecret;
+    private readonly hmacSignatureSecret?;
     private readonly hmacKeySignatureSecret?;
     private readonly createChallengeParameters;
-    private readonly deriveKey;
+    private readonly deriveKey?;
     private readonly fieldName;
     private readonly setCookieOptions?;
     private readonly store?;
+    private readonly verifyServerOptions?;
     constructor(options: AltchaOptions);
     get setCookie(): RequireField<SetCookieOptions, 'name'> | undefined;
     getChallenge(): Promise<{
@@ -43,7 +44,7 @@ export declare class AltchaService {
     verify(payload: string | undefined): Promise<{
         error: string | null;
         payload: import("../types.js").Payload | import("../types.js").ServerSignaturePayload | null;
-        verification: import("../types.js").VerifySolutionResult | null;
+        verification: import("../types.js").VerifySolutionResult | import("../types.js").VerifyServerResult | null;
     }>;
 }
 export declare class AltchaController {
@@ -60,7 +61,7 @@ export declare class AltchaController {
     verifySolution(req: Request): Promise<{
         error: string | null;
         payload: import("../types.js").Payload | import("../types.js").ServerSignaturePayload | null;
-        verification: import("../types.js").VerifySolutionResult | null;
+        verification: import("../types.js").VerifySolutionResult | import("../types.js").VerifyServerResult | null;
     }>;
 }
 export declare class AltchaMiddleware implements NestMiddleware {

package/dist/esm/v2/frameworks/nestjs.js

@@ -61,6 +61,7 @@ let AltchaService = class AltchaService {
     fieldName;
     setCookieOptions;
     store;
+    verifyServerOptions;
     constructor(options) {
         this.hmacSignatureSecret = options.hmacSignatureSecret;
         this.hmacKeySignatureSecret = options.hmacKeySignatureSecret;
@@ -69,16 +70,21 @@ let AltchaService = class AltchaService {
         this.fieldName = options.fieldName || 'altcha';
         this.setCookieOptions = options.setCookie;
         this.store = options.store;
+        this.verifyServerOptions = options.verifyServer;
     }
     get setCookie() {
         return this.setCookieOptions;
     }
     async getChallenge() {
+        const { createChallengeParameters, deriveKey } = this;
+        if (!deriveKey || !createChallengeParameters) {
+            throw new HttpException('deriveKey and createChallengeParameters are required to generate challenges. Omit the /challenge route when relying on Sentinel to issue challenges.', HttpStatus.INTERNAL_SERVER_ERROR);
+        }
         const challenge = await createChallenge({
-            deriveKey: this.deriveKey,
+            deriveKey,
             hmacSignatureSecret: this.hmacSignatureSecret,
             hmacKeySignatureSecret: this.hmacKeySignatureSecret,
-            ...this.createChallengeParameters(),
+            ...createChallengeParameters(),
         });
         return {
             configuration: this.setCookieOptions
@@ -94,7 +100,7 @@ let AltchaService = class AltchaService {
         return req.body?.[this.fieldName];
     }
     async verify(payload) {
-        return verify(payload, this.deriveKey, this.hmacSignatureSecret, this.hmacKeySignatureSecret, this.store);
+        return verify(payload, this.deriveKey, this.hmacSignatureSecret, this.hmacKeySignatureSecret, this.store, this.verifyServerOptions);
     }
 };
 AltchaService = __decorate([

package/dist/esm/v2/frameworks/nextjs.js

@@ -15,9 +15,12 @@ function deleteCookie(res, name, path) {
     res.headers.append('Set-Cookie', `${name}=; Path=${path ?? '/'}; Max-Age=0`);
 }
 export function create(options) {
-    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, } = options;
+    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, verifyServer: verifyServerOptions, } = options;
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     async function challengeHandler(_req) {
+        if (!deriveKey || !createChallengeParameters) {
+            throw new Error('deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.');
+        }
         const challenge = await createChallenge({
             deriveKey,
             hmacSignatureSecret,
@@ -39,7 +42,7 @@ export function create(options) {
     }
     async function verifyHandler(req) {
         const payload = await getPayloadFromRequest(req);
-        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         return Response.json(result);
     }
     async function getPayloadFromRequest(req, cookieName) {
@@ -63,7 +66,7 @@ export function create(options) {
     }
     async function middleware(req, throwOnFailure = true) {
         const payload = await getPayloadFromRequest(req, setCookie?.name);
-        const { error, payload: verifiedPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const { error, payload: verifiedPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         const result = {
             error,
             payload: verifiedPayload,

package/dist/esm/v2/frameworks/shared.d.ts

@@ -1,8 +1,8 @@
-import { DeriveKeyFunction, Payload, ServerSignaturePayload, VerifySolutionResult } from '../types.js';
-import type { Store } from './types.js';
+import { DeriveKeyFunction, Payload, ServerSignaturePayload, VerifyServerResult, VerifySolutionResult } from '../types.js';
+import type { AltchaVerifyServerOptions, Store } from './types.js';
 export declare function deriveHmacKeySecret(masterSecret: string): Promise<string>;
-export declare function verify(payload: unknown, deriveKey: DeriveKeyFunction, hmacSignatureSecret: string, hmacKeySignatureSecret?: string, store?: Store): Promise<{
+export declare function verify(payload: unknown, deriveKey: DeriveKeyFunction | undefined, hmacSignatureSecret: string | undefined, hmacKeySignatureSecret?: string, store?: Store, verifyServerOptions?: AltchaVerifyServerOptions): Promise<{
     error: string | null;
     payload: Payload | ServerSignaturePayload | null;
-    verification: VerifySolutionResult | null;
+    verification: VerifySolutionResult | VerifyServerResult | null;
 }>;

package/dist/esm/v2/frameworks/shared.js

@@ -1,11 +1,12 @@
 import { verifySolution } from '../pow.js';
 import { verifyServerSignature } from '../server-signature.js';
+import { verifyServer } from '../verify-server.js';
 import { bufferToHex, hmac } from '../helpers.js';
 import { HmacAlgorithm, } from '../types.js';
 export async function deriveHmacKeySecret(masterSecret) {
     return bufferToHex(await hmac(HmacAlgorithm.SHA_256, masterSecret, 'derived-secret'));
 }
-export async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store) {
+export async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions) {
     if (!payload) {
         return {
             error: 'ALTCHA payload is missing.',
@@ -29,6 +30,12 @@ export async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySig
     try {
         switch (type) {
             case 'client':
+                if (!deriveKey) {
+                    throw new Error('deriveKey is required to verify self-hosted ALTCHA challenges.');
+                }
+                if (!hmacSignatureSecret) {
+                    throw new Error('hmacSignatureSecret is required to verify self-hosted ALTCHA challenges.');
+                }
                 challengeId = getChallengeId(payload);
                 if (store && challengeId) {
                     await checkChallengeId(store, challengeId);
@@ -40,7 +47,18 @@ export async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySig
                 if (store && challengeId) {
                     await checkChallengeId(store, challengeId);
                 }
-                verification = await verifyServerSignaturePayload(payload, hmacSignatureSecret);
+                if (verifyServerOptions) {
+                    verification = await verifyServer({
+                        ...verifyServerOptions,
+                        payload: payload,
+                    });
+                }
+                else {
+                    if (!hmacSignatureSecret) {
+                        throw new Error('hmacSignatureSecret or verifyServer must be configured to verify this payload.');
+                    }
+                    verification = await verifyServerSignaturePayload(payload, hmacSignatureSecret);
+                }
                 break;
             default:
                 throw new Error('ALTCHA payload is invalid.');
@@ -55,7 +73,8 @@ export async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySig
     }
     if (!verification?.verified) {
         return {
-            error: 'ALTCHA verification failed.',
+            error: (verification && 'reason' in verification && verification.reason) ||
+                'ALTCHA verification failed.',
             payload: payload,
             verification,
         };

package/dist/esm/v2/frameworks/sveltekit.js

@@ -21,8 +21,11 @@ async function getPayloadFromEvent(event, fieldName, cookieName) {
     return body?.[fieldName];
 }
 export function create(options) {
-    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, } = options;
+    const { createChallengeParameters, deriveKey, fieldName = 'altcha', hmacSignatureSecret, hmacKeySignatureSecret, setCookie, store, verifyServer: verifyServerOptions, } = options;
     async function challengeHandler() {
+        if (!deriveKey || !createChallengeParameters) {
+            error(500, 'deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.');
+        }
         const challenge = await createChallenge({
             deriveKey,
             hmacSignatureSecret,
@@ -40,14 +43,14 @@ export function create(options) {
     }
     async function verifyHandler(event) {
         const payload = await getPayloadFromEvent(event, fieldName);
-        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const result = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         return json(result);
     }
     function createHandle(middlewareOptions = {}) {
         const { throwOnFailure = true } = middlewareOptions;
         return async ({ event, resolve }) => {
             const payload = await getPayloadFromEvent(event, fieldName, setCookie?.name);
-            const { error: verifyError, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error: verifyError, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             event.locals.altcha = {
                 error: verifyError,
                 payload: resultPayload,
@@ -66,7 +69,7 @@ export function create(options) {
     }
     async function verifyEvent(event) {
         const payload = await getPayloadFromEvent(event, fieldName, setCookie?.name);
-        const { error: verifyError, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const { error: verifyError, payload: resultPayload, verification, } = await verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         if (setCookie) {
             event.cookies.delete(setCookie.name, {
                 path: setCookie.path ?? '/',

package/dist/esm/v2/frameworks/types.d.ts

@@ -1,14 +1,19 @@
-import type { CreateChallengeOptions, DeriveKeyFunction, Payload, ServerSignaturePayload, SetCookieOptions, VerifySolutionResult } from '../types.js';
+import type { CreateChallengeOptions, DeriveKeyFunction, Payload, ServerSignaturePayload, SetCookieOptions, VerifyServerOptions, VerifyServerResult, VerifySolutionResult } from '../types.js';
+export type AltchaVerifyServerOptions = Omit<VerifyServerOptions, 'payload'>;
 export interface AltchaOptions {
     /**
      * Returns configuration options passed to `createChallenge`.
      * Must include `algorithm` and `cost`; all other `CreateChallengeOptions` fields are optional.
+     * Required to use `challengeHandler`; optional if challenges are issued by Sentinel and
+     * only `verifyServer` is used.
      */
-    createChallengeParameters: () => Pick<CreateChallengeOptions, 'algorithm' | 'cost'> & Partial<CreateChallengeOptions>;
+    createChallengeParameters?: () => Pick<CreateChallengeOptions, 'algorithm' | 'cost'> & Partial<CreateChallengeOptions>;
     /**
      * Algorithm-specific key derivation function used to generate challenge keys.
+     * Required to use `challengeHandler` or to verify self-hosted (client-type) payloads;
+     * optional if challenges are issued by Sentinel and only `verifyServer` is used.
      */
-    deriveKey: DeriveKeyFunction;
+    deriveKey?: DeriveKeyFunction;
     /**
      * Name of the form field that carries the ALTCHA payload.
      * Defaults to `'altcha'` if not specified.
@@ -16,8 +21,10 @@ export interface AltchaOptions {
     fieldName?: string;
     /**
      * HMAC secret used to sign and verify challenge signatures.
+     * Optional if `verifyServer` is configured and only Sentinel-issued (server-signed)
+     * payloads are verified remotely.
      */
-    hmacSignatureSecret: string;
+    hmacSignatureSecret?: string;
     /**
      * HMAC secret used to sign keys in deterministic mode.
      */
@@ -31,6 +38,11 @@ export interface AltchaOptions {
      * Store implementation for tracking used challenges and preventing replay attacks.
      */
     store?: Store;
+    /**
+     * When set, Sentinel-issued (server-signed) payloads are verified remotely via
+     * `POST /v1/verify/signature` instead of locally with `hmacSignatureSecret`.
+     */
+    verifyServer?: AltchaVerifyServerOptions;
 }
 export interface AltchaMiddlewareOptions {
     throwOnFailure?: boolean;
@@ -38,7 +50,7 @@ export interface AltchaMiddlewareOptions {
 export interface AltchaResult {
     error: string | null;
     payload: Payload | ServerSignaturePayload | null;
-    verification: VerifySolutionResult | null;
+    verification: VerifySolutionResult | VerifyServerResult | null;
 }
 export type RequireField<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
 export interface Store {

package/dist/esm/v2/index.d.ts

@@ -1,10 +1,11 @@
 import { createChallenge, solveChallenge, solveChallengeWorkers, verifySolution } from './pow.js';
 import { verifyFieldsHash, verifyServerSignature } from './server-signature.js';
+import { verifyServer } from './verify-server.js';
 import { CappedMap } from './capped-map.js';
 import { randomInt } from './helpers.js';
 import { HmacAlgorithm } from './types.js';
 export type * from './types.js';
-export { CappedMap, HmacAlgorithm, createChallenge, randomInt, solveChallenge, solveChallengeWorkers, verifyFieldsHash, verifyServerSignature, verifySolution, };
+export { CappedMap, HmacAlgorithm, createChallenge, randomInt, solveChallenge, solveChallengeWorkers, verifyFieldsHash, verifyServer, verifyServerSignature, verifySolution, };
 declare const _default: {
     CappedMap: typeof CappedMap;
     HmacAlgorithm: typeof HmacAlgorithm;
@@ -13,6 +14,7 @@ declare const _default: {
     solveChallenge: typeof solveChallenge;
     solveChallengeWorkers: typeof solveChallengeWorkers;
     verifyFieldsHash: typeof verifyFieldsHash;
+    verifyServer: typeof verifyServer;
     verifyServerSignature: typeof verifyServerSignature;
     verifySolution: typeof verifySolution;
 };

package/dist/esm/v2/index.js

@@ -1,9 +1,10 @@
 import { createChallenge, solveChallenge, solveChallengeWorkers, verifySolution, } from './pow.js';
 import { verifyFieldsHash, verifyServerSignature } from './server-signature.js';
+import { verifyServer } from './verify-server.js';
 import { CappedMap } from './capped-map.js';
 import { randomInt } from './helpers.js';
 import { HmacAlgorithm } from './types.js';
-export { CappedMap, HmacAlgorithm, createChallenge, randomInt, solveChallenge, solveChallengeWorkers, verifyFieldsHash, verifyServerSignature, verifySolution, };
+export { CappedMap, HmacAlgorithm, createChallenge, randomInt, solveChallenge, solveChallengeWorkers, verifyFieldsHash, verifyServer, verifyServerSignature, verifySolution, };
 export default {
     CappedMap,
     HmacAlgorithm,
@@ -12,6 +13,7 @@ export default {
     solveChallenge,
     solveChallengeWorkers,
     verifyFieldsHash,
+    verifyServer,
     verifyServerSignature,
     verifySolution,
 };

package/dist/esm/v2/types.d.ts

@@ -233,6 +233,60 @@ export interface VerifyResult {
 export interface VerifyServerSignatureResult extends VerifySolutionResult {
     verificationData?: ServerSignatureVerificationData | null;
 }
+export interface VerifyServerOptions {
+    /**
+     * The payload to verify, as received from `POST /v1/verify`
+     * (either the raw string or the decoded object).
+     */
+    payload: string | ServerSignaturePayload | Record<string, unknown>;
+    /**
+     * Full URL of the Sentinel `/v1/verify/signature` endpoint.
+     */
+    url: string;
+    /**
+     * API key secret. If provided, Sentinel checks that it matches the
+     * API key associated with the payload.
+     */
+    secret?: string;
+    /**
+     * Custom fetch implementation. Defaults to the global `fetch`.
+     */
+    fetch?: typeof fetch;
+    /**
+     * Additional headers to send with the request.
+     */
+    headers?: Record<string, string>;
+    /**
+     * AbortController for cancelling the verification request.
+     */
+    controller?: AbortController;
+    /**
+     * Per-attempt request timeout in milliseconds.
+     * Defaults to `10_000` (10 seconds).
+     */
+    timeout?: number;
+    /**
+     * Number of retry attempts after the first try.
+     * Defaults to `0` (no retries).
+     */
+    retries?: number;
+    /**
+     * Base delay in milliseconds between retry attempts.
+     * Defaults to `300`.
+     */
+    retryDelay?: number;
+    /**
+     * Backoff strategy applied to `retryDelay` between retries.
+     * Defaults to `'exponential'`.
+     */
+    retryBackoff?: 'fixed' | 'exponential';
+}
+export interface VerifyServerResult {
+    apiKey?: string | null;
+    reason?: string;
+    verificationData?: ServerSignatureVerificationData | null;
+    verified: boolean;
+}
 export interface VerifySolutionOptions {
     /**
      * Challenge object to verify against, either decoded from the client payload

package/dist/esm/v2/verify-server.d.ts

@@ -0,0 +1,3 @@
+import type { VerifyServerOptions, VerifyServerResult } from './types.js';
+/** Verifies a payload remotely via the ALTCHA Sentinel `/v1/verify/signature` API. */
+export declare function verifyServer(options: VerifyServerOptions): Promise<VerifyServerResult>;