altcha-lib 2.2.0 → 2.3.1

package/README.md

@@ -55,6 +55,8 @@ The library includes plugins for several popular frameworks to simplify integrat
 
 If your framework is not listed, see the [Advanced Usage](/docs/advanced-usage.md) guide for custom integrations.
 
+All plugins also support remote verification via ALTCHA Sentinel (`verifyServer` option) — see [`/docs/server-signatures.md`](/docs/server-signatures.md#remote-verification-sentinel-api).
+
 ## Documentation
 
 - Advanced Usage: [`/docs/advanced-usage.md`](/docs/advanced-usage.md)
@@ -96,6 +98,12 @@ bun run --port 3000 examples/hono-example.ts
 deno serve --allow-net --sloppy-imports --port 3000 examples/hono-example.ts
 ```
 
+**Hono + Sentinel remote verification example (Bun):**
+
+```sh
+bun run --port 3000 examples/hono-sentinel-example.ts
+```
+
 ## Breaking Changes (v2)
 
 Version 2 introduces a new proof-of-work mechanism and challenge format. See the [PoW documentation](https://playground.altcha.org/#/about) for details.
@@ -217,6 +225,32 @@ Returns `VerifyServerSignatureResult` (extends `VerifySolutionResult`):
 | `verified` | `boolean` | Whether the signature is valid. |
 | `verificationData` | `ServerSignatureVerificationData \| null` | Parsed verification data. |
 
+#### `verifyServer(options: VerifyServerOptions): Promise<VerifyServerResult>`
+
+Verifies a payload remotely by calling ALTCHA Sentinel's `POST /v1/verify/signature` API, instead of verifying the HMAC signature locally.
+
+| Option | Type | Description |
+|---|---|---|
+| `payload` | `string \| ServerSignaturePayload \| Record<string, unknown>` | The payload to verify, as received from `POST /v1/verify`. |
+| `url` | `string` | Full URL of the Sentinel `/v1/verify/signature` endpoint. |
+| `secret` | `string?` | API key secret. If provided, Sentinel checks that it matches the API key associated with the payload. |
+| `fetch` | `typeof fetch?` | Custom fetch implementation. Defaults to the global `fetch`. |
+| `headers` | `Record<string, string>?` | Additional headers to send with the request. |
+| `controller` | `AbortController?` | For cancelling the verification request. |
+| `timeout` | `number?` | Per-attempt request timeout in milliseconds. Defaults to `10000`. |
+| `retries` | `number?` | Number of retry attempts after the first try. Defaults to `0`. |
+| `retryDelay` | `number?` | Base delay in milliseconds between retries. Defaults to `300`. |
+| `retryBackoff` | `'fixed' \| 'exponential'?` | Backoff strategy for `retryDelay`. Defaults to `'exponential'`. |
+
+Returns `VerifyServerResult`:
+
+| Field | Type | Description |
+|---|---|---|
+| `verified` | `boolean` | Whether the payload was successfully verified. |
+| `apiKey` | `string \| null?` | API key associated with the verification. |
+| `reason` | `string?` | Reason or error message if verification failed. |
+| `verificationData` | `ServerSignatureVerificationData \| null?` | Verification data returned by Sentinel. |
+
 #### `obfuscate(str: string, options?): Promise<string>`
 
 > Import from `altcha-lib/obfuscation`

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

@@ -13,8 +13,11 @@ const asyncHandler = (fn) => (req, res, next) => {
     fn(req, res, next).catch(next);
 };
 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 (0, pow_js_1.createChallenge)({
             deriveKey,
             hmacSignatureSecret,
@@ -45,7 +48,7 @@ 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 (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             res.locals.altcha = {
                 error,
                 payload: resultPayload,

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

@@ -10,7 +10,7 @@ Object.defineProperty(exports, "deriveHmacKeySecret", { enumerable: true, get: f
 const capped_map_js_1 = require("../capped-map.js");
 Object.defineProperty(exports, "CappedMap", { enumerable: true, get: function () { return capped_map_js_1.CappedMap; } });
 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`);
     };
@@ -34,6 +34,9 @@ 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 (0, pow_js_1.createChallenge)({
             deriveKey,
             hmacSignatureSecret,
@@ -58,7 +61,7 @@ function create(options) {
         const { throwOnFailure = true } = options;
         return async (request, reply) => {
             const payload = await getPayloadFromRequest(request, setCookie?.name);
-            const { error, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             request.altcha = {
                 error,
                 payload: resultPayload,

package/dist/cjs/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/cjs/v2/frameworks/h3.js

@@ -11,8 +11,14 @@ Object.defineProperty(exports, "CappedMap", { enumerable: true, get: function ()
 const shared_js_1 = require("./shared.js");
 Object.defineProperty(exports, "deriveHmacKeySecret", { enumerable: true, get: function () { return shared_js_1.deriveHmacKeySecret; } });
 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 = (0, h3_1.defineEventHandler)(async (event) => {
+        if (!deriveKey || !createChallengeParameters) {
+            throw new h3_1.HTTPError({
+                message: 'deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.',
+                status: 500,
+            });
+        }
         (0, h3_1.setResponseHeader)(event, 'Cache-Control', 'no-store');
         return {
             configuration: setCookie
@@ -60,7 +66,7 @@ function create(options) {
     const middleware = (options = {}) => {
         const { throwOnFailure = true } = options;
         return (0, h3_1.defineEventHandler)(async (event) => {
-            const { error, payload, verification } = await (0, shared_js_1.verify)(await getPayloadFromEvent(event, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload, verification } = await (0, shared_js_1.verify)(await getPayloadFromEvent(event, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             event.context.altcha = {
                 error,
                 payload,

package/dist/cjs/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.js").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.js").ContentfulStatusCode, "json">>;
     getPayloadFromContext: (c: Context, cookieName?: string) => Promise<string | undefined>;

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

@@ -12,8 +12,13 @@ Object.defineProperty(exports, "CappedMap", { enumerable: true, get: function ()
 const shared_js_1 = require("./shared.js");
 Object.defineProperty(exports, "deriveHmacKeySecret", { enumerable: true, get: function () { return shared_js_1.deriveHmacKeySecret; } });
 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 http_exception_1.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
@@ -54,7 +59,7 @@ function create(options) {
     const middleware = (options = {}) => {
         const { throwOnFailure = true } = options;
         return async (c, next) => {
-            const { error, payload, verification } = await (0, shared_js_1.verify)(await getPayloadFromContext(c, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error, payload, verification } = await (0, shared_js_1.verify)(await getPayloadFromContext(c, setCookie?.name), deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             c.set('altcha', {
                 error,
                 payload,

package/dist/cjs/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<{
@@ -40,10 +41,12 @@ export declare class AltchaService {
         } | undefined;
     }>;
     getPayloadFromRequest(req: Request, cookieName?: string): string | undefined;
-    verify(payload: string | undefined): Promise<{
+    verify(payload: string | undefined, options?: {
+        allowRemote?: boolean;
+    }): 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 +63,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/cjs/v2/frameworks/nestjs.js

@@ -36,7 +36,7 @@ function createAltchaMiddleware(options = {}) {
         }
         async use(req, res, next) {
             const payload = this.altchaService.getPayloadFromRequest(req);
-            const { error, payload: resultPayload, verification, } = await this.altchaService.verify(payload);
+            const { error, payload: resultPayload, verification, } = await this.altchaService.verify(payload, { allowRemote: true });
             req.altcha = {
                 error,
                 payload: resultPayload,
@@ -67,16 +67,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 common_1.HttpException('deriveKey and createChallengeParameters are required to generate challenges. Omit the /challenge route when relying on Sentinel to issue challenges.', common_1.HttpStatus.INTERNAL_SERVER_ERROR);
+        }
         const challenge = await (0, pow_js_1.createChallenge)({
-            deriveKey: this.deriveKey,
+            deriveKey,
             hmacSignatureSecret: this.hmacSignatureSecret,
             hmacKeySignatureSecret: this.hmacKeySignatureSecret,
-            ...this.createChallengeParameters(),
+            ...createChallengeParameters(),
         });
         return {
             configuration: this.setCookieOptions
@@ -91,8 +96,8 @@ let AltchaService = class AltchaService {
         }
         return req.body?.[this.fieldName];
     }
-    async verify(payload) {
-        return (0, shared_js_1.verify)(payload, this.deriveKey, this.hmacSignatureSecret, this.hmacKeySignatureSecret, this.store);
+    async verify(payload, options = {}) {
+        return (0, shared_js_1.verify)(payload, this.deriveKey, this.hmacSignatureSecret, this.hmacKeySignatureSecret, this.store, options.allowRemote ? this.verifyServerOptions : undefined);
     }
 };
 exports.AltchaService = AltchaService;
@@ -138,7 +143,7 @@ let AltchaMiddleware = class AltchaMiddleware {
     }
     async use(req, res, next) {
         const payload = this.altchaService.getPayloadFromRequest(req, this.altchaService.setCookie?.name);
-        const { error, payload: resultPayload, verification, } = await this.altchaService.verify(payload);
+        const { error, payload: resultPayload, verification, } = await this.altchaService.verify(payload, { allowRemote: true });
         req.altcha = {
             error,
             payload: resultPayload,

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

@@ -21,9 +21,12 @@ function deleteCookie(res, name, path) {
     res.headers.append('Set-Cookie', `${name}=; Path=${path ?? '/'}; Max-Age=0`);
 }
 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 (0, pow_js_1.createChallenge)({
             deriveKey,
             hmacSignatureSecret,
@@ -69,7 +72,7 @@ function create(options) {
     }
     async function middleware(req, throwOnFailure = true) {
         const payload = await getPayloadFromRequest(req, setCookie?.name);
-        const { error, payload: verifiedPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const { error, payload: verifiedPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         const result = {
             error,
             payload: verifiedPayload,

package/dist/cjs/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/cjs/v2/frameworks/shared.js

@@ -4,12 +4,13 @@ exports.deriveHmacKeySecret = deriveHmacKeySecret;
 exports.verify = verify;
 const pow_js_1 = require("../pow.js");
 const server_signature_js_1 = require("../server-signature.js");
+const verify_server_js_1 = require("../verify-server.js");
 const helpers_js_1 = require("../helpers.js");
 const types_js_1 = require("../types.js");
 async function deriveHmacKeySecret(masterSecret) {
     return (0, helpers_js_1.bufferToHex)(await (0, helpers_js_1.hmac)(types_js_1.HmacAlgorithm.SHA_256, masterSecret, 'derived-secret'));
 }
-async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store) {
+async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions) {
     if (!payload) {
         return {
             error: 'ALTCHA payload is missing.',
@@ -33,6 +34,12 @@ async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureS
     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);
@@ -44,7 +51,18 @@ async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureS
                 if (store && challengeId) {
                     await checkChallengeId(store, challengeId);
                 }
-                verification = await verifyServerSignaturePayload(payload, hmacSignatureSecret);
+                if (verifyServerOptions) {
+                    verification = await (0, verify_server_js_1.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.');
@@ -59,7 +77,8 @@ async function verify(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureS
     }
     if (!verification?.verified) {
         return {
-            error: 'ALTCHA verification failed.',
+            error: (verification && 'reason' in verification && verification.reason) ||
+                'ALTCHA verification failed.',
             payload: payload,
             verification,
         };

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

@@ -27,8 +27,11 @@ async function getPayloadFromEvent(event, fieldName, cookieName) {
     return body?.[fieldName];
 }
 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) {
+            (0, kit_1.error)(500, 'deriveKey and createChallengeParameters are required to generate challenges. Omit challengeHandler when relying on Sentinel to issue challenges.');
+        }
         const challenge = await (0, pow_js_1.createChallenge)({
             deriveKey,
             hmacSignatureSecret,
@@ -53,7 +56,7 @@ function create(options) {
         const { throwOnFailure = true } = middlewareOptions;
         return async ({ event, resolve }) => {
             const payload = await getPayloadFromEvent(event, fieldName, setCookie?.name);
-            const { error: verifyError, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+            const { error: verifyError, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
             event.locals.altcha = {
                 error: verifyError,
                 payload: resultPayload,
@@ -72,7 +75,7 @@ function create(options) {
     }
     async function verifyEvent(event) {
         const payload = await getPayloadFromEvent(event, fieldName, setCookie?.name);
-        const { error: verifyError, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store);
+        const { error: verifyError, payload: resultPayload, verification, } = await (0, shared_js_1.verify)(payload, deriveKey, hmacSignatureSecret, hmacKeySignatureSecret, store, verifyServerOptions);
         if (setCookie) {
             event.cookies.delete(setCookie.name, {
                 path: setCookie.path ?? '/',

package/dist/cjs/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/cjs/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/cjs/v2/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.verifySolution = exports.verifyServerSignature = exports.verifyFieldsHash = exports.solveChallengeWorkers = exports.solveChallenge = exports.randomInt = exports.createChallenge = exports.HmacAlgorithm = exports.CappedMap = void 0;
+exports.verifySolution = exports.verifyServerSignature = exports.verifyServer = exports.verifyFieldsHash = exports.solveChallengeWorkers = exports.solveChallenge = exports.randomInt = exports.createChallenge = exports.HmacAlgorithm = exports.CappedMap = void 0;
 const pow_js_1 = require("./pow.js");
 Object.defineProperty(exports, "createChallenge", { enumerable: true, get: function () { return pow_js_1.createChallenge; } });
 Object.defineProperty(exports, "solveChallenge", { enumerable: true, get: function () { return pow_js_1.solveChallenge; } });
@@ -9,6 +9,8 @@ Object.defineProperty(exports, "verifySolution", { enumerable: true, get: functi
 const server_signature_js_1 = require("./server-signature.js");
 Object.defineProperty(exports, "verifyFieldsHash", { enumerable: true, get: function () { return server_signature_js_1.verifyFieldsHash; } });
 Object.defineProperty(exports, "verifyServerSignature", { enumerable: true, get: function () { return server_signature_js_1.verifyServerSignature; } });
+const verify_server_js_1 = require("./verify-server.js");
+Object.defineProperty(exports, "verifyServer", { enumerable: true, get: function () { return verify_server_js_1.verifyServer; } });
 const capped_map_js_1 = require("./capped-map.js");
 Object.defineProperty(exports, "CappedMap", { enumerable: true, get: function () { return capped_map_js_1.CappedMap; } });
 const helpers_js_1 = require("./helpers.js");
@@ -23,6 +25,7 @@ exports.default = {
     solveChallenge: pow_js_1.solveChallenge,
     solveChallengeWorkers: pow_js_1.solveChallengeWorkers,
     verifyFieldsHash: server_signature_js_1.verifyFieldsHash,
+    verifyServer: verify_server_js_1.verifyServer,
     verifyServerSignature: server_signature_js_1.verifyServerSignature,
     verifySolution: pow_js_1.verifySolution,
 };

package/dist/cjs/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/cjs/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>;

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' };
+}