@eventuras/fides-auth 0.14.1 → 0.15.0

package/README.md

@@ -8,6 +8,7 @@ Framework-agnostic OAuth 2.0 / OpenID Connect library with PKCE, encrypted sessi
 - **Pushed Authorization Requests** — Opt-in RFC 9126 support (`usePar`) when the provider advertises it
 - **Dual environment** — Node.js (`openid-client`) and browser (Web Crypto) entry points
 - **Encrypted sessions** — AES-256-GCM encrypted JWTs for secure session storage
+- **Server-side sessions** — Opt-in store behind an opaque handle cookie, for providers whose tokens don't fit a cookie
 - **Rate limiting** — Generic token-bucket algorithm, ready for login protection
 - **RP-initiated logout** — End the provider's session too, with `id_token_hint` (OIDC RP-Initiated Logout 1.0)
 - **Silent login** — Detect `prompt=none` results without user interaction
@@ -68,37 +69,6 @@ const jwt = await createEncryptedJWT({ user, tokens }, secret);
 const { status, session } = await validateSessionJwt(jwt, secret);
 ```
 
-### Browser — OAuth SPA Flow
-
-```typescript
-import {
-  generatePKCE,
-  buildAuthorizationUrl,
-  exchangeCodeForTokens,
-} from "@eventuras/fides-auth/oauth-browser";
-
-const config = {
-  issuer: "https://auth.example.com",
-  clientId: "my-client-id",
-  redirect_uri: "https://myapp.com/callback",
-  scope: "openid profile email",
-};
-
-// Start flow
-const pkce = await generatePKCE();
-sessionStorage.setItem("code_verifier", pkce.code_verifier);
-sessionStorage.setItem("state", pkce.state);
-window.location.href = buildAuthorizationUrl(config, pkce);
-
-// Handle callback
-const code = new URLSearchParams(location.search).get("code");
-const tokens = await exchangeCodeForTokens(
-  config,
-  code,
-  sessionStorage.getItem("code_verifier")!,
-);
-```
-
 ## Modules
 
 Each module is available as a separate entry point for tree-shaking:
@@ -107,7 +77,9 @@ Each module is available as a separate entry point for tree-shaking:
 | ------------------------------------------ | ----------- | ----------------------------------------------------- |
 | `@eventuras/fides-auth`                    | Node.js     | Main entry — re-exports utils, session, types, logger |
 | `@eventuras/fides-auth/oauth`              | Node.js     | OAuth/OIDC flows with `openid-client`                 |
-| `@eventuras/fides-auth/oauth-browser`      | Browser     | OAuth/OIDC flows with Web Crypto API                  |
+| `@eventuras/fides-auth/pkce`               | Universal   | PKCE verifier/challenge and `state` (Web Crypto)      |
+| `@eventuras/fides-auth/id-token`           | Universal   | ID token verification against the provider JWKS       |
+| `@eventuras/fides-auth/oauth-browser`      | Browser     | **Deprecated** — OAuth/OIDC flows with Web Crypto API |
 | `@eventuras/fides-auth/session-validation` | Node.js     | Encrypted JWT session validation                      |
 | `@eventuras/fides-auth/session-refresh`    | Node.js     | Automatic token refresh for sessions                  |
 | `@eventuras/fides-auth/silent-login`       | Node.js     | Silent login (`prompt=none`) utilities                |
@@ -138,6 +110,133 @@ import {
 } from "@eventuras/fides-auth/oauth";
 ```
 
+`extractUserFromTokens` and `buildSessionFromTokens` only decode the ID token —
+they don't check its signature, `iss`, `aud` or `exp`. That is safe on tokens
+straight from `exchangeAuthorizationCode`. Verify tokens from anywhere else
+first with `verifyIdToken` from `@eventuras/fides-auth/id-token`.
+
+#### Session mapping
+
+`buildSessionFromTokens` keeps the standard fields. To keep more of the token
+response or the ID token claims, pass `mapSession`, here or to
+`handleOidcCallback`:
+
+```typescript
+const session = buildSessionFromTokens(tokens, {
+  rolesClaim: "groups",
+  mapSession: (tokens, claims, session) => ({
+    ...session,
+    data: { tenant: tokens.tenant },
+  }),
+});
+```
+
+`claims` are decoded, not verified. Without an `id_token` (no `openid` scope),
+`claims` is undefined and the session has no `user`. `user.email` is optional.
+Extra fields make the session bigger; large ones need
+[server-side sessions](./docs/server-sessions.md).
+
+#### Client authentication
+
+`clientAuth` sets how the client authenticates at the token endpoint. Omit it
+for `client_secret_post`:
+
+```typescript
+{ clientSecret: "…" }                                    // client_secret_post
+{ clientAuth: "client_secret_basic", clientSecret: "…" }
+{ clientAuth: "none" }                                   // public client, PKCE only
+{ clientAuth: "private_key_jwt", privateKey }            // CryptoKey or { key, kid }
+```
+
+`clientCredentialsGrant` takes the same options except `none`.
+
+#### Server metadata instead of discovery
+
+If the server publishes its metadata somewhere other than
+`/.well-known/openid-configuration` (an RFC 8414 document, say), fetch it
+yourself and pass it as `serverMetadata`. fides-auth then skips discovery:
+
+```typescript
+const oauthConfig: OAuthConfig = {
+  issuer: "https://auth.example.com",
+  clientId: "your-client-id",
+  clientAuth: "none",
+  redirect_uri: "https://app.example.com/callback",
+  scope: "openid profile",
+  serverMetadata: await fetch(metadataUrl).then((r) => r.json()),
+};
+```
+
+With `openid` in the scope the metadata must include `issuer`, so the ID token's
+`iss` can be checked.
+
+#### PKCE and state (`/pkce`)
+
+For flows that manage their own login transaction. Web Crypto only, so it also
+runs in the browser and on edge runtimes:
+
+```typescript
+import { createPkcePair, createState } from "@eventuras/fides-auth/pkce";
+
+const { verifier, challenge } = await createPkcePair(); // S256
+const state = createState();
+```
+
+`buildPKCEOptions` is built on the same two functions.
+
+#### ID token verification (`/id-token`)
+
+Checks an ID token's signature, `iss`, `aud` and `exp` against the provider's
+JWKS and returns the claims. Also runs in the browser:
+
+```typescript
+import { verifyIdToken } from "@eventuras/fides-auth/id-token";
+
+const claims = await verifyIdToken(idToken, {
+  issuer: "https://auth.example.com",
+  audience: "your-client-id",
+  oauthConfig, // or jwksUri: "https://auth.example.com/jwks"
+});
+```
+
+`algorithms` defaults to `RS*`, `PS*`, `ES*` and `EdDSA`. The JWKS is cached per URI.
+
+#### Scope and extra authorization parameters
+
+`scope` takes a string or an array. Other authorization parameters (`prompt`,
+`login_hint`, `resource`, …) can be set on the config, per call, or per request
+in `handleOidcLogin`. They go through PAR too.
+
+```typescript
+const oauthConfig = {
+  // …
+  scope: ["openid", "profile", "offline_access"],
+  authorizationParameters: { resource: "https://api.example.com" },
+};
+
+const pkce = await buildPKCEOptions(oauthConfig, {
+  parameters: { login_hint: "user@example.com" },
+});
+
+// Or per request in the server handler
+return handleOidcLogin(request, {
+  oauthConfig,
+  cookies,
+  secret: process.env.SESSION_SECRET!,
+  authorizationParameters: (request) =>
+    new URL(request.url).searchParams.has("reauth") ? { prompt: "login" } : {},
+});
+```
+
+Per-call parameters override the config's, and a `scope` among them replaces
+`OAuthConfig.scope`. These keys are reserved, and passing one throws:
+
+- `state`, `code_challenge`, `code_challenge_method` and `redirect_uri`, which
+  fides-auth sets.
+- `client_id` and `response_type`, which openid-client sets.
+- `request` and `request_uri`, which would bypass PKCE and `state`.
+- `nonce`, which the callback doesn't check, so the login would fail.
+
 #### Pushed Authorization Requests (PAR, RFC 9126)
 
 Opt in by setting `usePar: true` on your `OAuthConfig`. The convenience
@@ -190,7 +289,7 @@ const logoutUrl = await buildOidcLogoutUrl(oauthConfig, {
 ```
 
 The `/server` entry point wraps the whole dance — read the hint, clear the cookies,
-redirect:
+redirect. Its handlers never read the environment; pass the session `secret` in:
 
 ```typescript
 import { handleOidcLogout } from "@eventuras/fides-auth/server";
@@ -198,6 +297,7 @@ import { handleOidcLogout } from "@eventuras/fides-auth/server";
 return handleOidcLogout(request, {
   oauthConfig,
   cookies,
+  secret: process.env.SESSION_SECRET!,
   postLogoutRedirectUri: "https://app.example.com/",
 });
 ```
@@ -205,8 +305,100 @@ return handleOidcLogout(request, {
 See [docs/rp-initiated-logout.md](./docs/rp-initiated-logout.md) for the full
 parameter set, where the ID token is stored, and why `client_id` is still sent.
 
+#### Server-side sessions
+
+By default the session is encrypted into cookies. When a provider's tokens are
+too large for that (OpenIddict's encrypted JWE tokens, for instance), keep the
+session in a store and give the browser only a handle:
+
+```typescript
+import { serverPersistence, createMemorySessionStore } from "@eventuras/fides-auth/server";
+
+const persistence = serverPersistence({
+  store: createMemorySessionStore(), // or your own SessionStore (Mongo, Redis, …)
+  secret: process.env.SESSION_SECRET!,
+});
+
+return handleHeartbeat(request, { oauthConfig, cookies, persistence });
+```
+
+Logout, heartbeat and the session helpers take `persistence` in place of
+`secret`. The callback takes both: `secret` also opens the login transaction.
+The store gets encrypted records keyed by a hash of the handle; `clearSession`
+deletes the record, so logout revokes a copied cookie too. See
+[docs/server-sessions.md](./docs/server-sessions.md).
+
+#### Login transaction
+
+`handleOidcLogin` seals each login (state, PKCE verifier, returnTo, start time)
+into one of three `__Host-oauth_tx_<n>` cookies, so parallel logins don't
+collide; a fourth evicts the oldest, and a `returnTo` over 1 KB as JSON is dropped. With
+an `http:` `redirect_uri` (plain-http development) the cookie is a plain,
+non-Secure `oauth_tx_<n>`. `handleOidcCallback` rejects it after 10 minutes and
+deletes it whatever the outcome. Pass both handlers the same `secret`. A denied
+or cancelled login redirects to `defaultRedirectPath` with
+`?login=error&error=<code>`, or `error=login_expired` once the login has ended.
+
+Custom flows use the same helpers. Pass them the handlers' cookie options, so a
+custom login and the built-in callback (or the reverse) agree on the cookie:
+
+```typescript
+import {
+  createTransaction,
+  persistTransaction,
+  readTransaction,
+  clearTransaction,
+  validateCallback,
+  transactionCookieOptions,
+} from "@eventuras/fides-auth/server";
+
+const txCookie = transactionCookieOptions(oauthConfig.redirect_uri);
+
+// Login
+const pkce = await buildPKCEOptions(oauthConfig);
+await persistTransaction(cookies, createTransaction(pkce, { returnTo }), secret, txCookie);
+
+// Callback
+try {
+  const transaction = await readTransaction(cookies, state, secret, txCookie);
+  if (!transaction) throw new Error("No login in progress");
+  validateCallback(query, transaction); // throws CallbackValidationError
+  // … exchangeAuthorizationCode(oauthConfig, url, transaction.codeVerifier, transaction.state)
+} finally {
+  await clearTransaction(cookies, state, secret, txCookie);
+}
+```
+
+#### API calls with the access token
+
+`authorizedFetch` sends the session's access token only to URLs under
+`allowedBase` (same origin, and a path under its path), never follows a
+redirect, and times out after 10 seconds by default. A refused URL, non-2xx
+response, timeout or failed `parse` throws an `AuthorizedFetchError` with a
+`reason`, the status, and the URL without its query. On a 401 it calls `refresh`
+once and retries once:
+
+```typescript
+import { authorizedFetch, tryRefreshSessionInStore } from "@eventuras/fides-auth/server";
+
+const { data, session: current } = await authorizedFetch(session, `users/${id}`, {
+  allowedBase: "https://api.example.com/v1/",
+  parse: async (response) => parseUser(await response.json()),
+  refresh: () => tryRefreshSessionInStore(cookies, oauthConfig, secret),
+});
+```
+
+`refresh` may also return `refreshSessionInStore`'s result. Both persist the new
+session; use the returned `session` for later calls. When the refresh fails, the
+error is `refresh_failed`, and `error.refreshFailure.cause === "invalid_grant"`
+means the user must log in again.
+
 ### OAuth — Browser (`/oauth-browser`)
 
+> **Deprecated.** It hardcodes the provider endpoints and doesn't validate the
+> token response. Use the server flow instead (`handleOidcLogin` /
+> `handleOidcCallback` from `/server`). It will be removed in a later minor.
+
 Lightweight browser-only flows using Web Crypto:
 
 ```typescript

package/dist/activity-tracker.js

@@ -1,4 +1,4 @@
-//#region src/activity-tracker.ts
+// src/activity-tracker.ts
 /**
 * Records the most recent user activity timestamp by listening to DOM events.
 *
@@ -69,7 +69,6 @@ function createActivityTracker(options = {}) {
 		}
 	};
 }
-//#endregion
 export { DEFAULT_ACTIVITY_EVENTS, createActivityTracker };
 
 //# sourceMappingURL=activity-tracker.js.map

package/dist/cookies.d.ts

@@ -89,6 +89,12 @@ export declare const ID_TOKEN_COOKIE_NAME = "session_it";
  * apart.
  */
 export declare const SESSION_COOKIE_NAME = "session";
+/**
+ * Name of the cookie holding the opaque session handle under server
+ * persistence, where the session itself lives in a `SessionStore` and no token
+ * reaches the browser. See `server/session-persistence.ts`.
+ */
+export declare const SESSION_REF_COOKIE_NAME = "session_ref";
 /**
  * Serialized byte size of a `name=value` cookie pair. The browser per-cookie
  * limit applies to the serialized pair, so the `=` separator is counted too —

package/dist/cookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../src/cookies.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,UAAU,EAAE,MAAM;aAClB,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,MAAM;IAH/B,YACkB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAyB,EAMjD;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAMzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAMvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3E"}
+{"version":3,"file":"cookies.d.ts","sourceRoot":"","sources":["../src/cookies.ts"],"names":[],"mappings":"AAUA;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,OAAO,CAAC;AAEtC;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;aAE1B,UAAU,EAAE,MAAM;aAClB,IAAI,EAAE,MAAM;aACZ,KAAK,EAAE,MAAM;IAH/B,YACkB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,KAAK,GAAE,MAAyB,EAMjD;CACF;AAED,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IACrC,qCAAqC;IACrC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,2BAA2B,EAAE,aAMzC,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,EAAE,aAMvC,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,eAAe,CAAC;AAErD;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,eAAe,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,YAAY,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AAErD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAGlE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAM3E"}

package/dist/cookies.js

@@ -1,4 +1,4 @@
-//#region src/cookies.ts
+// src/cookies.ts
 /**
 * Browser per-cookie size limit (RFC 6265: browsers must support at least
 * 4096 bytes for the sum of the cookie's name and value). Cookies at or above
@@ -93,6 +93,12 @@ var ID_TOKEN_COOKIE_NAME = "session_it";
 */
 var SESSION_COOKIE_NAME = "session";
 /**
+* Name of the cookie holding the opaque session handle under server
+* persistence, where the session itself lives in a `SessionStore` and no token
+* reaches the browser. See `server/session-persistence.ts`.
+*/
+var SESSION_REF_COOKIE_NAME = "session_ref";
+/**
 * Serialized byte size of a `name=value` cookie pair. The browser per-cookie
 * limit applies to the serialized pair, so the `=` separator is counted too —
 * otherwise a borderline pair (name+value === 4095) would slip through only to be
@@ -112,7 +118,6 @@ function assertCookieWithinLimit(name, value) {
 	if (size >= 4096) throw new CookieTooLargeError(name, size);
 	return size;
 }
-//#endregion
-export { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, assertCookieWithinLimit, cookieByteSize, defaultOAuthCookieOptions, defaultSessionCookieOptions };
+export { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, SESSION_REF_COOKIE_NAME, assertCookieWithinLimit, cookieByteSize, defaultOAuthCookieOptions, defaultSessionCookieOptions };
 
 //# sourceMappingURL=cookies.js.map

package/dist/cookies.js.map

@@ -1 +1 @@
-{"version":3,"file":"cookies.js","names":[],"sources":["../src/cookies.ts"],"sourcesContent":["// cookies.ts\n//\n// Framework-agnostic cookie attributes, size limits, and the access-token cookie\n// name. This module performs no I/O — it never reads or writes cookies. Framework\n// adapters (Next.js, React Router, …) own the actual cookie store and use these\n// values and helpers to configure and size-check the cookies they set.\n//\n// The companion module `session-cookies.ts` encodes/decodes a session into cookie\n// *values*; this module is about the cookie *attributes* and *limits*.\n\n/**\n * Browser per-cookie size limit (RFC 6265: browsers must support at least\n * 4096 bytes for the sum of the cookie's name and value). Cookies at or above\n * this size are silently dropped by the browser, which manifests as a broken\n * login (the cookie is never stored, so the user appears unauthenticated).\n */\nexport const COOKIE_MAX_BYTES = 4096;\n\n/**\n * Threshold at which an adapter should emit an informational log that a cookie is\n * getting large. This is not an error — a session with many scopes/roles can\n * legitimately approach this size — it just gives visibility before the hard limit.\n */\nexport const COOKIE_INFO_BYTES = 3500;\n\n/**\n * Thrown when a cookie's name + value would meet or exceed the browser's\n * per-cookie size limit. Setting such a cookie would be silently dropped by the\n * browser, so adapters should fail loudly instead. Callers (e.g. an OIDC callback)\n * can catch this to surface a clear error rather than producing a broken login.\n */\nexport class CookieTooLargeError extends Error {\n  constructor(\n    public readonly cookieName: string,\n    public readonly size: number,\n    public readonly limit: number = COOKIE_MAX_BYTES,\n  ) {\n    super(\n      `Cookie \"${cookieName}\" is ${size} bytes, which meets or exceeds the browser limit of ${limit} bytes and would be silently dropped`,\n    );\n    this.name = 'CookieTooLargeError';\n  }\n}\n\nexport interface CookieOptions {\n  /** Cookie path (default: '/') */\n  path?: string;\n  /** Max age in seconds */\n  maxAge?: number;\n  /** SameSite policy (default: 'lax') */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** HTTP only flag (default: true) */\n  httpOnly?: boolean;\n  /**\n   * Secure flag. `true` in {@link defaultSessionCookieOptions} and\n   * {@link defaultOAuthCookieOptions}; when omitted from a hand-built options\n   * object, the adapter's own default applies.\n   */\n  secure?: boolean;\n}\n\n/**\n * Default cookie options for session cookies.\n * - Secure\n * - HTTP only\n * - Lax same-site policy\n * - 30 days max age\n *\n * `secure` is unconditional rather than derived from NODE_ENV: a deployment that\n * doesn't set it — staging, a container, any non-Next server — would otherwise put\n * the session cookie on the wire in the clear, silently.\n *\n * The cookie spec exempts localhost from the https requirement, so a `Secure`\n * cookie is still set and sent over `http://localhost` and local development is\n * unaffected. Plain http on any other host — a LAN address, a custom dev hostname —\n * needs an explicit `secure: false`.\n */\nexport const defaultSessionCookieOptions: CookieOptions = {\n  path: '/',\n  maxAge: 60 * 60 * 24 * 30, // 30 days\n  sameSite: 'lax',\n  httpOnly: true,\n  secure: true,\n};\n\n/**\n * Default cookie options for OAuth state/PKCE cookies.\n * - Secure — see {@link defaultSessionCookieOptions}\n * - HTTP only\n * - Lax same-site policy\n * - 10 minutes max age (short-lived for security)\n */\nexport const defaultOAuthCookieOptions: CookieOptions = {\n  path: '/',\n  maxAge: 60 * 10, // 10 minutes\n  sameSite: 'lax',\n  httpOnly: true,\n  secure: true,\n};\n\n/**\n * Name of the cookie holding the (split-out) access token.\n *\n * The access token — typically a large JWT carrying scopes/roles — is stored in\n * its own cookie so it gets a full per-cookie byte budget, instead of competing\n * for space with the rest of the session inside a single \"session\" cookie. See\n * {@link CookieTooLargeError} for the limit this works around.\n */\nexport const ACCESS_TOKEN_COOKIE_NAME = 'session_at';\n\n/**\n * Name of the cookie holding the (split-out) ID token, kept for `id_token_hint`\n * on RP-initiated logout.\n *\n * It gets its own cookie for two reasons: it is a second large JWT, which would\n * eat into the access token's byte budget, and it must outlive access-token\n * expiry — a logout after the session has gone stale is exactly when the hint is\n * needed.\n */\nexport const ID_TOKEN_COOKIE_NAME = 'session_it';\n\n/**\n * Name of the main session cookie (everything except the split-out access and ID\n * tokens). See {@link ACCESS_TOKEN_COOKIE_NAME} for why the raw tokens are stored\n * apart.\n */\nexport const SESSION_COOKIE_NAME = 'session';\n\n/**\n * Serialized byte size of a `name=value` cookie pair. The browser per-cookie\n * limit applies to the serialized pair, so the `=` separator is counted too —\n * otherwise a borderline pair (name+value === 4095) would slip through only to be\n * dropped at 4096 once serialized.\n */\nexport function cookieByteSize(name: string, value: string): number {\n  const encoder = new TextEncoder();\n  return encoder.encode(name).length + 1 + encoder.encode(value).length;\n}\n\n/**\n * Asserts that a `name=value` cookie pair is within the browser's per-cookie\n * limit, throwing {@link CookieTooLargeError} if not. Returns the measured byte\n * size so callers can additionally log when it crosses {@link COOKIE_INFO_BYTES}.\n */\nexport function assertCookieWithinLimit(name: string, value: string): number {\n  const size = cookieByteSize(name, value);\n  if (size >= COOKIE_MAX_BYTES) {\n    throw new CookieTooLargeError(name, size);\n  }\n  return size;\n}\n"],"mappings":";;;;;;;AAgBA,IAAa,mBAAmB;;;;;;AAOhC,IAAa,oBAAoB;;;;;;;AAQjC,IAAa,sBAAb,cAAyC,MAAM;CAE3B;CACA;CACA;CAHlB,YACE,YACA,MACA,QAAgC,kBAChC;EACA,MACE,WAAW,WAAW,OAAO,KAAK,sDAAsD,MAAM,qCAChG;EANgB,KAAA,aAAA;EACA,KAAA,OAAA;EACA,KAAA,QAAA;EAKhB,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;AAmCA,IAAa,8BAA6C;CACxD,MAAM;CACN,QAAQ;CACR,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;;;;;AASA,IAAa,4BAA2C;CACtD,MAAM;CACN,QAAQ;CACR,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;;;;;;AAUA,IAAa,2BAA2B;;;;;;;;;;AAWxC,IAAa,uBAAuB;;;;;;AAOpC,IAAa,sBAAsB;;;;;;;AAQnC,SAAgB,eAAe,MAAc,OAAuB;CAClE,MAAM,UAAU,IAAI,YAAY;CAChC,OAAO,QAAQ,OAAO,IAAI,CAAC,CAAC,SAAS,IAAI,QAAQ,OAAO,KAAK,CAAC,CAAC;AACjE;;;;;;AAOA,SAAgB,wBAAwB,MAAc,OAAuB;CAC3E,MAAM,OAAO,eAAe,MAAM,KAAK;CACvC,IAAI,QAAA,MACF,MAAM,IAAI,oBAAoB,MAAM,IAAI;CAE1C,OAAO;AACT"}
+{"version":3,"file":"cookies.js","names":[],"sources":["../src/cookies.ts"],"sourcesContent":["// cookies.ts\n//\n// Framework-agnostic cookie attributes, size limits, and the access-token cookie\n// name. This module performs no I/O — it never reads or writes cookies. Framework\n// adapters (Next.js, React Router, …) own the actual cookie store and use these\n// values and helpers to configure and size-check the cookies they set.\n//\n// The companion module `session-cookies.ts` encodes/decodes a session into cookie\n// *values*; this module is about the cookie *attributes* and *limits*.\n\n/**\n * Browser per-cookie size limit (RFC 6265: browsers must support at least\n * 4096 bytes for the sum of the cookie's name and value). Cookies at or above\n * this size are silently dropped by the browser, which manifests as a broken\n * login (the cookie is never stored, so the user appears unauthenticated).\n */\nexport const COOKIE_MAX_BYTES = 4096;\n\n/**\n * Threshold at which an adapter should emit an informational log that a cookie is\n * getting large. This is not an error — a session with many scopes/roles can\n * legitimately approach this size — it just gives visibility before the hard limit.\n */\nexport const COOKIE_INFO_BYTES = 3500;\n\n/**\n * Thrown when a cookie's name + value would meet or exceed the browser's\n * per-cookie size limit. Setting such a cookie would be silently dropped by the\n * browser, so adapters should fail loudly instead. Callers (e.g. an OIDC callback)\n * can catch this to surface a clear error rather than producing a broken login.\n */\nexport class CookieTooLargeError extends Error {\n  constructor(\n    public readonly cookieName: string,\n    public readonly size: number,\n    public readonly limit: number = COOKIE_MAX_BYTES,\n  ) {\n    super(\n      `Cookie \"${cookieName}\" is ${size} bytes, which meets or exceeds the browser limit of ${limit} bytes and would be silently dropped`,\n    );\n    this.name = 'CookieTooLargeError';\n  }\n}\n\nexport interface CookieOptions {\n  /** Cookie path (default: '/') */\n  path?: string;\n  /** Max age in seconds */\n  maxAge?: number;\n  /** SameSite policy (default: 'lax') */\n  sameSite?: 'strict' | 'lax' | 'none';\n  /** HTTP only flag (default: true) */\n  httpOnly?: boolean;\n  /**\n   * Secure flag. `true` in {@link defaultSessionCookieOptions} and\n   * {@link defaultOAuthCookieOptions}; when omitted from a hand-built options\n   * object, the adapter's own default applies.\n   */\n  secure?: boolean;\n}\n\n/**\n * Default cookie options for session cookies.\n * - Secure\n * - HTTP only\n * - Lax same-site policy\n * - 30 days max age\n *\n * `secure` is unconditional rather than derived from NODE_ENV: a deployment that\n * doesn't set it — staging, a container, any non-Next server — would otherwise put\n * the session cookie on the wire in the clear, silently.\n *\n * The cookie spec exempts localhost from the https requirement, so a `Secure`\n * cookie is still set and sent over `http://localhost` and local development is\n * unaffected. Plain http on any other host — a LAN address, a custom dev hostname —\n * needs an explicit `secure: false`.\n */\nexport const defaultSessionCookieOptions: CookieOptions = {\n  path: '/',\n  maxAge: 60 * 60 * 24 * 30, // 30 days\n  sameSite: 'lax',\n  httpOnly: true,\n  secure: true,\n};\n\n/**\n * Default cookie options for OAuth state/PKCE cookies.\n * - Secure — see {@link defaultSessionCookieOptions}\n * - HTTP only\n * - Lax same-site policy\n * - 10 minutes max age (short-lived for security)\n */\nexport const defaultOAuthCookieOptions: CookieOptions = {\n  path: '/',\n  maxAge: 60 * 10, // 10 minutes\n  sameSite: 'lax',\n  httpOnly: true,\n  secure: true,\n};\n\n/**\n * Name of the cookie holding the (split-out) access token.\n *\n * The access token — typically a large JWT carrying scopes/roles — is stored in\n * its own cookie so it gets a full per-cookie byte budget, instead of competing\n * for space with the rest of the session inside a single \"session\" cookie. See\n * {@link CookieTooLargeError} for the limit this works around.\n */\nexport const ACCESS_TOKEN_COOKIE_NAME = 'session_at';\n\n/**\n * Name of the cookie holding the (split-out) ID token, kept for `id_token_hint`\n * on RP-initiated logout.\n *\n * It gets its own cookie for two reasons: it is a second large JWT, which would\n * eat into the access token's byte budget, and it must outlive access-token\n * expiry — a logout after the session has gone stale is exactly when the hint is\n * needed.\n */\nexport const ID_TOKEN_COOKIE_NAME = 'session_it';\n\n/**\n * Name of the main session cookie (everything except the split-out access and ID\n * tokens). See {@link ACCESS_TOKEN_COOKIE_NAME} for why the raw tokens are stored\n * apart.\n */\nexport const SESSION_COOKIE_NAME = 'session';\n\n/**\n * Name of the cookie holding the opaque session handle under server\n * persistence, where the session itself lives in a `SessionStore` and no token\n * reaches the browser. See `server/session-persistence.ts`.\n */\nexport const SESSION_REF_COOKIE_NAME = 'session_ref';\n\n/**\n * Serialized byte size of a `name=value` cookie pair. The browser per-cookie\n * limit applies to the serialized pair, so the `=` separator is counted too —\n * otherwise a borderline pair (name+value === 4095) would slip through only to be\n * dropped at 4096 once serialized.\n */\nexport function cookieByteSize(name: string, value: string): number {\n  const encoder = new TextEncoder();\n  return encoder.encode(name).length + 1 + encoder.encode(value).length;\n}\n\n/**\n * Asserts that a `name=value` cookie pair is within the browser's per-cookie\n * limit, throwing {@link CookieTooLargeError} if not. Returns the measured byte\n * size so callers can additionally log when it crosses {@link COOKIE_INFO_BYTES}.\n */\nexport function assertCookieWithinLimit(name: string, value: string): number {\n  const size = cookieByteSize(name, value);\n  if (size >= COOKIE_MAX_BYTES) {\n    throw new CookieTooLargeError(name, size);\n  }\n  return size;\n}\n"],"mappings":";;;;;;;AAgBA,IAAa,mBAAmB;;;;;;AAOhC,IAAa,oBAAoB;;;;;;;AAQjC,IAAa,sBAAb,cAAyC,MAAM;CAE3B;CACA;CACA;CAHlB,YACE,YACA,MACA,QAAgC,kBAChC;EACA,MACE,WAAW,WAAW,OAAO,KAAK,sDAAsD,MAAM,qCAChG;EANgB,KAAA,aAAA;EACA,KAAA,OAAA;EACA,KAAA,QAAA;EAKhB,KAAK,OAAO;CACd;AACF;;;;;;;;;;;;;;;;;AAmCA,IAAa,8BAA6C;CACxD,MAAM;CACN,QAAQ;CACR,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;;;;;AASA,IAAa,4BAA2C;CACtD,MAAM;CACN,QAAQ;CACR,UAAU;CACV,UAAU;CACV,QAAQ;AACV;;;;;;;;;AAUA,IAAa,2BAA2B;;;;;;;;;;AAWxC,IAAa,uBAAuB;;;;;;AAOpC,IAAa,sBAAsB;;;;;;AAOnC,IAAa,0BAA0B;;;;;;;AAQvC,SAAgB,eAAe,MAAc,OAAuB;CAClE,MAAM,UAAU,IAAI,YAAY;CAChC,OAAO,QAAQ,OAAO,IAAI,CAAC,CAAC,SAAS,IAAI,QAAQ,OAAO,KAAK,CAAC,CAAC;AACjE;;;;;;AAOA,SAAgB,wBAAwB,MAAc,OAAuB;CAC3E,MAAM,OAAO,eAAe,MAAM,KAAK;CACvC,IAAI,QAAA,MACF,MAAM,IAAI,oBAAoB,MAAM,IAAI;CAE1C,OAAO;AACT"}

package/dist/heartbeat.js

@@ -1,7 +1,7 @@
 import { DEFAULT_ACTIVITY_EVENTS, createActivityTracker } from "./activity-tracker.js";
 import { createLogger } from "./logger.js";
 import { SESSION_EVENT, isSessionRejectedReason } from "./session-events.js";
-//#region src/heartbeat.ts
+// src/heartbeat.ts
 var DEFAULTS = {
 	endpoint: "/api/auth/heartbeat",
 	fraction: .3,
@@ -197,7 +197,6 @@ function createHeartbeat(config = {}) {
 	}, "Heartbeat started");
 	return { stop: teardown };
 }
-//#endregion
 export { createHeartbeat };
 
 //# sourceMappingURL=heartbeat.js.map

package/dist/id-token.d.ts

@@ -0,0 +1,31 @@
+import { type JWTPayload } from 'jose';
+import type { OAuthConfig } from './oauth-config';
+interface VerifyIdTokenBaseOptions {
+    /** Expected `iss`. */
+    issuer: string;
+    /** Expected `aud`, usually the client ID. */
+    audience: string | string[];
+    /** Accepted `alg` values. Defaults to `RS*`, `PS*`, `ES*` and `EdDSA`. */
+    algorithms?: string[];
+}
+/** Options for {@link verifyIdToken}. Pass `jwksUri` or `oauthConfig`. */
+export type VerifyIdTokenOptions = VerifyIdTokenBaseOptions & ({
+    /** The provider's JWKS URL. */
+    jwksUri: string | URL;
+    oauthConfig?: never;
+} | {
+    /** Reads `jwks_uri` from discovery, or from `serverMetadata`. */
+    oauthConfig: OAuthConfig;
+    jwksUri?: never;
+});
+/** Drops every cached JWKS. Tests should call it between cases. */
+export declare function clearJwksCache(): void;
+/**
+ * Verifies an ID token's signature, `iss`, `aud` and `exp` against the provider's JWKS.
+ *
+ * @returns The verified claims.
+ * @throws A jose error if the token is invalid, or a `TypeError` if no JWKS URI is found.
+ */
+export declare function verifyIdToken(idToken: string, options: VerifyIdTokenOptions): Promise<JWTPayload>;
+export {};
+//# sourceMappingURL=id-token.d.ts.map

package/dist/id-token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-token.d.ts","sourceRoot":"","sources":["../src/id-token.ts"],"names":[],"mappings":"AAIA,OAAO,EAAsB,KAAK,UAAU,EAAa,MAAM,MAAM,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAsBlD,UAAU,wBAAwB;IAChC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC5B,0EAA0E;IAC1E,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,0EAA0E;AAC1E,MAAM,MAAM,oBAAoB,GAAG,wBAAwB,GACzD,CACI;IACE,+BAA+B;IAC/B,OAAO,EAAE,MAAM,GAAG,GAAG,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC;CACrB,GACD;IACE,iEAAiE;IACjE,WAAW,EAAE,WAAW,CAAC;IACzB,OAAO,CAAC,EAAE,KAAK,CAAC;CACjB,CACJ,CAAC;AAEJ,mEAAmE;AACnE,wBAAgB,cAAc,IAAI,IAAI,CAErC;AAqBD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,UAAU,CAAC,CAUrB"}

package/dist/id-token.js

@@ -0,0 +1,60 @@
+import { discoverConfiguration } from "./oidc-discovery.js";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+// src/id-token.ts
+/** Asymmetric only, so `none` and `HS*` are rejected. */
+var DEFAULT_ALGORITHMS = [
+	"RS256",
+	"RS384",
+	"RS512",
+	"PS256",
+	"PS384",
+	"PS512",
+	"ES256",
+	"ES384",
+	"ES512",
+	"EdDSA"
+];
+/** One getter per JWKS URI; jose refetches it on an unknown `kid`. */
+var jwksCache = /* @__PURE__ */ new Map();
+/** Drops every cached JWKS. Tests should call it between cases. */
+function clearJwksCache() {
+	jwksCache.clear();
+}
+function getJwks(uri) {
+	const url = new URL(uri);
+	let jwks = jwksCache.get(url.href);
+	if (!jwks) {
+		jwks = createRemoteJWKSet(url);
+		jwksCache.set(url.href, jwks);
+	}
+	return jwks;
+}
+async function resolveJwksUri(options) {
+	if (options.jwksUri !== void 0) return options.jwksUri;
+	const { jwks_uri } = (await discoverConfiguration(options.oauthConfig)).serverMetadata();
+	if (!jwks_uri) throw new TypeError("The provider metadata has no jwks_uri");
+	return jwks_uri;
+}
+/**
+* Verifies an ID token's signature, `iss`, `aud` and `exp` against the provider's JWKS.
+*
+* @returns The verified claims.
+* @throws A jose error if the token is invalid, or a `TypeError` if no JWKS URI is found.
+*/
+async function verifyIdToken(idToken, options) {
+	const jwks = getJwks(await resolveJwksUri(options));
+	const { payload } = await jwtVerify(idToken, jwks, {
+		issuer: options.issuer,
+		audience: options.audience,
+		algorithms: options.algorithms ?? DEFAULT_ALGORITHMS,
+		requiredClaims: [
+			"sub",
+			"exp",
+			"iat"
+		]
+	});
+	return payload;
+}
+export { clearJwksCache, verifyIdToken };
+
+//# sourceMappingURL=id-token.js.map

package/dist/id-token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-token.js","names":[],"sources":["../src/id-token.ts"],"sourcesContent":["// id-token.ts\n//\n// Verifies ID tokens against the provider's JWKS. Universal: jose uses Web Crypto and fetch.\n\nimport { createRemoteJWKSet, type JWTPayload, jwtVerify } from 'jose';\n\nimport type { OAuthConfig } from './oauth-config';\nimport { discoverConfiguration } from './oidc-discovery';\n\n/** Asymmetric only, so `none` and `HS*` are rejected. */\nconst DEFAULT_ALGORITHMS = [\n  'RS256',\n  'RS384',\n  'RS512',\n  'PS256',\n  'PS384',\n  'PS512',\n  'ES256',\n  'ES384',\n  'ES512',\n  'EdDSA',\n];\n\ntype RemoteJwks = ReturnType<typeof createRemoteJWKSet>;\n\n/** One getter per JWKS URI; jose refetches it on an unknown `kid`. */\nconst jwksCache = new Map<string, RemoteJwks>();\n\ninterface VerifyIdTokenBaseOptions {\n  /** Expected `iss`. */\n  issuer: string;\n  /** Expected `aud`, usually the client ID. */\n  audience: string | string[];\n  /** Accepted `alg` values. Defaults to `RS*`, `PS*`, `ES*` and `EdDSA`. */\n  algorithms?: string[];\n}\n\n/** Options for {@link verifyIdToken}. Pass `jwksUri` or `oauthConfig`. */\nexport type VerifyIdTokenOptions = VerifyIdTokenBaseOptions &\n  (\n    | {\n        /** The provider's JWKS URL. */\n        jwksUri: string | URL;\n        oauthConfig?: never;\n      }\n    | {\n        /** Reads `jwks_uri` from discovery, or from `serverMetadata`. */\n        oauthConfig: OAuthConfig;\n        jwksUri?: never;\n      }\n  );\n\n/** Drops every cached JWKS. Tests should call it between cases. */\nexport function clearJwksCache(): void {\n  jwksCache.clear();\n}\n\nfunction getJwks(uri: string | URL): RemoteJwks {\n  const url = new URL(uri);\n  let jwks = jwksCache.get(url.href);\n  if (!jwks) {\n    jwks = createRemoteJWKSet(url);\n    jwksCache.set(url.href, jwks);\n  }\n  return jwks;\n}\n\nasync function resolveJwksUri(options: VerifyIdTokenOptions): Promise<string | URL> {\n  if (options.jwksUri !== undefined) return options.jwksUri;\n\n  const configuration = await discoverConfiguration(options.oauthConfig);\n  const { jwks_uri } = configuration.serverMetadata();\n  if (!jwks_uri) throw new TypeError('The provider metadata has no jwks_uri');\n  return jwks_uri;\n}\n\n/**\n * Verifies an ID token's signature, `iss`, `aud` and `exp` against the provider's JWKS.\n *\n * @returns The verified claims.\n * @throws A jose error if the token is invalid, or a `TypeError` if no JWKS URI is found.\n */\nexport async function verifyIdToken(\n  idToken: string,\n  options: VerifyIdTokenOptions,\n): Promise<JWTPayload> {\n  const jwks = getJwks(await resolveJwksUri(options));\n  const { payload } = await jwtVerify(idToken, jwks, {\n    issuer: options.issuer,\n    audience: options.audience,\n    algorithms: options.algorithms ?? DEFAULT_ALGORITHMS,\n    // jose checks `exp` only when present; OIDC requires it.\n    requiredClaims: ['sub', 'exp', 'iat'],\n  });\n  return payload;\n}\n"],"mappings":";;;;AAUA,IAAM,qBAAqB;CACzB;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF;;AAKA,IAAM,4BAAY,IAAI,IAAwB;;AA2B9C,SAAgB,iBAAuB;CACrC,UAAU,MAAM;AAClB;AAEA,SAAS,QAAQ,KAA+B;CAC9C,MAAM,MAAM,IAAI,IAAI,GAAG;CACvB,IAAI,OAAO,UAAU,IAAI,IAAI,IAAI;CACjC,IAAI,CAAC,MAAM;EACT,OAAO,mBAAmB,GAAG;EAC7B,UAAU,IAAI,IAAI,MAAM,IAAI;CAC9B;CACA,OAAO;AACT;AAEA,eAAe,eAAe,SAAsD;CAClF,IAAI,QAAQ,YAAY,KAAA,GAAW,OAAO,QAAQ;CAGlD,MAAM,EAAE,cAAa,MADO,sBAAsB,QAAQ,WAAW,EAAA,CAClC,eAAe;CAClD,IAAI,CAAC,UAAU,MAAM,IAAI,UAAU,uCAAuC;CAC1E,OAAO;AACT;;;;;;;AAQA,eAAsB,cACpB,SACA,SACqB;CACrB,MAAM,OAAO,QAAQ,MAAM,eAAe,OAAO,CAAC;CAClD,MAAM,EAAE,YAAY,MAAM,UAAU,SAAS,MAAM;EACjD,QAAQ,QAAQ;EAChB,UAAU,QAAQ;EAClB,YAAY,QAAQ,cAAc;EAElC,gBAAgB;GAAC;GAAO;GAAO;EAAK;CACtC,CAAC;CACD,OAAO;AACT"}

package/dist/index.js

@@ -1,10 +1,10 @@
 import { DEFAULT_ACTIVITY_EVENTS, createActivityTracker } from "./activity-tracker.js";
-import { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, assertCookieWithinLimit, cookieByteSize, defaultOAuthCookieOptions, defaultSessionCookieOptions } from "./cookies.js";
+import { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, SESSION_REF_COOKIE_NAME, assertCookieWithinLimit, cookieByteSize, defaultOAuthCookieOptions, defaultSessionCookieOptions } from "./cookies.js";
 import { configureLogger, createLogger } from "./logger.js";
 import { classifyRefreshFailure, getOAuthConfigLogContext, getOAuthErrorLogContext } from "./oauth-logging.js";
 import { SESSION_EVENT, SESSION_REJECTED_REASONS, isSessionRejectedReason, logSessionEvent, newSessionId, sessionEventLevel } from "./session-events.js";
 import { refreshSession } from "./session-refresh.js";
-import { accessTokenExpires, createEncryptedJWT, decrypt, decryptJWT, encrypt, generateToken, getSessionSecret, getSessionSecretUint8Array, hasScope, hexToUint8Array, sha256, sha512, toHex } from "./utils.js";
+import { accessTokenExpires, createEncryptedJWT, decrypt, decryptJWT, encrypt, generateToken, hasScope, hexToUint8Array, sha256, sha512, toHex } from "./utils.js";
 import { isSession, validateSessionJwt } from "./session-validation.js";
 import "./types.js";
-export { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, DEFAULT_ACTIVITY_EVENTS, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, SESSION_EVENT, SESSION_REJECTED_REASONS, accessTokenExpires, assertCookieWithinLimit, classifyRefreshFailure, configureLogger, cookieByteSize, createActivityTracker, createEncryptedJWT, createLogger, decrypt, decryptJWT, defaultOAuthCookieOptions, defaultSessionCookieOptions, encrypt, generateToken, getOAuthConfigLogContext, getOAuthErrorLogContext, getSessionSecret, getSessionSecretUint8Array, hasScope, hexToUint8Array, isSession, isSessionRejectedReason, logSessionEvent, newSessionId, refreshSession, sessionEventLevel, sha256, sha512, toHex, validateSessionJwt };
+export { ACCESS_TOKEN_COOKIE_NAME, COOKIE_INFO_BYTES, COOKIE_MAX_BYTES, CookieTooLargeError, DEFAULT_ACTIVITY_EVENTS, ID_TOKEN_COOKIE_NAME, SESSION_COOKIE_NAME, SESSION_EVENT, SESSION_REF_COOKIE_NAME, SESSION_REJECTED_REASONS, accessTokenExpires, assertCookieWithinLimit, classifyRefreshFailure, configureLogger, cookieByteSize, createActivityTracker, createEncryptedJWT, createLogger, decrypt, decryptJWT, defaultOAuthCookieOptions, defaultSessionCookieOptions, encrypt, generateToken, getOAuthConfigLogContext, getOAuthErrorLogContext, hasScope, hexToUint8Array, isSession, isSessionRejectedReason, logSessionEvent, newSessionId, refreshSession, sessionEventLevel, sha256, sha512, toHex, validateSessionJwt };

package/dist/logger.js

@@ -1,4 +1,4 @@
-//#region src/logger.ts
+// src/logger.ts
 function serializeError(value) {
 	if (value instanceof Error) return {
 		name: value.name,
@@ -129,7 +129,6 @@ function createLogger(options) {
 		}
 	};
 }
-//#endregion
 export { configureLogger, createLogger };
 
 //# sourceMappingURL=logger.js.map

package/dist/oauth-browser.d.ts

@@ -1,14 +1,8 @@
 /**
  * Browser-compatible OAuth 2.0 + PKCE helpers
  *
- * This module provides OAuth 2.0 helpers that work in browser environments.
- * Unlike `oauth.ts` which uses openid-client (Node.js only), this uses
- * browser-native Web Crypto API for PKCE generation.
- *
- * **Use this in:**
- * - Vite/React SPAs
- * - Browser-only applications
- * - Any frontend that can't use Node.js APIs
+ * Deprecated and will be removed in a later minor. Use the server flow instead:
+ * `handleOidcLogin` / `handleOidcCallback` from `@eventuras/fides-auth/server`.
  *
  * **Usage:**
  * ```typescript
@@ -29,14 +23,20 @@
  * const tokens = await exchangeCodeForTokens(config, code, verifier);
  * ```
  */
-/** Configuration for browser-side OAuth / OIDC flows (no client secret). */
+/**
+ * Configuration for browser-side OAuth / OIDC flows (no client secret).
+ * @deprecated Only used by the deprecated `oauth-browser` helpers. Use `handleOidcLogin` / `handleOidcCallback`.
+ */
 export interface OAuthConfig {
     issuer: string;
     clientId: string;
     redirect_uri: string;
     scope: string;
 }
-/** PKCE parameters for a browser-initiated authorization request. */
+/**
+ * PKCE parameters for a browser-initiated authorization request.
+ * @deprecated Only used by the deprecated `oauth-browser` helpers. Use `handleOidcLogin`.
+ */
 export interface PKCEParams {
     code_verifier: string;
     code_challenge: string;
@@ -44,14 +44,17 @@ export interface PKCEParams {
 }
 /**
  * Generate PKCE parameters for OAuth flow
+ * @deprecated The random strings have modulo bias. Use `handleOidcLogin`, which builds PKCE server-side.
  */
 export declare function generatePKCE(): Promise<PKCEParams>;
 /**
  * Build authorization URL for OAuth flow
+ * @deprecated Hardcodes `${issuer}/auth` instead of using discovery. Use `handleOidcLogin`.
  */
 export declare function buildAuthorizationUrl(config: OAuthConfig, pkce: PKCEParams): string;
 /**
  * Exchange authorization code for tokens
+ * @deprecated Hardcodes `${issuer}/token` and doesn't validate the response. Use `handleOidcCallback`.
  */
 export declare function exchangeCodeForTokens(config: OAuthConfig, code: string, codeVerifier: string): Promise<{
     access_token: string;

package/dist/oauth-browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-browser.d.ts","sourceRoot":"","sources":["../src/oauth-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,4EAA4E;AAC5E,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,qEAAqE;AACrE,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AA+BD;;GAEG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC,CAUxD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,UAAU,GACf,MAAM,CAYR;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAqBD"}
+{"version":3,"file":"oauth-browser.d.ts","sourceRoot":"","sources":["../src/oauth-browser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;CACf;AA+BD;;;GAGG;AACH,wBAAsB,YAAY,IAAI,OAAO,CAAC,UAAU,CAAC,CAUxD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,UAAU,GACf,MAAM,CAYR;AAED;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IACT,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAqBD"}