@phantom/embedded-provider-core 0.1.7 → 0.1.9

package/dist/index.d.mts

@@ -10,6 +10,8 @@ interface Keypair {
 interface StamperInfo {
     keyId: string;
     publicKey: string;
+    createdAt?: number;
+    authenticatorId?: string;
 }
 interface Session {
     sessionId: string;
@@ -22,6 +24,10 @@ interface Session {
     status: "pending" | "completed" | "failed";
     createdAt: number;
     lastUsed: number;
+    authenticatorCreatedAt: number;
+    authenticatorExpiresAt: number;
+    lastRenewalAttempt?: number;
+    username: string;
 }
 interface EmbeddedStorage {
     getSession(): Promise<Session | null>;
@@ -168,6 +174,8 @@ declare class EmbeddedProvider {
     private handleJWTAuth;
     private handleRedirectAuth;
     private completeAuthConnection;
+    private ensureValidAuthenticator;
+    private renewAuthenticator;
     private initializeClientFromSession;
 }
 
@@ -179,4 +187,20 @@ declare function generateSessionId(): string;
 
 declare function retryWithBackoff<T>(operation: () => Promise<T>, operationName: string, logger: DebugLogger, maxRetries?: number, baseDelay?: number): Promise<T>;
 
-export { AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedProviderEvent, EmbeddedStorage, EventCallback, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, StamperInfo, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };
+/**
+ * Constants for authenticator lifecycle management
+ */
+/**
+ * How long an authenticator is valid before it expires (in milliseconds)
+ * Default: 7 days
+ * For testing: Use smaller values like 5 * 60 * 1000 (5 minutes)
+ */
+declare const AUTHENTICATOR_EXPIRATION_TIME_MS: number;
+/**
+ * How long before expiration should we attempt to renew the authenticator (in milliseconds)
+ * Default: 2 days before expiration
+ * For testing: Use smaller values like 2 * 60 * 1000 (2 minutes)
+ */
+declare const AUTHENTICATOR_RENEWAL_WINDOW_MS: number;
+
+export { AUTHENTICATOR_EXPIRATION_TIME_MS, AUTHENTICATOR_RENEWAL_WINDOW_MS, AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedProviderEvent, EmbeddedStorage, EventCallback, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, StamperInfo, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };

package/dist/index.d.ts

@@ -10,6 +10,8 @@ interface Keypair {
 interface StamperInfo {
     keyId: string;
     publicKey: string;
+    createdAt?: number;
+    authenticatorId?: string;
 }
 interface Session {
     sessionId: string;
@@ -22,6 +24,10 @@ interface Session {
     status: "pending" | "completed" | "failed";
     createdAt: number;
     lastUsed: number;
+    authenticatorCreatedAt: number;
+    authenticatorExpiresAt: number;
+    lastRenewalAttempt?: number;
+    username: string;
 }
 interface EmbeddedStorage {
     getSession(): Promise<Session | null>;
@@ -168,6 +174,8 @@ declare class EmbeddedProvider {
     private handleJWTAuth;
     private handleRedirectAuth;
     private completeAuthConnection;
+    private ensureValidAuthenticator;
+    private renewAuthenticator;
     private initializeClientFromSession;
 }
 
@@ -179,4 +187,20 @@ declare function generateSessionId(): string;
 
 declare function retryWithBackoff<T>(operation: () => Promise<T>, operationName: string, logger: DebugLogger, maxRetries?: number, baseDelay?: number): Promise<T>;
 
-export { AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedProviderEvent, EmbeddedStorage, EventCallback, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, StamperInfo, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };
+/**
+ * Constants for authenticator lifecycle management
+ */
+/**
+ * How long an authenticator is valid before it expires (in milliseconds)
+ * Default: 7 days
+ * For testing: Use smaller values like 5 * 60 * 1000 (5 minutes)
+ */
+declare const AUTHENTICATOR_EXPIRATION_TIME_MS: number;
+/**
+ * How long before expiration should we attempt to renew the authenticator (in milliseconds)
+ * Default: 2 days before expiration
+ * For testing: Use smaller values like 2 * 60 * 1000 (2 minutes)
+ */
+declare const AUTHENTICATOR_RENEWAL_WINDOW_MS: number;
+
+export { AUTHENTICATOR_EXPIRATION_TIME_MS, AUTHENTICATOR_RENEWAL_WINDOW_MS, AuthOptions, AuthProvider, AuthResult, ConnectResult, DebugLogger, EmbeddedProvider, EmbeddedProviderConfig, EmbeddedProviderEvent, EmbeddedStorage, EventCallback, JWTAuth, JWTAuthOptions, Keypair, PhantomConnectOptions, PlatformAdapter, Session, SignAndSendTransactionParams, SignMessageParams, SignMessageResult, SignedTransaction, StamperInfo, URLParamsAccessor, WalletAddress, generateSessionId, retryWithBackoff };

package/dist/index.js

@@ -30,6 +30,8 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var src_exports = {};
 __export(src_exports, {
+  AUTHENTICATOR_EXPIRATION_TIME_MS: () => AUTHENTICATOR_EXPIRATION_TIME_MS,
+  AUTHENTICATOR_RENEWAL_WINDOW_MS: () => AUTHENTICATOR_RENEWAL_WINDOW_MS,
   EmbeddedProvider: () => EmbeddedProvider,
   JWTAuth: () => JWTAuth,
   generateSessionId: () => generateSessionId,
@@ -43,6 +45,10 @@ var import_base64url = require("@phantom/base64url");
 var import_bs58 = __toESM(require("bs58"));
 var import_parsers = require("@phantom/parsers");
 
+// src/constants.ts
+var AUTHENTICATOR_EXPIRATION_TIME_MS = 7 * 24 * 60 * 60 * 1e3;
+var AUTHENTICATOR_RENEWAL_WINDOW_MS = 2 * 24 * 60 * 60 * 1e3;
+
 // src/auth/jwt-auth.ts
 var JWTAuth = class {
   async authenticate(options) {
@@ -257,6 +263,14 @@ var EmbeddedProvider = class {
         return null;
       }
     }
+    if (session.status === "completed" && !this.isSessionValid(session)) {
+      this.logger.warn("EMBEDDED_PROVIDER", "Session invalid due to authenticator expiration", {
+        sessionId: session.sessionId,
+        authenticatorExpiresAt: session.authenticatorExpiresAt
+      });
+      await this.storage.clearSession();
+      return null;
+    }
     return session;
   }
   /*
@@ -291,6 +305,7 @@ var EmbeddedProvider = class {
         walletId: this.walletId,
         addressCount: this.addresses.length
       });
+      await this.ensureValidAuthenticator();
       const result = {
         walletId: this.walletId,
         addresses: this.addresses,
@@ -320,8 +335,9 @@ var EmbeddedProvider = class {
     }
   }
   /*
-   * We use this method to validate if a session is still valid and can be used for auto-connect.
-   * This checks session status, expiration, and required fields.
+   * We use this method to validate if a session is still valid.
+   * This checks session status, required fields, and authenticator expiration.
+   * Sessions never expire by age - only authenticators expire.
    */
   isSessionValid(session) {
     if (!session) {
@@ -339,20 +355,23 @@ var EmbeddedProvider = class {
       this.logger.log("EMBEDDED_PROVIDER", "Session not completed", { status: session.status });
       return false;
     }
-    const sessionAge = Date.now() - session.lastUsed;
-    const maxSessionAge = 7 * 24 * 60 * 60 * 1e3;
-    if (sessionAge > maxSessionAge) {
-      this.logger.log("EMBEDDED_PROVIDER", "Session expired", {
-        sessionAge,
-        maxSessionAge,
-        lastUsed: new Date(session.lastUsed).toISOString()
+    if (!session.authenticatorExpiresAt) {
+      this.logger.log("EMBEDDED_PROVIDER", "Session invalid - missing authenticator timing", {
+        sessionId: session.sessionId
+      });
+      return false;
+    }
+    if (Date.now() >= session.authenticatorExpiresAt) {
+      this.logger.log("EMBEDDED_PROVIDER", "Authenticator expired, session invalid", {
+        authenticatorExpiresAt: new Date(session.authenticatorExpiresAt).toISOString(),
+        now: (/* @__PURE__ */ new Date()).toISOString()
       });
       return false;
     }
     this.logger.log("EMBEDDED_PROVIDER", "Session is valid", {
       sessionId: session.sessionId,
       walletId: session.walletId,
-      lastUsed: new Date(session.lastUsed).toISOString()
+      authenticatorExpires: new Date(session.authenticatorExpiresAt).toISOString()
     });
     return true;
   }
@@ -421,9 +440,11 @@ var EmbeddedProvider = class {
       platform: platformName
     });
     const base64urlPublicKey = (0, import_base64url.base64urlEncode)(import_bs58.default.decode(stamperInfo.publicKey));
+    const expiresAtMs = Date.now() + AUTHENTICATOR_EXPIRATION_TIME_MS;
+    const username = `user-${shortPubKey}`;
     const { organizationId } = await tempClient.createOrganization(organizationName, [
       {
-        username: `user-${shortPubKey}`,
+        username,
         role: "ADMIN",
         authenticators: [
           {
@@ -431,12 +452,14 @@ var EmbeddedProvider = class {
             authenticatorKind: "keypair",
             publicKey: base64urlPublicKey,
             algorithm: "Ed25519"
+            // Commented for now until KMS supports fully expirable organizations
+            // expiresAtMs: expiresAtMs,
           }
         ]
       }
     ]);
     this.logger.info("EMBEDDED_PROVIDER", "Organization created", { organizationId });
-    return { organizationId, stamperInfo };
+    return { organizationId, stamperInfo, expiresAtMs, username };
   }
   async connect(authOptions) {
     try {
@@ -465,8 +488,8 @@ var EmbeddedProvider = class {
       }
       this.validateAuthOptions(authOptions);
       this.logger.info("EMBEDDED_PROVIDER", "No existing connection, creating new auth flow");
-      const { organizationId, stamperInfo } = await this.createOrganizationAndStamper();
-      const session = await this.handleAuthFlow(organizationId, stamperInfo, authOptions);
+      const { organizationId, stamperInfo, expiresAtMs, username } = await this.createOrganizationAndStamper();
+      const session = await this.handleAuthFlow(organizationId, stamperInfo, authOptions, expiresAtMs, username);
       if (!session) {
         return {
           addresses: [],
@@ -478,6 +501,7 @@ var EmbeddedProvider = class {
         await this.storage.saveSession(session);
       }
       await this.initializeClientFromSession(session);
+      await this.ensureValidAuthenticator();
       const result = {
         walletId: this.walletId,
         addresses: this.addresses,
@@ -543,6 +567,7 @@ var EmbeddedProvider = class {
     if (!this.client || !this.walletId) {
       throw new Error("Not connected");
     }
+    await this.ensureValidAuthenticator();
     this.logger.info("EMBEDDED_PROVIDER", "Signing message", {
       walletId: this.walletId,
       message: params.message
@@ -563,6 +588,7 @@ var EmbeddedProvider = class {
     if (!this.client || !this.walletId) {
       throw new Error("Not connected");
     }
+    await this.ensureValidAuthenticator();
     this.logger.info("EMBEDDED_PROVIDER", "Signing and sending transaction", {
       walletId: this.walletId,
       networkId: params.networkId
@@ -596,20 +622,20 @@ var EmbeddedProvider = class {
    * It handles app-wallet creation directly or routes to JWT/redirect authentication for user-wallets.
    * Returns null for redirect flows since they don't complete synchronously.
    */
-  async handleAuthFlow(organizationId, stamperInfo, authOptions) {
+  async handleAuthFlow(organizationId, stamperInfo, authOptions, expiresAtMs, username) {
     if (this.config.embeddedWalletType === "user-wallet") {
       this.logger.info("EMBEDDED_PROVIDER", "Creating user-wallet, routing authentication", {
         authProvider: authOptions?.provider || "phantom-connect"
       });
       if (authOptions?.provider === "jwt") {
-        return await this.handleJWTAuth(organizationId, stamperInfo, authOptions);
+        return await this.handleJWTAuth(organizationId, stamperInfo, authOptions, expiresAtMs, username);
       } else {
         this.logger.info("EMBEDDED_PROVIDER", "Starting redirect-based authentication flow", {
           organizationId,
           parentOrganizationId: this.config.organizationId,
           provider: authOptions?.provider
         });
-        return await this.handleRedirectAuth(organizationId, stamperInfo, authOptions);
+        return await this.handleRedirectAuth(organizationId, stamperInfo, authOptions, username);
       }
     } else {
       this.logger.info("EMBEDDED_PROVIDER", "Creating app-wallet", {
@@ -634,7 +660,11 @@ var EmbeddedProvider = class {
         userInfo: { embeddedWalletType: this.config.embeddedWalletType },
         status: "completed",
         createdAt: now,
-        lastUsed: now
+        lastUsed: now,
+        authenticatorCreatedAt: now,
+        authenticatorExpiresAt: expiresAtMs,
+        lastRenewalAttempt: void 0,
+        username
       };
       await this.storage.saveSession(session);
       this.logger.info("EMBEDDED_PROVIDER", "App-wallet created successfully", { walletId, organizationId });
@@ -645,7 +675,7 @@ var EmbeddedProvider = class {
    * We use this method to handle JWT-based authentication for user-wallets.
    * It authenticates using the provided JWT token and creates a completed session.
    */
-  async handleJWTAuth(organizationId, stamperInfo, authOptions) {
+  async handleJWTAuth(organizationId, stamperInfo, authOptions, expiresAtMs, username) {
     this.logger.info("EMBEDDED_PROVIDER", "Using JWT authentication flow");
     if (!authOptions.jwtToken) {
       this.logger.error("EMBEDDED_PROVIDER", "JWT token missing for JWT authentication");
@@ -670,7 +700,11 @@ var EmbeddedProvider = class {
       userInfo: authResult.userInfo,
       status: "completed",
       createdAt: now,
-      lastUsed: now
+      lastUsed: now,
+      authenticatorCreatedAt: now,
+      authenticatorExpiresAt: expiresAtMs,
+      lastRenewalAttempt: void 0,
+      username
     };
     this.logger.log("EMBEDDED_PROVIDER", "Saving JWT session");
     await this.storage.saveSession(session);
@@ -681,7 +715,7 @@ var EmbeddedProvider = class {
    * It saves a temporary session before redirecting to prevent losing state during the redirect flow.
    * Session timestamp is updated before redirect to prevent race conditions.
    */
-  async handleRedirectAuth(organizationId, stamperInfo, authOptions) {
+  async handleRedirectAuth(organizationId, stamperInfo, authOptions, username) {
     this.logger.info("EMBEDDED_PROVIDER", "Using Phantom Connect authentication flow (redirect-based)", {
       provider: authOptions?.provider,
       hasRedirectUrl: !!this.config.authOptions?.redirectUrl,
@@ -699,7 +733,11 @@ var EmbeddedProvider = class {
       userInfo: { provider: authOptions?.provider },
       status: "pending",
       createdAt: now,
-      lastUsed: now
+      lastUsed: now,
+      authenticatorCreatedAt: now,
+      authenticatorExpiresAt: now + AUTHENTICATOR_EXPIRATION_TIME_MS,
+      lastRenewalAttempt: void 0,
+      username: username || `user-${stamperInfo.keyId.substring(0, 8)}`
     };
     this.logger.log("EMBEDDED_PROVIDER", "Saving temporary session before redirect", {
       sessionId: tempSession.sessionId,
@@ -750,12 +788,114 @@ var EmbeddedProvider = class {
     session.lastUsed = Date.now();
     await this.storage.saveSession(session);
     await this.initializeClientFromSession(session);
+    await this.ensureValidAuthenticator();
     return {
       walletId: this.walletId,
       addresses: this.addresses,
       status: "completed"
     };
   }
+  /*
+   * Ensures the authenticator is valid and performs renewal if needed.
+   * The renewal of the authenticator can only happen meanwhile the previous authenticator is still valid. 
+   */
+  async ensureValidAuthenticator() {
+    const session = await this.storage.getSession();
+    if (!session) {
+      throw new Error("No active session found");
+    }
+    const now = Date.now();
+    if (!session.authenticatorExpiresAt) {
+      this.logger.warn("EMBEDDED_PROVIDER", "Session missing authenticator timing - treating as invalid session");
+      await this.disconnect();
+      throw new Error("Invalid session - missing authenticator timing");
+    }
+    const timeUntilExpiry = session.authenticatorExpiresAt - now;
+    this.logger.log("EMBEDDED_PROVIDER", "Checking authenticator expiration", {
+      expiresAt: new Date(session.authenticatorExpiresAt).toISOString(),
+      timeUntilExpiry
+    });
+    if (timeUntilExpiry <= 0) {
+      this.logger.error("EMBEDDED_PROVIDER", "Authenticator has expired, disconnecting");
+      await this.disconnect();
+      throw new Error("Authenticator expired");
+    }
+    const renewalWindow = AUTHENTICATOR_RENEWAL_WINDOW_MS;
+    if (timeUntilExpiry <= renewalWindow) {
+      this.logger.info("EMBEDDED_PROVIDER", "Authenticator needs renewal", {
+        expiresAt: new Date(session.authenticatorExpiresAt).toISOString(),
+        timeUntilExpiry,
+        renewalWindow
+      });
+      try {
+        await this.renewAuthenticator(session);
+        this.logger.info("EMBEDDED_PROVIDER", "Authenticator renewed successfully");
+      } catch (error) {
+        this.logger.error("EMBEDDED_PROVIDER", "Failed to renew authenticator", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+    }
+  }
+  /*
+   * We use this method to perform silent authenticator renewal.
+   * It generates a new keypair, creates a new authenticator, and switches to it.
+   */
+  async renewAuthenticator(session) {
+    if (!this.client) {
+      throw new Error("Client not initialized");
+    }
+    this.logger.info("EMBEDDED_PROVIDER", "Starting authenticator renewal");
+    try {
+      const newKeyInfo = await this.stamper.rotateKeyPair();
+      this.logger.log("EMBEDDED_PROVIDER", "Generated new keypair for renewal", {
+        newKeyId: newKeyInfo.keyId,
+        newPublicKey: newKeyInfo.publicKey
+      });
+      const base64urlPublicKey = (0, import_base64url.base64urlEncode)(import_bs58.default.decode(newKeyInfo.publicKey));
+      const expiresAtMs = Date.now() + AUTHENTICATOR_EXPIRATION_TIME_MS;
+      let authenticatorResult;
+      try {
+        authenticatorResult = await this.client.createAuthenticator({
+          organizationId: session.organizationId,
+          username: session.username,
+          authenticatorName: `auth-${newKeyInfo.keyId.substring(0, 8)}`,
+          authenticator: {
+            authenticatorName: `auth-${newKeyInfo.keyId.substring(0, 8)}`,
+            authenticatorKind: "keypair",
+            publicKey: base64urlPublicKey,
+            algorithm: "Ed25519"
+            // Commented for now until KMS supports fully expiring organizations
+            // expiresAtMs: expiresAtMs,
+          },
+          replaceExpirable: true
+        });
+      } catch (error) {
+        this.logger.error("EMBEDDED_PROVIDER", "Failed to create new authenticator", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+        await this.stamper.rollbackRotation();
+        throw new Error(`Failed to create new authenticator: ${error instanceof Error ? error.message : String(error)}`);
+      }
+      this.logger.info("EMBEDDED_PROVIDER", "Created new authenticator", {
+        authenticatorId: authenticatorResult.id
+      });
+      await this.stamper.commitRotation(authenticatorResult.id || "unknown");
+      const now = Date.now();
+      session.stamperInfo = newKeyInfo;
+      session.authenticatorCreatedAt = now;
+      session.authenticatorExpiresAt = expiresAtMs;
+      session.lastRenewalAttempt = now;
+      await this.storage.saveSession(session);
+      this.logger.info("EMBEDDED_PROVIDER", "Authenticator renewal completed successfully", {
+        newKeyId: newKeyInfo.keyId,
+        expiresAt: new Date(expiresAtMs).toISOString()
+      });
+    } catch (error) {
+      await this.stamper.rollbackRotation();
+      throw error;
+    }
+  }
   /*
    * We use this method to initialize the PhantomClient and fetch wallet addresses from a completed session.
    * This is the final step that sets up the provider's client state and retrieves available addresses.
@@ -781,6 +921,8 @@ var EmbeddedProvider = class {
 };
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AUTHENTICATOR_EXPIRATION_TIME_MS,
+  AUTHENTICATOR_RENEWAL_WINDOW_MS,
   EmbeddedProvider,
   JWTAuth,
   generateSessionId,