@nucypher/taco-auth 0.3.0-alpha.1 → 0.3.0-alpha.3

package/dist/cjs/auth-sig.d.ts

@@ -1,18 +1,20 @@
 import { z } from 'zod';
-export declare const authSignatureSchema: z.ZodObject<{
+import { EIP1271AuthSignature } from './providers/eip1271/auth';
+import { EIP4361AuthSignature } from './providers/eip4361/auth';
+export declare const baseAuthSignatureSchema: z.ZodObject<{
     signature: z.ZodString;
     address: z.ZodEffects<z.ZodString, string, string>;
-    scheme: z.ZodEnum<["EIP4361"]>;
-    typedData: z.ZodEffects<z.ZodString, string, string>;
+    scheme: z.ZodString;
+    typedData: z.ZodUnknown;
 }, "strip", z.ZodTypeAny, {
     signature: string;
     address: string;
-    scheme: "EIP4361";
-    typedData: string;
+    scheme: string;
+    typedData?: unknown;
 }, {
     signature: string;
     address: string;
-    scheme: "EIP4361";
-    typedData: string;
+    scheme: string;
+    typedData?: unknown;
 }>;
-export type AuthSignature = z.infer<typeof authSignatureSchema>;
+export type AuthSignature = EIP4361AuthSignature | EIP1271AuthSignature;

package/dist/cjs/auth-sig.js

@@ -1,13 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.authSignatureSchema = void 0;
+exports.baseAuthSignatureSchema = void 0;
 const shared_1 = require("@nucypher/shared");
 const zod_1 = require("zod");
-const common_1 = require("./providers/eip4361/common");
-exports.authSignatureSchema = zod_1.z.object({
+exports.baseAuthSignatureSchema = zod_1.z.object({
     signature: zod_1.z.string(),
     address: shared_1.EthAddressSchema,
-    scheme: zod_1.z.enum([common_1.EIP4361_AUTH_METHOD]),
-    typedData: common_1.EIP4361TypedDataSchema,
+    scheme: zod_1.z.string(),
+    typedData: zod_1.z.unknown(),
 });
 //# sourceMappingURL=auth-sig.js.map

package/dist/cjs/auth-sig.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth-sig.js","sourceRoot":"","sources":["../../src/auth-sig.ts"],"names":[],"mappings":";;;AAAA,6CAAoD;AACpD,6BAAwB;AAExB,uDAGoC;AAEvB,QAAA,mBAAmB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC1C,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,OAAO,EAAE,yBAAgB;IACzB,MAAM,EAAE,OAAC,CAAC,IAAI,CAAC,CAAC,4BAAmB,CAAC,CAAC;IACrC,SAAS,EAAE,+BAAsB;CAClC,CAAC,CAAC"}
+{"version":3,"file":"auth-sig.js","sourceRoot":"","sources":["../../src/auth-sig.ts"],"names":[],"mappings":";;;AAAA,6CAAoD;AACpD,6BAAwB;AAKX,QAAA,uBAAuB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC9C,SAAS,EAAE,OAAC,CAAC,MAAM,EAAE;IACrB,OAAO,EAAE,yBAAgB;IACzB,MAAM,EAAE,OAAC,CAAC,MAAM,EAAE;IAClB,SAAS,EAAE,OAAC,CAAC,OAAO,EAAE;CACvB,CAAC,CAAC"}

package/dist/cjs/providers/eip1271/auth.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+export declare const EIP1271_AUTH_METHOD = "EIP1271";
+export declare const EIP1271TypedDataSchema: z.ZodObject<{
+    chain: z.ZodNumber;
+    dataHash: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    chain: number;
+    dataHash: string;
+}, {
+    chain: number;
+    dataHash: string;
+}>;
+export declare const eip1271AuthSignatureSchema: z.ZodObject<{
+    signature: z.ZodString;
+    address: z.ZodEffects<z.ZodString, string, string>;
+    scheme: z.ZodLiteral<"EIP1271">;
+    typedData: z.ZodObject<{
+        chain: z.ZodNumber;
+        dataHash: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        chain: number;
+        dataHash: string;
+    }, {
+        chain: number;
+        dataHash: string;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    address: string;
+    scheme: "EIP1271";
+    typedData: {
+        chain: number;
+        dataHash: string;
+    };
+}, {
+    signature: string;
+    address: string;
+    scheme: "EIP1271";
+    typedData: {
+        chain: number;
+        dataHash: string;
+    };
+}>;
+export type EIP1271AuthSignature = z.infer<typeof eip1271AuthSignatureSchema>;

package/dist/cjs/providers/eip1271/auth.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eip1271AuthSignatureSchema = exports.EIP1271TypedDataSchema = exports.EIP1271_AUTH_METHOD = void 0;
+const zod_1 = require("zod");
+const auth_sig_1 = require("../../auth-sig");
+exports.EIP1271_AUTH_METHOD = 'EIP1271';
+exports.EIP1271TypedDataSchema = zod_1.z.object({
+    chain: zod_1.z.number().int().nonnegative(),
+    dataHash: zod_1.z.string().startsWith('0x'), // hex string
+});
+exports.eip1271AuthSignatureSchema = auth_sig_1.baseAuthSignatureSchema.extend({
+    scheme: zod_1.z.literal(exports.EIP1271_AUTH_METHOD),
+    typedData: exports.EIP1271TypedDataSchema,
+});
+//# sourceMappingURL=auth.js.map

package/dist/cjs/providers/eip1271/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../../src/providers/eip1271/auth.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AAExB,6CAAyD;AAE5C,QAAA,mBAAmB,GAAG,SAAS,CAAC;AAEhC,QAAA,sBAAsB,GAAG,OAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE;IACrC,QAAQ,EAAE,OAAC,CAAC,MAAM,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,aAAa;CACrD,CAAC,CAAC;AAEU,QAAA,0BAA0B,GAAG,kCAAuB,CAAC,MAAM,CAAC;IACvE,MAAM,EAAE,OAAC,CAAC,OAAO,CAAC,2BAAmB,CAAC;IACtC,SAAS,EAAE,8BAAsB;CAClC,CAAC,CAAC"}

package/dist/cjs/providers/eip1271/eip1271.d.ts

@@ -0,0 +1,34 @@
+import { AuthProvider } from '../../auth-provider';
+import { EIP1271AuthSignature } from './auth';
+/**
+ * EIP1271AuthProvider handles EIP-1271 contract-based authentication.
+ * This provider manages authentication signatures from smart contracts that implement EIP-1271's `isValidSignature` solidity function.
+ */
+export declare class EIP1271AuthProvider implements AuthProvider {
+    readonly contractAddress: string;
+    readonly chain: number;
+    readonly dataHash: string;
+    readonly signature: string;
+    /**
+     * Creates a new EIP1271AuthProvider for contract-based authentication.
+     *
+     * @param contractAddress - The Ethereum address of the contract implementing EIP-1271
+     * @param chain - The chain ID where the contract is deployed
+     * @param dataHash - The hash of the data that was signed
+     * @param signature - The signature produced by the contract's signing method
+     */
+    constructor(contractAddress: string, chain: number, dataHash: string, signature: string);
+    /**
+     * Returns the authentication signature for the contract.
+     *
+     * Since contract signatures are created externally, this method simply returns
+     * the existing signature and metadata rather than creating a new one.
+     *
+     * @returns {Promise<EIP1271AuthSignature>} The authentication signature containing:
+     *   - signature: The contract-generated signature
+     *   - address: The contract's address
+     *   - scheme: The authentication scheme (EIP1271)
+     *   - typedData: Object containing the chain ID and data hash
+     */
+    getOrCreateAuthSignature(): Promise<EIP1271AuthSignature>;
+}

package/dist/cjs/providers/eip1271/eip1271.js

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EIP1271AuthProvider = void 0;
+const auth_1 = require("./auth");
+/**
+ * EIP1271AuthProvider handles EIP-1271 contract-based authentication.
+ * This provider manages authentication signatures from smart contracts that implement EIP-1271's `isValidSignature` solidity function.
+ */
+class EIP1271AuthProvider {
+    contractAddress;
+    chain;
+    dataHash;
+    signature;
+    /**
+     * Creates a new EIP1271AuthProvider for contract-based authentication.
+     *
+     * @param contractAddress - The Ethereum address of the contract implementing EIP-1271
+     * @param chain - The chain ID where the contract is deployed
+     * @param dataHash - The hash of the data that was signed
+     * @param signature - The signature produced by the contract's signing method
+     */
+    constructor(contractAddress, chain, dataHash, signature) {
+        this.contractAddress = contractAddress;
+        this.chain = chain;
+        this.dataHash = dataHash;
+        this.signature = signature;
+    }
+    /**
+     * Returns the authentication signature for the contract.
+     *
+     * Since contract signatures are created externally, this method simply returns
+     * the existing signature and metadata rather than creating a new one.
+     *
+     * @returns {Promise<EIP1271AuthSignature>} The authentication signature containing:
+     *   - signature: The contract-generated signature
+     *   - address: The contract's address
+     *   - scheme: The authentication scheme (EIP1271)
+     *   - typedData: Object containing the chain ID and data hash
+     */
+    async getOrCreateAuthSignature() {
+        return {
+            signature: this.signature,
+            address: this.contractAddress,
+            scheme: auth_1.EIP1271_AUTH_METHOD,
+            typedData: {
+                chain: this.chain,
+                dataHash: this.dataHash,
+            },
+        };
+    }
+}
+exports.EIP1271AuthProvider = EIP1271AuthProvider;
+//# sourceMappingURL=eip1271.js.map

package/dist/cjs/providers/eip1271/eip1271.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"eip1271.js","sourceRoot":"","sources":["../../../../src/providers/eip1271/eip1271.ts"],"names":[],"mappings":";;;AAEA,iCAAmE;AAEnE;;;GAGG;AACH,MAAa,mBAAmB;IAUZ;IACA;IACA;IACA;IAZlB;;;;;;;OAOG;IACH,YACkB,eAAuB,EACvB,KAAa,EACb,QAAgB,EAChB,SAAiB;QAHjB,oBAAe,GAAf,eAAe,CAAQ;QACvB,UAAK,GAAL,KAAK,CAAQ;QACb,aAAQ,GAAR,QAAQ,CAAQ;QAChB,cAAS,GAAT,SAAS,CAAQ;IAChC,CAAC;IAEJ;;;;;;;;;;;OAWG;IACI,KAAK,CAAC,wBAAwB;QACnC,OAAO;YACL,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,OAAO,EAAE,IAAI,CAAC,eAAe;YAC7B,MAAM,EAAE,0BAAmB;YAC3B,SAAS,EAAE;gBACT,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,QAAQ,EAAE,IAAI,CAAC,QAAQ;aACxB;SACF,CAAC;IACJ,CAAC;CACF;AAvCD,kDAuCC"}

package/dist/cjs/providers/eip4361/auth.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+export declare const EIP4361_AUTH_METHOD = "EIP4361";
+export declare const USER_ADDRESS_PARAM_DEFAULT = ":userAddress";
+export declare const EIP4361TypedDataSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const eip4361AuthSignatureSchema: z.ZodObject<{
+    signature: z.ZodString;
+    address: z.ZodEffects<z.ZodString, string, string>;
+    scheme: z.ZodLiteral<"EIP4361">;
+    typedData: z.ZodEffects<z.ZodString, string, string>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    address: string;
+    scheme: "EIP4361";
+    typedData: string;
+}, {
+    signature: string;
+    address: string;
+    scheme: "EIP4361";
+    typedData: string;
+}>;
+export type EIP4361AuthSignature = z.infer<typeof eip4361AuthSignatureSchema>;

package/dist/cjs/providers/eip4361/auth.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.eip4361AuthSignatureSchema = exports.EIP4361TypedDataSchema = exports.USER_ADDRESS_PARAM_DEFAULT = exports.EIP4361_AUTH_METHOD = void 0;
+const siwe_1 = require("siwe");
+const zod_1 = require("zod");
+const auth_sig_1 = require("../../auth-sig");
+exports.EIP4361_AUTH_METHOD = 'EIP4361';
+exports.USER_ADDRESS_PARAM_DEFAULT = ':userAddress';
+const isSiweMessage = (message) => {
+    try {
+        new siwe_1.SiweMessage(message);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+exports.EIP4361TypedDataSchema = zod_1.z
+    .string()
+    .refine(isSiweMessage, { message: 'Invalid SIWE message' });
+exports.eip4361AuthSignatureSchema = auth_sig_1.baseAuthSignatureSchema.extend({
+    scheme: zod_1.z.literal(exports.EIP4361_AUTH_METHOD),
+    typedData: exports.EIP4361TypedDataSchema,
+});
+//# sourceMappingURL=auth.js.map

package/dist/cjs/providers/eip4361/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../../../src/providers/eip4361/auth.ts"],"names":[],"mappings":";;;AAAA,+BAAmC;AACnC,6BAAwB;AAExB,6CAAyD;AAE5C,QAAA,mBAAmB,GAAG,SAAS,CAAC;AAEhC,QAAA,0BAA0B,GAAG,cAAc,CAAC;AAEzD,MAAM,aAAa,GAAG,CAAC,OAAe,EAAW,EAAE;IACjD,IAAI,CAAC;QACH,IAAI,kBAAW,CAAC,OAAO,CAAC,CAAC;QACzB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC,CAAC;AAEW,QAAA,sBAAsB,GAAG,OAAC;KACpC,MAAM,EAAE;KACR,MAAM,CAAC,aAAa,EAAE,EAAE,OAAO,EAAE,sBAAsB,EAAE,CAAC,CAAC;AAEjD,QAAA,0BAA0B,GAAG,kCAAuB,CAAC,MAAM,CAAC;IACvE,MAAM,EAAE,OAAC,CAAC,OAAO,CAAC,2BAAmB,CAAC;IACtC,SAAS,EAAE,8BAAsB;CAClC,CAAC,CAAC"}

package/dist/cjs/providers/eip4361/eip4361.d.ts

@@ -1,18 +1,84 @@
 import { ethers } from 'ethers';
-import { AuthSignature } from '../../auth-sig';
-export declare const USER_ADDRESS_PARAM_DEFAULT = ":userAddress";
+import { AuthProvider } from '../../auth-provider';
+import { EIP4361AuthSignature } from './auth';
 export type EIP4361AuthProviderParams = {
     domain: string;
     uri: string;
 };
-export declare class EIP4361AuthProvider {
+export declare const FRESHNESS_IN_MILLISECONDS: number;
+/**
+ * Implements Sign-In with Ethereum (EIP-4361/SIWE) authentication by managing SIWE message lifecycle.
+ *
+ * This provider handles:
+ * - Creating and signing new SIWE messages
+ * - Storing signed messages in local storage
+ * - Retrieving and validating stored messages
+ * - Automatically refreshing expired messages
+ *
+ * Messages are valid for 2 hours from creation and stored locally keyed by the signer's address.
+ *
+ * @implements {AuthProvider}
+ */
+export declare class EIP4361AuthProvider implements AuthProvider {
     private readonly provider;
     private readonly signer;
     private readonly storage;
     private readonly providerParams;
+    /**
+     * Creates a new EIP4361AuthProvider instance.
+     *
+     * @param provider - Ethers provider used to fetch the current chainId
+     * @param signer - Ethers signer used to sign SIWE messages
+     * @param providerParams - Optional SIWE message configuration
+     * @param providerParams.domain - Domain name for the signing request (e.g. 'app.example.com').
+     *                               Defaults to current website domain or 'taco.build'
+     * @param providerParams.uri - Full URI of signing request origin (e.g. 'https://app.example.com').
+     *                            Defaults to current website URL or 'https://taco.build'
+     *
+     * The SIWE message will include:
+     * - A human-readable statement: "{domain} wants you to sign in with your Ethereum account: {address}"
+     * - Version: "1"
+     * - 2 hour expiration from creation time
+     * - Chain ID from the provided provider
+     * - Nonce: Auto-generated
+     */
     constructor(provider: ethers.providers.Provider, signer: ethers.Signer, providerParams?: EIP4361AuthProviderParams);
+    /**
+     * Gets default domain and URI parameters based on runtime environment.
+     *
+     * @returns Default parameters object with domain and uri
+     * @returns.domain - Host domain from window.location or 'taco.build'
+     * @returns.uri - Origin URL from window.location or 'https://taco.build'
+     * @private
+     */
     private getDefaultParameters;
-    getOrCreateAuthSignature(): Promise<AuthSignature>;
-    private isMessageExpired;
+    /**
+     * Gets a valid auth signature, either from storage or by creating a new one.
+     *
+     * Process:
+     * 1. Check local storage for existing signature for the signer's address
+     * 2. If found, verify the signature and expiration time
+     * 3. If verification fails or no signature exists, create and store a new one
+     * 4. Return the valid signature
+     *
+     * @returns Promise resolving to a valid EIP-4361 auth signature containing:
+     * @returns.signature - The signed SIWE message
+     * @returns.address - The signer's Ethereum address
+     * @returns.scheme - Authentication scheme ('eip4361')
+     * @returns.typedData - Original SIWE message string
+     */
+    getOrCreateAuthSignature(): Promise<EIP4361AuthSignature>;
+    /**
+     * Creates and signs a new SIWE authentication message.
+     *
+     * Process:
+     * 1. Get signer's address and current chain ID
+     * 2. Create SIWE message with 2 hour expiration
+     * 3. Sign message with signer
+     * 4. Return signed auth signature object
+     *
+     * @returns Promise resolving to newly created and signed auth signature
+     * @private
+     */
     private createSIWEAuthMessage;
 }

package/dist/cjs/providers/eip4361/eip4361.js

@@ -1,22 +1,52 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EIP4361AuthProvider = exports.USER_ADDRESS_PARAM_DEFAULT = void 0;
+exports.EIP4361AuthProvider = exports.FRESHNESS_IN_MILLISECONDS = void 0;
 const siwe_1 = require("siwe");
 const storage_1 = require("../../storage");
-const common_1 = require("./common");
-exports.USER_ADDRESS_PARAM_DEFAULT = ':userAddress';
-const ERR_MISSING_SIWE_PARAMETERS = 'Missing default SIWE parameters';
+const auth_1 = require("./auth");
+exports.FRESHNESS_IN_MILLISECONDS = 2 * 60 * 60 * 1000;
+const TACO_DEFAULT_DOMAIN = 'taco.build';
+const TACO_DEFAULT_URI = 'https://taco.build';
+/**
+ * Implements Sign-In with Ethereum (EIP-4361/SIWE) authentication by managing SIWE message lifecycle.
+ *
+ * This provider handles:
+ * - Creating and signing new SIWE messages
+ * - Storing signed messages in local storage
+ * - Retrieving and validating stored messages
+ * - Automatically refreshing expired messages
+ *
+ * Messages are valid for 2 hours from creation and stored locally keyed by the signer's address.
+ *
+ * @implements {AuthProvider}
+ */
 class EIP4361AuthProvider {
     provider;
     signer;
     storage;
     providerParams;
-    constructor(
-    // TODO: We only need the provider to fetch the chainId, consider removing it
-    provider, signer, providerParams) {
+    /**
+     * Creates a new EIP4361AuthProvider instance.
+     *
+     * @param provider - Ethers provider used to fetch the current chainId
+     * @param signer - Ethers signer used to sign SIWE messages
+     * @param providerParams - Optional SIWE message configuration
+     * @param providerParams.domain - Domain name for the signing request (e.g. 'app.example.com').
+     *                               Defaults to current website domain or 'taco.build'
+     * @param providerParams.uri - Full URI of signing request origin (e.g. 'https://app.example.com').
+     *                            Defaults to current website URL or 'https://taco.build'
+     *
+     * The SIWE message will include:
+     * - A human-readable statement: "{domain} wants you to sign in with your Ethereum account: {address}"
+     * - Version: "1"
+     * - 2 hour expiration from creation time
+     * - Chain ID from the provided provider
+     * - Nonce: Auto-generated
+     */
+    constructor(provider, signer, providerParams) {
         this.provider = provider;
         this.signer = signer;
-        this.storage = new storage_1.LocalStorage();
+        this.storage = new storage_1.LocalStorage(auth_1.eip4361AuthSignatureSchema);
         if (providerParams) {
             this.providerParams = providerParams;
         }
@@ -24,6 +54,14 @@ class EIP4361AuthProvider {
             this.providerParams = this.getDefaultParameters();
         }
     }
+    /**
+     * Gets default domain and URI parameters based on runtime environment.
+     *
+     * @returns Default parameters object with domain and uri
+     * @returns.domain - Host domain from window.location or 'taco.build'
+     * @returns.uri - Origin URL from window.location or 'https://taco.build'
+     * @private
+     */
     getDefaultParameters() {
         if (typeof window !== 'undefined') {
             // If we are in a browser environment, we can get the domain and uri from the window object
@@ -32,45 +70,65 @@ class EIP4361AuthProvider {
                 uri: window.location?.origin,
             };
         }
-        // If not, we have no choice but to throw an error
-        throw new Error(ERR_MISSING_SIWE_PARAMETERS);
+        // not in a browser environment, use hardcoded defaults
+        return {
+            domain: TACO_DEFAULT_DOMAIN,
+            uri: TACO_DEFAULT_URI,
+        };
     }
+    /**
+     * Gets a valid auth signature, either from storage or by creating a new one.
+     *
+     * Process:
+     * 1. Check local storage for existing signature for the signer's address
+     * 2. If found, verify the signature and expiration time
+     * 3. If verification fails or no signature exists, create and store a new one
+     * 4. Return the valid signature
+     *
+     * @returns Promise resolving to a valid EIP-4361 auth signature containing:
+     * @returns.signature - The signed SIWE message
+     * @returns.address - The signer's Ethereum address
+     * @returns.scheme - Authentication scheme ('eip4361')
+     * @returns.typedData - Original SIWE message string
+     */
     async getOrCreateAuthSignature() {
         const address = await this.signer.getAddress();
-        const storageKey = `eth-${common_1.EIP4361_AUTH_METHOD}-message-${address}`;
+        const storageKey = `eth-${auth_1.EIP4361_AUTH_METHOD}-message-${address}`;
         // If we have a signature in localStorage, return it
         const maybeSignature = this.storage.getAuthSignature(storageKey);
         if (maybeSignature) {
-            // check whether older than node freshness requirement
-            if (this.isMessageExpired(maybeSignature.typedData)) {
+            const siweMessage = new siwe_1.SiweMessage(maybeSignature.typedData);
+            try {
+                // check message validity specifically here for the `expirationTime`.
+                await siweMessage.verify({ signature: maybeSignature.signature });
+                return maybeSignature;
+            }
+            catch (e) {
                 // clear signature so that it will be recreated and stored
                 this.storage.clear(storageKey);
             }
-            else {
-                return maybeSignature;
-            }
         }
         // If at this point we didn't return, we need to create a new message
         const authMessage = await this.createSIWEAuthMessage();
         this.storage.setAuthSignature(storageKey, authMessage);
         return authMessage;
     }
-    isMessageExpired(message) {
-        const siweMessage = new siwe_1.SiweMessage(message);
-        if (!siweMessage.issuedAt) {
-            // don't expect to ever happen; but just in case
-            return false;
-        }
-        const twoHourWindow = new Date(siweMessage.issuedAt);
-        twoHourWindow.setHours(twoHourWindow.getHours() + 2);
-        const now = new Date();
-        return twoHourWindow < now;
-    }
+    /**
+     * Creates and signs a new SIWE authentication message.
+     *
+     * Process:
+     * 1. Get signer's address and current chain ID
+     * 2. Create SIWE message with 2 hour expiration
+     * 3. Sign message with signer
+     * 4. Return signed auth signature object
+     *
+     * @returns Promise resolving to newly created and signed auth signature
+     * @private
+     */
     async createSIWEAuthMessage() {
         const address = await this.signer.getAddress();
         const { domain, uri } = this.providerParams;
         const version = '1';
-        const nonce = (0, siwe_1.generateNonce)();
         const chainId = (await this.provider.getNetwork()).chainId;
         const siweMessage = new siwe_1.SiweMessage({
             domain,
@@ -78,10 +136,11 @@ class EIP4361AuthProvider {
             statement: `${domain} wants you to sign in with your Ethereum account: ${address}`,
             uri,
             version,
-            nonce,
             chainId,
+            // set the expirationTime to 2 hours from now
+            expirationTime: new Date(Date.now() + exports.FRESHNESS_IN_MILLISECONDS).toISOString(),
         });
-        const scheme = common_1.EIP4361_AUTH_METHOD;
+        const scheme = auth_1.EIP4361_AUTH_METHOD;
         const message = siweMessage.prepareMessage();
         const signature = await this.signer.signMessage(message);
         return { signature, address, scheme, typedData: message };

package/dist/cjs/providers/eip4361/eip4361.js.map

@@ -1 +1 @@
-{"version":3,"file":"eip4361.js","sourceRoot":"","sources":["../../../../src/providers/eip4361/eip4361.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"eip4361.js","sourceRoot":"","sources":["../../../../src/providers/eip4361/eip4361.ts"],"names":[],"mappings":"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"}

package/dist/cjs/providers/eip4361/external-eip4361.d.ts

@@ -1,10 +1,41 @@
-import { AuthSignature } from '../../auth-sig';
-export declare const USER_ADDRESS_PARAM_EXTERNAL_EIP4361 = ":userAddressExternalEIP4361";
-export declare class SingleSignOnEIP4361AuthProvider {
+import { AuthProvider } from '../../auth-provider';
+import { EIP4361AuthSignature } from './auth';
+/**
+ * SingleSignOnEIP4361AuthProvider handles Sign-In with Ethereum (EIP-4361/SIWE) authentication
+ * using an existing SIWE message and signature.
+ *
+ * This provider validates and reuses an existing SIWE message and signature rather than generating new ones.
+ * It's useful for implementing single sign-on flows where the SIWE authentication was performed elsewhere.
+ */
+export declare class SingleSignOnEIP4361AuthProvider implements AuthProvider {
     private readonly existingSiweMessage;
     readonly address: string;
     private readonly signature;
+    /**
+     * Creates a new SingleSignOnEIP4361AuthProvider from an existing SIWE message and signature.
+     *
+     * @param existingSiweMessage - The existing SIWE message string to validate and reuse
+     * @param signature - The signature corresponding to the SIWE message
+     * @returns A new SingleSignOnEIP4361AuthProvider instance
+     * @throws {Error} If signature verification fails or message parameters are invalid
+     */
     static fromExistingSiweInfo(existingSiweMessage: string, signature: string): Promise<SingleSignOnEIP4361AuthProvider>;
+    /**
+     * Private constructor - use fromExistingSiweInfo() to create instances.
+     *
+     * @param existingSiweMessage - The validated SIWE message string
+     * @param address - The Ethereum address that signed the message
+     * @param signature - The validated signature
+     */
     private constructor();
-    getOrCreateAuthSignature(): Promise<AuthSignature>;
+    /**
+     * Returns the existing auth signature after re-validating it.
+     *
+     * This method verifies that the stored signature and message are still valid
+     * before returning them as an EIP4361AuthSignature object.
+     *
+     * @returns {Promise<EIP4361AuthSignature>} The validated authentication signature
+     * @throws {Error} If signature verification fails
+     */
+    getOrCreateAuthSignature(): Promise<EIP4361AuthSignature>;
 }