Programmatic PAR (#1946)

Author: tusharpandey13

EXAMPLES.md

@@ -752,3 +752,33 @@ const sessionCookieValue = await generateSessionCookie(
   }
 )
 ```
+
+
+## Programmatic Pushed Authentication Requests (PAR)
+
+The method `startInteractiveLogin` can be called with authorizationParams to initiate an interactive login flow.  
+The code collects authorization parameters on the server side rather than constructing them directly in the browser.
+
+```typescript
+// app/api/auth/login/route.ts
+import { auth0 } from "./lib/auth0";
+import { NextRequest } from "next/server";
+
+export const GET = async (req: NextRequest) => {
+  // Extract custom parameters from request URL if needed
+  const searchParams = Object.fromEntries(req.nextUrl.searchParams.entries());
+
+  // Call startInteractiveLogin with optional parameters
+  return auth0.startInteractiveLogin({
+    // a custom returnTo URL can be specified
+    returnTo: "/dashboard",
+    authorizationParameters: {
+      prompt: searchParams.prompt,
+      login_hint: searchParams.login_hint,
+      // Add any custom auth parameters if required
+      audience: "custom-audience"
+    }
+  });
+};
+
+```

src/server/auth-client.test.ts

@@ -4214,6 +4214,250 @@ ca/T0LLtgmbMmxSv/MmzIg==
       });
     });
   });
+
+  describe("startInteractiveLogin", async () => {
+    const createAuthClient = async ({
+      pushedAuthorizationRequests = false,
+      signInReturnToPath = "/",
+      authorizationParameters = {}
+    } = {}) => {
+      const secret = await generateSecret(32);
+      const transactionStore = new TransactionStore({
+        secret
+      });
+      const sessionStore = new StatelessSessionStore({
+        secret
+      });
+
+      return new AuthClient({
+        transactionStore,
+        sessionStore,
+
+        domain: DEFAULT.domain,
+        clientId: DEFAULT.clientId,
+        clientSecret: DEFAULT.clientSecret,
+
+        secret,
+        appBaseUrl: DEFAULT.appBaseUrl,
+        signInReturnToPath,
+        pushedAuthorizationRequests,
+        authorizationParameters: {
+          scope: "openid profile email",
+          ...authorizationParameters
+        },
+
+        fetch: getMockAuthorizationServer()
+      });
+    };
+
+    it("should use the default returnTo path when no returnTo is provided", async () => {
+      const defaultReturnTo = "/default-path";
+      const authClient = await createAuthClient({
+        signInReturnToPath: defaultReturnTo
+      });
+      
+      // Mock the transactionStore.save method to verify the saved state
+      const originalSave = authClient['transactionStore'].save;
+      authClient['transactionStore'].save = vi.fn(async (cookies, state) => {
+        expect(state.returnTo).toBe(defaultReturnTo);
+        return originalSave.call(authClient['transactionStore'], cookies, state);
+      });
+
+      await authClient.startInteractiveLogin();
+      
+      expect(authClient['transactionStore'].save).toHaveBeenCalled();
+    });
+
+    it("should sanitize and use the provided returnTo parameter", async () => {
+      const authClient = await createAuthClient();
+      const returnTo = "/custom-return-path";
+      
+      // Mock the transactionStore.save method to verify the saved state
+      const originalSave = authClient['transactionStore'].save;
+      authClient['transactionStore'].save = vi.fn(async (cookies, state) => {
+        // The full URL is saved, not just the path
+        expect(state.returnTo).toBe("https://example.com/custom-return-path");
+        return originalSave.call(authClient['transactionStore'], cookies, state);
+      });
+
+      await authClient.startInteractiveLogin({ returnTo });
+      
+      expect(authClient['transactionStore'].save).toHaveBeenCalled();
+    });
+
+    it("should reject unsafe returnTo URLs", async () => {
+      const authClient = await createAuthClient({
+        signInReturnToPath: "/safe-path"
+      });
+      const unsafeReturnTo = "https://malicious-site.com";
+      
+      // Mock the transactionStore.save method to verify the saved state
+      const originalSave = authClient['transactionStore'].save;
+      authClient['transactionStore'].save = vi.fn(async (cookies, state) => {
+        // Should use the default safe path instead of the malicious one
+        expect(state.returnTo).toBe("/safe-path");
+        return originalSave.call(authClient['transactionStore'], cookies, state);
+      });
+
+      await authClient.startInteractiveLogin({ returnTo: unsafeReturnTo });
+      
+      expect(authClient['transactionStore'].save).toHaveBeenCalled();
+    });
+
+    it("should pass authorization parameters to the authorization URL", async () => {
+      const authClient = await createAuthClient();
+      const authorizationParameters = {
+        audience: "https://api.example.com",
+        scope: "openid profile email custom_scope"
+      };
+      
+      // Spy on the authorizationUrl method to verify the passed params
+      const originalAuthorizationUrl = authClient['authorizationUrl'];
+      authClient['authorizationUrl'] = vi.fn(async (params) => {
+        // Verify the audience is set correctly
+        expect(params.get("audience")).toBe(authorizationParameters.audience);
+        // Verify the scope is set correctly
+        expect(params.get("scope")).toBe(authorizationParameters.scope);
+        return originalAuthorizationUrl.call(authClient, params);
+      });
+
+      await authClient.startInteractiveLogin({ authorizationParameters });
+      
+      expect(authClient['authorizationUrl']).toHaveBeenCalled();
+    });
+
+    it("should handle pushed authorization requests (PAR) correctly", async () => {
+      let parRequestCalled = false;
+      const mockFetch = getMockAuthorizationServer({
+        onParRequest: async () => {
+          parRequestCalled = true;
+        }
+      });
+      
+      const secret = await generateSecret(32);
+      const transactionStore = new TransactionStore({ secret });
+      const sessionStore = new StatelessSessionStore({ secret });
+      
+      const authClient = new AuthClient({
+        transactionStore,
+        sessionStore,
+        domain: DEFAULT.domain,
+        clientId: DEFAULT.clientId,
+        clientSecret: DEFAULT.clientSecret,
+        secret,
+        appBaseUrl: DEFAULT.appBaseUrl,
+        pushedAuthorizationRequests: true,
+        authorizationParameters: {
+          scope: "openid profile email"
+        },
+        fetch: mockFetch
+      });
+      
+      await authClient.startInteractiveLogin();
+      
+      // Verify that PAR was used
+      expect(parRequestCalled).toBe(true);
+    });
+    
+    it("should save the transaction state with correct values", async () => {
+      const authClient = await createAuthClient();
+      const returnTo = "/custom-path";
+      
+      // Instead of mocking the oauth functions, we'll just check the structure of the transaction state
+      const originalSave = authClient['transactionStore'].save;
+      authClient['transactionStore'].save = vi.fn(async (cookies, transactionState) => {
+        expect(transactionState).toEqual(expect.objectContaining({
+          nonce: expect.any(String),
+          codeVerifier: expect.any(String),
+          responseType: "code",
+          state: expect.any(String),
+          returnTo: "https://example.com/custom-path"
+        }));
+        return originalSave.call(authClient['transactionStore'], cookies, transactionState);
+      });
+
+      await authClient.startInteractiveLogin({ returnTo });
+      
+      expect(authClient['transactionStore'].save).toHaveBeenCalled();
+    });
+
+    it("should merge configuration authorizationParameters with method arguments", async () => {
+      const configScope = "openid profile email";
+      const configAudience = "https://default-api.example.com";
+      const authClient = await createAuthClient({
+        authorizationParameters: {
+          scope: configScope,
+          audience: configAudience
+        }
+      });
+      
+      const methodScope = "openid profile email custom_scope";
+      const methodAudience = "https://custom-api.example.com";
+      
+      // Spy on the authorizationUrl method to verify the passed params
+      const originalAuthorizationUrl = authClient['authorizationUrl'];
+      authClient['authorizationUrl'] = vi.fn(async (params) => {
+        // Method's authorization parameters should override config
+        expect(params.get("audience")).toBe(methodAudience);
+        expect(params.get("scope")).toBe(methodScope);
+        return originalAuthorizationUrl.call(authClient, params);
+      });
+
+      await authClient.startInteractiveLogin({
+        authorizationParameters: {
+          scope: methodScope,
+          audience: methodAudience
+        }
+      });
+      
+      expect(authClient['authorizationUrl']).toHaveBeenCalled();
+    });
+
+    // Add tests for handleLogin method
+    it("should create correct options in handleLogin with returnTo parameter", async () => {
+      const authClient = await createAuthClient();
+      
+      // Mock startInteractiveLogin to check what options are passed to it
+      const originalStartInteractiveLogin = authClient.startInteractiveLogin;
+      authClient.startInteractiveLogin = vi.fn(async (options) => {
+        expect(options).toEqual({
+          authorizationParameters: { foo: "bar", returnTo: "custom-return" },
+          returnTo: "custom-return"
+        });
+        return originalStartInteractiveLogin.call(authClient, options);
+      });
+
+      const reqUrl = new URL("https://example.com/auth/login?foo=bar&returnTo=custom-return");
+      const req = new NextRequest(reqUrl, { method: "GET" });
+      
+      await authClient.handleLogin(req);
+      
+      expect(authClient.startInteractiveLogin).toHaveBeenCalled();
+    });
+
+    it("should handle PAR correctly in handleLogin by not forwarding params", async () => {
+      const authClient = await createAuthClient({
+        pushedAuthorizationRequests: true
+      });
+      
+      // Mock startInteractiveLogin to check what options are passed to it
+      const originalStartInteractiveLogin = authClient.startInteractiveLogin;
+      authClient.startInteractiveLogin = vi.fn(async (options) => {
+        expect(options).toEqual({
+          authorizationParameters: {},
+          returnTo: "custom-return"
+        });
+        return originalStartInteractiveLogin.call(authClient, options);
+      });
+
+      const reqUrl = new URL("https://example.com/auth/login?foo=bar&returnTo=custom-return");
+      const req = new NextRequest(reqUrl, { method: "GET" });
+      
+      await authClient.handleLogin(req);
+      
+      expect(authClient.startInteractiveLogin).toHaveBeenCalled();
+    });
+  });
 });
 
 const _authorizationServerMetadata = {