Merge commit from fork

* remove accessToken and sealedSession, add getAccessToken helper method

* update README to document changes and add section about advanced witHAuth usage

* add tests

* remove unused includeAccessToken property in interface

Author: nicknisi

README.md

@@ -146,7 +146,7 @@ export const loader = (args: LoaderFunctionArgs) => authkitLoader(args);
 
 export function App() {
   // Retrieves the user from the session or returns `null` if no user is signed in
-  // Other supported values include `sessionId`, `accessToken`, `organizationId`,
+  // Other supported values include `sessionId`, `organizationId`,
   // `role`, `permissions`, `entitlements`, `featureFlags`, and `impersonator`.
   const { user, signInUrl, signUpUrl } = useLoaderData<typeof loader>();
 
@@ -230,32 +230,122 @@ export async function action({ request }: ActionFunctionArgs) {
 
 ### Get the access token
 
-Sometimes it is useful to obtain the access token directly, for instance to make API requests to another service.
+Access tokens are available through the `getAccessToken()` function within your loader. This design encourages server-side token usage while making the security implications explicit.
 
 ```tsx
 import { data, type LoaderFunctionArgs } from 'react-router';
 import { authkitLoader } from '@workos-inc/authkit-react-router';
 
 export const loader = (args: LoaderFunctionArgs) =>
-  authkitLoader(args, async ({ auth }) => {
-    const { accessToken } = auth;
-
-    if (!accessToken) {
-      // Not signed in
+  authkitLoader(args, async ({ auth, getAccessToken }) => {
+    if (!auth.user) {
+      // Not signed in - getAccessToken() would return null
+      return data({ data: null });
     }
 
+    // Explicitly call the function to get the access token
+    const accessToken = getAccessToken();
+    
     const serviceData = await fetch('/api/path', {
       headers: {
         Authorization: `Bearer ${accessToken}`,
       },
     });
 
     return data({
-      data: serviceData,
+      data: await serviceData.json(),
     });
   });
 ```
 
+#### Security Considerations
+
+By default, access tokens are not included in the data sent to React components. This helps prevent unintentional token exposure in:
+- Browser developer tools
+- HTML source code  
+- Client-side logs or error reporting
+
+If you need to expose the access token to client-side code, you can explicitly return it from your loader:
+
+```tsx
+export const loader = (args: LoaderFunctionArgs) =>
+  authkitLoader(args, async ({ auth, getAccessToken }) => {
+    const accessToken = getAccessToken();
+    
+    return {
+      // Only expose to client if absolutely necessary
+      accessToken,
+      userData: await fetchUserData(accessToken)
+    };
+  }, { ensureSignedIn: true });
+```
+
+**Note:** Only expose access tokens to the client when necessary for your use case (e.g., making direct API calls from the browser). Consider alternatives like:
+- Making API calls server-side in your loaders
+- Creating proxy endpoints in your application
+- Using separate client-specific tokens with limited scope
+
+#### Using with `ensureSignedIn`
+
+When using the `ensureSignedIn` option, you can be confident that `getAccessToken()` will always return a valid token:
+
+```tsx
+export const loader = (args: LoaderFunctionArgs) =>
+  authkitLoader(args, async ({ auth, getAccessToken }) => {
+    // With ensureSignedIn: true, the user is guaranteed to be authenticated
+    const accessToken = getAccessToken();
+    
+    // Use the token for your API calls
+    const data = await fetchProtectedData(accessToken);
+    
+    return { data };
+  }, { ensureSignedIn: true });
+```
+
+### Using withAuth for low-level access
+
+For advanced use cases, the `withAuth` function provides direct access to authentication data, including the access token. Unlike `authkitLoader`, this function:
+
+- Does not handle automatic token refresh
+- Does not manage cookies or session updates  
+- Returns the access token directly as a property
+- Requires manual redirect handling for unauthenticated users
+
+```tsx
+import { withAuth } from '@workos-inc/authkit-react-router';
+import { redirect, type LoaderFunctionArgs } from 'react-router';
+
+export const loader = async (args: LoaderFunctionArgs) => {
+  const auth = await withAuth(args);
+  
+  if (!auth.user) {
+    // Manual redirect - withAuth doesn't handle this automatically
+    throw redirect('/sign-in');
+  }
+  
+  // Access token is directly available as a property
+  const { accessToken, user, sessionId } = auth;
+  
+  // Use the token for server-side operations
+  const apiData = await fetch('https://api.example.com/data', {
+    headers: { Authorization: `Bearer ${accessToken}` }
+  });
+  
+  // Be careful what you return - accessToken will be exposed if included
+  return {
+    user,
+    apiData: await apiData.json(),
+    // accessToken, // ⚠️ Only include if client-side access is necessary
+  };
+};
+```
+
+**When to use `withAuth` vs `authkitLoader`:**
+
+- Use `authkitLoader` for most cases - it handles token refresh, cookies, and provides safer defaults
+- Use `withAuth` when you need more control or are building custom authentication flows
+- `withAuth` is useful for API routes or middleware where you don't need the full loader functionality
+
 ### Debugging
 
 To enable debug logs, pass in the debug flag when using `authkitLoader`.

src/interfaces.ts

@@ -108,27 +108,23 @@ export type AuthKitLoaderOptions = {
 export interface AuthorizedData {
   user: User;
   sessionId: string;
-  accessToken: string;
   organizationId: string | null;
   role: string | null;
   permissions: string[];
   entitlements: string[];
   featureFlags: string[];
   impersonator: Impersonator | null;
-  sealedSession: string;
 }
 
 export interface UnauthorizedData {
   user: null;
   sessionId: null;
-  accessToken: null;
   organizationId: null;
   role: null;
   permissions: null;
   entitlements: null;
   featureFlags: null;
   impersonator: null;
-  sealedSession: null;
 }
 
 /**

src/session.spec.ts

@@ -277,15 +277,13 @@ describe('session', () => {
 
         expect(data).toEqual({
           user: null,
-          accessToken: null,
           impersonator: null,
           organizationId: null,
           permissions: null,
           entitlements: null,
           featureFlags: null,
           role: null,
           sessionId: null,
-          sealedSession: null,
         });
       });
 
@@ -397,15 +395,13 @@ describe('session', () => {
 
         expect(data).toEqual({
           user: mockSessionData.user,
-          accessToken: mockSessionData.accessToken,
           impersonator: null,
           organizationId: 'org-123',
           permissions: ['read', 'write'],
           entitlements: ['premium'],
           featureFlags: ['flag-1', 'flag-2'],
           role: 'admin',
           sessionId: 'test-session-id',
-          sealedSession: 'encrypted-jwt',
         });
       });
 
@@ -422,7 +418,6 @@ describe('session', () => {
             customData: 'test-value',
             metadata: { key: 'value' },
             user: mockSessionData.user,
-            accessToken: mockSessionData.accessToken,
             sessionId: 'test-session-id',
           }),
         );
@@ -469,6 +464,53 @@ describe('session', () => {
           expect(response.headers.get('X-Redirect-Reason')).toBe('test');
         }
       });
+
+      it('should provide getAccessToken function to custom loader', async () => {
+        const customLoader = jest.fn().mockImplementation(({ getAccessToken }) => {
+          const token = getAccessToken();
+          return { retrievedToken: token };
+        });
+
+        const { data } = await authkitLoader(createLoaderArgs(createMockRequest()), customLoader);
+
+        // Verify the loader was called with getAccessToken function
+        expect(customLoader).toHaveBeenCalledWith(
+          expect.objectContaining({
+            auth: expect.objectContaining({
+              user: mockSessionData.user,
+            }),
+            getAccessToken: expect.any(Function),
+          }),
+        );
+
+        // Verify the token was retrieved correctly
+        expect(data).toEqual(
+          expect.objectContaining({
+            retrievedToken: mockSessionData.accessToken,
+            user: mockSessionData.user,
+          }),
+        );
+      });
+
+      it('should return null from getAccessToken for unauthenticated users', async () => {
+        // Mock no session
+        unsealData.mockResolvedValue(null);
+        
+        const customLoader = jest.fn().mockImplementation(({ getAccessToken }) => {
+          const token = getAccessToken();
+          return { retrievedToken: token };
+        });
+
+        const { data } = await authkitLoader(createLoaderArgs(createMockRequest()), customLoader);
+
+        // Verify getAccessToken returned null
+        expect(data).toEqual(
+          expect.objectContaining({
+            retrievedToken: null,
+            user: null,
+          }),
+        );
+      });
     });
 
     describe('session refresh', () => {
@@ -539,7 +581,6 @@ describe('session', () => {
         // Verify the response contains the new token data
         expect(data).toEqual(
           expect.objectContaining({
-            accessToken: 'new.valid.token',
             sessionId: 'new-session-id',
             organizationId: 'org-123',
             role: 'user',

src/session.ts

@@ -164,10 +164,12 @@ type LoaderValue<Data> = Response | TypedResponse<Data> | NonNullable<Data> | nu
 type LoaderReturnValue<Data> = Promise<LoaderValue<Data>> | LoaderValue<Data>;
 
 type AuthLoader<Data> = (
-  args: LoaderFunctionArgs & { auth: AuthorizedData | UnauthorizedData },
+  args: LoaderFunctionArgs & { auth: AuthorizedData | UnauthorizedData; getAccessToken: () => string | null },
 ) => LoaderReturnValue<Data>;
 
-type AuthorizedAuthLoader<Data> = (args: LoaderFunctionArgs & { auth: AuthorizedData }) => LoaderReturnValue<Data>;
+type AuthorizedAuthLoader<Data> = (
+  args: LoaderFunctionArgs & { auth: AuthorizedData; getAccessToken: () => string },
+) => LoaderReturnValue<Data>;
 
 /**
  * This loader handles authentication state, session management, and access token refreshing
@@ -322,15 +324,13 @@ export async function authkitLoader<Data = unknown>(
 
       const auth: UnauthorizedData = {
         user: null,
-        accessToken: null,
         impersonator: null,
         organizationId: null,
         permissions: null,
         entitlements: null,
         featureFlags: null,
         role: null,
         sessionId: null,
-        sealedSession: null,
       };
 
       return await handleAuthLoader(loader, loaderArgs, auth);
@@ -346,7 +346,6 @@ export async function authkitLoader<Data = unknown>(
       featureFlags = [],
     } = getClaimsFromAccessToken(session.accessToken);
 
-    const cookieSession = await getSession(request.headers.get('Cookie'));
     const { impersonator = null } = session;
 
     // checking for 'headers' in session determines if the session was refreshed or not
@@ -362,14 +361,12 @@ export async function authkitLoader<Data = unknown>(
     const auth: AuthorizedData = {
       user: session.user,
       sessionId,
-      accessToken: session.accessToken,
       organizationId,
       role,
       permissions,
       entitlements,
       featureFlags,
       impersonator,
-      sealedSession: cookieSession.get('jwt'),
     };
 
     return await handleAuthLoader(loader, loaderArgs, auth, session);
@@ -420,7 +417,26 @@ async function handleAuthLoader(
 
   // If there's a custom loader, get the resulting data and return it with our
   // auth data plus session cookie header
-  const loaderResult = await loader({ ...args, auth: auth as AuthorizedData });
+  let loaderResult;
+
+  if (auth.user) {
+    // Authorized case
+    const getAccessToken = () => {
+      if (!session?.accessToken) {
+        throw new Error('No access token available');
+      }
+      return session.accessToken;
+    };
+    loaderResult = await (loader as AuthorizedAuthLoader<unknown>)({
+      ...args,
+      auth: auth as AuthorizedData,
+      getAccessToken,
+    });
+  } else {
+    // Unauthorized case
+    const getAccessToken = () => null;
+    loaderResult = await (loader as AuthLoader<unknown>)({ ...args, auth, getAccessToken });
+  }
 
   if (isResponse(loaderResult)) {
     // If the result is a redirect, return it unedited