@imtbl/auth-nextjs 0.0.1-alpha.0 → 2.12.4-alpha.5

package/dist/types/server/with-page-auth.d.ts

@@ -0,0 +1,94 @@
+import type { GetServerSideProps, GetServerSidePropsContext, GetServerSidePropsResult } from 'next';
+import type { IncomingMessage, ServerResponse } from 'http';
+import { type Session } from 'next-auth';
+import type { ImmutableAuthConfig, WithPageAuthRequiredOptions } from '../types';
+/**
+ * Extended options for withPageAuthRequired
+ */
+export interface WithPageAuthRequiredFullOptions<P extends Record<string, unknown> = Record<string, unknown>> extends WithPageAuthRequiredOptions {
+    /**
+     * Custom getServerSideProps that runs after auth check.
+     * Session is guaranteed to exist when this runs.
+     */
+    getServerSideProps?: (ctx: GetServerSidePropsContext, session: Session) => Promise<GetServerSidePropsResult<P>>;
+}
+/**
+ * Props added by withPageAuthRequired
+ */
+export interface WithPageAuthRequiredProps {
+    session: Session;
+}
+/**
+ * Get the Immutable session on the server side.
+ *
+ * @example
+ * ```typescript
+ * // pages/api/user.ts
+ * import { getImmutableSession } from "@imtbl/auth-nextjs/server";
+ *
+ * const config = { clientId: "...", redirectUri: "..." };
+ *
+ * export default async function handler(req, res) {
+ *   const session = await getImmutableSession(req, res, config);
+ *   if (!session) {
+ *     return res.status(401).json({ error: "Not authenticated" });
+ *   }
+ *   res.json({ user: session.user });
+ * }
+ * ```
+ *
+ * @example In getServerSideProps
+ * ```typescript
+ * export const getServerSideProps = async (ctx) => {
+ *   const session = await getImmutableSession(ctx.req, ctx.res, config);
+ *   return { props: { user: session?.user ?? null } };
+ * };
+ * ```
+ */
+export declare function getImmutableSession(req: IncomingMessage & {
+    cookies: Partial<Record<string, string>>;
+}, res: ServerResponse, config: ImmutableAuthConfig): Promise<Session | null>;
+/**
+ * Higher-order function that protects a page with authentication.
+ *
+ * When a signed-out user visits the page:
+ * 1. Server checks session via getServerSession() → returns null
+ * 2. Returns HTTP redirect to login page with returnTo parameter
+ * 3. After login, user is redirected back to original page
+ *
+ * @example Basic usage:
+ * ```typescript
+ * // pages/dashboard.tsx
+ * import { withPageAuthRequired } from "@imtbl/auth-nextjs/server";
+ *
+ * const config = { clientId: "...", redirectUri: "..." };
+ *
+ * function DashboardPage() {
+ *   // Page only renders if user is authenticated
+ *   return <h1>Dashboard</h1>;
+ * }
+ *
+ * export default DashboardPage;
+ * export const getServerSideProps = withPageAuthRequired(config);
+ * ```
+ *
+ * @example With additional data fetching:
+ * ```typescript
+ * export const getServerSideProps = withPageAuthRequired(config, {
+ *   async getServerSideProps(ctx, session) {
+ *     // session is guaranteed to exist here
+ *     const data = await fetchData(session.accessToken);
+ *     return { props: { data } };
+ *   },
+ * });
+ * ```
+ *
+ * @example With custom options:
+ * ```typescript
+ * export const getServerSideProps = withPageAuthRequired(config, {
+ *   loginUrl: "/auth/signin",
+ *   returnTo: "/dashboard",
+ * });
+ * ```
+ */
+export declare function withPageAuthRequired<P extends Record<string, unknown> = Record<string, unknown>>(config: ImmutableAuthConfig, options?: WithPageAuthRequiredFullOptions<P>): GetServerSideProps<WithPageAuthRequiredProps & P>;

package/dist/types/types.d.ts

@@ -0,0 +1,192 @@
+import type { DefaultSession, DefaultUser, Session } from 'next-auth';
+import type { DefaultJWT } from 'next-auth/jwt';
+/**
+ * Configuration for ImmutableAuthProvider and createAuthOptions
+ */
+export interface ImmutableAuthConfig {
+    /**
+     * Immutable OAuth client ID
+     */
+    clientId: string;
+    /**
+     * OAuth callback redirect URI
+     */
+    redirectUri: string;
+    /**
+     * Where to redirect after logout
+     */
+    logoutRedirectUri?: string;
+    /**
+     * OAuth audience (default: "platform_api")
+     */
+    audience?: string;
+    /**
+     * OAuth scopes (default: "openid profile email offline_access transact")
+     */
+    scope?: string;
+    /**
+     * Authentication domain (default: "https://auth.immutable.com")
+     */
+    authenticationDomain?: string;
+}
+/**
+ * zkEVM wallet information
+ */
+export interface ZkEvmInfo {
+    ethAddress: string;
+    userAdminAddress: string;
+}
+/**
+ * User profile from Immutable
+ */
+export interface ImmutableUser {
+    sub: string;
+    email?: string;
+    nickname?: string;
+}
+/**
+ * NextAuth module augmentation to add Immutable-specific fields
+ */
+declare module 'next-auth' {
+    interface Session extends DefaultSession {
+        user: ImmutableUser;
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+        error?: string;
+    }
+    interface User extends DefaultUser {
+        sub: string;
+        email?: string;
+        nickname?: string;
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+    }
+}
+declare module 'next-auth/jwt' {
+    interface JWT extends DefaultJWT {
+        sub: string;
+        email?: string;
+        nickname?: string;
+        accessToken: string;
+        refreshToken?: string;
+        idToken?: string;
+        accessTokenExpires: number;
+        zkEvm?: ZkEvmInfo;
+        error?: string;
+    }
+}
+/**
+ * Token data passed from client to NextAuth credentials provider
+ */
+export interface ImmutableTokenData {
+    accessToken: string;
+    refreshToken?: string;
+    idToken?: string;
+    accessTokenExpires: number;
+    profile: {
+        sub: string;
+        email?: string;
+        nickname?: string;
+    };
+    zkEvm?: ZkEvmInfo;
+}
+/**
+ * Response from the userinfo endpoint
+ * Used for server-side token validation
+ */
+export interface UserInfoResponse {
+    /** Subject - unique user identifier */
+    sub: string;
+    /** User's email address */
+    email?: string;
+    /** User's nickname/username */
+    nickname?: string;
+    /** User's full name */
+    name?: string;
+    /** User's profile picture URL */
+    picture?: string;
+    /** When the user profile was last updated */
+    updated_at?: string;
+    /** Whether the email has been verified */
+    email_verified?: boolean;
+}
+/**
+ * Props for ImmutableAuthProvider
+ */
+export interface ImmutableAuthProviderProps {
+    children: React.ReactNode;
+    /**
+     * Immutable auth configuration
+     */
+    config: ImmutableAuthConfig;
+    /**
+     * Initial session from server (for SSR hydration)
+     * Can be Session from getServerSession or any compatible session object
+     */
+    session?: Session | DefaultSession | null;
+    /**
+     * Custom base path for NextAuth API routes
+     * Use this when you have multiple auth endpoints (e.g., per environment)
+     * @default "/api/auth"
+     */
+    basePath?: string;
+}
+/**
+ * Return type of useImmutableAuth hook
+ */
+export interface UseImmutableAuthReturn {
+    /**
+     * Current user profile (null if not authenticated)
+     */
+    user: ImmutableUser | null;
+    /**
+     * Full NextAuth session with tokens
+     */
+    session: Session | null;
+    /**
+     * Whether authentication state is loading
+     */
+    isLoading: boolean;
+    /**
+     * Whether user is authenticated
+     */
+    isAuthenticated: boolean;
+    /**
+     * Sign in with Immutable (opens popup)
+     * @param options - Optional login options (cached session, silent login, redirect flow, direct login)
+     */
+    signIn: (options?: import('@imtbl/auth').LoginOptions) => Promise<void>;
+    /**
+     * Sign out from both NextAuth and Immutable
+     */
+    signOut: () => Promise<void>;
+    /**
+     * Get a valid access token (refreshes if needed)
+     */
+    getAccessToken: () => Promise<string>;
+    /**
+     * The underlying Auth instance (for advanced use)
+     */
+    auth: import('@imtbl/auth').Auth | null;
+}
+/**
+ * Options for withPageAuthRequired
+ */
+export interface WithPageAuthRequiredOptions {
+    /**
+     * URL to redirect to when not authenticated
+     * @default "/login"
+     */
+    loginUrl?: string;
+    /**
+     * URL to redirect to after login
+     * @default current page
+     */
+    returnTo?: string | false;
+}

package/dist/types/utils/token.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Extract the expiry timestamp from a JWT access token.
+ * Returns the expiry as a Unix timestamp in milliseconds.
+ *
+ * @param accessToken - JWT access token
+ * @returns Expiry timestamp in milliseconds, or a default 15-minute expiry if extraction fails
+ */
+export declare function getTokenExpiry(accessToken: string | undefined): number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imtbl/auth-nextjs",
-  "version": "0.0.1-alpha.0",
+  "version": "2.12.4-alpha.5",
   "description": "Next.js authentication integration for Immutable SDK using NextAuth",
   "author": "Immutable",
   "bugs": "https://github.com/immutable/ts-immutable-sdk/issues",
@@ -51,7 +51,7 @@
     "dist"
   ],
   "dependencies": {
-    "@imtbl/auth": "2.12.4-alpha.3"
+    "@imtbl/auth": "2.12.4-alpha.5"
   },
   "peerDependencies": {
     "next": "14.2.25",