@buildersgarden/siwa 0.0.20 → 0.0.21

package/dist/captcha.d.ts

@@ -0,0 +1,188 @@
+/**
+ * captcha.ts
+ *
+ * Reverse CAPTCHA — inspired by MoltCaptcha (https://github.com/MoltCaptcha/MoltCaptcha).
+ *
+ * Challenges exploit how LLMs generate text in a single autoregressive pass
+ * (satisfying multiple constraints simultaneously), while humans must iterate.
+ *
+ * Two integration points:
+ *   1. Sign-in flow — server can require captcha before issuing a nonce
+ *   2. Per-request — middleware randomly challenges agents during authenticated API calls
+ *
+ * No external dependencies — only `node:crypto`.
+ */
+export type CaptchaDifficulty = 'easy' | 'medium' | 'hard' | 'extreme';
+export type CaptchaFormat = 'haiku' | 'quatrain' | 'free_verse' | 'micro_story';
+export interface CaptchaChallenge {
+    topic: string;
+    format: CaptchaFormat;
+    lineCount: number;
+    asciiTarget: number;
+    wordCount?: number;
+    charPosition?: [number, string];
+    totalChars?: number;
+    timeLimitSeconds: number;
+    difficulty: CaptchaDifficulty;
+    createdAt: number;
+}
+export interface CaptchaSolution {
+    text: string;
+    solvedAt: number;
+}
+export interface CaptchaVerificationResult {
+    asciiSum: {
+        pass: boolean;
+        actual: number;
+        target: number;
+    };
+    lineCount?: {
+        pass: boolean;
+        actual: number;
+        target: number;
+    };
+    wordCount?: {
+        pass: boolean;
+        actual: number;
+        target: number;
+    };
+    charPosition?: {
+        pass: boolean;
+    };
+    totalChars?: {
+        pass: boolean;
+        actual: number;
+        target?: number;
+    };
+    timing: {
+        pass: boolean;
+        elapsedSeconds: number;
+    };
+    overallPass: boolean;
+    verdict: 'VERIFIED_AI_AGENT' | 'CHALLENGE_FAILED';
+}
+export type CaptchaPolicy = (context: {
+    address: string;
+    agentId: number;
+    agentRegistry: string;
+    request?: Request;
+}) => CaptchaDifficulty | null | Promise<CaptchaDifficulty | null>;
+export interface CaptchaVerifyOptions {
+    /** Use server wall-clock time instead of trusting the agent's solvedAt. Default: true */
+    useServerTiming?: boolean;
+    /** Extra seconds added to time limit for network latency. Default: 2 */
+    timingToleranceSeconds?: number;
+    /** Whether verification results include actual vs target values. Default: true */
+    revealConstraints?: boolean;
+    /** Tolerance for ASCII sum comparison (±N). Default: 0 (exact match) */
+    asciiTolerance?: number;
+    /** Callback to consume a challenge token (one-time use). Return false to reject replays. */
+    consumeChallenge?: (challengeToken: string) => boolean | Promise<boolean>;
+}
+export interface CaptchaOptions {
+    secret: string;
+    topics?: string[];
+    formats?: CaptchaFormat[];
+    /** Override difficulty settings per tier */
+    difficulties?: Partial<Record<CaptchaDifficulty, Partial<DifficultyConfig>>>;
+    /** Verification options (passed through to verifyCaptchaSolution) */
+    verify?: CaptchaVerifyOptions;
+}
+export declare const CHALLENGE_HEADER = "X-SIWA-Challenge";
+export declare const CHALLENGE_RESPONSE_HEADER = "X-SIWA-Challenge-Response";
+export interface DifficultyConfig {
+    timeLimitSeconds: number;
+    lineCount: [number, number];
+    useWordCount: boolean;
+    useCharPosition: boolean;
+    useTotalChars: boolean;
+}
+/**
+ * Generate a captcha challenge and HMAC-signed token.
+ *
+ * @param difficulty  Challenge difficulty tier
+ * @param options     Secret for HMAC signing + optional topic/format pools
+ * @returns           `{ challenge, challengeToken }` — the challenge data and its signed token
+ */
+export declare function createCaptchaChallenge(difficulty: CaptchaDifficulty, options: CaptchaOptions): {
+    challenge: CaptchaChallenge;
+    challengeToken: string;
+};
+/**
+ * Verify a captcha solution against a signed challenge token.
+ *
+ * @param challengeToken  HMAC-signed token from createCaptchaChallenge
+ * @param solution        The agent's solution (text + timestamp)
+ * @param secret          HMAC secret used to sign the token
+ * @param options         Verification options (timing, tolerance, replay protection, redaction)
+ * @returns               Verification result, or `null` if the token is invalid/replayed
+ */
+export declare function verifyCaptchaSolution(challengeToken: string, solution: CaptchaSolution, secret: string, options?: CaptchaVerifyOptions): Promise<CaptchaVerificationResult | null>;
+/**
+ * Callback that receives a captcha challenge and returns the solution text.
+ *
+ * Typically implemented by prompting an LLM to generate text that satisfies
+ * all constraints (line count, ASCII sum, word count, etc.) in a single pass.
+ */
+export type CaptchaSolver = (challenge: CaptchaChallenge) => string | Promise<string>;
+/**
+ * Detect and solve a captcha challenge from a nonce response.
+ *
+ * When a server's nonce endpoint returns `{ status: 'captcha_required' }`,
+ * this helper calls the solver, packs the response, and returns a
+ * `challengeResponse` string for the agent to include in the retry request.
+ *
+ * @param nonceResponse  The parsed JSON body from the nonce endpoint
+ * @param solver         Callback that generates solution text from a challenge
+ * @returns `{ solved: true, challengeResponse }` if captcha was solved,
+ *          `{ solved: false }` if no captcha was required
+ *
+ * @example
+ * ```typescript
+ * import { solveCaptchaChallenge } from '@buildersgarden/siwa/captcha';
+ *
+ * const res = await fetch('/siwa/nonce', { method: 'POST', body: JSON.stringify(params) });
+ * const nonceResult = await res.json();
+ *
+ * const captcha = await solveCaptchaChallenge(nonceResult, async (challenge) => {
+ *   // LLM generates text satisfying all constraints
+ *   return await generateText(challenge); // your LLM solver
+ * });
+ *
+ * if (captcha.solved) {
+ *   // Retry with challenge response
+ *   const retry = await fetch('/siwa/nonce', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ ...params, challengeResponse: captcha.challengeResponse }),
+ *   });
+ * }
+ * ```
+ */
+export declare function solveCaptchaChallenge(nonceResponse: {
+    status: string;
+    challenge?: CaptchaChallenge;
+    challengeToken?: string;
+}, solver: CaptchaSolver): Promise<{
+    solved: true;
+    challengeResponse: string;
+} | {
+    solved: false;
+}>;
+/**
+ * Package a captcha solution for submission (agent-side).
+ *
+ * @param challengeToken  The challenge token received from the server
+ * @param text            The agent's solution text
+ * @returns               A packed string to send in the challenge response header/field
+ */
+export declare function packCaptchaResponse(challengeToken: string, text: string): string;
+/**
+ * Unpack a captcha response (server-side).
+ *
+ * @param packed  The base64url-encoded response from the agent
+ * @returns       The challenge token and solution, or `null` if malformed
+ */
+export declare function unpackCaptchaResponse(packed: string): {
+    challengeToken: string;
+    solution: CaptchaSolution;
+} | null;

package/dist/captcha.js

@@ -0,0 +1,335 @@
+/**
+ * captcha.ts
+ *
+ * Reverse CAPTCHA — inspired by MoltCaptcha (https://github.com/MoltCaptcha/MoltCaptcha).
+ *
+ * Challenges exploit how LLMs generate text in a single autoregressive pass
+ * (satisfying multiple constraints simultaneously), while humans must iterate.
+ *
+ * Two integration points:
+ *   1. Sign-in flow — server can require captcha before issuing a nonce
+ *   2. Per-request — middleware randomly challenges agents during authenticated API calls
+ *
+ * No external dependencies — only `node:crypto`.
+ */
+import * as crypto from 'crypto';
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+export const CHALLENGE_HEADER = 'X-SIWA-Challenge';
+export const CHALLENGE_RESPONSE_HEADER = 'X-SIWA-Challenge-Response';
+const DEFAULT_TOPICS = [
+    'quantum computing',
+    'neural networks',
+    'blockchain consensus',
+    'compiler optimization',
+    'distributed systems',
+    'cryptographic hashing',
+    'orbital mechanics',
+    'gene editing',
+    'photonic circuits',
+    'autonomous navigation',
+    'protein folding',
+    'dark matter',
+    'fusion reactors',
+    'swarm robotics',
+    'topological insulators',
+    'zero-knowledge proofs',
+];
+const DEFAULT_FORMATS = ['haiku', 'quatrain', 'free_verse', 'micro_story'];
+const DIFFICULTY_TABLE = {
+    easy: {
+        timeLimitSeconds: 30,
+        lineCount: [3, 4],
+        useWordCount: false,
+        useCharPosition: false,
+        useTotalChars: false,
+    },
+    medium: {
+        timeLimitSeconds: 20,
+        lineCount: [4, 6],
+        useWordCount: true,
+        useCharPosition: false,
+        useTotalChars: false,
+    },
+    hard: {
+        timeLimitSeconds: 15,
+        lineCount: [4, 6],
+        useWordCount: true,
+        useCharPosition: true,
+        useTotalChars: false,
+    },
+    extreme: {
+        timeLimitSeconds: 10,
+        lineCount: [5, 7],
+        useWordCount: true,
+        useCharPosition: true,
+        useTotalChars: true,
+    },
+};
+const FORMAT_LINE_COUNTS = {
+    haiku: 3,
+    quatrain: 4,
+    free_verse: 5,
+    micro_story: 4,
+};
+// ---------------------------------------------------------------------------
+// HMAC token helpers (same pattern as receipt.ts)
+// ---------------------------------------------------------------------------
+function signToken(payload, secret) {
+    const data = Buffer.from(JSON.stringify(payload)).toString('base64url');
+    const sig = crypto.createHmac('sha256', secret).update(data).digest('base64url');
+    return `${data}.${sig}`;
+}
+function verifyToken(token, secret) {
+    const dotIdx = token.indexOf('.');
+    if (dotIdx === -1)
+        return null;
+    const data = token.slice(0, dotIdx);
+    const sig = token.slice(dotIdx + 1);
+    if (!data || !sig)
+        return null;
+    const expected = crypto.createHmac('sha256', secret).update(data).digest('base64url');
+    if (sig.length !== expected.length)
+        return null;
+    if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
+        return null;
+    try {
+        return JSON.parse(Buffer.from(data, 'base64url').toString());
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function randomInt(min, max) {
+    return min + (crypto.randomInt(max - min + 1));
+}
+function randomChoice(arr) {
+    return arr[crypto.randomInt(arr.length)];
+}
+// ---------------------------------------------------------------------------
+// Server-side: challenge generation
+// ---------------------------------------------------------------------------
+/**
+ * Generate a captcha challenge and HMAC-signed token.
+ *
+ * @param difficulty  Challenge difficulty tier
+ * @param options     Secret for HMAC signing + optional topic/format pools
+ * @returns           `{ challenge, challengeToken }` — the challenge data and its signed token
+ */
+export function createCaptchaChallenge(difficulty, options) {
+    const baseConfig = DIFFICULTY_TABLE[difficulty];
+    const overrides = options.difficulties?.[difficulty];
+    const config = overrides ? { ...baseConfig, ...overrides } : baseConfig;
+    const topics = options.topics ?? DEFAULT_TOPICS;
+    const formats = options.formats ?? DEFAULT_FORMATS;
+    const topic = randomChoice(topics);
+    const format = randomChoice(formats);
+    const lineCount = FORMAT_LINE_COUNTS[format] ?? randomInt(config.lineCount[0], config.lineCount[1]);
+    // ASCII target: sum of first-char ASCII values, plausible range for uppercase/lowercase letters
+    // Each line starts with a letter (65-122), so target is roughly lineCount * 65..122
+    const asciiTarget = randomInt(lineCount * 65, lineCount * 122);
+    const challenge = {
+        topic,
+        format,
+        lineCount,
+        asciiTarget,
+        timeLimitSeconds: config.timeLimitSeconds,
+        difficulty,
+        createdAt: Date.now(),
+    };
+    if (config.useWordCount) {
+        // Target word count: reasonable range for the format
+        challenge.wordCount = randomInt(lineCount * 3, lineCount * 7);
+    }
+    if (config.useCharPosition) {
+        // Pick a character position in flattened text and require a specific letter
+        const pos = randomInt(5, 30);
+        const charCode = randomInt(97, 122); // lowercase a-z
+        challenge.charPosition = [pos, String.fromCharCode(charCode)];
+    }
+    if (config.useTotalChars) {
+        // Total character count (excluding newlines)
+        challenge.totalChars = randomInt(lineCount * 15, lineCount * 40);
+    }
+    const challengeToken = signToken(challenge, options.secret);
+    return { challenge, challengeToken };
+}
+// ---------------------------------------------------------------------------
+// Server-side: solution verification
+// ---------------------------------------------------------------------------
+/**
+ * Verify a captcha solution against a signed challenge token.
+ *
+ * @param challengeToken  HMAC-signed token from createCaptchaChallenge
+ * @param solution        The agent's solution (text + timestamp)
+ * @param secret          HMAC secret used to sign the token
+ * @param options         Verification options (timing, tolerance, replay protection, redaction)
+ * @returns               Verification result, or `null` if the token is invalid/replayed
+ */
+export async function verifyCaptchaSolution(challengeToken, solution, secret, options) {
+    const payload = verifyToken(challengeToken, secret);
+    if (!payload)
+        return null;
+    // One-time use: consume the challenge token if a store is provided
+    if (options?.consumeChallenge) {
+        const consumed = await options.consumeChallenge(challengeToken);
+        if (!consumed)
+            return null; // replay rejected
+    }
+    const challenge = payload;
+    const lines = solution.text.split('\n').filter(l => l.length > 0);
+    const flatText = lines.join('');
+    const reveal = options?.revealConstraints ?? true;
+    const asciiTolerance = options?.asciiTolerance ?? 0;
+    // 1. ASCII sum of first characters
+    const firstChars = lines.map(l => l.charCodeAt(0));
+    const actualAsciiSum = firstChars.reduce((sum, c) => sum + c, 0);
+    const asciiPass = Math.abs(actualAsciiSum - challenge.asciiTarget) <= asciiTolerance;
+    const result = {
+        asciiSum: {
+            pass: asciiPass,
+            actual: reveal ? actualAsciiSum : 0,
+            target: reveal ? challenge.asciiTarget : 0,
+        },
+        timing: { pass: false, elapsedSeconds: 0 },
+        overallPass: false,
+        verdict: 'CHALLENGE_FAILED',
+    };
+    // 2. Line count check
+    const lineCountPass = lines.length === challenge.lineCount;
+    result.lineCount = {
+        pass: lineCountPass,
+        actual: reveal ? lines.length : 0,
+        target: reveal ? challenge.lineCount : 0,
+    };
+    // 3. Word count
+    let wordCountPass = true;
+    if (challenge.wordCount !== undefined) {
+        const words = solution.text.split(/\s+/).filter(w => w.length > 0);
+        const actualWordCount = words.length;
+        wordCountPass = actualWordCount === challenge.wordCount;
+        result.wordCount = {
+            pass: wordCountPass,
+            actual: reveal ? actualWordCount : 0,
+            target: reveal ? challenge.wordCount : 0,
+        };
+    }
+    // 4. Character at position
+    let charPositionPass = true;
+    if (challenge.charPosition) {
+        const [pos, expectedChar] = challenge.charPosition;
+        const actualChar = flatText[pos] ?? '';
+        charPositionPass = actualChar === expectedChar;
+        result.charPosition = { pass: charPositionPass };
+    }
+    // 5. Total chars (excluding newlines)
+    let totalCharsPass = true;
+    if (challenge.totalChars !== undefined) {
+        const actualTotalChars = flatText.length;
+        totalCharsPass = actualTotalChars === challenge.totalChars;
+        result.totalChars = {
+            pass: totalCharsPass,
+            actual: reveal ? actualTotalChars : 0,
+            target: reveal ? challenge.totalChars : 0,
+        };
+    }
+    // 6. Timing — use server wall-clock by default, fall back to client solvedAt
+    const useServerTiming = options?.useServerTiming ?? true;
+    const toleranceSeconds = options?.timingToleranceSeconds ?? 2;
+    const elapsedMs = useServerTiming
+        ? (Date.now() - challenge.createdAt)
+        : (solution.solvedAt - challenge.createdAt);
+    const elapsedSeconds = elapsedMs / 1000;
+    const timingPass = elapsedSeconds >= 0 && elapsedSeconds <= (challenge.timeLimitSeconds + toleranceSeconds);
+    result.timing = { pass: timingPass, elapsedSeconds };
+    // Overall
+    result.overallPass = asciiPass && lineCountPass && wordCountPass && charPositionPass && totalCharsPass && timingPass;
+    result.verdict = result.overallPass ? 'VERIFIED_AI_AGENT' : 'CHALLENGE_FAILED';
+    return result;
+}
+// ---------------------------------------------------------------------------
+// Agent-side: sign-in captcha helper
+// ---------------------------------------------------------------------------
+/**
+ * Detect and solve a captcha challenge from a nonce response.
+ *
+ * When a server's nonce endpoint returns `{ status: 'captcha_required' }`,
+ * this helper calls the solver, packs the response, and returns a
+ * `challengeResponse` string for the agent to include in the retry request.
+ *
+ * @param nonceResponse  The parsed JSON body from the nonce endpoint
+ * @param solver         Callback that generates solution text from a challenge
+ * @returns `{ solved: true, challengeResponse }` if captcha was solved,
+ *          `{ solved: false }` if no captcha was required
+ *
+ * @example
+ * ```typescript
+ * import { solveCaptchaChallenge } from '@buildersgarden/siwa/captcha';
+ *
+ * const res = await fetch('/siwa/nonce', { method: 'POST', body: JSON.stringify(params) });
+ * const nonceResult = await res.json();
+ *
+ * const captcha = await solveCaptchaChallenge(nonceResult, async (challenge) => {
+ *   // LLM generates text satisfying all constraints
+ *   return await generateText(challenge); // your LLM solver
+ * });
+ *
+ * if (captcha.solved) {
+ *   // Retry with challenge response
+ *   const retry = await fetch('/siwa/nonce', {
+ *     method: 'POST',
+ *     body: JSON.stringify({ ...params, challengeResponse: captcha.challengeResponse }),
+ *   });
+ * }
+ * ```
+ */
+export async function solveCaptchaChallenge(nonceResponse, solver) {
+    if (nonceResponse.status !== 'captcha_required' ||
+        !nonceResponse.challenge ||
+        !nonceResponse.challengeToken) {
+        return { solved: false };
+    }
+    const text = await solver(nonceResponse.challenge);
+    const challengeResponse = packCaptchaResponse(nonceResponse.challengeToken, text);
+    return { solved: true, challengeResponse };
+}
+// ---------------------------------------------------------------------------
+// Agent-side: pack / unpack response
+// ---------------------------------------------------------------------------
+/**
+ * Package a captcha solution for submission (agent-side).
+ *
+ * @param challengeToken  The challenge token received from the server
+ * @param text            The agent's solution text
+ * @returns               A packed string to send in the challenge response header/field
+ */
+export function packCaptchaResponse(challengeToken, text) {
+    const solution = {
+        text,
+        solvedAt: Date.now(),
+    };
+    const payload = Buffer.from(JSON.stringify({ challengeToken, solution })).toString('base64url');
+    return payload;
+}
+/**
+ * Unpack a captcha response (server-side).
+ *
+ * @param packed  The base64url-encoded response from the agent
+ * @returns       The challenge token and solution, or `null` if malformed
+ */
+export function unpackCaptchaResponse(packed) {
+    try {
+        const decoded = JSON.parse(Buffer.from(packed, 'base64url').toString());
+        if (!decoded.challengeToken || !decoded.solution?.text || typeof decoded.solution?.solvedAt !== 'number') {
+            return null;
+        }
+        return { challengeToken: decoded.challengeToken, solution: decoded.solution };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/erc8128.d.ts

@@ -12,6 +12,7 @@
 import type { Address, PublicClient } from 'viem';
 import { type EthHttpSigner, type NonceStore } from '@slicekit/erc8128';
 import type { Signer, SignerType } from './signer/index.js';
+import { type CaptchaChallenge, type CaptchaPolicy, type CaptchaOptions, type CaptchaSolver } from './captcha.js';
 export interface VerifyOptions {
     receiptSecret: string;
     rpcUrl?: string;
@@ -19,6 +20,8 @@ export interface VerifyOptions {
     publicClient?: PublicClient;
     nonceStore?: NonceStore;
     allowedSignerTypes?: SignerType[];
+    captchaPolicy?: CaptchaPolicy;
+    captchaOptions?: CaptchaOptions;
 }
 /** Verified agent identity returned from a successful auth check. */
 export interface SiwaAgent {
@@ -34,6 +37,12 @@ export type AuthResult = {
 } | {
     valid: false;
     error: string;
+} | {
+    valid: false;
+    error: string;
+    captchaRequired: true;
+    challenge: CaptchaChallenge;
+    challengeToken: string;
 };
 /**
  * Resolve the receipt secret from an explicit value or environment variables.
@@ -98,6 +107,65 @@ export declare function attachReceipt(request: Request, receipt: string): Reques
 export declare function signAuthenticatedRequest(request: Request, receipt: string, signer: Signer, chainId: number, options?: {
     signerAddress?: Address;
 }): Promise<Request>;
+/**
+ * Detect a captcha challenge in a server response and build a re-signed retry request.
+ *
+ * When a server returns 401 with `{ captchaRequired: true, challenge, challengeToken }`,
+ * this function:
+ *   1. Extracts the challenge from the response body
+ *   2. Calls the solver to generate solution text
+ *   3. Packs the solution into the `X-SIWA-Challenge-Response` header
+ *   4. Re-signs the request with ERC-8128 (binding the challenge response into the signature)
+ *   5. Returns the new signed request ready for retry
+ *
+ * **Important:** The `request` parameter must be a fresh, unconsumed Request
+ * (not the one already sent via `fetch`). Keep the original URL, method, headers,
+ * and body around so you can reconstruct it for the retry.
+ *
+ * @param response  The server's 401 response (body is read via `.clone()`, so the original stays readable)
+ * @param request   A fresh, unconsumed Request matching the original call
+ * @param receipt   Verification receipt from SIWA sign-in
+ * @param signer    A SIWA Signer
+ * @param chainId   Chain ID for the ERC-8128 keyid
+ * @param solver    Callback that generates solution text from a challenge
+ * @param options   Optional overrides (e.g. signerAddress for TBA identity)
+ * @returns `{ retry: true, request }` with the signed retry request, or `{ retry: false }` if no captcha
+ *
+ * @example
+ * ```typescript
+ * import { signAuthenticatedRequest, retryWithCaptcha } from '@buildersgarden/siwa/erc8128';
+ *
+ * const url = 'https://api.example.com/action';
+ * const body = JSON.stringify({ key: 'value' });
+ *
+ * // First attempt
+ * const signed = await signAuthenticatedRequest(
+ *   new Request(url, { method: 'POST', body }),
+ *   receipt, signer, 84532,
+ * );
+ * const response = await fetch(signed);
+ *
+ * // Handle captcha if required
+ * const result = await retryWithCaptcha(
+ *   response,
+ *   new Request(url, { method: 'POST', body }), // fresh request
+ *   receipt, signer, 84532,
+ *   async (challenge) => generateText(challenge), // your LLM solver
+ * );
+ *
+ * if (result.retry) {
+ *   const retryResponse = await fetch(result.request);
+ * }
+ * ```
+ */
+export declare function retryWithCaptcha(response: Response, request: Request, receipt: string, signer: Signer, chainId: number, solver: CaptchaSolver, options?: {
+    signerAddress?: Address;
+}): Promise<{
+    retry: true;
+    request: Request;
+} | {
+    retry: false;
+}>;
 /**
  * Verify an authenticated request: ERC-8128 signature + receipt + optional onchain check.
  *

package/dist/erc8128.js

@@ -11,6 +11,7 @@
  */
 import { signRequest, verifyRequest, } from '@slicekit/erc8128';
 import { verifyReceipt } from './receipt.js';
+import { createCaptchaChallenge, unpackCaptchaResponse, verifyCaptchaSolution, packCaptchaResponse, CHALLENGE_RESPONSE_HEADER, } from './captcha.js';
 /**
  * Resolve the receipt secret from an explicit value or environment variables.
  *
@@ -111,6 +112,90 @@ export async function signAuthenticatedRequest(request, receipt, signer, chainId
     });
 }
 // ---------------------------------------------------------------------------
+// Agent-side: captcha retry helper
+// ---------------------------------------------------------------------------
+/**
+ * Detect a captcha challenge in a server response and build a re-signed retry request.
+ *
+ * When a server returns 401 with `{ captchaRequired: true, challenge, challengeToken }`,
+ * this function:
+ *   1. Extracts the challenge from the response body
+ *   2. Calls the solver to generate solution text
+ *   3. Packs the solution into the `X-SIWA-Challenge-Response` header
+ *   4. Re-signs the request with ERC-8128 (binding the challenge response into the signature)
+ *   5. Returns the new signed request ready for retry
+ *
+ * **Important:** The `request` parameter must be a fresh, unconsumed Request
+ * (not the one already sent via `fetch`). Keep the original URL, method, headers,
+ * and body around so you can reconstruct it for the retry.
+ *
+ * @param response  The server's 401 response (body is read via `.clone()`, so the original stays readable)
+ * @param request   A fresh, unconsumed Request matching the original call
+ * @param receipt   Verification receipt from SIWA sign-in
+ * @param signer    A SIWA Signer
+ * @param chainId   Chain ID for the ERC-8128 keyid
+ * @param solver    Callback that generates solution text from a challenge
+ * @param options   Optional overrides (e.g. signerAddress for TBA identity)
+ * @returns `{ retry: true, request }` with the signed retry request, or `{ retry: false }` if no captcha
+ *
+ * @example
+ * ```typescript
+ * import { signAuthenticatedRequest, retryWithCaptcha } from '@buildersgarden/siwa/erc8128';
+ *
+ * const url = 'https://api.example.com/action';
+ * const body = JSON.stringify({ key: 'value' });
+ *
+ * // First attempt
+ * const signed = await signAuthenticatedRequest(
+ *   new Request(url, { method: 'POST', body }),
+ *   receipt, signer, 84532,
+ * );
+ * const response = await fetch(signed);
+ *
+ * // Handle captcha if required
+ * const result = await retryWithCaptcha(
+ *   response,
+ *   new Request(url, { method: 'POST', body }), // fresh request
+ *   receipt, signer, 84532,
+ *   async (challenge) => generateText(challenge), // your LLM solver
+ * );
+ *
+ * if (result.retry) {
+ *   const retryResponse = await fetch(result.request);
+ * }
+ * ```
+ */
+export async function retryWithCaptcha(response, request, receipt, signer, chainId, solver, options) {
+    // Only handle 401 responses
+    if (response.status !== 401)
+        return { retry: false };
+    // Read from a clone so the original response stays readable for the caller
+    let body;
+    try {
+        body = await response.clone().json();
+    }
+    catch {
+        return { retry: false };
+    }
+    if (!body.captchaRequired || !body.challenge || !body.challengeToken) {
+        return { retry: false };
+    }
+    // Solve the challenge
+    const text = await solver(body.challenge);
+    const packed = packCaptchaResponse(body.challengeToken, text);
+    // Rebuild the request with receipt + challenge response headers
+    const headers = new Headers(request.headers);
+    headers.set(RECEIPT_HEADER, receipt);
+    headers.set(CHALLENGE_RESPONSE_HEADER, packed);
+    const rebuiltRequest = new Request(request, { headers });
+    // Create ERC-8128 signer and sign with both headers bound into the signature
+    const erc8128Signer = await createErc8128Signer(signer, chainId, options);
+    const signedRequest = await signRequest(rebuiltRequest, erc8128Signer, {
+        components: [RECEIPT_HEADER, CHALLENGE_RESPONSE_HEADER],
+    });
+    return { retry: true, request: signedRequest };
+}
+// ---------------------------------------------------------------------------
 // Server-side: high-level request verification
 // ---------------------------------------------------------------------------
 /**
@@ -226,6 +311,48 @@ export async function verifyAuthenticatedRequest(request, options) {
             return { valid: false, error: 'Onchain ownership check failed: agent not registered' };
         }
     }
+    // 5. Captcha evaluation (after successful auth, server-defined policy)
+    if (options.captchaPolicy) {
+        const captchaSecret = options.captchaOptions?.secret ?? options.receiptSecret;
+        const difficulty = await options.captchaPolicy({
+            address: receipt.address,
+            agentId: receipt.agentId,
+            agentRegistry: receipt.agentRegistry,
+            request,
+        });
+        if (difficulty) {
+            const responseHeader = request.headers.get(CHALLENGE_RESPONSE_HEADER);
+            if (responseHeader) {
+                // Agent submitted a challenge response — verify it
+                const unpacked = unpackCaptchaResponse(responseHeader);
+                if (!unpacked) {
+                    return { valid: false, error: 'Invalid captcha response format' };
+                }
+                const verification = await verifyCaptchaSolution(unpacked.challengeToken, unpacked.solution, captchaSecret, options.captchaOptions?.verify);
+                if (!verification || !verification.overallPass) {
+                    return { valid: false, error: `Captcha verification failed: ${verification?.verdict ?? 'invalid token'}` };
+                }
+                // Captcha passed — fall through to return success
+            }
+            else {
+                // No challenge response — issue a new challenge
+                const captchaOpts = {
+                    secret: captchaSecret,
+                    topics: options.captchaOptions?.topics,
+                    formats: options.captchaOptions?.formats,
+                    difficulties: options.captchaOptions?.difficulties,
+                };
+                const { challenge, challengeToken } = createCaptchaChallenge(difficulty, captchaOpts);
+                return {
+                    valid: false,
+                    error: 'Captcha required',
+                    captchaRequired: true,
+                    challenge,
+                    challengeToken,
+                };
+            }
+        }
+    }
     return {
         valid: true,
         agent: {

package/dist/index.d.ts

@@ -9,5 +9,6 @@ export * from './receipt.js';
 export * from './erc8128.js';
 export * from './nonce-store.js';
 export * from './tba.js';
+export * from './captcha.js';
 export * from './x402.js';
 export * from './client-resolver.js';

package/dist/index.js

@@ -9,5 +9,6 @@ export * from './receipt.js';
 export * from './erc8128.js';
 export * from './nonce-store.js';
 export * from './tba.js';
+export * from './captcha.js';
 export * from './x402.js';
 export * from './client-resolver.js';

package/dist/server-side-wrappers/express.d.ts

@@ -16,6 +16,7 @@
  */
 import type { RequestHandler } from 'express';
 import { type SiwaAgent, type VerifyOptions } from '../erc8128.js';
+import { type CaptchaPolicy, type CaptchaOptions } from '../captcha.js';
 import type { SignerType } from '../signer/index.js';
 import { type X402Config, type X402Payment } from '../x402.js';
 export type { SiwaAgent };
@@ -39,6 +40,10 @@ export interface SiwaMiddlewareOptions {
     publicClient?: VerifyOptions['publicClient'];
     /** Allowed signer types. Omit to accept all. */
     allowedSignerTypes?: SignerType[];
+    /** Captcha policy for per-request challenges. */
+    captchaPolicy?: CaptchaPolicy;
+    /** Captcha options (secret, topics, formats). Secret defaults to receiptSecret. */
+    captchaOptions?: CaptchaOptions;
     /** Optional x402 payment gate. When set, both SIWA auth AND a valid payment are required. */
     x402?: X402Config;
 }
@@ -77,3 +82,35 @@ export declare function siwaJsonParser(): RequestHandler;
  *   - Both succeed → `req.agent` + `req.payment` → `next()`
  */
 export declare function siwaMiddleware(options?: SiwaMiddlewareOptions): RequestHandler;
+/**
+ * Create a pre-configured `siwaMiddleware` with shared defaults.
+ *
+ * Use this to apply the same captcha policy and options globally,
+ * with optional per-route overrides.
+ *
+ * @param defaults  Shared options applied to all routes
+ * @returns         A `siwaMiddleware`-like function that bakes in the defaults
+ *
+ * @example
+ * ```typescript
+ * import { createSiwaMiddleware, siwaJsonParser, siwaCors } from "@buildersgarden/siwa/express";
+ *
+ * const auth = createSiwaMiddleware({
+ *   captchaPolicy: async ({ address }) => {
+ *     const known = await db.agents.exists(address);
+ *     return known ? null : 'medium';
+ *   },
+ *   captchaOptions: { secret: process.env.SIWA_SECRET! },
+ * });
+ *
+ * app.use(siwaJsonParser());
+ * app.use(siwaCors());
+ *
+ * // Apply globally
+ * app.use(auth());
+ *
+ * // Or per-route with overrides
+ * app.post('/api/transfer', auth({ captchaPolicy: () => 'hard' }), handler);
+ * ```
+ */
+export declare function createSiwaMiddleware(defaults: SiwaMiddlewareOptions): (overrides?: Partial<SiwaMiddlewareOptions>) => RequestHandler;

package/dist/server-side-wrappers/express.js

@@ -16,11 +16,12 @@
  */
 import express from 'express';
 import { verifyAuthenticatedRequest, expressToFetchRequest, resolveReceiptSecret, } from '../erc8128.js';
+import { CHALLENGE_HEADER } from '../captcha.js';
 import { X402_HEADERS, encodeX402Header, decodeX402Header, processX402Payment, } from '../x402.js';
 // ---------------------------------------------------------------------------
 // CORS middleware
 // ---------------------------------------------------------------------------
-const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest';
+const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, X-SIWA-Challenge-Response, Signature, Signature-Input, Content-Digest';
 const X402_CORS_HEADERS = `${X402_HEADERS.PAYMENT_SIGNATURE}, ${X402_HEADERS.PAYMENT_REQUIRED}`;
 const X402_EXPOSE_HEADERS = `${X402_HEADERS.PAYMENT_REQUIRED}, ${X402_HEADERS.PAYMENT_RESPONSE}`;
 /**
@@ -36,13 +37,14 @@ export function siwaCors(options) {
     if (options?.x402) {
         headers = `${headers}, ${X402_CORS_HEADERS}`;
     }
+    const exposeHeaders = options?.x402
+        ? `X-SIWA-Challenge, ${X402_EXPOSE_HEADERS}`
+        : 'X-SIWA-Challenge';
     return (req, res, next) => {
         res.header('Access-Control-Allow-Origin', origin);
         res.header('Access-Control-Allow-Methods', methods);
         res.header('Access-Control-Allow-Headers', headers);
-        if (options?.x402) {
-            res.header('Access-Control-Expose-Headers', X402_EXPOSE_HEADERS);
-        }
+        res.header('Access-Control-Expose-Headers', exposeHeaders);
         if (req.method === 'OPTIONS') {
             res.sendStatus(204);
             return;
@@ -100,8 +102,20 @@ export function siwaMiddleware(options) {
                 verifyOnchain: options?.verifyOnchain,
                 publicClient: options?.publicClient,
                 allowedSignerTypes: options?.allowedSignerTypes,
+                captchaPolicy: options?.captchaPolicy,
+                captchaOptions: options?.captchaOptions,
             });
             if (!result.valid) {
+                if ('captchaRequired' in result && result.captchaRequired) {
+                    res.header(CHALLENGE_HEADER, result.challengeToken);
+                    res.status(401).json({
+                        error: result.error,
+                        challenge: result.challenge,
+                        challengeToken: result.challengeToken,
+                        captchaRequired: true,
+                    });
+                    return;
+                }
                 res.status(401).json({ error: result.error });
                 return;
             }
@@ -167,3 +181,40 @@ export function siwaMiddleware(options) {
         next();
     };
 }
+// ---------------------------------------------------------------------------
+// Factory: pre-configured middleware
+// ---------------------------------------------------------------------------
+/**
+ * Create a pre-configured `siwaMiddleware` with shared defaults.
+ *
+ * Use this to apply the same captcha policy and options globally,
+ * with optional per-route overrides.
+ *
+ * @param defaults  Shared options applied to all routes
+ * @returns         A `siwaMiddleware`-like function that bakes in the defaults
+ *
+ * @example
+ * ```typescript
+ * import { createSiwaMiddleware, siwaJsonParser, siwaCors } from "@buildersgarden/siwa/express";
+ *
+ * const auth = createSiwaMiddleware({
+ *   captchaPolicy: async ({ address }) => {
+ *     const known = await db.agents.exists(address);
+ *     return known ? null : 'medium';
+ *   },
+ *   captchaOptions: { secret: process.env.SIWA_SECRET! },
+ * });
+ *
+ * app.use(siwaJsonParser());
+ * app.use(siwaCors());
+ *
+ * // Apply globally
+ * app.use(auth());
+ *
+ * // Or per-route with overrides
+ * app.post('/api/transfer', auth({ captchaPolicy: () => 'hard' }), handler);
+ * ```
+ */
+export function createSiwaMiddleware(defaults) {
+    return (overrides) => siwaMiddleware({ ...defaults, ...overrides });
+}

package/dist/server-side-wrappers/next.d.ts

@@ -17,6 +17,7 @@
  * ```
  */
 import { type SiwaAgent } from '../erc8128.js';
+import { type CaptchaPolicy, type CaptchaOptions } from '../captcha.js';
 import type { SignerType } from '../signer/index.js';
 import { type X402Config, type X402Payment } from '../x402.js';
 export type { SiwaAgent, X402Payment };
@@ -29,6 +30,10 @@ export interface WithSiwaOptions {
     verifyOnchain?: boolean;
     /** Allowed signer types. Omit to accept all. */
     allowedSignerTypes?: SignerType[];
+    /** Captcha policy for per-request challenges. */
+    captchaPolicy?: CaptchaPolicy;
+    /** Captcha options (secret, topics, formats). Secret defaults to receiptSecret. */
+    captchaOptions?: CaptchaOptions;
     /** Optional x402 payment gate. When set, both SIWA auth AND a valid payment are required. */
     x402?: X402Config;
 }

package/dist/server-side-wrappers/next.js

@@ -17,11 +17,12 @@
  * ```
  */
 import { verifyAuthenticatedRequest, nextjsToFetchRequest, resolveReceiptSecret, } from '../erc8128.js';
+import { CHALLENGE_HEADER } from '../captcha.js';
 import { X402_HEADERS, encodeX402Header, decodeX402Header, processX402Payment, } from '../x402.js';
 // ---------------------------------------------------------------------------
 // CORS helpers
 // ---------------------------------------------------------------------------
-const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, Signature, Signature-Input, Content-Digest';
+const DEFAULT_SIWA_HEADERS = 'Content-Type, X-SIWA-Receipt, X-SIWA-Challenge-Response, Signature, Signature-Input, Content-Digest';
 const X402_CORS_HEADERS = `${X402_HEADERS.PAYMENT_SIGNATURE}, ${X402_HEADERS.PAYMENT_REQUIRED}`;
 const X402_EXPOSE_HEADERS = `${X402_HEADERS.PAYMENT_REQUIRED}, ${X402_HEADERS.PAYMENT_RESPONSE}`;
 /** CORS headers required by SIWA-authenticated requests. */
@@ -76,9 +77,21 @@ export function withSiwa(handler, options) {
             rpcUrl: options?.rpcUrl,
             verifyOnchain: options?.verifyOnchain,
             allowedSignerTypes: options?.allowedSignerTypes,
+            captchaPolicy: options?.captchaPolicy,
+            captchaOptions: options?.captchaOptions,
         };
         const result = await verifyAuthenticatedRequest(nextjsToFetchRequest(verifyReq), verifyOptions);
         if (!result.valid) {
+            if ('captchaRequired' in result && result.captchaRequired) {
+                const response = corsJson({
+                    error: result.error,
+                    challenge: result.challenge,
+                    challengeToken: result.challengeToken,
+                    captchaRequired: true,
+                }, { status: 401 }, corsOpts);
+                response.headers.set(CHALLENGE_HEADER, result.challengeToken);
+                return response;
+            }
             return corsJson({ error: result.error }, { status: 401 }, corsOpts);
         }
         // -----------------------------------------------------------------

package/dist/siwa.d.ts

@@ -11,6 +11,7 @@ import { type PublicClient } from 'viem';
 import { AgentProfile, ServiceType, TrustModel } from './registry.js';
 import type { Signer, SignerType } from './signer/index.js';
 import type { SIWANonceStore } from './nonce-store.js';
+import { type CaptchaChallenge, type CaptchaPolicy, type CaptchaOptions } from './captcha.js';
 export declare enum SIWAErrorCode {
     INVALID_SIGNATURE = "INVALID_SIGNATURE",
     DOMAIN_MISMATCH = "DOMAIN_MISMATCH",
@@ -25,7 +26,9 @@ export declare enum SIWAErrorCode {
     MISSING_TRUST_MODEL = "MISSING_TRUST_MODEL",
     LOW_REPUTATION = "LOW_REPUTATION",
     CUSTOM_CHECK_FAILED = "CUSTOM_CHECK_FAILED",
-    VERIFICATION_FAILED = "VERIFICATION_FAILED"
+    VERIFICATION_FAILED = "VERIFICATION_FAILED",
+    CAPTCHA_REQUIRED = "CAPTCHA_REQUIRED",
+    CAPTCHA_FAILED = "CAPTCHA_FAILED"
 }
 export interface SIWAMessageFields {
     domain: string;
@@ -114,11 +117,14 @@ export interface SIWANonceParams {
     address: string;
     agentId: number;
     agentRegistry: string;
+    challengeResponse?: string;
 }
 export interface SIWANonceOptions {
     expirationTTL?: number;
     secret?: string;
     nonceStore?: SIWANonceStore;
+    captchaPolicy?: CaptchaPolicy;
+    captchaOptions?: CaptchaOptions;
 }
 export type SIWANonceResult = {
     status: 'nonce_issued';
@@ -126,6 +132,10 @@ export type SIWANonceResult = {
     nonceToken?: string;
     issuedAt: string;
     expirationTime: string;
+} | {
+    status: 'captcha_required';
+    challenge: CaptchaChallenge;
+    challengeToken: string;
 } | SIWAResponse;
 /**
  * Validate agent registration and create a SIWA nonce.

package/dist/siwa.js

@@ -9,6 +9,7 @@
  */
 import * as crypto from 'crypto';
 import { getAgent, getReputation } from './registry.js';
+import { createCaptchaChallenge, unpackCaptchaResponse, verifyCaptchaSolution, } from './captcha.js';
 // ─── Types ───────────────────────────────────────────────────────────
 export var SIWAErrorCode;
 (function (SIWAErrorCode) {
@@ -26,6 +27,8 @@ export var SIWAErrorCode;
     SIWAErrorCode["LOW_REPUTATION"] = "LOW_REPUTATION";
     SIWAErrorCode["CUSTOM_CHECK_FAILED"] = "CUSTOM_CHECK_FAILED";
     SIWAErrorCode["VERIFICATION_FAILED"] = "VERIFICATION_FAILED";
+    SIWAErrorCode["CAPTCHA_REQUIRED"] = "CAPTCHA_REQUIRED";
+    SIWAErrorCode["CAPTCHA_FAILED"] = "CAPTCHA_FAILED";
 })(SIWAErrorCode || (SIWAErrorCode = {}));
 /**
  * Convert a SIWAVerificationResult into a standard SIWAResponse
@@ -268,6 +271,57 @@ export async function createSIWANonce(params, client, options) {
             error: 'Signer is not the owner of this agent NFT',
         });
     }
+    // Captcha evaluation (after ownership check, before nonce issuance)
+    if (options?.captchaPolicy) {
+        const captchaSecret = options.captchaOptions?.secret ?? options.secret;
+        if (!captchaSecret) {
+            throw new Error('captchaPolicy requires a secret — set captchaOptions.secret or options.secret');
+        }
+        const difficulty = await options.captchaPolicy({ address, agentId, agentRegistry });
+        if (difficulty) {
+            // Check if the agent submitted a challenge response
+            if (params.challengeResponse) {
+                const unpacked = unpackCaptchaResponse(params.challengeResponse);
+                if (!unpacked) {
+                    return buildSIWAResponse({
+                        valid: false,
+                        address,
+                        agentId,
+                        agentRegistry,
+                        chainId,
+                        verified: 'onchain',
+                        code: SIWAErrorCode.CAPTCHA_FAILED,
+                        error: 'Invalid captcha response format',
+                    });
+                }
+                const verification = await verifyCaptchaSolution(unpacked.challengeToken, unpacked.solution, captchaSecret, options.captchaOptions?.verify);
+                if (!verification || !verification.overallPass) {
+                    return buildSIWAResponse({
+                        valid: false,
+                        address,
+                        agentId,
+                        agentRegistry,
+                        chainId,
+                        verified: 'onchain',
+                        code: SIWAErrorCode.CAPTCHA_FAILED,
+                        error: `Captcha verification failed: ${verification?.verdict ?? 'invalid token'}`,
+                    });
+                }
+                // Captcha passed — fall through to issue nonce
+            }
+            else {
+                // No response yet — issue a challenge
+                const captchaOpts = {
+                    secret: captchaSecret,
+                    topics: options.captchaOptions?.topics,
+                    formats: options.captchaOptions?.formats,
+                    difficulties: options.captchaOptions?.difficulties,
+                };
+                const { challenge, challengeToken } = createCaptchaChallenge(difficulty, captchaOpts);
+                return { status: 'captcha_required', challenge, challengeToken };
+            }
+        }
+    }
     // Agent is registered — issue the nonce
     const now = new Date();
     const expiresAt = new Date(now.getTime() + ttl);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildersgarden/siwa",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "type": "module",
   "exports": {
     ".": {
@@ -67,6 +67,10 @@
       "types": "./dist/tba.d.ts",
       "default": "./dist/tba.js"
     },
+    "./captcha": {
+      "types": "./dist/captcha.d.ts",
+      "default": "./dist/captcha.js"
+    },
     "./x402": {
       "types": "./dist/x402.d.ts",
       "default": "./dist/x402.js"