feat(provider): add POST callback and id_token handling for OAuth2 (#245)

* feat(provider): add POST callback and id_token handling for OAuth2

- Add form_post response_mode support for Apple Sign In
- Implement POST callback route in OAuth2 provider
- Add ID token verification using JWKS endpoint
- Refactor callback logic to reduce duplication
- Extract and expose decoded ID token claims

This change enables Apple Sign In with name and email scopes which requires
form_post response mode and proper handling of the ID token.

* rm comment

* feat(provider): add JWKS endpoint for Google OAuth

- Include JWKS endpoint for Google provider to support ID token verification.

Author: aryasaatvik

packages/openauth/src/provider/apple.ts

@@ -16,6 +16,24 @@
  * })
  * ```
  *
+ * #### Using OAuth with form_post response mode
+ * 
+ * When requesting name or email scopes from Apple, you must use form_post response mode:
+ * 
+ * ```ts {5-9}
+ * import { AppleProvider } from "@openauthjs/openauth/provider/apple"
+ *
+ * export default issuer({
+ *   providers: {
+ *     apple: AppleProvider({
+ *       clientID: "1234567890",
+ *       clientSecret: "0987654321",
+ *       responseMode: "form_post"
+ *     })
+ *   }
+ * })
+ * ```
+ *
  * #### Using OIDC
  *
  * ```ts {5-7}
@@ -36,7 +54,14 @@
 import { Oauth2Provider, Oauth2WrappedConfig } from "./oauth2.js"
 import { OidcProvider, OidcWrappedConfig } from "./oidc.js"
 
-export interface AppleConfig extends Oauth2WrappedConfig {}
+export interface AppleConfig extends Oauth2WrappedConfig {
+  /**
+   * The response mode to use for the authorization request.
+   * Apple requires 'form_post' response mode when requesting name or email scopes.
+   * @default "query"
+   */
+  responseMode?: "query" | "form_post"
+}
 export interface AppleOidcConfig extends OidcWrappedConfig {}
 
 /**
@@ -45,20 +70,37 @@ export interface AppleOidcConfig extends OidcWrappedConfig {}
  * @param config - The config for the provider.
  * @example
  * ```ts
+ * // Using default query response mode (GET callback)
  * AppleProvider({
  *   clientID: "1234567890",
  *   clientSecret: "0987654321"
  * })
+ * 
+ * // Using form_post response mode (POST callback)
+ * // Required when requesting name or email scope
+ * AppleProvider({
+ *   clientID: "1234567890",
+ *   clientSecret: "0987654321",
+ *   responseMode: "form_post",
+ *   scopes: ["name", "email"]
+ * })
  * ```
  */
 export function AppleProvider(config: AppleConfig) {
+  const { responseMode, ...restConfig } = config
+  const additionalQuery = responseMode === "form_post" 
+    ? { response_mode: "form_post", ...config.query } 
+    : config.query || {}
+
   return Oauth2Provider({
-    ...config,
+    ...restConfig,
     type: "apple" as const,
     endpoint: {
       authorization: "https://appleid.apple.com/auth/authorize",
       token: "https://appleid.apple.com/auth/token",
+      jwks: "https://appleid.apple.com/auth/keys",
     },
+    query: additionalQuery,
   })
 }
 
@@ -80,5 +122,6 @@ export function AppleOidcProvider(config: AppleOidcConfig) {
     ...config,
     type: "apple" as const,
     issuer: "https://appleid.apple.com",
+
   })
 }

packages/openauth/src/provider/google.ts

@@ -58,6 +58,7 @@ export function GoogleProvider(config: GoogleConfig) {
     endpoint: {
       authorization: "https://accounts.google.com/o/oauth2/v2/auth",
       token: "https://oauth2.googleapis.com/token",
+      jwks: "https://www.googleapis.com/oauth2/v3/certs",
     },
   })
 }

packages/openauth/src/provider/oauth2.ts

@@ -22,6 +22,7 @@
  * @packageDocumentation
  */
 
+import { createRemoteJWKSet, jwtVerify } from "jose"
 import { OauthError } from "../error.js"
 import { generatePKCE } from "../pkce.js"
 import { getRelativeUrl } from "../util.js"
@@ -66,7 +67,8 @@ export interface Oauth2Config {
    * {
    *   endpoint: {
    *     authorization: "https://auth.myserver.com/authorize",
-   *     token: "https://auth.myserver.com/token"
+   *     token: "https://auth.myserver.com/token",
+   *     jwks: "https://auth.myserver.com/auth/keys"
    *   }
    * }
    * ```
@@ -80,6 +82,10 @@ export interface Oauth2Config {
      * The URL of the token endpoint.
      */
     token: string
+    /**
+     * The URL of the JWKS endpoint.
+     */
+    jwks?: string
   }
   /**
    * A list of OAuth scopes that you want to request.
@@ -125,6 +131,7 @@ export interface Oauth2Token {
   access: string
   refresh: string
   expiry: number
+  id?: Record<string, any>
   raw: Record<string, any>
 }
 
@@ -138,6 +145,76 @@ export function Oauth2Provider(
   config: Oauth2Config,
 ): Provider<{ tokenset: Oauth2Token; clientID: string }> {
   const query = config.query || {}
+  
+  // Helper function to handle token exchange and response building
+  async function handleCallbackLogic(
+    c: any, 
+    ctx: any, 
+    provider: ProviderState, 
+    code: string | undefined
+  ) {
+    if (!provider || !code) {
+      return c.redirect(getRelativeUrl(c, "./authorize"));
+    }
+    
+    const body = new URLSearchParams({
+      client_id: config.clientID,
+      client_secret: config.clientSecret,
+      code,
+      grant_type: "authorization_code",
+      redirect_uri: provider.redirect,
+      ...(provider.codeVerifier
+        ? { code_verifier: provider.codeVerifier }
+        : {}),
+    });
+    
+    const json: any = await fetch(config.endpoint.token, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        Accept: "application/json",
+      },
+      body: body.toString(),
+    }).then((r) => r.json());
+    
+    if ("error" in json) {
+      throw new OauthError(json.error, json.error_description);
+    }
+
+    let idTokenPayload: Record<string, any> | null = null;
+    if (config.endpoint.jwks) {
+      const jwksEndpoint = new URL(config.endpoint.jwks);
+      // @ts-expect-error bun/node mismatch
+      const jwks = createRemoteJWKSet(jwksEndpoint);
+      const { payload } = await jwtVerify(json.id_token, jwks, {
+        audience: config.clientID,
+      });
+      idTokenPayload = payload;
+    }
+    
+    return ctx.success(c, {
+      clientID: config.clientID,
+      tokenset: {
+        get access() {
+          return json.access_token;
+        },
+        get refresh() {
+          return json.refresh_token;
+        },
+        get expiry() {
+          return json.expires_in;
+        },
+        get id() {
+          if (!idTokenPayload) return null;
+          return idTokenPayload;
+        },
+        get raw() {
+          return json;
+        },
+      },
+    });
+  }
+  
   return {
     type: config.type || "oauth2",
     init(routes, ctx) {
@@ -173,50 +250,39 @@ export function Oauth2Provider(
         const code = c.req.query("code")
         const state = c.req.query("state")
         const error = c.req.query("error")
+        
         if (error)
           throw new OauthError(
             error.toString() as any,
             c.req.query("error_description")?.toString() || "",
           )
-        if (!provider || !code || (provider.state && state !== provider.state))
+        if (!provider || !code || (provider.state && state !== provider.state)) {
           return c.redirect(getRelativeUrl(c, "./authorize"))
-        const body = new URLSearchParams({
-          client_id: config.clientID,
-          client_secret: config.clientSecret,
-          code,
-          grant_type: "authorization_code",
-          redirect_uri: provider.redirect,
-          ...(provider.codeVerifier
-            ? { code_verifier: provider.codeVerifier }
-            : {}),
-        })
-        const json: any = await fetch(config.endpoint.token, {
-          method: "POST",
-          headers: {
-            "Content-Type": "application/x-www-form-urlencoded",
-            Accept: "application/json",
-          },
-          body: body.toString(),
-        }).then((r) => r.json())
-        if ("error" in json)
-          throw new OauthError(json.error, json.error_description)
-        return ctx.success(c, {
-          clientID: config.clientID,
-          tokenset: {
-            get access() {
-              return json.access_token
-            },
-            get refresh() {
-              return json.refresh_token
-            },
-            get expiry() {
-              return json.expires_in
-            },
-            get raw() {
-              return json
-            },
-          },
-        })
+        }
+        
+        return handleCallbackLogic(c, ctx, provider, code)
+      })
+
+      routes.post("/callback", async (c) => {
+        const provider = (await ctx.get(c, "provider")) as ProviderState
+        
+        // Handle form data from POST request
+        const formData = await c.req.formData()
+        const code = formData.get("code")?.toString()
+        const state = formData.get("state")?.toString()
+        const error = formData.get("error")?.toString()
+        
+        if (error)
+          throw new OauthError(
+            error as any,
+            formData.get("error_description")?.toString() || "",
+          )
+        
+        if (!provider || !code || (provider.state && state !== provider.state)) {
+          return c.redirect(getRelativeUrl(c, "./authorize"))
+        }
+        
+        return handleCallbackLogic(c, ctx, provider, code)
       })
     },
   }