@mastra/auth-clerk 1.0.2-alpha.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @mastra/auth-clerk
 
+## 1.1.0
+
+### Minor Changes
+
+- Added full Studio authentication support for Clerk users. ([#16659](https://github.com/mastra-ai/mastra/pull/16659))
+
+  **What's new:**
+  - **Studio SSO login** — your internal team can now sign in to Mastra Studio using their Clerk accounts via OAuth 2.0/OIDC
+  - **JWT validation** — API requests with Clerk-issued JWTs are automatically validated
+  - **Session persistence** — Studio sessions are maintained with encrypted cookies (no need to log in repeatedly)
+
+  **Setup:**
+  1. Create an OAuth Application in your Clerk Dashboard
+  2. Configure the auth provider with your Clerk credentials
+
+  ```typescript
+  import { MastraAuthClerk } from '@mastra/auth-clerk';
+
+  const auth = new MastraAuthClerk({
+    jwksUri: process.env.CLERK_JWKS_URI,
+    secretKey: process.env.CLERK_SECRET_KEY,
+    publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+    // For Studio SSO login:
+    oauthClientId: process.env.CLERK_OAUTH_CLIENT_ID,
+    oauthClientSecret: process.env.CLERK_OAUTH_CLIENT_SECRET,
+    session: { cookiePassword: process.env.CLERK_COOKIE_PASSWORD },
+  });
+  ```
+
+  **Note:** This release includes updates to `@mastra/core` (ISSOProvider interface now supports async getLoginUrl) and `@mastra/server` (handles async login URLs). All three packages should be updated together.
+
+### Patch Changes
+
+- Updated dependencies [[`de66bb0`](https://github.com/mastra-ai/mastra/commit/de66bb040570444c702ce4d8e1e228a5de2949cb), [`67bf8e2`](https://github.com/mastra-ai/mastra/commit/67bf8e206dfe583954d96015cf0d09f7ac50e45f), [`8216d05`](https://github.com/mastra-ai/mastra/commit/8216d0528d866eb9a07f5d4c87ea3bb1e1139b45), [`d18b23c`](https://github.com/mastra-ai/mastra/commit/d18b23c5e29dfc381e73e3c51fcf6c779afd1823), [`5eb94eb`](https://github.com/mastra-ai/mastra/commit/5eb94ebcf66d4e28c9e26d5821ac93379bab20a0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`f9ee2ac`](https://github.com/mastra-ai/mastra/commit/f9ee2ac661af584e61bc063ac208c9035cd752ef), [`c853d53`](https://github.com/mastra-ai/mastra/commit/c853d535d2df84ab89db1adb4c28900c54c9a2d2), [`d8df1f8`](https://github.com/mastra-ai/mastra/commit/d8df1f8e947e1966c9d4e54713df56d0d0d65226), [`9192ddb`](https://github.com/mastra-ai/mastra/commit/9192ddbced8949113b30de444cbe763f075b59f5), [`ae96523`](https://github.com/mastra-ai/mastra/commit/ae965231f562d9766b0c90c49a69fc68acaa031c), [`17d5a92`](https://github.com/mastra-ai/mastra/commit/17d5a9211aa293b4d4418de3de70dc0394d58101), [`5573693`](https://github.com/mastra-ai/mastra/commit/5573693b589822250e20dfe6cf66e9ff3bc96da8), [`ec4da8a`](https://github.com/mastra-ai/mastra/commit/ec4da8a09e0d2ab452c6ee2c786042ea826b77e5), [`adc44e1`](https://github.com/mastra-ai/mastra/commit/adc44e13c7e570b91e86b20ea7556e61d819db31), [`ed346c0`](https://github.com/mastra-ai/mastra/commit/ed346c0bee2d8496690a4e538bfba1e46894660f), [`c9ce1b2`](https://github.com/mastra-ai/mastra/commit/c9ce1b28d10871110648f9d7b6d76e880b9fa999), [`3ef01fd`](https://github.com/mastra-ai/mastra/commit/3ef01fd130b53d5bd4f828beb174e516a2eb1158), [`245a9a3`](https://github.com/mastra-ai/mastra/commit/245a9a315705fce17ddd980f78a92504b6615c4a), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`38b5de8`](https://github.com/mastra-ai/mastra/commit/38b5de8e5d1d41a69522addf53d96f4b3a1d5bf0), [`dc0b611`](https://github.com/mastra-ai/mastra/commit/dc0b6119b769bd00ee2c5df9259fb376fe63077a), [`dd6a66e`](https://github.com/mastra-ai/mastra/commit/dd6a66ea0b32e0dea8059aec6b35d151e2c87dc4), [`d785c59`](https://github.com/mastra-ai/mastra/commit/d785c593b67fcb4cdc4fab9fdbde5f3b7665efc0), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`8b984f4`](https://github.com/mastra-ai/mastra/commit/8b984f4361c202270ceb69257185c4756c9a7c56), [`bf08402`](https://github.com/mastra-ai/mastra/commit/bf084022374fa5d06ca70ed67a86dd64e379071b), [`81fe587`](https://github.com/mastra-ai/mastra/commit/81fe587275035715c1720ddf3fee0505cf053036), [`1fa3e12`](https://github.com/mastra-ai/mastra/commit/1fa3e123582b63cfe49de4ee52dc6a065e8d956a), [`403c438`](https://github.com/mastra-ai/mastra/commit/403c438e417278989ce247233d2c465b8d902cdd), [`f8ba195`](https://github.com/mastra-ai/mastra/commit/f8ba1954e27ee2b20586cc6cd9cf13c002c232f2)]:
+  - @mastra/core@1.43.0
+
+## 1.0.2
+
+### Patch Changes
+
+- Updated dependencies [[`6b7aa31`](https://github.com/mastra-ai/mastra/commit/6b7aa31e2506b03f5cbcc387dd51bf281804ad73)]:
+  - @mastra/auth@1.0.2
+
 ## 1.0.2-alpha.0
 
 ### Patch Changes

package/dist/index.cjs

@@ -2,168 +2,117 @@
 
 var backend = require('@clerk/backend');
 var auth = require('@mastra/auth');
+var server = require('@mastra/core/server');
 
 // src/index.ts
-
-// ../../packages/core/dist/chunk-X2WMFSPB.js
-var RegisteredLogger = {
-  LLM: "LLM"};
-var LogLevel = {
-  DEBUG: "debug",
-  INFO: "info",
-  WARN: "warn",
-  ERROR: "error"};
-var MastraLogger = class {
-  name;
-  level;
-  transports;
-  constructor(options = {}) {
-    this.name = options.name || "Mastra";
-    this.level = options.level || LogLevel.ERROR;
-    this.transports = new Map(Object.entries(options.transports || {}));
-  }
-  getTransports() {
-    return this.transports;
-  }
-  trackException(_error) {
-  }
-  async listLogs(transportId, params) {
-    if (!transportId || !this.transports.has(transportId)) {
-      return { logs: [], total: 0, page: params?.page ?? 1, perPage: params?.perPage ?? 100, hasMore: false };
-    }
-    return this.transports.get(transportId).listLogs(params) ?? {
-      logs: [],
-      total: 0,
-      page: params?.page ?? 1,
-      perPage: params?.perPage ?? 100,
-      hasMore: false
-    };
-  }
-  async listLogsByRunId({
-    transportId,
-    runId,
-    fromDate,
-    toDate,
-    logLevel,
-    filters,
-    page,
-    perPage
-  }) {
-    if (!transportId || !this.transports.has(transportId) || !runId) {
-      return { logs: [], total: 0, page: page ?? 1, perPage: perPage ?? 100, hasMore: false };
-    }
-    return this.transports.get(transportId).listLogsByRunId({ runId, fromDate, toDate, logLevel, filters, page, perPage }) ?? {
-      logs: [],
-      total: 0,
-      page: page ?? 1,
-      perPage: perPage ?? 100,
-      hasMore: false
-    };
-  }
-};
-var ConsoleLogger = class extends MastraLogger {
-  constructor(options = {}) {
-    super(options);
-  }
-  debug(message, ...args) {
-    if (this.level === LogLevel.DEBUG) {
-      console.info(message, ...args);
-    }
-  }
-  info(message, ...args) {
-    if (this.level === LogLevel.INFO || this.level === LogLevel.DEBUG) {
-      console.info(message, ...args);
-    }
-  }
-  warn(message, ...args) {
-    if (this.level === LogLevel.WARN || this.level === LogLevel.INFO || this.level === LogLevel.DEBUG) {
-      console.info(message, ...args);
-    }
+var DEFAULT_COOKIE_NAME = "clerk_session";
+var DEFAULT_COOKIE_MAX_AGE = 86400;
+var DEFAULT_SCOPES = ["openid", "profile", "email"];
+var SALT_LENGTH = 16;
+var IV_LENGTH = 12;
+async function deriveKey(password, salt, usage) {
+  const encoder = new TextEncoder();
+  const keyMaterial = await crypto.subtle.importKey("raw", encoder.encode(password), "PBKDF2", false, [
+    "deriveBits",
+    "deriveKey"
+  ]);
+  return crypto.subtle.deriveKey(
+    { name: "PBKDF2", salt, iterations: 1e5, hash: "SHA-256" },
+    keyMaterial,
+    { name: "AES-GCM", length: 256 },
+    false,
+    [usage]
+  );
+}
+async function encryptSession(data, password) {
+  const encoder = new TextEncoder();
+  const salt = crypto.getRandomValues(new Uint8Array(SALT_LENGTH));
+  const key = await deriveKey(password, salt, "encrypt");
+  const iv = crypto.getRandomValues(new Uint8Array(IV_LENGTH));
+  const encrypted = await crypto.subtle.encrypt({ name: "AES-GCM", iv }, key, encoder.encode(JSON.stringify(data)));
+  const combined = new Uint8Array(salt.length + iv.length + new Uint8Array(encrypted).length);
+  combined.set(salt);
+  combined.set(iv, salt.length);
+  combined.set(new Uint8Array(encrypted), salt.length + iv.length);
+  return btoa(String.fromCharCode(...combined));
+}
+async function decryptSession(encrypted, password) {
+  const combined = Uint8Array.from(atob(encrypted), (c) => c.charCodeAt(0));
+  const salt = combined.slice(0, SALT_LENGTH);
+  const iv = combined.slice(SALT_LENGTH, SALT_LENGTH + IV_LENGTH);
+  const data = combined.slice(SALT_LENGTH + IV_LENGTH);
+  const key = await deriveKey(password, salt, "decrypt");
+  const decrypted = await crypto.subtle.decrypt({ name: "AES-GCM", iv }, key, data);
+  return JSON.parse(new TextDecoder().decode(decrypted));
+}
+var STATE_TOKEN_EXPIRY_MS = 10 * 60 * 1e3;
+async function hmacSign(data, secret) {
+  const encoder = new TextEncoder();
+  const keyData = encoder.encode(secret);
+  const dataBytes = encoder.encode(data);
+  const cryptoKey = await crypto.subtle.importKey("raw", keyData, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const signature = await crypto.subtle.sign("HMAC", cryptoKey, dataBytes);
+  const sigBytes = new Uint8Array(signature);
+  return btoa(String.fromCharCode(...sigBytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let result = 0;
+  for (let i = 0; i < a.length; i++) {
+    result |= a.charCodeAt(i) ^ b.charCodeAt(i);
   }
-  error(message, ...args) {
-    if (this.level === LogLevel.ERROR || this.level === LogLevel.WARN || this.level === LogLevel.INFO || this.level === LogLevel.DEBUG) {
-      console.error(message, ...args);
-    }
+  return result === 0;
+}
+async function createStateToken(originalState, redirectUri, secret) {
+  const payload = {
+    s: originalState,
+    r: redirectUri,
+    e: Date.now() + STATE_TOKEN_EXPIRY_MS
+  };
+  const payloadB64 = btoa(JSON.stringify(payload));
+  const signature = await hmacSign(payloadB64, secret);
+  return `${payloadB64}.${signature}`;
+}
+async function verifyStateToken(stateToken, secret) {
+  const parts = stateToken.split(".");
+  if (parts.length !== 2) {
+    throw new Error("Invalid state token format");
   }
-  async listLogs(_transportId, _params) {
-    return { logs: [], total: 0, page: _params?.page ?? 1, perPage: _params?.perPage ?? 100, hasMore: false };
+  const [payloadB64, signature] = parts;
+  const expectedSig = await hmacSign(payloadB64, secret);
+  if (!timingSafeEqual(signature, expectedSig)) {
+    throw new Error("Invalid state token signature");
   }
-  async listLogsByRunId(_args) {
-    return { logs: [], total: 0, page: _args.page ?? 1, perPage: _args.perPage ?? 100, hasMore: false };
+  const payload = JSON.parse(atob(payloadB64));
+  if (payload.e < Date.now()) {
+    throw new Error("State token has expired");
   }
-};
-
-// ../../packages/core/dist/chunk-WCAFTXGK.js
-var MastraBase = class {
-  component = RegisteredLogger.LLM;
-  logger;
-  name;
-  #rawConfig;
-  constructor({
-    component,
-    name,
-    rawConfig
-  }) {
-    this.component = component || RegisteredLogger.LLM;
-    this.name = name;
-    this.#rawConfig = rawConfig;
-    this.logger = new ConsoleLogger({ name: `${this.component} - ${this.name}` });
-  }
-  /**
-   * Returns the raw storage configuration this primitive was created from,
-   * or undefined if it was created from code.
-   */
-  toRawConfig() {
-    return this.#rawConfig;
-  }
-  /**
-   * Sets the raw storage configuration for this primitive.
-   * @internal
-   */
-  __setRawConfig(rawConfig) {
-    this.#rawConfig = rawConfig;
-  }
-  /**
-   * Set the logger for the agent
-   * @param logger
-   */
-  __setLogger(logger) {
-    this.logger = logger;
-    if (this.component !== RegisteredLogger.LLM) {
-      this.logger.debug(`Logger updated [component=${this.component}] [name=${this.name}]`);
-    }
-  }
-};
-
-// ../../packages/core/dist/server/index.js
-var MastraAuthProvider = class extends MastraBase {
-  protected;
-  public;
-  constructor(options) {
-    super({ component: "AUTH", name: options?.name });
-    if (options?.authorizeUser) {
-      this.authorizeUser = options.authorizeUser.bind(this);
-    }
-    this.protected = options?.protected;
-    this.public = options?.public;
-  }
-  registerOptions(opts) {
-    if (opts?.authorizeUser) {
-      this.authorizeUser = opts.authorizeUser.bind(this);
-    }
-    if (opts?.protected) {
-      this.protected = opts.protected;
-    }
-    if (opts?.public) {
-      this.public = opts.public;
-    }
-  }
-};
-
-// src/index.ts
-var MastraAuthClerk = class extends MastraAuthProvider {
+  return { originalState: payload.s, redirectUri: payload.r };
+}
+function escapeRegex(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function deriveFapiUrl(publishableKey) {
+  const withoutPrefix = publishableKey.replace(/^pk_(test|live)_/, "");
+  const decoded = atob(withoutPrefix);
+  const domain = decoded.replace(/\$$/, "");
+  return `https://${domain}`;
+}
+var MastraAuthClerk = class extends server.MastraAuthProvider {
   clerk;
   jwksUri;
+  publishableKey;
+  fapiUrl;
+  // SSO fields
+  oauthClientId;
+  oauthClientSecret;
+  _redirectUri;
+  scopes;
+  cookieName;
+  cookieMaxAge;
+  cookiePassword;
+  secureCookies;
+  ssoEnabled;
   constructor(options) {
     super({ name: options?.name ?? "clerk" });
     const jwksUri = options?.jwksUri ?? process.env.CLERK_JWKS_URI;
@@ -175,18 +124,317 @@ var MastraAuthClerk = class extends MastraAuthProvider {
       );
     }
     this.jwksUri = jwksUri;
+    this.publishableKey = publishableKey;
+    this.fapiUrl = deriveFapiUrl(publishableKey);
     this.clerk = backend.createClerkClient({
       secretKey,
       publishableKey
     });
+    const oauthClientId = options?.oauthClientId ?? process.env.CLERK_OAUTH_CLIENT_ID;
+    const oauthClientSecret = options?.oauthClientSecret ?? process.env.CLERK_OAUTH_CLIENT_SECRET;
+    const redirectUri = options?.redirectUri ?? process.env.CLERK_OAUTH_REDIRECT_URI;
+    const cookiePassword = options?.session?.cookiePassword ?? process.env.CLERK_COOKIE_PASSWORD ?? crypto.randomUUID() + crypto.randomUUID();
+    this.oauthClientId = oauthClientId ?? null;
+    this.oauthClientSecret = oauthClientSecret ?? null;
+    this._redirectUri = redirectUri ?? null;
+    this.scopes = options?.scopes ?? DEFAULT_SCOPES;
+    this.cookieName = options?.session?.cookieName ?? DEFAULT_COOKIE_NAME;
+    this.cookieMaxAge = options?.session?.cookieMaxAge ?? DEFAULT_COOKIE_MAX_AGE;
+    this.cookiePassword = cookiePassword;
+    this.secureCookies = options?.session?.secureCookies ?? process.env.NODE_ENV === "production";
+    this.ssoEnabled = !!(oauthClientId && oauthClientSecret);
+    if (this.ssoEnabled) {
+      if (cookiePassword.length < 32) {
+        throw new Error(
+          "Cookie password must be at least 32 characters for SSO. Set CLERK_COOKIE_PASSWORD environment variable."
+        );
+      }
+      if (!options?.session?.cookiePassword && !process.env.CLERK_COOKIE_PASSWORD) {
+        console.warn(
+          "[MastraAuthClerk] No cookie password set \u2014 using auto-generated value. Sessions will not survive restarts. Set CLERK_COOKIE_PASSWORD for production use."
+        );
+      }
+      this._attachSSOProvider();
+      this._attachSessionProvider();
+    }
     this.registerOptions(options);
   }
-  async authenticateToken(token) {
-    const user = await auth.verifyJwks(token, this.jwksUri);
-    return user;
+  // ============================================================================
+  // MastraAuthProvider Implementation
+  // ============================================================================
+  async authenticateToken(token, request) {
+    if (this.ssoEnabled && request) {
+      const sessionUser = await this.getUserFromSessionCookie(request);
+      if (sessionUser) return sessionUser;
+    }
+    if (!token || typeof token !== "string") {
+      return null;
+    }
+    try {
+      const user = await auth.verifyJwks(token, this.jwksUri);
+      return user;
+    } catch {
+      return null;
+    }
   }
   async authorizeUser(user) {
-    return !!user.sub;
+    return !!(user.sub || user.id);
+  }
+  // ============================================================================
+  // IUserProvider Implementation
+  // ============================================================================
+  /**
+   * Extract the bearer token from the request's Authorization header or __session cookie.
+   */
+  extractToken(request) {
+    const authHeader = request.headers.get("Authorization");
+    if (authHeader) {
+      const token = authHeader.replace(/^Bearer\s+/i, "").trim();
+      if (token) return token;
+    }
+    const cookie = request.headers.get("Cookie");
+    if (cookie) {
+      const match = cookie.match(/__session=([^;]+)/);
+      if (match?.[1]) return match[1];
+    }
+    return null;
+  }
+  async getCurrentUser(request) {
+    if (this.ssoEnabled) {
+      const sessionUser = await this.getUserFromSessionCookie(request);
+      if (sessionUser) return sessionUser;
+    }
+    const token = this.extractToken(request);
+    if (!token) return null;
+    try {
+      const payload = await this.authenticateToken(token);
+      if (!payload?.sub) return null;
+      try {
+        const clerkUser = await this.clerk.users.getUser(payload.sub);
+        return {
+          id: clerkUser.id,
+          email: clerkUser.emailAddresses?.[0]?.emailAddress,
+          name: [clerkUser.firstName, clerkUser.lastName].filter(Boolean).join(" ") || void 0,
+          avatarUrl: clerkUser.imageUrl,
+          metadata: clerkUser.publicMetadata
+        };
+      } catch {
+        return {
+          id: payload.sub,
+          email: payload.email ?? void 0,
+          name: payload.name ?? void 0
+        };
+      }
+    } catch {
+      return null;
+    }
+  }
+  async getUser(userId) {
+    try {
+      const clerkUser = await this.clerk.users.getUser(userId);
+      return {
+        id: clerkUser.id,
+        email: clerkUser.emailAddresses?.[0]?.emailAddress,
+        name: [clerkUser.firstName, clerkUser.lastName].filter(Boolean).join(" ") || void 0,
+        avatarUrl: clerkUser.imageUrl,
+        metadata: clerkUser.publicMetadata
+      };
+    } catch {
+      return null;
+    }
+  }
+  getUserProfileUrl(user) {
+    return `/user/${user.id}`;
+  }
+  // ============================================================================
+  // Helper Methods
+  // ============================================================================
+  /**
+   * Check if SSO is enabled (OAuth credentials are configured).
+   */
+  isSSOEnabled() {
+    return this.ssoEnabled;
+  }
+  /**
+   * Get the derived Frontend API URL.
+   */
+  getFapiUrl() {
+    return this.fapiUrl;
+  }
+  /**
+   * Build consistent cookie attribute string for set/clear operations.
+   */
+  cookieFlags(maxAge) {
+    const flags = `Path=/; HttpOnly; SameSite=Lax; Max-Age=${maxAge}`;
+    return this.secureCookies ? `${flags}; Secure` : flags;
+  }
+  /**
+   * Extract user from the encrypted SSO session cookie.
+   */
+  async getUserFromSessionCookie(request) {
+    const cookie = "header" in request && typeof request.header === "function" ? request.header("cookie") : request.headers?.get("cookie");
+    if (!cookie) return null;
+    const match = cookie.match(new RegExp(`(?:^|;\\s*)${escapeRegex(this.cookieName)}=([^;]+)`));
+    if (!match?.[1]) return null;
+    try {
+      const sessionData = await decryptSession(decodeURIComponent(match[1]), this.cookiePassword);
+      if (sessionData.expiresAt < Date.now()) {
+        return null;
+      }
+      return sessionData.user;
+    } catch {
+      return null;
+    }
+  }
+  // ============================================================================
+  // Dynamic ISSOProvider attachment (only when OAuth is configured)
+  // ============================================================================
+  /**
+   * Dynamically attach ISSOProvider methods to this instance.
+   * This ensures duck-typing detection only finds these methods when SSO is configured.
+   */
+  _attachSSOProvider() {
+    const self = this;
+    this.getLoginUrl = async function(redirectUri, state) {
+      const actualRedirectUri = redirectUri ?? self._redirectUri;
+      if (!actualRedirectUri) {
+        throw new Error("Redirect URI is required for SSO login");
+      }
+      const signedState = await createStateToken(state, actualRedirectUri, self.cookiePassword);
+      const params = new URLSearchParams({
+        client_id: self.oauthClientId,
+        response_type: "code",
+        scope: self.scopes.join(" "),
+        redirect_uri: actualRedirectUri,
+        state: signedState
+      });
+      return `${self.fapiUrl}/oauth/authorize?${params.toString()}`;
+    };
+    this.handleCallback = async function(code, stateToken) {
+      const { redirectUri } = await verifyStateToken(stateToken, self.cookiePassword);
+      const tokenResponse = await fetch(`${self.fapiUrl}/oauth/token`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/x-www-form-urlencoded",
+          Authorization: `Basic ${btoa(`${self.oauthClientId}:${self.oauthClientSecret}`)}`
+        },
+        body: new URLSearchParams({
+          grant_type: "authorization_code",
+          code,
+          redirect_uri: redirectUri
+        }),
+        signal: AbortSignal.timeout(1e4)
+        // 10 second timeout
+      });
+      if (!tokenResponse.ok) {
+        const error = await tokenResponse.text();
+        throw new Error(`Token exchange failed: ${error}`);
+      }
+      const tokens = await tokenResponse.json();
+      let user;
+      if (tokens.id_token) {
+        const payload = await auth.verifyJwks(tokens.id_token, self.jwksUri);
+        user = {
+          id: payload.sub,
+          email: payload.email ?? void 0,
+          name: payload.name ?? void 0,
+          avatarUrl: payload.picture ?? void 0
+        };
+      } else {
+        const userInfoResponse = await fetch(`${self.fapiUrl}/oauth/userinfo`, {
+          headers: { Authorization: `Bearer ${tokens.access_token}` },
+          signal: AbortSignal.timeout(1e4)
+          // 10 second timeout
+        });
+        if (!userInfoResponse.ok) {
+          throw new Error("Failed to fetch user info from Clerk");
+        }
+        const userInfo = await userInfoResponse.json();
+        user = {
+          id: userInfo.sub,
+          email: userInfo.email,
+          name: userInfo.name,
+          avatarUrl: userInfo.picture
+        };
+      }
+      try {
+        const fullUser = await self.getUser(user.id);
+        if (fullUser) {
+          user = fullUser;
+        }
+      } catch {
+      }
+      const sessionData = {
+        user,
+        expiresAt: Date.now() + self.cookieMaxAge * 1e3
+      };
+      const encryptedSession = await encryptSession(sessionData, self.cookiePassword);
+      const cookieValue = `${self.cookieName}=${encodeURIComponent(encryptedSession)}; ${self.cookieFlags(self.cookieMaxAge)}`;
+      return {
+        user,
+        tokens: {
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+          idToken: tokens.id_token,
+          expiresAt: new Date(Date.now() + tokens.expires_in * 1e3)
+        },
+        cookies: [cookieValue]
+      };
+    };
+    this.getLoginButtonConfig = function() {
+      return {
+        provider: "clerk",
+        text: "Sign in with Clerk",
+        description: "Sign in using your Clerk account"
+      };
+    };
+    this.getLoginCookies = function(_state) {
+      return [];
+    };
+    this.getLogoutUrl = async function(_redirectUri, _request) {
+      return null;
+    };
+  }
+  // ============================================================================
+  // Dynamic ISessionProvider attachment (only when OAuth is configured)
+  // ============================================================================
+  /**
+   * Dynamically attach ISessionProvider methods to this instance.
+   */
+  _attachSessionProvider() {
+    const self = this;
+    this.createSession = async function(userId, metadata) {
+      const now = /* @__PURE__ */ new Date();
+      return {
+        id: crypto.randomUUID(),
+        userId,
+        createdAt: now,
+        expiresAt: new Date(now.getTime() + self.cookieMaxAge * 1e3),
+        metadata
+      };
+    };
+    this.validateSession = async function(_sessionId) {
+      return null;
+    };
+    this.destroySession = async function(_sessionId) {
+    };
+    this.refreshSession = async function(_sessionId) {
+      return null;
+    };
+    this.getSessionIdFromRequest = function(request) {
+      const cookie = request.headers.get("Cookie");
+      if (!cookie) return null;
+      const match = cookie.match(new RegExp(`(?:^|;\\s*)${escapeRegex(self.cookieName)}=([^;]+)`));
+      return match?.[1] ? decodeURIComponent(match[1]) : null;
+    };
+    this.getSessionHeaders = function(_session) {
+      return {};
+    };
+    this.getClearSessionHeaders = function() {
+      return {
+        "Set-Cookie": `${self.cookieName}=; ${self.cookieFlags(0)}`
+      };
+    };
   }
 };