@rpcbase/auth 0.90.0 → 0.92.0

package/README.md

@@ -2,15 +2,6 @@
 
 UI helpers + API routes for authentication.
 
-## OAuth (OIDC Authorization Code + PKCE)
-
-OAuth support lives behind two framework routes:
-
-- `GET /api/rb/auth/oauth/:provider/start` (initiates the flow)
-- `GET /api/rb/auth/oauth/:provider/callback` (handles the return from the provider)
-
-`provider` is the provider id you configure (for example `mock`, `google`, `github`).
-
 ### 1) Register auth routes in your API
 
 Example (like `sample-app`):
@@ -29,7 +20,7 @@ export const runApi = async ({ app }) => {
 }
 ```
 
-These routes require an Express session to be available (used to store `state` + PKCE verifier between `start` and `callback`).
+The OAuth request (`state` + PKCE verifier) is stored server-side in `RBOAuthRequest` (global model). A short-lived HttpOnly cookie binds `state` to the initiating browser (SameSite=None; Secure on HTTPS). The callback handler uses an Express session only to sign the user in.
 
 ### 2) Configure providers
 
@@ -39,13 +30,15 @@ Call `configureOAuthProviders()` before initializing your API routes:
 
 ```ts
 import { initApi } from "@rpcbase/api"
-import { configureOAuthProviders, routes as authRoutes } from "@rpcbase/auth/routes"
+import { configureOAuthProviders } from "@rpcbase/auth/oauth"
+import { routes as authRoutes } from "@rpcbase/auth/routes"
 
 configureOAuthProviders({
   mock: {
     issuer: "http://localhost:9400",
     clientId: "rpcbase-sample-app",
     scope: "openid email profile",
+    callbackPath: "/api/auth/oauth/mock/callback",
   },
 })
 
@@ -61,10 +54,55 @@ export const runApi = async ({ app }) => {
 
 The app is responsible for sourcing secrets (env, vault, etc.) and passing them to `configureOAuthProviders()`.
 
+Each provider must define a `scope` and a `callbackPath` so the generated `redirect_uri` matches your routing:
+
+```ts
+configureOAuthProviders({
+  google: {
+    issuer: "https://accounts.google.com",
+    clientId: process.env.GOOGLE_CLIENT_ID!,
+    scope: "openid email profile",
+    callbackPath: "/api/auth/oauth/google/callback",
+  },
+})
+```
+
 ### 3) Start the OAuth flow from the client
 
 ```ts
-window.location.assign("/api/rb/auth/oauth/mock/start")
+window.location.assign("/api/auth/oauth/mock/start")
+```
+
+You can optionally pass a return path:
+
+```ts
+window.location.assign("/api/auth/oauth/mock/start?returnTo=/app")
+```
+
+### Optional: declare OAuth routes yourself
+
+If you don’t want to mount the full `authRoutes`, you can register the OAuth handlers manually:
+
+```ts
+import { createOAuthCallbackHandler, createOAuthStartHandler } from "@rpcbase/auth/oauth"
+
+export default (api) => {
+  api.get("/api/auth/oauth/:provider/start", createOAuthStartHandler({
+    getAuthorizationParams: (providerId) =>
+      providerId === "apple"
+        ? { response_mode: "form_post" }
+        : undefined,
+  }))
+
+  const callback = createOAuthCallbackHandler({
+    createUserOnFirstSignIn: false,
+    missingUserRedirectPath: "/auth/sign-up",
+    successRedirectPath: "/app",
+  })
+
+  api.get("/api/auth/oauth/:provider/callback", callback)
+  api.post("/api/auth/oauth/:provider/callback", callback)
+}
 ```
 
 ### 4) What happens on callback
@@ -76,6 +114,16 @@ On a successful callback:
 - the matching `RBUser` is created on first-seen identity (and the OAuth credentials are saved under `RBUser.oauthProviders[provider]`)
 - the session is signed in, and the user is redirected to `/onboarding`
 
+If the callback handler is configured with `createUserOnFirstSignIn: false` and no matching user is found, it redirects to `missingUserRedirectPath` (when provided).
+
+### Apple (helper)
+
+Apple requires a JWT `clientSecret`. You can generate it server-side:
+
+```ts
+import { createAppleClientSecret } from "@rpcbase/auth/oauth"
+```
+
 ### Mock provider (dev/tests)
 
 This repo uses `oauth2-mock-server` in `sample-app/server.js` to spin up a local OIDC provider for development and Playwright tests.
@@ -83,5 +131,4 @@ This repo uses `oauth2-mock-server` in `sample-app/server.js` to spin up a local
 Notes:
 
 - `oauth2-mock-server` simulates auth and immediately redirects back on `/authorize` (it does not provide a UI to pick an account).
-- Disable it with `RB_DISABLE_OAUTH_MOCK=1`
 - Override the port with `RB_OAUTH_MOCK_SERVER_PORT` (default `9400`)

package/dist/oauth/config.d.ts

@@ -2,7 +2,8 @@ export type OAuthProviderConfig = {
     issuer: string;
     clientId: string;
     clientSecret?: string;
-    scope?: string;
+    scope: string;
+    callbackPath: string;
 };
 export declare const configureOAuthProviders: (providers: Record<string, OAuthProviderConfig>) => void;
 export declare const setOAuthProviders: (providers: Record<string, OAuthProviderConfig>) => void;

package/dist/oauth/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/oauth/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf,CAAA;AAoDD,eAAO,MAAM,uBAAuB,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,SAIrF,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,SAG/E,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,YAAY,MAAM,KAAG,mBAAmB,GAAG,IAGjF,CAAA"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/oauth/config.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAChC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,MAAM,CAAA;IACb,YAAY,EAAE,MAAM,CAAA;CACrB,CAAA;AAiED,eAAO,MAAM,uBAAuB,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,SAIrF,CAAA;AAED,eAAO,MAAM,iBAAiB,GAAI,WAAW,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,SAG/E,CAAA;AAED,eAAO,MAAM,sBAAsB,GAAI,YAAY,MAAM,KAAG,mBAAmB,GAAG,IAGjF,CAAA"}

package/dist/oauth/index.d.ts

@@ -0,0 +1,5 @@
+export { configureOAuthProviders, setOAuthProviders } from './config';
+export type { OAuthProviderConfig } from './config';
+export { createAppleClientSecret, createOAuthCallbackHandler, createOAuthStartHandler, getOAuthStartRedirectUrl, processOAuthCallback, } from './lib';
+export type { OAuthCallbackResult, OAuthStartResult } from './lib';
+//# sourceMappingURL=index.d.ts.map

package/dist/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,uBAAuB,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AACrE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAEnD,OAAO,EACL,uBAAuB,EACvB,0BAA0B,EAC1B,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,GACrB,MAAM,OAAO,CAAA;AACd,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAA"}