@imtbl/auth-next-server 2.12.5-alpha.13

package/dist/node/types.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Server-side types for @imtbl/auth-next-server
+ */
+import type { DefaultSession } from 'next-auth';
+/**
+ * zkEVM wallet information for module augmentation
+ */
+interface ZkEvmInfo {
+    ethAddress: string;
+    userAdminAddress: string;
+}
+/**
+ * Auth.js v5 module augmentation to add Immutable-specific fields
+ * This extends the Session type to include our custom fields
+ */
+declare module 'next-auth' {
+    interface Session extends DefaultSession {
+        user: {
+            sub: string;
+            email?: string;
+            nickname?: string;
+        } & DefaultSession['user'];
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+        error?: string;
+    }
+    interface User {
+        id: string;
+        sub: string;
+        email?: string | null;
+        nickname?: string;
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+    }
+}
+/**
+ * Configuration options for Immutable authentication
+ */
+export interface ImmutableAuthConfig {
+    /**
+     * Your Immutable application client ID
+     */
+    clientId: string;
+    /**
+     * The OAuth redirect URI configured in your Immutable Hub project
+     */
+    redirectUri: string;
+    /**
+     * OAuth audience (default: "platform_api")
+     */
+    audience?: string;
+    /**
+     * OAuth scopes (default: "openid profile email offline_access transact")
+     */
+    scope?: string;
+    /**
+     * The Immutable authentication domain (default: "https://auth.immutable.com")
+     */
+    authenticationDomain?: string;
+}
+/**
+ * Token data passed from client to server during authentication
+ */
+export interface ImmutableTokenData {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpires: number;
+    profile: {
+        sub: string;
+        email?: string;
+        nickname?: string;
+    };
+    zkEvm?: {
+        ethAddress: string;
+        userAdminAddress: string;
+    };
+}
+/**
+ * Response from the userinfo endpoint
+ */
+export interface UserInfoResponse {
+    sub: string;
+    email?: string;
+    email_verified?: boolean;
+    nickname?: string;
+    [key: string]: unknown;
+}
+/**
+ * zkEVM user data stored in session
+ */
+export interface ZkEvmUser {
+    ethAddress: string;
+    userAdminAddress: string;
+}
+/**
+ * Immutable user data structure
+ */
+export interface ImmutableUser {
+    sub: string;
+    email?: string;
+    nickname?: string;
+    zkEvm?: ZkEvmUser;
+}
+export {};

package/dist/node/utils/pathMatch.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Check if pathname matches a string pattern as a path prefix.
+ * Ensures proper path boundary checking: '/api' matches '/api' and '/api/users'
+ * but NOT '/apiversion' or '/api-docs'.
+ *
+ * @param pathname - The URL pathname to check
+ * @param pattern - The string pattern to match against
+ * @returns true if pathname matches the pattern with proper path boundaries
+ */
+export declare function matchPathPrefix(pathname: string, pattern: string): boolean;

package/jest.config.ts

@@ -0,0 +1,16 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  clearMocks: true,
+  coverageProvider: 'v8',
+  moduleDirectories: ['node_modules', 'src'],
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.(t|j)sx?$': '@swc/jest',
+  },
+  transformIgnorePatterns: [],
+  restoreMocks: true,
+  roots: ['<rootDir>/src'],
+};
+
+export default config;

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@imtbl/auth-next-server",
+  "version": "2.12.5-alpha.13",
+  "description": "Immutable Auth.js v5 integration for Next.js - Server-side utilities",
+  "author": "Immutable",
+  "license": "Apache-2.0",
+  "repository": "immutable/ts-immutable-sdk.git",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/node/index.cjs",
+  "module": "./dist/node/index.js",
+  "types": "./dist/node/index.d.ts",
+  "exports": {
+    ".": {
+      "development": {
+        "types": "./src/index.ts",
+        "require": "./dist/node/index.cjs",
+        "default": "./dist/node/index.js"
+      },
+      "default": {
+        "types": "./dist/node/index.d.ts",
+        "require": "./dist/node/index.cjs",
+        "default": "./dist/node/index.js"
+      }
+    }
+  },
+  "peerDependencies": {
+    "next": "^14.2.0 || ^15.0.0",
+    "next-auth": "^5.0.0-beta.25"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    },
+    "next-auth": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@swc/core": "^1.4.2",
+    "@swc/jest": "^0.2.37",
+    "@types/jest": "^29.5.12",
+    "@types/node": "^22.10.7",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "next": "^15.1.6",
+    "next-auth": "^5.0.0-beta.30",
+    "tsup": "^8.3.0",
+    "typescript": "^5.6.2"
+  },
+  "scripts": {
+    "build": "tsup && pnpm build:types",
+    "build:types": "tsc --project tsconfig.types.json",
+    "clean": "rm -rf dist",
+    "lint": "eslint src/**/*.ts --max-warnings=0",
+    "test": "jest --passWithNoTests"
+  }
+}

package/src/config.ts

@@ -0,0 +1,243 @@
+// NextAuthConfig type from next-auth v5
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore - Type exists in next-auth v5 but TS resolver may use stale types
+import type { NextAuthConfig } from 'next-auth';
+import CredentialsImport from 'next-auth/providers/credentials';
+import type { ImmutableAuthConfig, ImmutableTokenData, UserInfoResponse } from './types';
+import { isTokenExpired } from './refresh';
+import {
+  DEFAULT_AUTH_DOMAIN,
+  IMMUTABLE_PROVIDER_ID,
+  DEFAULT_SESSION_MAX_AGE_SECONDS,
+} from './constants';
+
+// Handle ESM/CJS interop - in some bundler configurations, the default export
+// may be nested under a 'default' property
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const Credentials = ((CredentialsImport as any).default || CredentialsImport) as typeof CredentialsImport;
+
+/**
+ * Validate tokens by calling the userinfo endpoint.
+ * This is the standard OAuth 2.0 way to validate access tokens server-side.
+ * The auth server validates signature, issuer, audience, and expiry.
+ *
+ * @param accessToken - The access token to validate
+ * @param authDomain - The authentication domain
+ * @returns The user info if valid, null otherwise
+ */
+async function validateTokens(
+  accessToken: string,
+  authDomain: string,
+): Promise<UserInfoResponse | null> {
+  try {
+    const response = await fetch(`${authDomain}/userinfo`, {
+      method: 'GET',
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+      },
+    });
+
+    if (!response.ok) {
+      // eslint-disable-next-line no-console
+      console.error('[auth-next-server] Token validation failed:', response.status, response.statusText);
+      return null;
+    }
+
+    return await response.json();
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error('[auth-next-server] Token validation error:', error);
+    return null;
+  }
+}
+
+/**
+ * Create Auth.js v5 configuration for Immutable authentication
+ *
+ * @example
+ * ```typescript
+ * // lib/auth.ts
+ * import NextAuth from "next-auth";
+ * import { createAuthConfig } from "@imtbl/auth-next-server";
+ *
+ * const config = {
+ *   clientId: process.env.NEXT_PUBLIC_IMMUTABLE_CLIENT_ID!,
+ *   redirectUri: `${process.env.NEXT_PUBLIC_BASE_URL}/callback`,
+ * };
+ *
+ * export const { handlers, auth, signIn, signOut } = NextAuth(createAuthConfig(config));
+ * ```
+ */
+export function createAuthConfig(config: ImmutableAuthConfig): NextAuthConfig {
+  const authDomain = config.authenticationDomain || DEFAULT_AUTH_DOMAIN;
+
+  return {
+    providers: [
+      Credentials({
+        id: IMMUTABLE_PROVIDER_ID,
+        name: 'Immutable',
+        credentials: {
+          tokens: { label: 'Tokens', type: 'text' },
+        },
+        async authorize(credentials) {
+          if (!credentials?.tokens || typeof credentials.tokens !== 'string') {
+            return null;
+          }
+
+          let tokenData: ImmutableTokenData;
+          try {
+            tokenData = JSON.parse(credentials.tokens);
+          } catch (error) {
+            // eslint-disable-next-line no-console
+            console.error('[auth-next-server] Failed to parse token data:', error);
+            return null;
+          }
+
+          // Validate required fields exist to prevent TypeError on malformed requests
+          // accessTokenExpires must be a valid number to ensure isTokenExpired() works correctly
+          // (NaN comparisons always return false, which would prevent token refresh)
+          if (
+            !tokenData.accessToken
+            || typeof tokenData.accessToken !== 'string'
+            || !tokenData.profile
+            || typeof tokenData.profile !== 'object'
+            || !tokenData.profile.sub
+            || typeof tokenData.profile.sub !== 'string'
+            || typeof tokenData.accessTokenExpires !== 'number'
+            || Number.isNaN(tokenData.accessTokenExpires)
+          ) {
+            // eslint-disable-next-line no-console
+            console.error('[auth-next-server] Invalid token data structure - missing required fields');
+            return null;
+          }
+
+          // Validate tokens server-side via userinfo endpoint.
+          // This is the standard OAuth 2.0 way - the auth server validates the token.
+          const userInfo = await validateTokens(tokenData.accessToken, authDomain);
+          if (!userInfo) {
+            // eslint-disable-next-line no-console
+            console.error('[auth-next-server] Token validation failed - rejecting authentication');
+            return null;
+          }
+
+          // Verify the user ID (sub) from userinfo matches the client-provided profile.
+          // This prevents spoofing a different user ID with a valid token.
+          if (userInfo.sub !== tokenData.profile.sub) {
+            // eslint-disable-next-line no-console
+            console.error(
+              '[auth-next-server] User ID mismatch - userinfo sub:',
+              userInfo.sub,
+              'provided sub:',
+              tokenData.profile.sub,
+            );
+            return null;
+          }
+
+          // Return user object with validated data
+          return {
+            id: userInfo.sub,
+            sub: userInfo.sub,
+            email: userInfo.email ?? tokenData.profile.email,
+            nickname: userInfo.nickname ?? tokenData.profile.nickname,
+            accessToken: tokenData.accessToken,
+            refreshToken: tokenData.refreshToken,
+            idToken: tokenData.idToken,
+            accessTokenExpires: tokenData.accessTokenExpires,
+            zkEvm: tokenData.zkEvm,
+          };
+        },
+      }),
+    ],
+
+    callbacks: {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async jwt({
+        token, user, trigger, session: sessionUpdate,
+      }: any) {
+        // Initial sign in - store all token data
+        if (user) {
+          return {
+            ...token,
+            sub: user.sub,
+            email: user.email,
+            nickname: user.nickname,
+            accessToken: user.accessToken,
+            refreshToken: user.refreshToken,
+            idToken: user.idToken,
+            accessTokenExpires: user.accessTokenExpires,
+            zkEvm: user.zkEvm,
+          };
+        }
+
+        // Handle session update (for client-side token sync)
+        // When client-side Auth refreshes tokens via TOKEN_REFRESHED event,
+        // it calls updateSession() which triggers this callback with the new tokens.
+        // We clear any stale error (e.g., TokenExpired) on successful update.
+        if (trigger === 'update' && sessionUpdate) {
+          const update = sessionUpdate as Record<string, unknown>;
+          return {
+            ...token,
+            ...(update.accessToken ? { accessToken: update.accessToken } : {}),
+            ...(update.refreshToken ? { refreshToken: update.refreshToken } : {}),
+            ...(update.idToken ? { idToken: update.idToken } : {}),
+            ...(update.accessTokenExpires ? { accessTokenExpires: update.accessTokenExpires } : {}),
+            ...(update.zkEvm ? { zkEvm: update.zkEvm } : {}),
+            // Clear any stale error when valid tokens are synced from client-side
+            error: undefined,
+          };
+        }
+
+        // Return token if not expired
+        if (!isTokenExpired(token.accessTokenExpires as number)) {
+          return token;
+        }
+
+        // Token expired - DON'T refresh server-side!
+        // Server-side refresh causes race conditions with 403 errors when multiple
+        // concurrent SSR requests detect expired tokens. The pendingRefreshes Map
+        // mutex doesn't work across serverless isolates/processes.
+        //
+        // Instead, mark the token as expired and let the client handle refresh:
+        // 1. SSR completes with session.error = "TokenExpired"
+        // 2. Client hydrates, calls getAccessToken() for data fetches
+        // 3. getAccessToken() calls auth.getAccessToken() which auto-refreshes
+        //    with proper mutex protection (refreshingPromise in @imtbl/auth)
+        // 4. TOKEN_REFRESHED event fires → updateSession() syncs fresh tokens
+        // 5. NextAuth receives update trigger → clears error, stores fresh tokens
+        return {
+          ...token,
+          error: 'TokenExpired',
+        };
+      },
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async session({ session, token }: any) {
+        // Expose token data to the session
+        return {
+          ...session,
+          user: {
+            ...session.user,
+            sub: token.sub as string,
+            email: token.email as string | undefined,
+            nickname: token.nickname as string | undefined,
+          },
+          accessToken: token.accessToken as string,
+          refreshToken: token.refreshToken as string | undefined,
+          idToken: token.idToken as string | undefined,
+          accessTokenExpires: token.accessTokenExpires as number,
+          zkEvm: token.zkEvm,
+          ...(token.error && { error: token.error as string }),
+        };
+      },
+    },
+
+    session: {
+      strategy: 'jwt',
+      // Session max age in seconds (365 days default)
+      maxAge: DEFAULT_SESSION_MAX_AGE_SECONDS,
+    },
+  };
+}
+
+// Keep backwards compatibility alias
+export const createAuthOptions = createAuthConfig;

package/src/constants.ts

@@ -0,0 +1,51 @@
+/**
+ * Shared constants for @imtbl/auth-next-server
+ */
+
+/**
+ * Default Immutable authentication domain
+ */
+export const DEFAULT_AUTH_DOMAIN = 'https://auth.immutable.com';
+
+/**
+ * Default OAuth audience
+ */
+export const DEFAULT_AUDIENCE = 'platform_api';
+
+/**
+ * Default OAuth scopes
+ */
+export const DEFAULT_SCOPE = 'openid profile email offline_access transact';
+
+/**
+ * NextAuth credentials provider ID for Immutable
+ */
+export const IMMUTABLE_PROVIDER_ID = 'immutable';
+
+/**
+ * Default NextAuth API base path
+ */
+export const DEFAULT_NEXTAUTH_BASE_PATH = '/api/auth';
+
+/**
+ * Default token expiry in seconds (15 minutes)
+ * Used as fallback when exp claim cannot be extracted from JWT
+ */
+export const DEFAULT_TOKEN_EXPIRY_SECONDS = 900;
+
+/**
+ * Default token expiry in milliseconds
+ */
+export const DEFAULT_TOKEN_EXPIRY_MS = DEFAULT_TOKEN_EXPIRY_SECONDS * 1000;
+
+/**
+ * Buffer time in seconds before token expiry to trigger refresh
+ * Tokens will be refreshed when they expire within this window
+ */
+export const TOKEN_EXPIRY_BUFFER_SECONDS = 60;
+
+/**
+ * Default session max age in seconds (365 days)
+ * This is how long the NextAuth session cookie will be valid
+ */
+export const DEFAULT_SESSION_MAX_AGE_SECONDS = 365 * 24 * 60 * 60;