@rockerone/xprnkit 0.3.3 → 0.3.5

package/build/services/identity-proof/create-identity-proof.js

@@ -42,6 +42,7 @@ export async function createIdentityProof(session, options) {
         },
         transaction: txResult.resolvedTransaction,
         signatures: txResult.signatures.map(sig => sig.toString()),
+        chainId: session.chainId.toString(),
     };
     return proof;
 }

package/build/services/identity-proof/index.d.ts

@@ -1,6 +1,10 @@
-export type { IdentityProof, IdentityProofConfig, IdentityProofResult, IdentityProofSigner, IdentityProofStatus, UseIdentityProofOptions, UseIdentityProofReturn, } from "./types";
+export type { IdentityProof, IdentityProofConfig, IdentityProofResult, IdentityProofSigner, IdentityProofStatus, LegacyIdentityProofConfig, UseIdentityProofOptions, UseIdentityProofReturn, } from "./types";
 export { createIdentityProof } from "./create-identity-proof";
 export type { CreateIdentityProofOptions } from "./create-identity-proof";
 export { verifyIdentityProof } from "./verify-identity-proof";
 export type { VerifyIdentityProofOptions } from "./verify-identity-proof";
+export { validateIdentityProof } from "./validate-identity-proof";
+export type { ValidateIdentityProofOptions, ValidateIdentityProofResult, } from "./validate-identity-proof";
+export { parseToken, isTokenExpired, shouldValidateToken, getTokenExpiresIn, } from "./token-utils";
+export type { IdentityProofTokenClaims } from "./token-utils";
 export { useIdentityProof } from "./use-identity-proof";

package/build/services/identity-proof/index.js

@@ -1,5 +1,8 @@
 // Pure functions
 export { createIdentityProof } from "./create-identity-proof";
 export { verifyIdentityProof } from "./verify-identity-proof";
+export { validateIdentityProof } from "./validate-identity-proof";
+// Token utilities
+export { parseToken, isTokenExpired, shouldValidateToken, getTokenExpiresIn, } from "./token-utils";
 // React hook
 export { useIdentityProof } from "./use-identity-proof";

package/build/services/identity-proof/token-utils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * JWT Token utilities for identity proof validation
+ */
+/**
+ * Parsed JWT token claims relevant for identity proof
+ */
+export type IdentityProofTokenClaims = {
+    /** Expiration time (Unix timestamp in seconds) */
+    exp?: number;
+    /** Issued at time (Unix timestamp in seconds) */
+    iat?: number;
+    /** Subject (usually the actor) */
+    sub?: string;
+    /** Raw token string */
+    raw: string;
+};
+/**
+ * Parse a JWT token and extract claims.
+ * Does NOT verify the signature - that should be done by the backend.
+ *
+ * @param token - The JWT token string
+ * @returns Parsed token claims or null if parsing fails
+ */
+export declare function parseToken(token: string): IdentityProofTokenClaims | null;
+/**
+ * Check if a token is expired.
+ *
+ * @param token - Parsed token claims
+ * @returns true if token is expired or has no expiration claim
+ */
+export declare function isTokenExpired(token: IdentityProofTokenClaims): boolean;
+/**
+ * Check if a token should be validated with the backend.
+ * Validation is needed when the token is approaching expiration
+ * (within the buffer window) but not yet expired.
+ *
+ * @param token - Parsed token claims
+ * @param bufferSeconds - Time before expiration to trigger validation (default: 300 = 5 minutes)
+ * @returns true if token should be validated
+ */
+export declare function shouldValidateToken(token: IdentityProofTokenClaims, bufferSeconds?: number): boolean;
+/**
+ * Get time remaining until token expiration in seconds.
+ *
+ * @param token - Parsed token claims
+ * @returns Seconds until expiration, or 0 if expired/no exp claim
+ */
+export declare function getTokenExpiresIn(token: IdentityProofTokenClaims): number;

package/build/services/identity-proof/token-utils.js

@@ -0,0 +1,85 @@
+/**
+ * JWT Token utilities for identity proof validation
+ */
+/**
+ * Parse a JWT token and extract claims.
+ * Does NOT verify the signature - that should be done by the backend.
+ *
+ * @param token - The JWT token string
+ * @returns Parsed token claims or null if parsing fails
+ */
+export function parseToken(token) {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3) {
+            return null;
+        }
+        // Decode the payload (second part)
+        const payload = parts[1];
+        if (!payload) {
+            return null;
+        }
+        const decoded = atob(payload.replace(/-/g, "+").replace(/_/g, "/"));
+        const claims = JSON.parse(decoded);
+        return {
+            exp: claims.exp,
+            iat: claims.iat,
+            sub: claims.sub,
+            raw: token,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if a token is expired.
+ *
+ * @param token - Parsed token claims
+ * @returns true if token is expired or has no expiration claim
+ */
+export function isTokenExpired(token) {
+    if (!token.exp) {
+        // No expiration claim - consider it expired for safety
+        return true;
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return nowSeconds >= token.exp;
+}
+/**
+ * Check if a token should be validated with the backend.
+ * Validation is needed when the token is approaching expiration
+ * (within the buffer window) but not yet expired.
+ *
+ * @param token - Parsed token claims
+ * @param bufferSeconds - Time before expiration to trigger validation (default: 300 = 5 minutes)
+ * @returns true if token should be validated
+ */
+export function shouldValidateToken(token, bufferSeconds = 300) {
+    if (!token.exp) {
+        // No expiration - always validate
+        return true;
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const expiresIn = token.exp - nowSeconds;
+    // Already expired
+    if (expiresIn <= 0) {
+        return false; // Don't validate expired tokens, need full re-auth
+    }
+    // Within buffer window - should validate
+    return expiresIn <= bufferSeconds;
+}
+/**
+ * Get time remaining until token expiration in seconds.
+ *
+ * @param token - Parsed token claims
+ * @returns Seconds until expiration, or 0 if expired/no exp claim
+ */
+export function getTokenExpiresIn(token) {
+    if (!token.exp) {
+        return 0;
+    }
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    const expiresIn = token.exp - nowSeconds;
+    return Math.max(0, expiresIn);
+}

package/build/services/identity-proof/types.d.ts

@@ -14,6 +14,7 @@ export type IdentityProof = {
     signer: IdentityProofSigner;
     transaction: any;
     signatures: string[];
+    chainId: string;
 };
 /**
  * Result of identity proof verification
@@ -23,9 +24,31 @@ export type IdentityProofResult<T = any> = {
     response: T;
 };
 /**
- * Configuration for identity proof verification
+ * Configuration for identity proof (used in XPRProviderConfig.identityProof)
  */
 export type IdentityProofConfig = {
+    /** URL for creating identity proof (sign + verify) */
+    createUrl: string;
+    /** URL for validating existing tokens (optional - if not provided, tokens won't be validated) */
+    validationUrl?: string;
+    /** Time in seconds before expiration to trigger validation (default: 300 = 5 minutes) */
+    validationBuffer?: number;
+    /** Automatically authenticate on connect (default: false) */
+    enforceOnConnect?: boolean;
+    /** Automatically re-authenticate when token expires (default: false) */
+    autoReauthenticate?: boolean;
+    /** Require identity proof for the app - enables helper booleans and gate component (default: false) */
+    required?: boolean;
+    /** Additional headers for identity proof requests */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+};
+/**
+ * Legacy config type for backwards compatibility
+ * @deprecated Use IdentityProofConfig instead
+ */
+export type LegacyIdentityProofConfig = {
     authenticationUrl: string;
     headers?: Record<string, string>;
     timeout?: number;
@@ -33,7 +56,7 @@ export type IdentityProofConfig = {
 /**
  * Status of identity proof process
  */
-export type IdentityProofStatus = "idle" | "signing" | "verifying" | "success" | "error";
+export type IdentityProofStatus = "idle" | "signing" | "verifying" | "validating" | "success" | "expired" | "error";
 /**
  * Options for useIdentityProof hook
  */

package/build/services/identity-proof/use-identity-proof.js

@@ -72,8 +72,10 @@ export function useIdentityProof(options) {
             onError?.(err);
             return null;
         }
-        if (!config?.authenticationUrl) {
-            const err = new Error("Authentication URL not configured");
+        // Support both new (createUrl) and legacy (authenticationUrl) config
+        const createUrl = config?.createUrl ?? config?.authenticationUrl;
+        if (!createUrl) {
+            const err = new Error("Identity proof URL not configured");
             setError(err);
             setStatus("error");
             onError?.(err);
@@ -99,7 +101,7 @@ export function useIdentityProof(options) {
             });
             // Step 2: Verify with backend
             setStatus("verifying");
-            const response = await verifyIdentityProof(proof, config, {
+            const response = await verifyIdentityProof(proof, { createUrl, headers: config?.headers }, {
                 signal: abortController.signal,
             });
             // Success

package/build/services/identity-proof/validate-identity-proof.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Validate an existing identity proof token with the backend.
+ *
+ * This is used to extend/refresh a token that is approaching expiration
+ * without requiring a new wallet signature.
+ */
+export type ValidateIdentityProofOptions = {
+    /** The validation endpoint URL */
+    validationUrl: string;
+    /** The token to validate */
+    token: string;
+    /** Additional headers for the request */
+    headers?: Record<string, string>;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+    /** Request timeout in milliseconds */
+    timeout?: number;
+};
+export type ValidateIdentityProofResult = {
+    /** Whether the token is valid */
+    valid: boolean;
+    /** New token if refreshed, otherwise the original token */
+    token?: string;
+    /** Error message if validation failed */
+    error?: string;
+};
+/**
+ * Validates an identity proof token with the backend.
+ *
+ * The backend should check if the token is still valid and optionally
+ * return a refreshed token with extended expiration.
+ *
+ * @param options - Validation options
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```typescript
+ * const result = await validateIdentityProof({
+ *   validationUrl: '/api/auth/validate',
+ *   token: 'eyJhbGci...',
+ * });
+ *
+ * if (result.valid) {
+ *   // Token is still valid (or was refreshed)
+ *   const activeToken = result.token || originalToken;
+ * } else {
+ *   // Need full re-authentication
+ * }
+ * ```
+ */
+export declare function validateIdentityProof(options: ValidateIdentityProofOptions): Promise<ValidateIdentityProofResult>;

package/build/services/identity-proof/validate-identity-proof.js

@@ -0,0 +1,93 @@
+/**
+ * Validate an existing identity proof token with the backend.
+ *
+ * This is used to extend/refresh a token that is approaching expiration
+ * without requiring a new wallet signature.
+ */
+/**
+ * Validates an identity proof token with the backend.
+ *
+ * The backend should check if the token is still valid and optionally
+ * return a refreshed token with extended expiration.
+ *
+ * @param options - Validation options
+ * @returns Promise resolving to validation result
+ *
+ * @example
+ * ```typescript
+ * const result = await validateIdentityProof({
+ *   validationUrl: '/api/auth/validate',
+ *   token: 'eyJhbGci...',
+ * });
+ *
+ * if (result.valid) {
+ *   // Token is still valid (or was refreshed)
+ *   const activeToken = result.token || originalToken;
+ * } else {
+ *   // Need full re-authentication
+ * }
+ * ```
+ */
+export async function validateIdentityProof(options) {
+    const { validationUrl, token, headers, signal, timeout } = options;
+    // Check for abort before starting
+    if (signal?.aborted) {
+        throw new DOMException("Aborted", "AbortError");
+    }
+    // Create abort controller for timeout
+    const controller = new AbortController();
+    const timeoutId = timeout
+        ? setTimeout(() => controller.abort(), timeout)
+        : null;
+    // Link external signal to controller
+    if (signal) {
+        signal.addEventListener("abort", () => controller.abort());
+    }
+    try {
+        const response = await fetch(validationUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${token}`,
+                ...headers,
+            },
+            body: JSON.stringify({ token }),
+            signal: controller.signal,
+        });
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        // Check for abort after fetch
+        if (signal?.aborted) {
+            throw new DOMException("Aborted", "AbortError");
+        }
+        // Handle response
+        if (response.ok) {
+            const data = await response.json();
+            return {
+                valid: true,
+                token: data.token || token, // Use new token if provided, else keep original
+            };
+        }
+        // Non-OK response means invalid
+        const errorText = await response.text().catch(() => "Validation failed");
+        return {
+            valid: false,
+            error: errorText,
+        };
+    }
+    catch (err) {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+        }
+        // Re-throw abort errors
+        if (err instanceof Error && err.name === "AbortError") {
+            throw err;
+        }
+        // Return invalid for other errors
+        return {
+            valid: false,
+            error: err instanceof Error ? err.message : "Validation request failed",
+        };
+    }
+}

package/build/services/identity-proof/verify-identity-proof.d.ts

@@ -1,4 +1,4 @@
-import type { IdentityProof, IdentityProofConfig } from "./types";
+import type { IdentityProof, IdentityProofConfig, LegacyIdentityProofConfig } from "./types";
 export type VerifyIdentityProofOptions = {
     /** AbortSignal for cancellation */
     signal?: AbortSignal;
@@ -10,7 +10,7 @@ export type VerifyIdentityProofOptions = {
  * Use `createIdentityProof` first to generate the proof.
  *
  * @param proof - The identity proof from createIdentityProof
- * @param config - Configuration with authentication URL
+ * @param config - Configuration with createUrl (or legacy authenticationUrl)
  * @param options - Optional configuration (abort signal)
  * @returns Promise resolving to the backend response
  *
@@ -18,8 +18,8 @@ export type VerifyIdentityProofOptions = {
  * ```typescript
  * const proof = await createIdentityProof(session);
  * const response = await verifyIdentityProof(proof, {
- *   authenticationUrl: '/api/auth/verify'
+ *   createUrl: '/api/auth/verify'
  * });
  * ```
  */
-export declare function verifyIdentityProof<T = any>(proof: IdentityProof, config: IdentityProofConfig, options?: VerifyIdentityProofOptions): Promise<T>;
+export declare function verifyIdentityProof<T = any>(proof: IdentityProof, config: IdentityProofConfig | LegacyIdentityProofConfig, options?: VerifyIdentityProofOptions): Promise<T>;

package/build/services/identity-proof/verify-identity-proof.js

@@ -1,3 +1,13 @@
+/**
+ * Get the URL from config (supports both new and legacy config)
+ */
+function getCreateUrl(config) {
+    if ("createUrl" in config) {
+        return config.createUrl;
+    }
+    // Legacy config uses authenticationUrl
+    return config.authenticationUrl;
+}
 /**
  * Verifies an identity proof by sending it to the authentication backend.
  *
@@ -5,7 +15,7 @@
  * Use `createIdentityProof` first to generate the proof.
  *
  * @param proof - The identity proof from createIdentityProof
- * @param config - Configuration with authentication URL
+ * @param config - Configuration with createUrl (or legacy authenticationUrl)
  * @param options - Optional configuration (abort signal)
  * @returns Promise resolving to the backend response
  *
@@ -13,7 +23,7 @@
  * ```typescript
  * const proof = await createIdentityProof(session);
  * const response = await verifyIdentityProof(proof, {
- *   authenticationUrl: '/api/auth/verify'
+ *   createUrl: '/api/auth/verify'
  * });
  * ```
  */
@@ -22,6 +32,7 @@ export async function verifyIdentityProof(proof, config, options) {
     if (options?.signal?.aborted) {
         throw new DOMException("Aborted", "AbortError");
     }
+    const url = getCreateUrl(config);
     // Build request body
     const requestBody = {
         signer: {
@@ -31,6 +42,7 @@ export async function verifyIdentityProof(proof, config, options) {
         },
         transaction: proof.transaction,
         signatures: proof.signatures,
+        chainId: proof.chainId,
     };
     // Build fetch options
     const fetchOptions = {
@@ -43,7 +55,7 @@ export async function verifyIdentityProof(proof, config, options) {
         signal: options?.signal,
     };
     // Make the request
-    const response = await fetch(config.authenticationUrl, fetchOptions);
+    const response = await fetch(url, fetchOptions);
     // Check for abort after fetch
     if (options?.signal?.aborted) {
         throw new DOMException("Aborted", "AbortError");

package/build/utils/auth-storage.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Identity proof storage utilities for XPRNKit
+ *
+ * Stores all session entries in a single array per dApp for easy listing.
+ * For production apps, consider using more secure methods like httpOnly cookies or server-side sessions.
+ */
+import { LinkChannelSessionData, SerializedLinkSession } from "@proton/link";
+import { XPRNProfile } from "providers/XPRNProvider";
+/**
+ * Single session entry stored in the array
+ */
+export interface SessionStorageEntry {
+    auth: {
+        actor: string;
+        permission: string;
+    };
+    chainId: string;
+    profile: XPRNProfile;
+    /** Identity proof token (JWT) from authentication */
+    identityProofToken: string | null;
+}
+/**
+ * @deprecated Use SessionStorageEntry instead
+ */
+export type AuthStorageEntry = SessionStorageEntry;
+/**
+ * Session reference from proton-web-sdk storage
+ */
+export interface StoredSessionRef {
+    auth: {
+        actor: string;
+        permission: string;
+    };
+    chainId: string;
+}
+/**
+ * Session storage helper for client-side persistence
+ * All session entries are stored in a single array for easy listing
+ */
+export declare const sessionStorage: {
+    /**
+     * List all stored session entries for a dApp
+     * Use this to build UI components that display stored sessions
+     */
+    list: (dAppName: string) => SessionStorageEntry[];
+    /**
+     * Get a specific session entry
+     */
+    get: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string) => SessionStorageEntry | null;
+    /**
+     * Save or update a session entry
+     */
+    save: (dAppName: string, entry: SessionStorageEntry) => void;
+    /**
+     * Remove a specific session entry
+     */
+    remove: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string) => void;
+    /**
+     * Update only the identity proof token for an existing entry
+     */
+    updateIdentityProofToken: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string, token: string | null) => void;
+    /**
+     * Clear all session entries for a dApp
+     */
+    clear: (dAppName: string) => void;
+    /**
+     * Get list of sessions stored by proton-web-sdk
+     */
+    getLinkList: (dAppName: string) => StoredSessionRef[];
+    /**
+     * Get link session data from proton-web-sdk storage
+     */
+    getLink: (dAppName: string, auth: string, chainId: string) => LinkChannelSessionData | null;
+    /**
+     * Get serialized session data for restoration
+     */
+    getSerializedSession: (dAppName: string, auth: string, chainId: string) => SerializedLinkSession | null;
+};
+/**
+ * @deprecated Use sessionStorage instead
+ * Legacy authentication storage helper for backwards compatibility
+ */
+export declare const authStorage: {
+    /** @deprecated Use sessionStorage.list instead */
+    listAuth: (dAppName: string) => SessionStorageEntry[];
+    /** @deprecated Use sessionStorage.get instead */
+    getAuth: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string) => SessionStorageEntry | null;
+    /** @deprecated Use sessionStorage.save instead */
+    saveAuth: (dAppName: string, entry: SessionStorageEntry) => void;
+    /** @deprecated Use sessionStorage.remove instead */
+    removeAuth: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string) => void;
+    /** @deprecated Use sessionStorage.updateIdentityProofToken instead */
+    updateIdentityProofToken: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string, token: string | null) => void;
+    /** @deprecated Use sessionStorage.updateIdentityProofToken instead */
+    updateAuthToken: (dAppName: string, auth: {
+        actor: string;
+        permission: string;
+    }, chainId: string, authToken: string | null) => void;
+    /** @deprecated Use sessionStorage.clear instead */
+    clearAuth: (dAppName: string) => void;
+    /** @deprecated Use sessionStorage.getLinkList instead */
+    getLinkList: (dAppName: string) => StoredSessionRef[];
+    /** @deprecated Use sessionStorage.getLink instead */
+    getLink: (dAppName: string, auth: string, chainId: string) => LinkChannelSessionData | null;
+    /** @deprecated Use sessionStorage.getSerializedSession instead */
+    getSerializedSession: (dAppName: string, auth: string, chainId: string) => SerializedLinkSession | null;
+};
+export type AuthStorageData = AuthStorageEntry;