@bankofai/x402-extensions 1.0.0-beta.0

package/dist/esm/sign-in-with-x/index.d.mts

@@ -0,0 +1,1117 @@
+import { z } from 'zod';
+import { ResourceServerExtension } from '@bankofai/x402-core/types';
+import { ClientExtension } from '@bankofai/x402-core/client';
+
+/**
+ * Type definitions for the Sign-In-With-X (SIWX) extension
+ *
+ * Implements CAIP-122 standard for chain-agnostic wallet-based identity assertions.
+ * Per x402 v2 spec: typescript/site/CHANGELOG-v2.md lines 237-341
+ */
+
+/**
+ * Extension identifier constant
+ */
+declare const SIGN_IN_WITH_X = "sign-in-with-x";
+/**
+ * Supported signature schemes per CHANGELOG-v2.md line 271.
+ *
+ * NOTE: This is primarily informational. Actual signature verification
+ * is determined by the chainId prefix, not this field:
+ * - `eip155:*` chains use EVM verification (handles eip191, eip712, eip1271, eip6492 automatically)
+ * - `solana:*` chains use Ed25519 verification (siws)
+ *
+ * The signatureScheme field serves as a hint for clients to select
+ * the appropriate signing UX.
+ */
+type SignatureScheme = "eip191" | "eip1271" | "eip6492" | "siws";
+/** Signature algorithm type per CAIP-122 */
+type SignatureType = "eip191" | "ed25519";
+/**
+ * Supported chain configuration in supportedChains array.
+ * Specifies which chains the server accepts for authentication.
+ */
+interface SupportedChain {
+    /** CAIP-2 chain identifier (e.g., "eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp") */
+    chainId: string;
+    /** Signature algorithm type per CAIP-122 */
+    type: SignatureType;
+    /** Optional signature scheme hint (informational) */
+    signatureScheme?: SignatureScheme;
+}
+/**
+ * Server-declared extension info included in PaymentRequired.extensions.
+ * Contains message metadata shared across all supported chains.
+ * Per CHANGELOG-v2.md lines 263-272
+ */
+interface SIWxExtensionInfo {
+    /** Server's domain */
+    domain: string;
+    /** Full resource URI */
+    uri: string;
+    /** Human-readable purpose for signing */
+    statement?: string;
+    /** CAIP-122 version, always "1" */
+    version: string;
+    /** Cryptographic nonce (SDK auto-generates) */
+    nonce: string;
+    /** ISO 8601 timestamp (SDK auto-generates) */
+    issuedAt: string;
+    /** Optional expiry (default: +5 min) */
+    expirationTime?: string;
+    /** Optional validity start */
+    notBefore?: string;
+    /** Optional correlation ID */
+    requestId?: string;
+    /** Associated resources */
+    resources?: string[];
+}
+/**
+ * JSON Schema for SIWX extension validation
+ * Per CHANGELOG-v2.md lines 276-292
+ */
+interface SIWxExtensionSchema {
+    $schema: string;
+    type: "object";
+    properties: {
+        domain: {
+            type: "string";
+        };
+        address: {
+            type: "string";
+        };
+        statement?: {
+            type: "string";
+        };
+        uri: {
+            type: "string";
+            format: "uri";
+        };
+        version: {
+            type: "string";
+        };
+        chainId: {
+            type: "string";
+        };
+        type: {
+            type: "string";
+        };
+        nonce: {
+            type: "string";
+        };
+        issuedAt: {
+            type: "string";
+            format: "date-time";
+        };
+        expirationTime?: {
+            type: "string";
+            format: "date-time";
+        };
+        notBefore?: {
+            type: "string";
+            format: "date-time";
+        };
+        requestId?: {
+            type: "string";
+        };
+        resources?: {
+            type: "array";
+            items: {
+                type: "string";
+                format: "uri";
+            };
+        };
+        signature: {
+            type: "string";
+        };
+    };
+    required: string[];
+}
+/**
+ * Complete SIWX extension structure (info + supportedChains + schema).
+ * Follows standard x402 v2 extension pattern with multi-chain support.
+ */
+interface SIWxExtension {
+    info: SIWxExtensionInfo;
+    supportedChains: SupportedChain[];
+    schema: SIWxExtensionSchema;
+}
+/**
+ * Zod schema for SIWX payload validation
+ * Client proof payload sent in SIGN-IN-WITH-X header
+ * Per CHANGELOG-v2.md lines 301-315
+ */
+declare const SIWxPayloadSchema: z.ZodObject<{
+    domain: z.ZodString;
+    address: z.ZodString;
+    statement: z.ZodOptional<z.ZodString>;
+    uri: z.ZodString;
+    version: z.ZodString;
+    chainId: z.ZodString;
+    type: z.ZodEnum<["eip191", "ed25519"]>;
+    nonce: z.ZodString;
+    issuedAt: z.ZodString;
+    expirationTime: z.ZodOptional<z.ZodString>;
+    notBefore: z.ZodOptional<z.ZodString>;
+    requestId: z.ZodOptional<z.ZodString>;
+    resources: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    signatureScheme: z.ZodOptional<z.ZodEnum<["eip191", "eip1271", "eip6492", "siws"]>>;
+    signature: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "eip191" | "ed25519";
+    uri: string;
+    domain: string;
+    address: string;
+    version: string;
+    chainId: string;
+    nonce: string;
+    issuedAt: string;
+    signature: string;
+    statement?: string | undefined;
+    expirationTime?: string | undefined;
+    notBefore?: string | undefined;
+    requestId?: string | undefined;
+    resources?: string[] | undefined;
+    signatureScheme?: "eip191" | "eip1271" | "eip6492" | "siws" | undefined;
+}, {
+    type: "eip191" | "ed25519";
+    uri: string;
+    domain: string;
+    address: string;
+    version: string;
+    chainId: string;
+    nonce: string;
+    issuedAt: string;
+    signature: string;
+    statement?: string | undefined;
+    expirationTime?: string | undefined;
+    notBefore?: string | undefined;
+    requestId?: string | undefined;
+    resources?: string[] | undefined;
+    signatureScheme?: "eip191" | "eip1271" | "eip6492" | "siws" | undefined;
+}>;
+/**
+ * Client proof payload type (inferred from zod schema)
+ */
+type SIWxPayload = z.infer<typeof SIWxPayloadSchema>;
+/**
+ * Options for declaring SIWX extension on server.
+ *
+ * Most fields are optional and derived automatically from request context:
+ * - `domain`: Parsed from resourceUri or request URL
+ * - `resourceUri`: From request URL
+ * - `network`: From payment requirements (accepts[].network)
+ *
+ * Explicit values override automatic derivation.
+ */
+interface DeclareSIWxOptions {
+    /** Server's domain. If omitted, derived from resourceUri or request URL. */
+    domain?: string;
+    /** Full resource URI. If omitted, derived from request URL. */
+    resourceUri?: string;
+    /** Human-readable purpose */
+    statement?: string;
+    /** CAIP-122 version (default: "1") */
+    version?: string;
+    /**
+     * Network(s) to support. If omitted, derived from payment requirements.
+     * - Single chain: "eip155:8453" or "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+     * - Multi-chain: ["eip155:8453", "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"]
+     */
+    network?: string | string[];
+    /**
+     * Optional expiration duration in seconds.
+     * - Number (e.g., 300): Signature expires after this many seconds
+     * - undefined: Infinite expiration (no expirationTime field in wire format)
+     */
+    expirationSeconds?: number;
+}
+/**
+ * Validation result from validateSIWxMessage
+ */
+interface SIWxValidationResult {
+    valid: boolean;
+    error?: string;
+}
+/**
+ * Options for message validation
+ */
+interface SIWxValidationOptions {
+    /** Maximum age for issuedAt in milliseconds (default: 5 minutes) */
+    maxAge?: number;
+    /** Custom nonce validation function */
+    checkNonce?: (nonce: string) => boolean | Promise<boolean>;
+}
+/**
+ * Result from signature verification
+ */
+interface SIWxVerifyResult {
+    valid: boolean;
+    /** Recovered/verified address (checksummed) */
+    address?: string;
+    error?: string;
+}
+/**
+ * EVM message verifier function type.
+ * Compatible with viem's publicClient.verifyMessage().
+ *
+ * When provided to verifySIWxSignature, enables:
+ * - EIP-1271 (deployed smart contract wallets)
+ * - EIP-6492 (counterfactual/pre-deploy smart wallets)
+ *
+ * Without a verifier, only EOA signatures (EIP-191) can be verified.
+ *
+ * @example
+ * ```typescript
+ * import { createPublicClient, http } from 'viem';
+ * import { base } from 'viem/chains';
+ *
+ * const publicClient = createPublicClient({ chain: base, transport: http() });
+ * // publicClient.verifyMessage satisfies EVMMessageVerifier
+ * ```
+ */
+type EVMMessageVerifier = (args: {
+    address: `0x${string}`;
+    message: string;
+    signature: `0x${string}`;
+}) => Promise<boolean>;
+/**
+ * Options for SIWX signature verification
+ */
+interface SIWxVerifyOptions {
+    /**
+     * EVM message verifier for smart wallet support.
+     *
+     * Pass `publicClient.verifyMessage` from viem to enable verification of:
+     * - Smart contract wallets (EIP-1271)
+     * - Counterfactual/undeployed smart wallets (EIP-6492)
+     *
+     * If not provided, only EOA signatures are verified using standalone
+     * ECDSA recovery (no RPC calls required).
+     */
+    evmVerifier?: EVMMessageVerifier;
+}
+
+/**
+ * Message signing for SIWX extension
+ *
+ * Client-side helpers for signing SIWX messages.
+ * Supports both EVM (viem) and Solana wallet adapters.
+ */
+/**
+ * Signer interface for EVM SIWX message signing.
+ * Compatible with viem WalletClient and PrivateKeyAccount.
+ */
+interface EVMSigner {
+    /** Sign a message and return hex-encoded signature */
+    signMessage: (args: {
+        message: string;
+        account?: unknown;
+    }) => Promise<string>;
+    /** Account object (for WalletClient) */
+    account?: {
+        address: string;
+    };
+    /** Direct address (for PrivateKeyAccount) */
+    address?: string;
+}
+/**
+ * Wallet adapter style Solana signer.
+ * Compatible with @solana/wallet-adapter, Phantom/Solflare wallet APIs.
+ */
+interface WalletAdapterSigner {
+    /** Sign a message and return raw signature bytes */
+    signMessage: (message: Uint8Array) => Promise<Uint8Array>;
+    /** Solana public key (Base58 encoded string or PublicKey-like object) */
+    publicKey: string | {
+        toBase58: () => string;
+    };
+}
+/**
+ * Solana Kit KeyPairSigner style.
+ * Compatible with createKeyPairSignerFromBytes and generateKeyPairSigner from @solana/kit.
+ */
+type SolanaKitSigner = {
+    /** Solana address (Base58 encoded string) */
+    address: string;
+    /** Sign messages - accepts messages with content and signatures */
+    signMessages: (messages: Array<{
+        content: Uint8Array;
+        signatures: Record<string, unknown>;
+    }>) => Promise<Array<Record<string, Uint8Array>>>;
+};
+/**
+ * Union type for Solana signers - supports both wallet adapter and @solana/kit.
+ */
+type SolanaSigner = WalletAdapterSigner | SolanaKitSigner;
+/**
+ * Union type for SIWX signers - supports both EVM and Solana wallets.
+ */
+type SIWxSigner = EVMSigner | SolanaSigner;
+/**
+ * Get address from an EVM signer.
+ *
+ * @param signer - EVM wallet signer instance
+ * @returns The wallet address as a hex string
+ */
+declare function getEVMAddress(signer: EVMSigner): string;
+/**
+ * Get address from a Solana signer.
+ * Supports both wallet adapter (publicKey) and @solana/kit (address) interfaces.
+ *
+ * @param signer - Solana wallet signer instance
+ * @returns The wallet address as a Base58 string
+ */
+declare function getSolanaAddress(signer: SolanaSigner): string;
+/**
+ * Sign a message with an EVM wallet.
+ * Returns hex-encoded signature.
+ *
+ * @param message - The message to sign
+ * @param signer - EVM wallet signer instance
+ * @returns Hex-encoded signature
+ */
+declare function signEVMMessage(message: string, signer: EVMSigner): Promise<string>;
+/**
+ * Sign a message with a Solana wallet.
+ * Returns Base58-encoded signature.
+ * Supports both wallet adapter (signMessage) and @solana/kit (signMessages) interfaces.
+ *
+ * @param message - The message to sign
+ * @param signer - Solana wallet signer instance
+ * @returns Base58-encoded signature
+ */
+declare function signSolanaMessage(message: string, signer: SolanaSigner): Promise<string>;
+
+/**
+ * Complete client flow for SIWX extension
+ *
+ * Combines message construction, signing, and payload creation.
+ * Supports both EVM and Solana wallets.
+ */
+
+/**
+ * Complete SIWX info with chain-specific fields.
+ * Used by utility functions that need the selected chain information.
+ */
+type CompleteSIWxInfo = SIWxExtensionInfo & {
+    chainId: string;
+    type: SignatureType;
+    signatureScheme?: SignatureScheme;
+};
+/**
+ * Create a complete SIWX payload from server extension info with selected chain.
+ *
+ * Routes to EVM or Solana signing based on the chainId prefix:
+ * - `eip155:*` → EVM signing
+ * - `solana:*` → Solana signing
+ *
+ * @param serverExtension - Server extension info with chain selected (includes chainId, type)
+ * @param signer - Wallet that can sign messages (EVMSigner or SolanaSigner)
+ * @returns Complete SIWX payload with signature
+ *
+ * @example
+ * ```typescript
+ * // EVM wallet
+ * const completeInfo = { ...extension.info, chainId: "eip155:8453", type: "eip191" };
+ * const payload = await createSIWxPayload(completeInfo, evmWallet);
+ * ```
+ */
+declare function createSIWxPayload(serverExtension: CompleteSIWxInfo, signer: SIWxSigner): Promise<SIWxPayload>;
+
+/**
+ * Solana Sign-In-With-X (SIWS) support
+ *
+ * Implements CAIP-122 compliant message format and Ed25519 signature verification
+ * for Solana wallets.
+ */
+
+/**
+ * Common Solana network CAIP-2 identifiers.
+ * Uses genesis hash as the chain reference per CAIP-30.
+ */
+declare const SOLANA_MAINNET = "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp";
+declare const SOLANA_DEVNET = "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1";
+declare const SOLANA_TESTNET = "solana:4uhcVJyU9pJkvQyS88uRDiswHXSCkY3z";
+/**
+ * Extract chain reference from CAIP-2 Solana chainId.
+ *
+ * @param chainId - CAIP-2 format chain ID (e.g., "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp")
+ * @returns Chain reference (genesis hash)
+ *
+ * @example
+ * ```typescript
+ * extractSolanaChainReference("solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp") // "5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp"
+ * ```
+ */
+declare function extractSolanaChainReference(chainId: string): string;
+/**
+ * Format SIWS message following CAIP-122 ABNF specification.
+ *
+ * The message format is identical to SIWE (EIP-4361) but uses "Solana account"
+ * instead of "Ethereum account" in the header line.
+ *
+ * @param info - Server-provided extension info
+ * @param address - Client's Solana wallet address (Base58 encoded public key)
+ * @returns Message string ready for signing
+ *
+ * @example
+ * ```typescript
+ * const message = formatSIWSMessage(serverInfo, "BSmWDgE9ex6dZYbiTsJGcwMEgFp8q4aWh92hdErQPeVW");
+ * // Returns:
+ * // "api.example.com wants you to sign in with your Solana account:
+ * // BSmWDgE9ex6dZYbiTsJGcwMEgFp8q4aWh92hdErQPeVW
+ * //
+ * // Sign in to access your content
+ * //
+ * // URI: https://api.example.com/data
+ * // Version: 1
+ * // Chain ID: mainnet
+ * // Nonce: abc123
+ * // Issued At: 2024-01-01T00:00:00.000Z"
+ * ```
+ */
+declare function formatSIWSMessage(info: CompleteSIWxInfo, address: string): string;
+/**
+ * Verify Ed25519 signature for SIWS.
+ *
+ * @param message - The SIWS message that was signed
+ * @param signature - Ed25519 signature bytes
+ * @param publicKey - Solana public key bytes (32 bytes)
+ * @returns true if signature is valid
+ *
+ * @example
+ * ```typescript
+ * const messageBytes = new TextEncoder().encode(message);
+ * const valid = verifySolanaSignature(message, signatureBytes, publicKeyBytes);
+ * ```
+ */
+declare function verifySolanaSignature(message: string, signature: Uint8Array, publicKey: Uint8Array): boolean;
+/**
+ * Decode Base58 string to bytes.
+ *
+ * Solana uses Base58 encoding (Bitcoin alphabet) for addresses and signatures.
+ *
+ * @param encoded - Base58 encoded string
+ * @returns Decoded bytes
+ * @throws Error if string contains invalid Base58 characters
+ *
+ * @example
+ * ```typescript
+ * const publicKeyBytes = decodeBase58("BSmWDgE9ex6dZYbiTsJGcwMEgFp8q4aWh92hdErQPeVW");
+ * // Returns Uint8Array of 32 bytes
+ * ```
+ */
+declare function decodeBase58(encoded: string): Uint8Array;
+/**
+ * Encode bytes to Base58 string.
+ *
+ * @param bytes - Bytes to encode
+ * @returns Base58 encoded string
+ */
+declare function encodeBase58(bytes: Uint8Array): string;
+/**
+ * Detect if a signer is Solana-compatible.
+ * Checks for Solana-specific properties that don't exist on EVM signers.
+ *
+ * @param signer - The signer to check
+ * @returns true if the signer is a Solana signer
+ */
+declare function isSolanaSigner(signer: SIWxSigner): boolean;
+
+/**
+ * Server-side declaration helper for SIWX extension
+ *
+ * Helps servers declare SIWX authentication requirements in PaymentRequired responses.
+ */
+
+/**
+ * Internal type for SIWX declaration with stored options.
+ * The _options field is used by enrichPaymentRequiredResponse to derive
+ * values from request context.
+ */
+interface SIWxDeclaration extends SIWxExtension {
+    _options: DeclareSIWxOptions;
+}
+/**
+ * Create SIWX extension declaration for PaymentRequired.extensions
+ *
+ * Most fields are derived automatically from request context when using
+ * createSIWxResourceServerExtension:
+ * - `network`: From payment requirements (accepts[].network)
+ * - `resourceUri`: From request URL
+ * - `domain`: Parsed from resourceUri
+ *
+ * Explicit values in options override automatic derivation.
+ *
+ * @param options - Configuration options (most are optional)
+ * @returns Extension object ready for PaymentRequired.extensions
+ *
+ * @example
+ * ```typescript
+ * // Minimal - derives network, domain, resourceUri from context
+ * const extensions = declareSIWxExtension({
+ *   statement: 'Sign in to access your purchased content',
+ * });
+ *
+ * // With explicit network (overrides accepts)
+ * const extensions = declareSIWxExtension({
+ *   network: 'eip155:8453',
+ *   statement: 'Sign in to access',
+ * });
+ *
+ * // Full explicit config (no derivation)
+ * const extensions = declareSIWxExtension({
+ *   domain: 'api.example.com',
+ *   resourceUri: 'https://api.example.com/data',
+ *   network: ['eip155:8453', 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp'],
+ *   statement: 'Sign in to access',
+ *   expirationSeconds: 300,
+ * });
+ * ```
+ */
+declare function declareSIWxExtension(options?: DeclareSIWxOptions): Record<string, SIWxDeclaration>;
+
+/**
+ * Storage interface for SIWX payment tracking.
+ *
+ * Implementations track which addresses have paid for which resources,
+ * enabling SIWX authentication to grant access without re-payment.
+ *
+ * Optionally supports nonce tracking to prevent signature replay attacks.
+ */
+interface SIWxStorage {
+    /**
+     * Check if an address has paid for a resource.
+     *
+     * @param resource - The resource path (e.g., "/weather")
+     * @param address - The wallet address to check
+     * @returns True if the address has paid for the resource
+     */
+    hasPaid(resource: string, address: string): boolean | Promise<boolean>;
+    /**
+     * Record that an address has paid for a resource.
+     *
+     * @param resource - The resource path
+     * @param address - The wallet address that paid
+     */
+    recordPayment(resource: string, address: string): void | Promise<void>;
+    /**
+     * Check if a nonce has already been used (optional).
+     *
+     * Implementing this method prevents signature replay attacks where
+     * an intercepted SIWX header could be reused by an attacker.
+     *
+     * @param nonce - The nonce from the SIWX payload
+     * @returns True if the nonce has been used
+     */
+    hasUsedNonce?(nonce: string): boolean | Promise<boolean>;
+    /**
+     * Record that a nonce has been used (optional).
+     *
+     * Called after successfully granting access via SIWX.
+     * Implementations should consider adding expiration to avoid unbounded growth.
+     *
+     * @param nonce - The nonce to record as used
+     */
+    recordNonce?(nonce: string): void | Promise<void>;
+}
+/**
+ * In-memory implementation of SIWxStorage.
+ *
+ * Suitable for development and single-instance deployments.
+ * For production multi-instance deployments, use a persistent storage implementation.
+ */
+declare class InMemorySIWxStorage implements SIWxStorage {
+    private paidAddresses;
+    /**
+     * Check if an address has paid for a resource.
+     *
+     * @param resource - The resource path
+     * @param address - The wallet address to check
+     * @returns True if the address has paid
+     */
+    hasPaid(resource: string, address: string): boolean;
+    /**
+     * Record that an address has paid for a resource.
+     *
+     * @param resource - The resource path
+     * @param address - The wallet address that paid
+     */
+    recordPayment(resource: string, address: string): void;
+}
+
+/**
+ * SIWX Lifecycle Hooks
+ *
+ * Pre-built hooks for integrating SIWX authentication with x402 servers and clients.
+ */
+
+/**
+ * Options for creating server-side SIWX hooks.
+ */
+interface CreateSIWxHookOptions {
+    /** Storage for tracking paid addresses */
+    storage: SIWxStorage;
+    /** Options for signature verification (e.g., EVM smart wallet support) */
+    verifyOptions?: SIWxVerifyOptions;
+    /** Optional callback for logging/debugging */
+    onEvent?: (event: SIWxHookEvent) => void;
+}
+/**
+ * Options for creating the SIWX client extension.
+ */
+interface CreateSIWxClientExtensionOptions {
+    /** Wallet signers to try against the server's supported SIWX chains */
+    signers: SIWxSigner[];
+}
+/**
+ * Events emitted by SIWX hooks for logging/debugging.
+ */
+type SIWxHookEvent = {
+    type: "payment_recorded";
+    resource: string;
+    address: string;
+} | {
+    type: "access_granted";
+    resource: string;
+    address: string;
+} | {
+    type: "validation_failed";
+    resource: string;
+    error?: string;
+} | {
+    type: "nonce_reused";
+    resource: string;
+    nonce: string;
+} | {
+    type: "siwx_header_sent";
+    resource: string;
+};
+/**
+ * Creates an onAfterSettle hook that records payments for SIWX.
+ *
+ * @param options - Hook configuration
+ * @returns Hook function for x402ResourceServer.onAfterSettle()
+ *
+ * @example
+ * ```typescript
+ * const storage = new InMemorySIWxStorage();
+ * const resourceServer = new x402ResourceServer(facilitator)
+ *   .onAfterSettle(createSIWxSettleHook({ storage }));
+ * ```
+ */
+declare function createSIWxSettleHook(options: CreateSIWxHookOptions): (ctx: {
+    paymentPayload: {
+        payload: unknown;
+        resource?: {
+            url: string;
+        };
+    };
+    result: {
+        success: boolean;
+        payer?: string;
+    };
+}) => Promise<void>;
+/**
+ * Creates an onProtectedRequest hook that validates SIWX auth.
+ *
+ * For paid routes: grants access when the SIWX signature is valid and the address has paid.
+ * For auth-only routes (accepts: []): grants access on valid SIWX signature alone.
+ * Auth-only detection uses the routeConfig passed by x402HTTPResourceServer.
+ *
+ * @param options - Hook configuration
+ * @returns Hook function for x402HTTPResourceServer.onProtectedRequest()
+ *
+ * @example
+ * ```typescript
+ * const storage = new InMemorySIWxStorage();
+ * const httpServer = new x402HTTPResourceServer(resourceServer, routes)
+ *   .onProtectedRequest(createSIWxRequestHook({ storage }));
+ * ```
+ */
+declare function createSIWxRequestHook(options: CreateSIWxHookOptions): (context: {
+    adapter: {
+        getHeader(name: string): string | undefined;
+        getUrl(): string;
+    };
+    path: string;
+}, routeConfig?: {
+    accepts?: unknown;
+}) => Promise<void | {
+    grantAccess: true;
+}>;
+/**
+ * Creates an onPaymentRequired hook for client-side SIWX authentication.
+ *
+ * Matches the signer type to a compatible chain in supportedChains.
+ * For EVM signers: matches any eip191 chain
+ * For Solana signers: matches any ed25519 chain
+ *
+ * @param signer - Wallet signer for creating SIWX proofs
+ * @returns Hook function for x402HTTPClient.onPaymentRequired()
+ *
+ * @example
+ * ```typescript
+ * const httpClient = new x402HTTPClient(client)
+ *   .onPaymentRequired(createSIWxClientHook(signer));
+ * ```
+ */
+declare function createSIWxClientHook(signer: SIWxSigner): (context: {
+    paymentRequired: {
+        accepts?: Array<{
+            network: string;
+        }>;
+        extensions?: Record<string, unknown>;
+    };
+}) => Promise<{
+    headers: Record<string, string>;
+} | void>;
+/**
+ * Creates a SIWX client extension that signs HTTP SIWX challenges for compatible wallets.
+ *
+ * @param options - Client extension configuration (signers tried in order until one succeeds)
+ * @returns x402 client extension registering HTTP transport hooks for SIWX
+ */
+declare function createSIWxClientExtension(options: CreateSIWxClientExtensionOptions): ClientExtension;
+
+/**
+ * Server-side ResourceServerExtension factory for SIWX.
+ *
+ * The extension enriches PaymentRequired responses with fresh SIWX challenges,
+ * records successful settlements, and validates HTTP SIWX proofs for routes
+ * that declare the sign-in-with-x extension.
+ */
+
+/**
+ * Options for creating the SIWX resource server extension.
+ *
+ * Includes storage for paid wallet tracking, optional signature verification
+ * settings, and an optional event callback.
+ */
+type CreateSIWxResourceServerExtensionOptions = CreateSIWxHookOptions;
+/**
+ * Creates a SIWX server extension that publishes challenges, records payments,
+ * and validates HTTP SIWX proofs for declared routes.
+ *
+ * @param options - Storage, verification, and event callback configuration
+ * @returns Resource server extension for registration with x402ResourceServer
+ *
+ * @example
+ * ```typescript
+ * const storage = new InMemorySIWxStorage();
+ * const resourceServer = new x402ResourceServer(facilitator)
+ *   .registerExtension(createSIWxResourceServerExtension({ storage }));
+ * ```
+ */
+declare function createSIWxResourceServerExtension(options: CreateSIWxResourceServerExtensionOptions): ResourceServerExtension;
+
+/**
+ * Header parsing for SIWX extension
+ *
+ * Parses the SIGN-IN-WITH-X header from client requests.
+ * Requires base64-encoded JSON per x402 v2 spec.
+ */
+
+/**
+ * Parse SIGN-IN-WITH-X header into structured payload.
+ *
+ * Expects base64-encoded JSON per x402 v2 spec (CHANGELOG-v2.md line 335).
+ *
+ * @param header - The SIGN-IN-WITH-X header value (base64-encoded JSON)
+ * @returns Parsed SIWX payload
+ * @throws Error if header is invalid or missing required fields
+ *
+ * @example
+ * ```typescript
+ * const header = request.headers.get('SIGN-IN-WITH-X');
+ * if (header) {
+ *   const payload = parseSIWxHeader(header);
+ *   // payload.address, payload.signature, etc.
+ * }
+ * ```
+ */
+declare function parseSIWxHeader(header: string): SIWxPayload;
+
+/**
+ * Message validation for SIWX extension
+ *
+ * Validates SIWX payload fields before cryptographic verification.
+ * Per CHANGELOG-v2.md validation rules (lines 318-329).
+ */
+
+/**
+ * Validate SIWX message fields.
+ *
+ * Performs validation per spec (CHANGELOG-v2.md lines 318-329):
+ * - Domain binding: domain MUST match server's domain
+ * - URI validation: uri must refer to base url of resource
+ * - Temporal validation:
+ *   - issuedAt MUST be recent (< 5 minutes by default)
+ *   - expirationTime MUST be in the future
+ *   - notBefore (if present) MUST be in the past
+ * - Nonce: MUST be unique (via optional checkNonce callback)
+ *
+ * @param message - The SIWX payload to validate
+ * @param expectedResourceUri - Expected resource URI (for domain/URI matching)
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const payload = parseSIWxHeader(header);
+ * const result = await validateSIWxMessage(
+ *   payload,
+ *   'https://api.example.com/data',
+ *   { checkNonce: (n) => !usedNonces.has(n) }
+ * );
+ *
+ * if (!result.valid) {
+ *   return { error: result.error };
+ * }
+ * ```
+ */
+declare function validateSIWxMessage(message: SIWxPayload, expectedResourceUri: string, options?: SIWxValidationOptions): Promise<SIWxValidationResult>;
+
+/**
+ * Signature verification for SIWX extension
+ *
+ * Routes to chain-specific verification based on chainId namespace:
+ * - EVM (eip155:*): EOA by default, smart wallet (EIP-1271/EIP-6492) with verifier
+ * - Solana (solana:*): Ed25519 signature verification via tweetnacl
+ */
+
+/**
+ * Verify SIWX signature cryptographically.
+ *
+ * Routes to the appropriate chain-specific verification based on the
+ * chainId namespace prefix:
+ * - `eip155:*` → EVM verification (EOA by default, smart wallet with verifier)
+ * - `solana:*` → Ed25519 signature verification
+ *
+ * @param payload - The SIWX payload containing signature
+ * @param options - Optional verification options
+ * @returns Verification result with recovered address if valid
+ *
+ * @example
+ * ```typescript
+ * // EOA-only verification (default)
+ * const result = await verifySIWxSignature(payload);
+ *
+ * // Smart wallet verification
+ * import { createPublicClient, http } from 'viem';
+ * import { base } from 'viem/chains';
+ *
+ * const publicClient = createPublicClient({ chain: base, transport: http() });
+ * const result = await verifySIWxSignature(payload, {
+ *   evmVerifier: publicClient.verifyMessage,
+ * });
+ *
+ * if (result.valid) {
+ *   console.log('Verified wallet:', result.address);
+ * } else {
+ *   console.error('Verification failed:', result.error);
+ * }
+ * ```
+ */
+declare function verifySIWxSignature(payload: SIWxPayload, options?: SIWxVerifyOptions): Promise<SIWxVerifyResult>;
+
+/**
+ * JSON Schema builder for SIWX extension
+ *
+ * Per CHANGELOG-v2.md lines 276-292
+ */
+
+/**
+ * Build JSON Schema for SIWX extension validation.
+ * This schema validates the client proof payload structure.
+ *
+ * @returns JSON Schema for validating SIWX client payloads
+ */
+declare function buildSIWxSchema(): SIWxExtensionSchema;
+
+/**
+ * CAIP-122 message construction for SIWX extension
+ *
+ * Constructs the canonical message string for signing.
+ * Routes to chain-specific formatters based on chainId namespace.
+ */
+
+/**
+ * Construct CAIP-122 compliant message string for signing.
+ *
+ * Routes to the appropriate chain-specific message formatter based on the
+ * chainId namespace prefix:
+ * - `eip155:*` → SIWE (EIP-4361) format via siwe library
+ * - `solana:*` → SIWS format
+ *
+ * @param serverInfo - Server extension info with chain selected (includes chainId)
+ * @param address - Client wallet address
+ * @returns Message string ready for signing
+ * @throws Error if chainId namespace is not supported
+ *
+ * @example
+ * ```typescript
+ * // EVM (Ethereum, Base, etc.)
+ * const completeInfo = { ...extension.info, chainId: "eip155:8453", type: "eip191" };
+ * const evmMessage = createSIWxMessage(completeInfo, "0x1234...");
+ * ```
+ */
+declare function createSIWxMessage(serverInfo: CompleteSIWxInfo, address: string): string;
+
+/**
+ * Header encoding for SIWX extension
+ *
+ * Encodes SIWX payload for the SIGN-IN-WITH-X HTTP header.
+ * Per CHANGELOG-v2.md line 335: header should be base64-encoded.
+ */
+
+/**
+ * Encode SIWX payload for SIGN-IN-WITH-X header.
+ *
+ * Uses base64 encoding per x402 v2 spec (CHANGELOG-v2.md line 335).
+ *
+ * @param payload - Complete SIWX payload with signature
+ * @returns Base64-encoded JSON string
+ *
+ * @example
+ * ```typescript
+ * const payload = await createSIWxPayload(serverInfo, signer);
+ * const header = encodeSIWxHeader(payload);
+ *
+ * fetch(url, {
+ *   headers: { 'SIGN-IN-WITH-X': header }
+ * });
+ * ```
+ */
+declare function encodeSIWxHeader(payload: SIWxPayload): string;
+
+/**
+ * Fetch wrapper for SIWX authentication.
+ *
+ * Provides a convenient wrapper around fetch that automatically handles
+ * SIWX authentication when a 402 response includes SIWX extension info.
+ */
+
+/**
+ * Wraps fetch to automatically handle SIWX authentication.
+ *
+ * When a 402 response is received with a SIWX extension:
+ * 1. Extracts SIWX info from PAYMENT-REQUIRED header
+ * 2. Creates signed SIWX proof using the provided signer
+ * 3. Retries the request with the SIWX header
+ *
+ * If the 402 response doesn't include SIWX extension info, the original
+ * response is returned unchanged (allowing payment handling to proceed).
+ *
+ * @param fetch - The fetch function to wrap (typically globalThis.fetch)
+ * @param signer - Wallet signer (EVMSigner or SolanaSigner)
+ * @returns A wrapped fetch function that handles SIWX authentication
+ *
+ * @example
+ * ```typescript
+ * import { wrapFetchWithSIWx } from '@bankofai/x402-extensions/sign-in-with-x';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ *
+ * const signer = privateKeyToAccount(privateKey);
+ * const fetchWithSIWx = wrapFetchWithSIWx(fetch, signer);
+ *
+ * // Request that may require SIWX auth (for returning paid users)
+ * const response = await fetchWithSIWx('https://api.example.com/data');
+ * ```
+ */
+declare function wrapFetchWithSIWx(fetch: typeof globalThis.fetch, signer: SIWxSigner): (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * EVM Sign-In-With-Ethereum (SIWE) support
+ *
+ * Implements EIP-4361 compliant message format and signature verification
+ * for EVM chains (Ethereum, Base, Polygon, etc.)
+ */
+
+/**
+ * Extract numeric chain ID from CAIP-2 EVM chainId.
+ *
+ * @param chainId - CAIP-2 format chain ID (e.g., "eip155:8453")
+ * @returns Numeric chain ID (e.g., 8453)
+ * @throws Error if chainId format is invalid
+ *
+ * @example
+ * ```typescript
+ * extractEVMChainId("eip155:1")    // 1 (Ethereum mainnet)
+ * extractEVMChainId("eip155:8453") // 8453 (Base)
+ * extractEVMChainId("eip155:137")  // 137 (Polygon)
+ * ```
+ */
+declare function extractEVMChainId(chainId: string): number;
+/**
+ * Format SIWE message following EIP-4361 specification.
+ *
+ * Uses the siwe library to ensure message format matches verification.
+ *
+ * @param info - Server-provided extension info
+ * @param address - Client's EVM wallet address (0x-prefixed)
+ * @returns Message string ready for signing
+ *
+ * @example
+ * ```typescript
+ * const message = formatSIWEMessage(serverInfo, "0x1234...abcd");
+ * // Returns EIP-4361 formatted message:
+ * // "api.example.com wants you to sign in with your Ethereum account:
+ * // 0x1234...abcd
+ * //
+ * // Sign in to access your content
+ * //
+ * // URI: https://api.example.com/data
+ * // Version: 1
+ * // Chain ID: 8453
+ * // Nonce: abc123
+ * // Issued At: 2024-01-01T00:00:00.000Z"
+ * ```
+ */
+declare function formatSIWEMessage(info: CompleteSIWxInfo, address: string): string;
+/**
+ * Verify EVM signature.
+ *
+ * Supports:
+ * - EOA signatures (standard ECDSA via EIP-191) - always available
+ * - EIP-1271 (deployed smart contract wallets) - requires verifier
+ * - EIP-6492 (counterfactual/pre-deploy smart wallets) - requires verifier
+ *
+ * @param message - The SIWE message that was signed
+ * @param address - The claimed signer address
+ * @param signature - The signature to verify
+ * @param verifier - Optional message verifier for smart wallet support.
+ *                   Pass publicClient.verifyMessage for EIP-1271/EIP-6492 support.
+ *                   Without this, only EOA signatures are verified.
+ * @returns true if signature is valid
+ *
+ * @example
+ * ```typescript
+ * // EOA-only verification (default, no RPC required)
+ * const valid = await verifyEVMSignature(message, address, signature);
+ *
+ * // Smart wallet verification with viem PublicClient
+ * import { createPublicClient, http } from 'viem';
+ * import { base } from 'viem/chains';
+ *
+ * const publicClient = createPublicClient({ chain: base, transport: http() });
+ * const valid = await verifyEVMSignature(
+ *   message,
+ *   address,
+ *   signature,
+ *   publicClient.verifyMessage
+ * );
+ * ```
+ */
+declare function verifyEVMSignature(message: string, address: string, signature: string, verifier?: EVMMessageVerifier): Promise<boolean>;
+/**
+ * Detect if a signer is EVM-compatible.
+ * Checks for EVM-specific properties.
+ *
+ * @param signer - The signer to check
+ * @returns true if the signer is an EVM signer
+ */
+declare function isEVMSigner(signer: SIWxSigner): boolean;
+
+export { type CompleteSIWxInfo, type CreateSIWxClientExtensionOptions, type CreateSIWxHookOptions, type CreateSIWxResourceServerExtensionOptions, type DeclareSIWxOptions, type EVMMessageVerifier, type EVMSigner, InMemorySIWxStorage, SIGN_IN_WITH_X, type SIWxExtension, type SIWxExtensionInfo, type SIWxExtensionSchema, type SIWxHookEvent, type SIWxPayload, SIWxPayloadSchema, type SIWxSigner, type SIWxStorage, type SIWxValidationOptions, type SIWxValidationResult, type SIWxVerifyOptions, type SIWxVerifyResult, SOLANA_DEVNET, SOLANA_MAINNET, SOLANA_TESTNET, type SignatureScheme, type SignatureType, type SolanaSigner, type SupportedChain, buildSIWxSchema, createSIWxClientExtension, createSIWxClientHook, createSIWxMessage, createSIWxPayload, createSIWxRequestHook, createSIWxResourceServerExtension, createSIWxSettleHook, declareSIWxExtension, decodeBase58, encodeBase58, encodeSIWxHeader, extractEVMChainId, extractSolanaChainReference, formatSIWEMessage, formatSIWSMessage, getEVMAddress, getSolanaAddress, isEVMSigner, isSolanaSigner, parseSIWxHeader, signEVMMessage, signSolanaMessage, validateSIWxMessage, verifyEVMSignature, verifySIWxSignature, verifySolanaSignature, wrapFetchWithSIWx };