@t402/extensions 2.0.0 → 2.3.0

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

@@ -1,2 +1,361 @@
+/**
+ * Sign-In-With-X (SIWx) Type Definitions
+ *
+ * CAIP-122 compliant wallet-based identity assertions for t402 protocol.
+ */
+/**
+ * Supported signature schemes for SIWx.
+ */
+type SignatureScheme = "eip191" | "eip712" | "eip1271" | "eip6492" | "siws" | "sep10";
+/**
+ * Information provided by server about SIWx requirements.
+ */
+interface SIWxExtensionInfo {
+    /** Domain derived from resourceUri (without protocol) */
+    domain: string;
+    /** Full resource URI */
+    uri: string;
+    /** Optional statement explaining what the signature is for */
+    statement?: string;
+    /** SIWx version (default: "1") */
+    version: string;
+    /** Chain ID in CAIP-2 format (e.g., "eip155:8453") */
+    chainId: string;
+    /** Cryptographically secure nonce */
+    nonce: string;
+    /** ISO 8601 timestamp when message was issued */
+    issuedAt: string;
+    /** ISO 8601 timestamp when signature expires */
+    expirationTime?: string;
+    /** ISO 8601 timestamp before which signature is not valid */
+    notBefore?: string;
+    /** Optional request ID for session correlation */
+    requestId?: string;
+    /** Resources being authenticated for */
+    resources: string[];
+    /** Preferred signature scheme */
+    signatureScheme?: SignatureScheme;
+}
+/**
+ * SIWx extension declaration for server responses.
+ */
+interface SIWxExtension {
+    /** Extension information */
+    info: SIWxExtensionInfo;
+    /** JSON Schema for validation */
+    schema: object;
+}
+/**
+ * Complete SIWx payload including signature.
+ */
+interface SIWxPayload {
+    /** Domain from the server */
+    domain: string;
+    /** Wallet address making the assertion */
+    address: string;
+    /** Optional statement */
+    statement?: string;
+    /** Resource URI */
+    uri: string;
+    /** SIWx version */
+    version: string;
+    /** Chain ID in CAIP-2 format */
+    chainId: string;
+    /** Nonce from server */
+    nonce: string;
+    /** ISO 8601 timestamp when message was issued */
+    issuedAt: string;
+    /** ISO 8601 timestamp when signature expires */
+    expirationTime?: string;
+    /** ISO 8601 timestamp before which signature is not valid */
+    notBefore?: string;
+    /** Optional request ID */
+    requestId?: string;
+    /** Resources array */
+    resources?: string[];
+    /** Cryptographic signature */
+    signature: string;
+}
+/**
+ * Options for declaring SIWx extension on server.
+ */
+interface DeclareSIWxOptions {
+    /** Full URI of the resource (domain derived from this) */
+    resourceUri: string;
+    /** Optional statement explaining the sign-in purpose */
+    statement?: string;
+    /** SIWx version (defaults to "1") */
+    version?: string;
+    /** Network in CAIP-2 format (e.g., "eip155:8453") */
+    network: `${string}:${string}`;
+    /** Expiration time (auto-set to +5 minutes if not provided) */
+    expirationTime?: string;
+    /** Preferred signature scheme */
+    signatureScheme?: SignatureScheme;
+}
+/**
+ * Options for validating SIWx messages.
+ */
+interface ValidateSIWxOptions {
+    /** Maximum age of issuedAt in milliseconds (default: 5 minutes) */
+    maxAge?: number;
+    /** Custom nonce validation function */
+    checkNonce?: (nonce: string) => boolean;
+}
+/**
+ * Options for verifying SIWx signatures.
+ */
+interface VerifySIWxOptions {
+    /** Web3 provider for on-chain verification */
+    provider?: unknown;
+    /** Enable EIP-1271/6492 smart wallet verification */
+    checkSmartWallet?: boolean;
+}
+/**
+ * Result of SIWx message validation.
+ */
+interface SIWxValidationResult {
+    /** Whether the message is valid */
+    valid: boolean;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Result of SIWx signature verification.
+ */
+interface SIWxVerificationResult {
+    /** Whether the signature is valid */
+    valid: boolean;
+    /** Recovered/verified address */
+    address?: string;
+    /** Error message if invalid */
+    error?: string;
+}
+/**
+ * Signer interface for client-side signing.
+ */
+interface SIWxSigner {
+    /** Wallet address */
+    address: string;
+    /** Sign a message using personal_sign (EIP-191) */
+    signMessage?(message: string): Promise<string>;
+    /** Sign typed data (EIP-712) */
+    signTypedData?(data: unknown): Promise<string>;
+}
 
-export {  }
+/**
+ * Sign-In-With-X (SIWx) Server-Side Implementation
+ *
+ * Provides functions for servers to declare SIWx requirements,
+ * parse client headers, and verify signatures.
+ */
+
+/**
+ * Declares a SIWx extension for server responses.
+ *
+ * @param options - Extension declaration options
+ * @returns SIWx extension object ready for response
+ *
+ * @example
+ * ```typescript
+ * const extension = declareSIWxExtension({
+ *   resourceUri: "https://api.example.com/premium",
+ *   network: "eip155:8453",
+ *   statement: "Sign in to access premium content",
+ * });
+ * ```
+ */
+declare function declareSIWxExtension(options: DeclareSIWxOptions): SIWxExtension;
+/**
+ * Parses a SIWx header from client request.
+ *
+ * The header format is base64-encoded JSON.
+ *
+ * @param header - Base64-encoded SIWx header value
+ * @returns Parsed SIWx payload
+ * @throws Error if header is invalid
+ *
+ * @example
+ * ```typescript
+ * const payload = parseSIWxHeader(request.headers['x-t402-siwx']);
+ * ```
+ */
+declare function parseSIWxHeader(header: string): SIWxPayload;
+/**
+ * Validates a SIWx message against expected values.
+ *
+ * @param message - The SIWx payload to validate
+ * @param expectedResourceUri - Expected resource URI (domain validated from this)
+ * @param options - Validation options
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const result = validateSIWxMessage(payload, "https://api.example.com/premium", {
+ *   maxAge: 5 * 60 * 1000, // 5 minutes
+ *   checkNonce: (nonce) => usedNonces.has(nonce) === false,
+ * });
+ * ```
+ */
+declare function validateSIWxMessage(message: SIWxPayload, expectedResourceUri: string, options?: ValidateSIWxOptions): SIWxValidationResult;
+/**
+ * Verifies a SIWx signature.
+ *
+ * Supports EIP-191 personal signatures and can optionally verify
+ * smart wallet signatures via EIP-1271/6492.
+ *
+ * @param message - The SIWx payload to verify
+ * @param signature - The signature to verify (hex-encoded)
+ * @param options - Verification options
+ * @returns Verification result with recovered address
+ *
+ * @example
+ * ```typescript
+ * const result = await verifySIWxSignature(payload, payload.signature, {
+ *   checkSmartWallet: true,
+ *   provider: web3Provider,
+ * });
+ * ```
+ */
+declare function verifySIWxSignature(message: SIWxPayload, signature: string, options?: VerifySIWxOptions): Promise<SIWxVerificationResult>;
+/**
+ * Constructs the CAIP-122 message string from payload.
+ *
+ * @param payload - SIWx payload
+ * @returns CAIP-122 formatted message string
+ */
+declare function constructMessage(payload: SIWxPayload): string;
+/**
+ * Hashes a message with the Ethereum signed message prefix (EIP-191).
+ *
+ * @param message - Message to hash
+ * @returns Hex-encoded keccak256 hash with 0x prefix
+ */
+declare function hashMessage(message: string): string;
+/**
+ * Verifies a signature using EIP-6492 (universal signature verification).
+ *
+ * This supports both deployed and undeployed smart wallets.
+ *
+ * @param walletAddress - Wallet address (may be counterfactual)
+ * @param messageHash - Hash of the message that was signed
+ * @param signature - The signature (may include deployment data)
+ * @param provider - Ethereum provider
+ * @returns True if signature is valid
+ */
+declare function verifyEIP6492Signature(walletAddress: string, messageHash: string, signature: string, provider: unknown): Promise<boolean>;
+
+/**
+ * Sign-In-With-X (SIWx) Client-Side Implementation
+ *
+ * Provides functions for clients to create and sign SIWx messages.
+ */
+
+/**
+ * Encodes a SIWx payload for transmission in HTTP header.
+ *
+ * @param payload - The SIWx payload to encode
+ * @returns Base64-encoded JSON string
+ *
+ * @example
+ * ```typescript
+ * const header = encodeSIWxHeader(payload);
+ * fetch(url, {
+ *   headers: { 'X-T402-SIWx': header }
+ * });
+ * ```
+ */
+declare function encodeSIWxHeader(payload: SIWxPayload): string;
+/**
+ * Creates a CAIP-122 formatted message string from server info.
+ *
+ * @param serverInfo - Extension info from server
+ * @param address - Wallet address signing the message
+ * @returns CAIP-122 formatted message string ready for signing
+ *
+ * @example
+ * ```typescript
+ * const message = createSIWxMessage(extension.info, wallet.address);
+ * const signature = await wallet.signMessage(message);
+ * ```
+ */
+declare function createSIWxMessage(serverInfo: SIWxExtensionInfo, address: string): string;
+/**
+ * Creates EIP-712 typed data for SIWx signing.
+ *
+ * @param serverInfo - Extension info from server
+ * @param address - Wallet address signing the message
+ * @returns EIP-712 typed data object
+ */
+declare function createSIWxTypedData(serverInfo: SIWxExtensionInfo, address: string): {
+    domain: {
+        name: string;
+        version: string;
+        chainId: number;
+    };
+    types: {
+        SIWx: Array<{
+            name: string;
+            type: string;
+        }>;
+    };
+    primaryType: "SIWx";
+    message: Record<string, unknown>;
+};
+/**
+ * Signs a SIWx message using the provided signer.
+ *
+ * @param message - CAIP-122 formatted message to sign
+ * @param signer - Wallet/signer interface with signMessage
+ * @param options - Signing options
+ * @param options.signatureScheme - Signature scheme to use
+ * @param options.serverInfo - Server info for verification
+ * @returns Hex-encoded signature
+ *
+ * @example
+ * ```typescript
+ * const signature = await signSIWxMessage(message, wallet, {
+ *   signatureScheme: 'eip191'
+ * });
+ * ```
+ */
+declare function signSIWxMessage(message: string, signer: SIWxSigner, options?: {
+    signatureScheme?: SignatureScheme;
+    serverInfo?: SIWxExtensionInfo;
+}): Promise<string>;
+/**
+ * Creates a complete SIWx payload from server extension and signer.
+ *
+ * This is the main entry point for clients - it handles message construction,
+ * signing, and payload assembly.
+ *
+ * @param serverExtension - Extension from server's 402 response
+ * @param signer - Wallet/signer interface
+ * @returns Complete signed SIWx payload ready for header encoding
+ *
+ * @example
+ * ```typescript
+ * // Get extension from server 402 response
+ * const extension = paymentRequirements.extensions?.siwx;
+ *
+ * // Create signed payload
+ * const payload = await createSIWxPayload(extension, wallet);
+ *
+ * // Encode and send with retry
+ * const header = encodeSIWxHeader(payload);
+ * fetch(url, {
+ *   headers: { 'X-T402-SIWx': header }
+ * });
+ * ```
+ */
+declare function createSIWxPayload(serverExtension: SIWxExtension, signer: SIWxSigner): Promise<SIWxPayload>;
+/**
+ * Extension key for SIWx in payment requirements.
+ */
+declare const SIWX_EXTENSION_KEY = "siwx";
+/**
+ * HTTP header name for SIWx payload.
+ */
+declare const SIWX_HEADER_NAME = "X-T402-SIWx";
+
+export { type DeclareSIWxOptions, SIWX_EXTENSION_KEY, SIWX_HEADER_NAME, type SIWxExtension, type SIWxExtensionInfo, type SIWxPayload, type SIWxSigner, type SIWxValidationResult, type SIWxVerificationResult, type SignatureScheme, type ValidateSIWxOptions, type VerifySIWxOptions, constructMessage, createSIWxMessage, createSIWxPayload, createSIWxTypedData, declareSIWxExtension, encodeSIWxHeader, hashMessage, parseSIWxHeader, signSIWxMessage, validateSIWxMessage, verifyEIP6492Signature, verifySIWxSignature };

package/dist/esm/sign-in-with-x/index.mjs

@@ -1,2 +1,33 @@
-import "../chunk-MKFJ5AA3.mjs";
+import {
+  SIWX_EXTENSION_KEY,
+  SIWX_HEADER_NAME,
+  constructMessage,
+  createSIWxMessage,
+  createSIWxPayload,
+  createSIWxTypedData,
+  declareSIWxExtension,
+  encodeSIWxHeader,
+  hashMessage,
+  parseSIWxHeader,
+  signSIWxMessage,
+  validateSIWxMessage,
+  verifyEIP6492Signature,
+  verifySIWxSignature
+} from "../chunk-D7SENN2L.mjs";
+export {
+  SIWX_EXTENSION_KEY,
+  SIWX_HEADER_NAME,
+  constructMessage,
+  createSIWxMessage,
+  createSIWxPayload,
+  createSIWxTypedData,
+  declareSIWxExtension,
+  encodeSIWxHeader,
+  hashMessage,
+  parseSIWxHeader,
+  signSIWxMessage,
+  validateSIWxMessage,
+  verifyEIP6492Signature,
+  verifySIWxSignature
+};
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t402/extensions",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "main": "./dist/cjs/index.js",
   "module": "./dist/esm/index.js",
   "types": "./dist/cjs/index.d.ts",
@@ -23,18 +23,29 @@
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-jsdoc": "^50.6.9",
     "eslint-plugin-prettier": "^5.2.6",
+    "glob": "^13.0.0",
     "prettier": "3.5.2",
     "tsup": "^8.4.0",
-    "tsx": "^4.19.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.7.3",
-    "vite": "^6.2.6",
+    "vite": "^7.3.1",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^3.0.5"
+    "vitest": "^3.2.4"
   },
   "dependencies": {
+    "@noble/curves": "^1.8.1",
+    "@noble/hashes": "^1.7.1",
     "ajv": "^8.17.1",
     "zod": "^3.24.2",
-    "@t402/core": "2.0.0"
+    "@t402/core": "2.3.0"
+  },
+  "peerDependencies": {
+    "viem": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "viem": {
+      "optional": true
+    }
   },
   "exports": {
     ".": {

package/dist/esm/chunk-MKFJ5AA3.mjs

@@ -1 +0,0 @@
-//# sourceMappingURL=chunk-MKFJ5AA3.mjs.map

package/dist/esm/chunk-MKFJ5AA3.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}