@eventuras/fides-auth 0.14.1 → 0.15.0

package/dist/oauth-browser.js

@@ -1,4 +1,4 @@
-//#region src/oauth-browser.ts
+// src/oauth-browser.ts
 /**
 * Generate random string for code verifier (PKCE)
 * Uses Web Crypto API (browser-compatible)
@@ -20,6 +20,7 @@ async function generateCodeChallenge(verifier) {
 }
 /**
 * Generate PKCE parameters for OAuth flow
+* @deprecated The random strings have modulo bias. Use `handleOidcLogin`, which builds PKCE server-side.
 */
 async function generatePKCE() {
 	const code_verifier = generateRandomString(128);
@@ -31,6 +32,7 @@ async function generatePKCE() {
 }
 /**
 * Build authorization URL for OAuth flow
+* @deprecated Hardcodes `${issuer}/auth` instead of using discovery. Use `handleOidcLogin`.
 */
 function buildAuthorizationUrl(config, pkce) {
 	const params = new URLSearchParams({
@@ -46,6 +48,7 @@ function buildAuthorizationUrl(config, pkce) {
 }
 /**
 * Exchange authorization code for tokens
+* @deprecated Hardcodes `${issuer}/token` and doesn't validate the response. Use `handleOidcCallback`.
 */
 async function exchangeCodeForTokens(config, code, codeVerifier) {
 	const response = await fetch(`${config.issuer}/token`, {
@@ -65,7 +68,6 @@ async function exchangeCodeForTokens(config, code, codeVerifier) {
 	}
 	return response.json();
 }
-//#endregion
 export { buildAuthorizationUrl, exchangeCodeForTokens, generatePKCE };
 
 //# sourceMappingURL=oauth-browser.js.map

package/dist/oauth-browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-browser.js","names":[],"sources":["../src/oauth-browser.ts"],"sourcesContent":["/**\n * Browser-compatible OAuth 2.0 + PKCE helpers\n *\n * This module provides OAuth 2.0 helpers that work in browser environments.\n * Unlike `oauth.ts` which uses openid-client (Node.js only), this uses\n * browser-native Web Crypto API for PKCE generation.\n *\n * **Use this in:**\n * - Vite/React SPAs\n * - Browser-only applications\n * - Any frontend that can't use Node.js APIs\n *\n * **Usage:**\n * ```typescript\n * import { generatePKCE, buildAuthorizationUrl, exchangeCodeForTokens }\n *   from '@eventuras/fides-auth/oauth-browser';\n *\n * // 1. Start OAuth flow\n * const pkce = await generatePKCE();\n * sessionStorage.setItem('code_verifier', pkce.code_verifier);\n * sessionStorage.setItem('state', pkce.state);\n *\n * const authUrl = buildAuthorizationUrl(config, pkce);\n * window.location.href = authUrl;\n *\n * // 2. Handle callback\n * const code = new URLSearchParams(window.location.search).get('code');\n * const verifier = sessionStorage.getItem('code_verifier');\n * const tokens = await exchangeCodeForTokens(config, code, verifier);\n * ```\n */\n\n/** Configuration for browser-side OAuth / OIDC flows (no client secret). */\nexport interface OAuthConfig {\n  issuer: string;\n  clientId: string;\n  redirect_uri: string;\n  scope: string;\n}\n\n/** PKCE parameters for a browser-initiated authorization request. */\nexport interface PKCEParams {\n  code_verifier: string;\n  code_challenge: string;\n  state: string;\n}\n\n/**\n * Generate random string for code verifier (PKCE)\n * Uses Web Crypto API (browser-compatible)\n */\nfunction generateRandomString(length: number): string {\n  const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';\n  const randomValues = new Uint8Array(length);\n  crypto.getRandomValues(randomValues);\n  return Array.from(randomValues)\n    .map((x) => charset[x % charset.length])\n    .join('');\n}\n\n/**\n * Generate PKCE code challenge from verifier\n * Uses Web Crypto API SHA-256\n */\nasync function generateCodeChallenge(verifier: string): Promise<string> {\n  const encoder = new TextEncoder();\n  const data = encoder.encode(verifier);\n  const hash = await crypto.subtle.digest('SHA-256', data);\n\n  // Base64URL encode\n  return btoa(String.fromCharCode(...new Uint8Array(hash)))\n    .replaceAll('+', '-')\n    .replaceAll('/', '_')\n    .replace(/=+$/, '');\n}\n\n/**\n * Generate PKCE parameters for OAuth flow\n */\nexport async function generatePKCE(): Promise<PKCEParams> {\n  const code_verifier = generateRandomString(128);\n  const code_challenge = await generateCodeChallenge(code_verifier);\n  const state = generateRandomString(32);\n\n  return {\n    code_verifier,\n    code_challenge,\n    state,\n  };\n}\n\n/**\n * Build authorization URL for OAuth flow\n */\nexport function buildAuthorizationUrl(\n  config: OAuthConfig,\n  pkce: PKCEParams\n): string {\n  const params = new URLSearchParams({\n    client_id: config.clientId,\n    redirect_uri: config.redirect_uri,\n    response_type: 'code',\n    scope: config.scope,\n    state: pkce.state,\n    code_challenge: pkce.code_challenge,\n    code_challenge_method: 'S256',\n  });\n\n  return `${config.issuer}/auth?${params.toString()}`;\n}\n\n/**\n * Exchange authorization code for tokens\n */\nexport async function exchangeCodeForTokens(\n  config: OAuthConfig,\n  code: string,\n  codeVerifier: string\n): Promise<{\n  access_token: string;\n  id_token: string;\n  refresh_token?: string;\n  expires_in: number;\n}> {\n  const response = await fetch(`${config.issuer}/token`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/x-www-form-urlencoded',\n    },\n    body: new URLSearchParams({\n      grant_type: 'authorization_code',\n      code,\n      redirect_uri: config.redirect_uri,\n      client_id: config.clientId,\n      code_verifier: codeVerifier,\n    }),\n  });\n\n  if (!response.ok) {\n    const error = await response.text();\n    throw new Error(`Token exchange failed: ${response.status} - ${error}`);\n  }\n\n  return response.json();\n}\n"],"mappings":";;;;;AAmDA,SAAS,qBAAqB,QAAwB;CACpD,MAAM,UAAU;CAChB,MAAM,eAAe,IAAI,WAAW,MAAM;CAC1C,OAAO,gBAAgB,YAAY;CACnC,OAAO,MAAM,KAAK,YAAY,CAAC,CAC5B,KAAK,MAAM,QAAQ,IAAI,GAAe,CAAC,CACvC,KAAK,EAAE;AACZ;;;;;AAMA,eAAe,sBAAsB,UAAmC;CAEtE,MAAM,OAAO,IADO,YACP,CAAA,CAAQ,OAAO,QAAQ;CACpC,MAAM,OAAO,MAAM,OAAO,OAAO,OAAO,WAAW,IAAI;CAGvD,OAAO,KAAK,OAAO,aAAa,GAAG,IAAI,WAAW,IAAI,CAAC,CAAC,CAAC,CACtD,WAAW,KAAK,GAAG,CAAC,CACpB,WAAW,KAAK,GAAG,CAAC,CACpB,QAAQ,OAAO,EAAE;AACtB;;;;AAKA,eAAsB,eAAoC;CACxD,MAAM,gBAAgB,qBAAqB,GAAG;CAI9C,OAAO;EACL;EACA,gBAAA,MAL2B,sBAAsB,aAAa;EAM9D,OALY,qBAAqB,EAKjC;CACF;AACF;;;;AAKA,SAAgB,sBACd,QACA,MACQ;CACR,MAAM,SAAS,IAAI,gBAAgB;EACjC,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,eAAe;EACf,OAAO,OAAO;EACd,OAAO,KAAK;EACZ,gBAAgB,KAAK;EACrB,uBAAuB;CACzB,CAAC;CAED,OAAO,GAAG,OAAO,OAAO,QAAQ,OAAO,SAAS;AAClD;;;;AAKA,eAAsB,sBACpB,QACA,MACA,cAMC;CACD,MAAM,WAAW,MAAM,MAAM,GAAG,OAAO,OAAO,SAAS;EACrD,QAAQ;EACR,SAAS,EACP,gBAAgB,oCAClB;EACA,MAAM,IAAI,gBAAgB;GACxB,YAAY;GACZ;GACA,cAAc,OAAO;GACrB,WAAW,OAAO;GAClB,eAAe;EACjB,CAAC;CACH,CAAC;CAED,IAAI,CAAC,SAAS,IAAI;EAChB,MAAM,QAAQ,MAAM,SAAS,KAAK;EAClC,MAAM,IAAI,MAAM,0BAA0B,SAAS,OAAO,KAAK,OAAO;CACxE;CAEA,OAAO,SAAS,KAAK;AACvB"}
+{"version":3,"file":"oauth-browser.js","names":[],"sources":["../src/oauth-browser.ts"],"sourcesContent":["/**\n * Browser-compatible OAuth 2.0 + PKCE helpers\n *\n * Deprecated and will be removed in a later minor. Use the server flow instead:\n * `handleOidcLogin` / `handleOidcCallback` from `@eventuras/fides-auth/server`.\n *\n * **Usage:**\n * ```typescript\n * import { generatePKCE, buildAuthorizationUrl, exchangeCodeForTokens }\n *   from '@eventuras/fides-auth/oauth-browser';\n *\n * // 1. Start OAuth flow\n * const pkce = await generatePKCE();\n * sessionStorage.setItem('code_verifier', pkce.code_verifier);\n * sessionStorage.setItem('state', pkce.state);\n *\n * const authUrl = buildAuthorizationUrl(config, pkce);\n * window.location.href = authUrl;\n *\n * // 2. Handle callback\n * const code = new URLSearchParams(window.location.search).get('code');\n * const verifier = sessionStorage.getItem('code_verifier');\n * const tokens = await exchangeCodeForTokens(config, code, verifier);\n * ```\n */\n\n/**\n * Configuration for browser-side OAuth / OIDC flows (no client secret).\n * @deprecated Only used by the deprecated `oauth-browser` helpers. Use `handleOidcLogin` / `handleOidcCallback`.\n */\nexport interface OAuthConfig {\n  issuer: string;\n  clientId: string;\n  redirect_uri: string;\n  scope: string;\n}\n\n/**\n * PKCE parameters for a browser-initiated authorization request.\n * @deprecated Only used by the deprecated `oauth-browser` helpers. Use `handleOidcLogin`.\n */\nexport interface PKCEParams {\n  code_verifier: string;\n  code_challenge: string;\n  state: string;\n}\n\n/**\n * Generate random string for code verifier (PKCE)\n * Uses Web Crypto API (browser-compatible)\n */\nfunction generateRandomString(length: number): string {\n  const charset = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';\n  const randomValues = new Uint8Array(length);\n  crypto.getRandomValues(randomValues);\n  return Array.from(randomValues)\n    .map((x) => charset[x % charset.length])\n    .join('');\n}\n\n/**\n * Generate PKCE code challenge from verifier\n * Uses Web Crypto API SHA-256\n */\nasync function generateCodeChallenge(verifier: string): Promise<string> {\n  const encoder = new TextEncoder();\n  const data = encoder.encode(verifier);\n  const hash = await crypto.subtle.digest('SHA-256', data);\n\n  // Base64URL encode\n  return btoa(String.fromCharCode(...new Uint8Array(hash)))\n    .replaceAll('+', '-')\n    .replaceAll('/', '_')\n    .replace(/=+$/, '');\n}\n\n/**\n * Generate PKCE parameters for OAuth flow\n * @deprecated The random strings have modulo bias. Use `handleOidcLogin`, which builds PKCE server-side.\n */\nexport async function generatePKCE(): Promise<PKCEParams> {\n  const code_verifier = generateRandomString(128);\n  const code_challenge = await generateCodeChallenge(code_verifier);\n  const state = generateRandomString(32);\n\n  return {\n    code_verifier,\n    code_challenge,\n    state,\n  };\n}\n\n/**\n * Build authorization URL for OAuth flow\n * @deprecated Hardcodes `${issuer}/auth` instead of using discovery. Use `handleOidcLogin`.\n */\nexport function buildAuthorizationUrl(\n  config: OAuthConfig,\n  pkce: PKCEParams\n): string {\n  const params = new URLSearchParams({\n    client_id: config.clientId,\n    redirect_uri: config.redirect_uri,\n    response_type: 'code',\n    scope: config.scope,\n    state: pkce.state,\n    code_challenge: pkce.code_challenge,\n    code_challenge_method: 'S256',\n  });\n\n  return `${config.issuer}/auth?${params.toString()}`;\n}\n\n/**\n * Exchange authorization code for tokens\n * @deprecated Hardcodes `${issuer}/token` and doesn't validate the response. Use `handleOidcCallback`.\n */\nexport async function exchangeCodeForTokens(\n  config: OAuthConfig,\n  code: string,\n  codeVerifier: string\n): Promise<{\n  access_token: string;\n  id_token: string;\n  refresh_token?: string;\n  expires_in: number;\n}> {\n  const response = await fetch(`${config.issuer}/token`, {\n    method: 'POST',\n    headers: {\n      'Content-Type': 'application/x-www-form-urlencoded',\n    },\n    body: new URLSearchParams({\n      grant_type: 'authorization_code',\n      code,\n      redirect_uri: config.redirect_uri,\n      client_id: config.clientId,\n      code_verifier: codeVerifier,\n    }),\n  });\n\n  if (!response.ok) {\n    const error = await response.text();\n    throw new Error(`Token exchange failed: ${response.status} - ${error}`);\n  }\n\n  return response.json();\n}\n"],"mappings":";;;;;AAmDA,SAAS,qBAAqB,QAAwB;CACpD,MAAM,UAAU;CAChB,MAAM,eAAe,IAAI,WAAW,MAAM;CAC1C,OAAO,gBAAgB,YAAY;CACnC,OAAO,MAAM,KAAK,YAAY,CAAC,CAC5B,KAAK,MAAM,QAAQ,IAAI,GAAe,CAAC,CACvC,KAAK,EAAE;AACZ;;;;;AAMA,eAAe,sBAAsB,UAAmC;CAEtE,MAAM,OAAO,IADO,YACP,CAAA,CAAQ,OAAO,QAAQ;CACpC,MAAM,OAAO,MAAM,OAAO,OAAO,OAAO,WAAW,IAAI;CAGvD,OAAO,KAAK,OAAO,aAAa,GAAG,IAAI,WAAW,IAAI,CAAC,CAAC,CAAC,CACtD,WAAW,KAAK,GAAG,CAAC,CACpB,WAAW,KAAK,GAAG,CAAC,CACpB,QAAQ,OAAO,EAAE;AACtB;;;;;AAMA,eAAsB,eAAoC;CACxD,MAAM,gBAAgB,qBAAqB,GAAG;CAI9C,OAAO;EACL;EACA,gBAAA,MAL2B,sBAAsB,aAAa;EAM9D,OALY,qBAAqB,EAKjC;CACF;AACF;;;;;AAMA,SAAgB,sBACd,QACA,MACQ;CACR,MAAM,SAAS,IAAI,gBAAgB;EACjC,WAAW,OAAO;EAClB,cAAc,OAAO;EACrB,eAAe;EACf,OAAO,OAAO;EACd,OAAO,KAAK;EACZ,gBAAgB,KAAK;EACrB,uBAAuB;CACzB,CAAC;CAED,OAAO,GAAG,OAAO,OAAO,QAAQ,OAAO,SAAS;AAClD;;;;;AAMA,eAAsB,sBACpB,QACA,MACA,cAMC;CACD,MAAM,WAAW,MAAM,MAAM,GAAG,OAAO,OAAO,SAAS;EACrD,QAAQ;EACR,SAAS,EACP,gBAAgB,oCAClB;EACA,MAAM,IAAI,gBAAgB;GACxB,YAAY;GACZ;GACA,cAAc,OAAO;GACrB,WAAW,OAAO;GAClB,eAAe;EACjB,CAAC;CACH,CAAC;CAED,IAAI,CAAC,SAAS,IAAI;EAChB,MAAM,QAAQ,MAAM,SAAS,KAAK;EAClC,MAAM,IAAI,MAAM,0BAA0B,SAAS,OAAO,KAAK,OAAO;CACxE;CAEA,OAAO,SAAS,KAAK;AACvB"}

package/dist/oauth-config.d.ts

@@ -0,0 +1,70 @@
+import type * as openid from 'openid-client';
+/**
+ * How the client authenticates at the token endpoint. Omit `clientAuth` to use
+ * `client_secret_post`.
+ */
+export type ClientAuthConfig = {
+    /** @default 'client_secret_post' */
+    clientAuth?: 'client_secret_post' | 'client_secret_basic';
+    clientSecret: string;
+} | {
+    /** Public client: sends only `client_id`. Pair it with PKCE. */
+    clientAuth: 'none';
+} | {
+    clientAuth: 'private_key_jwt';
+    /** Signs the client assertion. Reuse one key object: a new one means a new cache entry. */
+    privateKey: openid.CryptoKey | openid.PrivateKey;
+};
+/** Configuration for server-side OAuth / OIDC flows. */
+export type OAuthConfig = ClientAuthConfig & {
+    issuer: string;
+    clientId: string;
+    redirect_uri: string;
+    /** Space-separated string or an array of scopes. */
+    scope: string | string[];
+    /**
+     * Extra authorization request parameters (e.g. `prompt`, `resource`), added by `buildPKCEOptions`.
+     * Reserved keys throw: `state`, `code_challenge`, `code_challenge_method`, `redirect_uri`,
+     * `client_id`, `response_type`, `request`, `request_uri` and `nonce`.
+     */
+    authorizationParameters?: Record<string, string>;
+    /**
+     * Opt in to Pushed Authorization Requests (RFC 9126) when the provider
+     * supports it. When true, authorization parameters are posted to the
+     * provider's PAR endpoint ahead of the redirect, and only `client_id` +
+     * `request_uri` travel through the user-agent. The provider must advertise
+     * `pushed_authorization_request_endpoint` in its discovery metadata.
+     */
+    usePar?: boolean;
+    /**
+     * Server metadata to use instead of OIDC discovery, e.g. an RFC 8414 document.
+     * Must include `issuer` when `scope` has `openid`. `issuer` above is then used
+     * only for logs and caching.
+     */
+    serverMetadata?: openid.ServerMetadata;
+};
+/**
+ * Configuration for OAuth client credentials flow (machine-to-machine authentication).
+ * Takes any {@link ClientAuthConfig} except `none`: the grant needs client authentication.
+ */
+export type ClientCredentialsConfig = Exclude<ClientAuthConfig, {
+    clientAuth: 'none';
+}> & {
+    /** OAuth token endpoint URL. Must be https. */
+    tokenEndpoint: string;
+    /** OAuth client ID */
+    clientId: string;
+    /** Optional scope for the access token */
+    scope?: string;
+    /**
+     * Issuer identifier; defaults to the token endpoint's origin. With
+     * `private_key_jwt` it is the client assertion's `aud`, so set it to what the server expects.
+     */
+    issuer?: string;
+    /**
+     * Request timeout in seconds.
+     * @default 30
+     */
+    timeout?: number;
+};
+//# sourceMappingURL=oauth-config.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-config.d.ts","sourceRoot":"","sources":["../src/oauth-config.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,MAAM,eAAe,CAAC;AAE7C;;;GAGG;AACH,MAAM,MAAM,gBAAgB,GACxB;IACE,oCAAoC;IACpC,UAAU,CAAC,EAAE,oBAAoB,GAAG,qBAAqB,CAAC;IAC1D,YAAY,EAAE,MAAM,CAAC;CACtB,GACD;IACE,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACpB,GACD;IACE,UAAU,EAAE,iBAAiB,CAAC;IAC9B,2FAA2F;IAC3F,UAAU,EAAE,MAAM,CAAC,SAAS,GAAG,MAAM,CAAC,UAAU,CAAC;CAClD,CAAC;AAEN,wDAAwD;AACxD,MAAM,MAAM,WAAW,GAAG,gBAAgB,GAAG;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;CACxC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,OAAO,CAAC,gBAAgB,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG;IACxF,+CAA+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,0CAA0C;IAC1C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC"}

package/dist/oauth-logging.d.ts

@@ -1,10 +1,11 @@
-import type { OAuthConfig } from './oauth';
+import type { OAuthConfig } from './oauth-config';
 import type { RefreshFailureCause } from './session-events';
 /**
  * Returns a structured, log-safe context describing an `OAuthConfig`.
  *
- * Excludes `clientSecret`. Use this to attach provider configuration to log
- * lines for debugging OAuth/OIDC flows without leaking credentials.
+ * Excludes credentials (`clientSecret`, `privateKey`). Use this to attach
+ * provider configuration to log lines for debugging OAuth/OIDC flows without
+ * leaking credentials.
  */
 export declare function getOAuthConfigLogContext(config: OAuthConfig): {
     clientId: string;

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

@@ -1 +1 @@
-{"version":3,"file":"oauth-logging.d.ts","sourceRoot":"","sources":["../src/oauth-logging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW;IAExD,QAAQ;IACR,MAAM;IACN,WAAW;IACX,KAAK;IACL,MAAM;EAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;EA0BrD;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAY1E"}
+{"version":3,"file":"oauth-logging.d.ts","sourceRoot":"","sources":["../src/oauth-logging.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,WAAW;IAExD,QAAQ;IACR,MAAM;IACN,WAAW;IACX,KAAK;IACL,MAAM;EAET;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO;;;;;;;;;;;;;;;;;;;;EA0BrD;AAmCD;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,mBAAmB,CAY1E"}

package/dist/oauth-logging.js

@@ -1,16 +1,17 @@
-//#region src/oauth-logging.ts
+// src/oauth-logging.ts
 /**
 * Returns a structured, log-safe context describing an `OAuthConfig`.
 *
-* Excludes `clientSecret`. Use this to attach provider configuration to log
-* lines for debugging OAuth/OIDC flows without leaking credentials.
+* Excludes credentials (`clientSecret`, `privateKey`). Use this to attach
+* provider configuration to log lines for debugging OAuth/OIDC flows without
+* leaking credentials.
 */
 function getOAuthConfigLogContext(config) {
 	return {
 		clientId: config.clientId,
 		issuer: config.issuer,
 		redirectUri: config.redirect_uri,
-		scope: config.scope,
+		scope: Array.isArray(config.scope) ? config.scope.join(" ") : config.scope,
 		usePar: config.usePar ?? false
 	};
 }
@@ -106,7 +107,6 @@ function syscallCode(error) {
 	const cause = typeof candidate.cause === "object" && candidate.cause !== null ? candidate.cause : null;
 	return cause ? stringProp(cause, "code") : void 0;
 }
-//#endregion
 export { classifyRefreshFailure, getOAuthConfigLogContext, getOAuthErrorLogContext };
 
 //# sourceMappingURL=oauth-logging.js.map

package/dist/oauth-logging.js.map

@@ -1 +1 @@
-{"version":3,"file":"oauth-logging.js","names":[],"sources":["../src/oauth-logging.ts"],"sourcesContent":["import type { OAuthConfig } from './oauth';\nimport type { RefreshFailureCause } from './session-events';\n\n/**\n * Returns a structured, log-safe context describing an `OAuthConfig`.\n *\n * Excludes `clientSecret`. Use this to attach provider configuration to log\n * lines for debugging OAuth/OIDC flows without leaking credentials.\n */\nexport function getOAuthConfigLogContext(config: OAuthConfig) {\n  return {\n    clientId: config.clientId,\n    issuer: config.issuer,\n    redirectUri: config.redirect_uri,\n    scope: config.scope,\n    usePar: config.usePar ?? false,\n  };\n}\n\n/**\n * Returns a structured log context for an unknown OAuth-related error.\n *\n * `oauth4webapi` (used via `openid-client`) wraps OAuth response errors. The\n * original OAuth response (`{error, error_description, ...}`) usually lives\n * either on the error itself or on `cause`.\n *\n * @see https://github.com/panva/oauth4webapi/blob/main/docs/classes/ResponseBodyError.md\n */\nexport function getOAuthErrorLogContext(error: unknown) {\n  if (typeof error !== 'object' || error === null) {\n    return { value: error };\n  }\n\n  const candidate = error as Record<string, unknown>;\n  const cause =\n    typeof candidate.cause === 'object' && candidate.cause !== null\n      ? (candidate.cause as Record<string, unknown>)\n      : null;\n\n  // OAuth-specific fields (code/error/error_description) may live either on\n  // the error itself or on `cause` depending on how oauth4webapi wraps the\n  // response. Prefer the top-level value but fall back to `cause`.\n  return {\n    code: stringProp(candidate, 'code') ?? (cause ? stringProp(cause, 'code') : undefined),\n    error: stringProp(candidate, 'error') ?? (cause ? stringProp(cause, 'error') : undefined),\n    errorDescription:\n      stringProp(candidate, 'error_description') ??\n      (cause ? stringProp(cause, 'error_description') : undefined),\n    message: stringProp(candidate, 'message'),\n    name: stringProp(candidate, 'name'),\n    status: numberProp(candidate, 'status'),\n    causeMessage: cause ? stringProp(cause, 'message') : undefined,\n    causeName: cause ? stringProp(cause, 'name') : undefined,\n  };\n}\n\nfunction stringProp(value: Record<string, unknown>, key: string): string | undefined {\n  return typeof value[key] === 'string' ? (value[key] as string) : undefined;\n}\n\nfunction numberProp(value: Record<string, unknown>, key: string): number | undefined {\n  return typeof value[key] === 'number' ? (value[key] as number) : undefined;\n}\n\n/**\n * Node/undici and browser fetch surface connectivity failures as syscall codes on\n * `cause`. Any of these means the request never reached the provider.\n */\nconst TRANSPORT_CODES = new Set([\n  'ECONNREFUSED',\n  'ECONNRESET',\n  'ENOTFOUND',\n  'EAI_AGAIN',\n  'ETIMEDOUT',\n  'EHOSTUNREACH',\n  'ENETUNREACH',\n  'EPIPE',\n  'EPROTO',\n  'CERT_HAS_EXPIRED',\n  'DEPTH_ZERO_SELF_SIGNED_CERT',\n  'UND_ERR_CONNECT_TIMEOUT',\n  'UND_ERR_HEADERS_TIMEOUT',\n  'UND_ERR_BODY_TIMEOUT',\n  'UND_ERR_SOCKET',\n]);\n\n/** `fetch` rejects with a bare TypeError on network failure; the wording is runtime-specific. */\nconst TRANSPORT_MESSAGE = /fetch failed|failed to fetch|network(?:\\s|error)|load failed|socket hang up/i;\n\n/**\n * Classifies a refresh failure into the three causes that call for different\n * responses.\n *\n * The distinction is not cosmetic: `invalid_grant` is the provider stating the\n * refresh token is dead, and the user genuinely has to log in again. A transport\n * fault or a provider 5xx says nothing about the session — treating those the\n * same way logs out a user whose session was perfectly valid, which is exactly\n * the bug that makes \"logged out every few minutes\" so hard to diagnose.\n *\n * Unknown errors fall back to `idp_error` rather than `invalid_grant`, so an\n * unrecognised failure never silently ends a session.\n */\nexport function classifyRefreshFailure(error: unknown): RefreshFailureCause {\n  const context = getOAuthErrorLogContext(error);\n\n  if (context.code === 'OAUTH_RESPONSE_BODY_ERROR' && context.error === 'invalid_grant') {\n    return 'invalid_grant';\n  }\n\n  if (isTransportFailure(error, context)) {\n    return 'transport';\n  }\n\n  return 'idp_error';\n}\n\nfunction isTransportFailure(\n  error: unknown,\n  context: ReturnType<typeof getOAuthErrorLogContext>,\n): boolean {\n  // An aborted or timed-out request never got an answer.\n  if (context.name === 'AbortError' || context.name === 'TimeoutError') return true;\n  if (context.causeName === 'AbortError' || context.causeName === 'TimeoutError') return true;\n\n  const code = syscallCode(error);\n  if (code !== undefined && TRANSPORT_CODES.has(code)) return true;\n\n  // Only trust the message when the error is a bare TypeError — the shape fetch\n  // uses for connectivity failures. A provider error that happens to mention a\n  // network is still a provider error.\n  if (context.name === 'TypeError') {\n    if (context.message && TRANSPORT_MESSAGE.test(context.message)) return true;\n    if (context.causeMessage && TRANSPORT_MESSAGE.test(context.causeMessage)) return true;\n  }\n\n  return false;\n}\n\n/** Reads a syscall code off the error or its `cause`, where fetch buries connectivity failures. */\nfunction syscallCode(error: unknown): string | undefined {\n  if (typeof error !== 'object' || error === null) return undefined;\n  const candidate = error as Record<string, unknown>;\n\n  const own = stringProp(candidate, 'code');\n  if (own !== undefined && own !== 'OAUTH_RESPONSE_BODY_ERROR') return own;\n\n  const cause =\n    typeof candidate.cause === 'object' && candidate.cause !== null\n      ? (candidate.cause as Record<string, unknown>)\n      : null;\n  return cause ? stringProp(cause, 'code') : undefined;\n}\n"],"mappings":";;;;;;;AASA,SAAgB,yBAAyB,QAAqB;CAC5D,OAAO;EACL,UAAU,OAAO;EACjB,QAAQ,OAAO;EACf,aAAa,OAAO;EACpB,OAAO,OAAO;EACd,QAAQ,OAAO,UAAU;CAC3B;AACF;;;;;;;;;;AAWA,SAAgB,wBAAwB,OAAgB;CACtD,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,EAAE,OAAO,MAAM;CAGxB,MAAM,YAAY;CAClB,MAAM,QACJ,OAAO,UAAU,UAAU,YAAY,UAAU,UAAU,OACtD,UAAU,QACX;CAKN,OAAO;EACL,MAAM,WAAW,WAAW,MAAM,MAAM,QAAQ,WAAW,OAAO,MAAM,IAAI,KAAA;EAC5E,OAAO,WAAW,WAAW,OAAO,MAAM,QAAQ,WAAW,OAAO,OAAO,IAAI,KAAA;EAC/E,kBACE,WAAW,WAAW,mBAAmB,MACxC,QAAQ,WAAW,OAAO,mBAAmB,IAAI,KAAA;EACpD,SAAS,WAAW,WAAW,SAAS;EACxC,MAAM,WAAW,WAAW,MAAM;EAClC,QAAQ,WAAW,WAAW,QAAQ;EACtC,cAAc,QAAQ,WAAW,OAAO,SAAS,IAAI,KAAA;EACrD,WAAW,QAAQ,WAAW,OAAO,MAAM,IAAI,KAAA;CACjD;AACF;AAEA,SAAS,WAAW,OAAgC,KAAiC;CACnF,OAAO,OAAO,MAAM,SAAS,WAAY,MAAM,OAAkB,KAAA;AACnE;AAEA,SAAS,WAAW,OAAgC,KAAiC;CACnF,OAAO,OAAO,MAAM,SAAS,WAAY,MAAM,OAAkB,KAAA;AACnE;;;;;AAMA,IAAM,kCAAkB,IAAI,IAAI;CAC9B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAGD,IAAM,oBAAoB;;;;;;;;;;;;;;AAe1B,SAAgB,uBAAuB,OAAqC;CAC1E,MAAM,UAAU,wBAAwB,KAAK;CAE7C,IAAI,QAAQ,SAAS,+BAA+B,QAAQ,UAAU,iBACpE,OAAO;CAGT,IAAI,mBAAmB,OAAO,OAAO,GACnC,OAAO;CAGT,OAAO;AACT;AAEA,SAAS,mBACP,OACA,SACS;CAET,IAAI,QAAQ,SAAS,gBAAgB,QAAQ,SAAS,gBAAgB,OAAO;CAC7E,IAAI,QAAQ,cAAc,gBAAgB,QAAQ,cAAc,gBAAgB,OAAO;CAEvF,MAAM,OAAO,YAAY,KAAK;CAC9B,IAAI,SAAS,KAAA,KAAa,gBAAgB,IAAI,IAAI,GAAG,OAAO;CAK5D,IAAI,QAAQ,SAAS,aAAa;EAChC,IAAI,QAAQ,WAAW,kBAAkB,KAAK,QAAQ,OAAO,GAAG,OAAO;EACvE,IAAI,QAAQ,gBAAgB,kBAAkB,KAAK,QAAQ,YAAY,GAAG,OAAO;CACnF;CAEA,OAAO;AACT;;AAGA,SAAS,YAAY,OAAoC;CACvD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO,KAAA;CACxD,MAAM,YAAY;CAElB,MAAM,MAAM,WAAW,WAAW,MAAM;CACxC,IAAI,QAAQ,KAAA,KAAa,QAAQ,6BAA6B,OAAO;CAErE,MAAM,QACJ,OAAO,UAAU,UAAU,YAAY,UAAU,UAAU,OACtD,UAAU,QACX;CACN,OAAO,QAAQ,WAAW,OAAO,MAAM,IAAI,KAAA;AAC7C"}
+{"version":3,"file":"oauth-logging.js","names":[],"sources":["../src/oauth-logging.ts"],"sourcesContent":["import type { OAuthConfig } from './oauth-config';\nimport type { RefreshFailureCause } from './session-events';\n\n/**\n * Returns a structured, log-safe context describing an `OAuthConfig`.\n *\n * Excludes credentials (`clientSecret`, `privateKey`). Use this to attach\n * provider configuration to log lines for debugging OAuth/OIDC flows without\n * leaking credentials.\n */\nexport function getOAuthConfigLogContext(config: OAuthConfig) {\n  return {\n    clientId: config.clientId,\n    issuer: config.issuer,\n    redirectUri: config.redirect_uri,\n    scope: Array.isArray(config.scope) ? config.scope.join(' ') : config.scope,\n    usePar: config.usePar ?? false,\n  };\n}\n\n/**\n * Returns a structured log context for an unknown OAuth-related error.\n *\n * `oauth4webapi` (used via `openid-client`) wraps OAuth response errors. The\n * original OAuth response (`{error, error_description, ...}`) usually lives\n * either on the error itself or on `cause`.\n *\n * @see https://github.com/panva/oauth4webapi/blob/main/docs/classes/ResponseBodyError.md\n */\nexport function getOAuthErrorLogContext(error: unknown) {\n  if (typeof error !== 'object' || error === null) {\n    return { value: error };\n  }\n\n  const candidate = error as Record<string, unknown>;\n  const cause =\n    typeof candidate.cause === 'object' && candidate.cause !== null\n      ? (candidate.cause as Record<string, unknown>)\n      : null;\n\n  // OAuth-specific fields (code/error/error_description) may live either on\n  // the error itself or on `cause` depending on how oauth4webapi wraps the\n  // response. Prefer the top-level value but fall back to `cause`.\n  return {\n    code: stringProp(candidate, 'code') ?? (cause ? stringProp(cause, 'code') : undefined),\n    error: stringProp(candidate, 'error') ?? (cause ? stringProp(cause, 'error') : undefined),\n    errorDescription:\n      stringProp(candidate, 'error_description') ??\n      (cause ? stringProp(cause, 'error_description') : undefined),\n    message: stringProp(candidate, 'message'),\n    name: stringProp(candidate, 'name'),\n    status: numberProp(candidate, 'status'),\n    causeMessage: cause ? stringProp(cause, 'message') : undefined,\n    causeName: cause ? stringProp(cause, 'name') : undefined,\n  };\n}\n\nfunction stringProp(value: Record<string, unknown>, key: string): string | undefined {\n  return typeof value[key] === 'string' ? (value[key] as string) : undefined;\n}\n\nfunction numberProp(value: Record<string, unknown>, key: string): number | undefined {\n  return typeof value[key] === 'number' ? (value[key] as number) : undefined;\n}\n\n/**\n * Node/undici and browser fetch surface connectivity failures as syscall codes on\n * `cause`. Any of these means the request never reached the provider.\n */\nconst TRANSPORT_CODES = new Set([\n  'ECONNREFUSED',\n  'ECONNRESET',\n  'ENOTFOUND',\n  'EAI_AGAIN',\n  'ETIMEDOUT',\n  'EHOSTUNREACH',\n  'ENETUNREACH',\n  'EPIPE',\n  'EPROTO',\n  'CERT_HAS_EXPIRED',\n  'DEPTH_ZERO_SELF_SIGNED_CERT',\n  'UND_ERR_CONNECT_TIMEOUT',\n  'UND_ERR_HEADERS_TIMEOUT',\n  'UND_ERR_BODY_TIMEOUT',\n  'UND_ERR_SOCKET',\n]);\n\n/** `fetch` rejects with a bare TypeError on network failure; the wording is runtime-specific. */\nconst TRANSPORT_MESSAGE = /fetch failed|failed to fetch|network(?:\\s|error)|load failed|socket hang up/i;\n\n/**\n * Classifies a refresh failure into the three causes that call for different\n * responses.\n *\n * The distinction is not cosmetic: `invalid_grant` is the provider stating the\n * refresh token is dead, and the user genuinely has to log in again. A transport\n * fault or a provider 5xx says nothing about the session — treating those the\n * same way logs out a user whose session was perfectly valid, which is exactly\n * the bug that makes \"logged out every few minutes\" so hard to diagnose.\n *\n * Unknown errors fall back to `idp_error` rather than `invalid_grant`, so an\n * unrecognised failure never silently ends a session.\n */\nexport function classifyRefreshFailure(error: unknown): RefreshFailureCause {\n  const context = getOAuthErrorLogContext(error);\n\n  if (context.code === 'OAUTH_RESPONSE_BODY_ERROR' && context.error === 'invalid_grant') {\n    return 'invalid_grant';\n  }\n\n  if (isTransportFailure(error, context)) {\n    return 'transport';\n  }\n\n  return 'idp_error';\n}\n\nfunction isTransportFailure(\n  error: unknown,\n  context: ReturnType<typeof getOAuthErrorLogContext>,\n): boolean {\n  // An aborted or timed-out request never got an answer.\n  if (context.name === 'AbortError' || context.name === 'TimeoutError') return true;\n  if (context.causeName === 'AbortError' || context.causeName === 'TimeoutError') return true;\n\n  const code = syscallCode(error);\n  if (code !== undefined && TRANSPORT_CODES.has(code)) return true;\n\n  // Only trust the message when the error is a bare TypeError — the shape fetch\n  // uses for connectivity failures. A provider error that happens to mention a\n  // network is still a provider error.\n  if (context.name === 'TypeError') {\n    if (context.message && TRANSPORT_MESSAGE.test(context.message)) return true;\n    if (context.causeMessage && TRANSPORT_MESSAGE.test(context.causeMessage)) return true;\n  }\n\n  return false;\n}\n\n/** Reads a syscall code off the error or its `cause`, where fetch buries connectivity failures. */\nfunction syscallCode(error: unknown): string | undefined {\n  if (typeof error !== 'object' || error === null) return undefined;\n  const candidate = error as Record<string, unknown>;\n\n  const own = stringProp(candidate, 'code');\n  if (own !== undefined && own !== 'OAUTH_RESPONSE_BODY_ERROR') return own;\n\n  const cause =\n    typeof candidate.cause === 'object' && candidate.cause !== null\n      ? (candidate.cause as Record<string, unknown>)\n      : null;\n  return cause ? stringProp(cause, 'code') : undefined;\n}\n"],"mappings":";;;;;;;;AAUA,SAAgB,yBAAyB,QAAqB;CAC5D,OAAO;EACL,UAAU,OAAO;EACjB,QAAQ,OAAO;EACf,aAAa,OAAO;EACpB,OAAO,MAAM,QAAQ,OAAO,KAAK,IAAI,OAAO,MAAM,KAAK,GAAG,IAAI,OAAO;EACrE,QAAQ,OAAO,UAAU;CAC3B;AACF;;;;;;;;;;AAWA,SAAgB,wBAAwB,OAAgB;CACtD,IAAI,OAAO,UAAU,YAAY,UAAU,MACzC,OAAO,EAAE,OAAO,MAAM;CAGxB,MAAM,YAAY;CAClB,MAAM,QACJ,OAAO,UAAU,UAAU,YAAY,UAAU,UAAU,OACtD,UAAU,QACX;CAKN,OAAO;EACL,MAAM,WAAW,WAAW,MAAM,MAAM,QAAQ,WAAW,OAAO,MAAM,IAAI,KAAA;EAC5E,OAAO,WAAW,WAAW,OAAO,MAAM,QAAQ,WAAW,OAAO,OAAO,IAAI,KAAA;EAC/E,kBACE,WAAW,WAAW,mBAAmB,MACxC,QAAQ,WAAW,OAAO,mBAAmB,IAAI,KAAA;EACpD,SAAS,WAAW,WAAW,SAAS;EACxC,MAAM,WAAW,WAAW,MAAM;EAClC,QAAQ,WAAW,WAAW,QAAQ;EACtC,cAAc,QAAQ,WAAW,OAAO,SAAS,IAAI,KAAA;EACrD,WAAW,QAAQ,WAAW,OAAO,MAAM,IAAI,KAAA;CACjD;AACF;AAEA,SAAS,WAAW,OAAgC,KAAiC;CACnF,OAAO,OAAO,MAAM,SAAS,WAAY,MAAM,OAAkB,KAAA;AACnE;AAEA,SAAS,WAAW,OAAgC,KAAiC;CACnF,OAAO,OAAO,MAAM,SAAS,WAAY,MAAM,OAAkB,KAAA;AACnE;;;;;AAMA,IAAM,kCAAkB,IAAI,IAAI;CAC9B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;;AAGD,IAAM,oBAAoB;;;;;;;;;;;;;;AAe1B,SAAgB,uBAAuB,OAAqC;CAC1E,MAAM,UAAU,wBAAwB,KAAK;CAE7C,IAAI,QAAQ,SAAS,+BAA+B,QAAQ,UAAU,iBACpE,OAAO;CAGT,IAAI,mBAAmB,OAAO,OAAO,GACnC,OAAO;CAGT,OAAO;AACT;AAEA,SAAS,mBACP,OACA,SACS;CAET,IAAI,QAAQ,SAAS,gBAAgB,QAAQ,SAAS,gBAAgB,OAAO;CAC7E,IAAI,QAAQ,cAAc,gBAAgB,QAAQ,cAAc,gBAAgB,OAAO;CAEvF,MAAM,OAAO,YAAY,KAAK;CAC9B,IAAI,SAAS,KAAA,KAAa,gBAAgB,IAAI,IAAI,GAAG,OAAO;CAK5D,IAAI,QAAQ,SAAS,aAAa;EAChC,IAAI,QAAQ,WAAW,kBAAkB,KAAK,QAAQ,OAAO,GAAG,OAAO;EACvE,IAAI,QAAQ,gBAAgB,kBAAkB,KAAK,QAAQ,YAAY,GAAG,OAAO;CACnF;CAEA,OAAO;AACT;;AAGA,SAAS,YAAY,OAAoC;CACvD,IAAI,OAAO,UAAU,YAAY,UAAU,MAAM,OAAO,KAAA;CACxD,MAAM,YAAY;CAElB,MAAM,MAAM,WAAW,WAAW,MAAM;CACxC,IAAI,QAAQ,KAAA,KAAa,QAAQ,6BAA6B,OAAO;CAErE,MAAM,QACJ,OAAO,UAAU,UAAU,YAAY,UAAU,UAAU,OACtD,UAAU,QACX;CACN,OAAO,QAAQ,WAAW,OAAO,MAAM,IAAI,KAAA;AAC7C"}

package/dist/oauth.d.ts

@@ -1,24 +1,13 @@
+import { type JWTPayload } from 'jose';
 import * as openid from 'openid-client';
+import type { ClientAuthConfig, ClientCredentialsConfig, OAuthConfig } from './oauth-config.js';
 import type { Session } from './types';
 export type { Configuration, TokenEndpointResponse } from 'openid-client';
+export type { ClientAuthConfig, ClientCredentialsConfig, OAuthConfig };
 /** Default OIDC scope requesting user identity, profile, email, and offline access. */
 export declare const defaultScope = "openid profile email offline_access";
-/** Configuration for server-side OAuth / OIDC flows. */
-export type OAuthConfig = {
-    issuer: string;
-    clientId: string;
-    clientSecret: string;
-    redirect_uri: string;
-    scope: string;
-    /**
-     * Opt in to Pushed Authorization Requests (RFC 9126) when the provider
-     * supports it. When true, authorization parameters are posted to the
-     * provider's PAR endpoint ahead of the redirect, and only `client_id` +
-     * `request_uri` travel through the user-agent. The provider must advertise
-     * `pushed_authorization_request_endpoint` in its discovery metadata.
-     */
-    usePar?: boolean;
-};
+/** Returns a scope as the space-separated string sent on the wire. */
+export declare function joinScope(scope: string | string[]): string;
 /**
  * Refreshes an access token using a refresh token grant.
  *
@@ -34,17 +23,26 @@ export interface PKCEOptions {
     state: string;
     parameters: Record<string, string>;
 }
+/** Per-request options for {@link buildPKCEOptions}. */
+export interface AuthorizationRequestOptions {
+    /** Extra authorization parameters, merged over `OAuthConfig.authorizationParameters`. */
+    parameters?: Record<string, string>;
+}
 /**
  * Creates PKCE parameters for an OAuth flow.
+ * For the verifier, challenge or state alone, use `createPkcePair` / `createState` from `/pkce`.
+ * Adds `config.authorizationParameters` and `options.parameters`; a `scope` among them wins.
  *
  * @param config - OAuthConfig configuration including the redirect URI and scope.
+ * @param options - Per-request extra parameters.
  * @returns A promise that resolves to an object containing:
  *  - code_verifier: The randomly generated PKCE code verifier.
  *  - code_challenge: The derived PKCE code challenge.
  *  - state: A random state to protect against CSRF.
  *  - parameters: A Record<string,string> with the assembled parameters.
+ * @throws Error if an extra parameter is a reserved key (see `OAuthConfig.authorizationParameters`).
  */
-export declare function buildPKCEOptions(config: OAuthConfig): Promise<PKCEOptions>;
+export declare function buildPKCEOptions(config: OAuthConfig, options?: AuthorizationRequestOptions): Promise<PKCEOptions>;
 /**
  * Builds an authorization URL with PKCE parameters.
  *
@@ -81,29 +79,6 @@ export declare function buildAuthorizationUrlWithPAR(config: openid.Configuratio
  * @returns A Promise that resolves to the authorization URL
  */
 export declare function discoverAndBuildAuthorizationUrl(oauthConfig: OAuthConfig, pkceOptions: PKCEOptions): Promise<URL>;
-/**
- * Configuration for OAuth client credentials flow (machine-to-machine authentication)
- */
-export type ClientCredentialsConfig = {
-    /** OAuth token endpoint URL. Must be https. */
-    tokenEndpoint: string;
-    /** OAuth client ID */
-    clientId: string;
-    /** OAuth client secret */
-    clientSecret: string;
-    /** Optional scope for the access token */
-    scope?: string;
-    /**
-     * Issuer identifier. Only used to satisfy the server metadata; defaults to the
-     * token endpoint's origin, which is right for the common case.
-     */
-    issuer?: string;
-    /**
-     * Request timeout in seconds.
-     * @default 30
-     */
-    timeout?: number;
-};
 /**
  * Exchanges an authorization code for tokens using OIDC discovery and PKCE.
  *
@@ -127,19 +102,46 @@ export interface OidcUserInfo {
  * Extracts user information from an OIDC token response.
  * Decodes the ID token and extracts standard claims plus roles from a configurable claim.
  *
+ * Decodes only: the signature, `iss`, `aud` and `exp` are not checked. Safe on tokens
+ * straight from `exchangeAuthorizationCode`; verify any others first (e.g. jose `jwtVerify`).
+ *
  * @param tokens - Token response from the OIDC provider
  * @param rolesClaim - Name of the claim containing user roles (default: 'roles')
  * @returns Extracted user information
  */
 export declare function extractUserFromTokens(tokens: openid.TokenEndpointResponse, rolesClaim?: string): OidcUserInfo;
+/**
+ * Changes the session built from a token response, e.g. to add `data` or custom user
+ * fields. `claims` are decoded from the ID token, not verified, and undefined without one.
+ */
+export type MapSession = (tokens: openid.TokenEndpointResponse, claims: JWTPayload | undefined, session: Session) => Session;
+/** Options for {@link buildSessionFromTokens}. */
+export interface BuildSessionOptions {
+    /**
+     * Name of the ID token claim that contains user roles.
+     * @default 'roles'
+     */
+    rolesClaim?: string;
+    /** Changes the session before it is returned. */
+    mapSession?: MapSession;
+}
 /**
  * Builds a Session object from an OIDC token response.
- * Maps provider tokens and user claims into the internal Session format.
+ * Maps provider tokens and user claims into the internal Session format. Without an
+ * `id_token` the session has no `user`.
+ *
+ * Decodes the ID token like `extractUserFromTokens`, without verifying it. Pass tokens
+ * straight from `exchangeAuthorizationCode`, or verify them first.
  *
  * @param tokens - Token response from the OIDC provider
- * @param rolesClaim - Name of the claim containing user roles (default: 'roles')
+ * @param options - `rolesClaim` and `mapSession`
  * @returns A Session object ready to be encrypted and stored
  */
+export declare function buildSessionFromTokens(tokens: openid.TokenEndpointResponse, options?: BuildSessionOptions): Session;
+/**
+ * @param tokens - Token response from the OIDC provider
+ * @param rolesClaim - Name of the claim containing user roles (default: 'roles')
+ */
 export declare function buildSessionFromTokens(tokens: openid.TokenEndpointResponse, rolesClaim?: string): Session;
 /**
  * Validates a return URL against open redirect attacks.
@@ -197,10 +199,10 @@ export declare function buildOidcLogoutUrl(oauthConfig: OAuthConfig, options: Oi
 /**
  * Performs OAuth 2.0 client credentials grant flow for machine-to-machine authentication.
  *
- * Uses client_secret_post against the given token endpoint. The endpoint must be
- * https — the request carries the client secret.
+ * Authenticates with `config.clientAuth` (default client_secret_post). The
+ * endpoint must be https — the request carries the client credentials.
  *
- * @param config - Client credentials configuration including token endpoint, client ID, and secret
+ * @param config - Client credentials configuration: token endpoint, client ID and credentials
  * @returns Token response from the OAuth provider
  * @throws Error if the endpoint is not https, the request times out, or the grant fails
  *

package/dist/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../src/oauth.ts"],"names":[],"mappings":"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"}

package/dist/oauth.js

@@ -1,13 +1,18 @@
 import { createLogger } from "./logger.js";
 import { getOAuthErrorLogContext } from "./oauth-logging.js";
 import { newSessionId } from "./session-events.js";
-import { discoverConfiguration } from "./oidc-discovery.js";
+import { discoverConfiguration, resolveClientAuth } from "./oidc-discovery.js";
+import { createPkcePair, createState } from "./pkce.js";
 import { decodeJwt } from "jose";
 import * as openid from "openid-client";
-//#region src/oauth.ts
+// src/oauth.ts
 var logger = createLogger({ namespace: "fides-auth:oauth" });
 /** Default OIDC scope requesting user identity, profile, email, and offline access. */
 var defaultScope = "openid profile email offline_access";
+/** Returns a scope as the space-separated string sent on the wire. */
+function joinScope(scope) {
+	return Array.isArray(scope) ? scope.join(" ") : scope;
+}
 /**
 * Refreshes an access token using a refresh token grant.
 *
@@ -19,7 +24,7 @@ async function refreshAccessToken(oAuthConfig, refreshToken) {
 	logger.debug({ issuer: oAuthConfig.issuer }, "Starting token refresh");
 	try {
 		const config = await discoverConfiguration(oAuthConfig);
-		const tokens = await openid.refreshTokenGrant(config, refreshToken, { scope: oAuthConfig.scope });
+		const tokens = await openid.refreshTokenGrant(config, refreshToken, { scope: joinScope(oAuthConfig.scope) });
 		logger.info({
 			hasAccessToken: !!tokens.access_token,
 			hasRefreshToken: !!tokens.refresh_token,
@@ -39,30 +44,53 @@ async function refreshAccessToken(oAuthConfig, refreshToken) {
 		throw error;
 	}
 }
+/** Extra parameters can't set these. */
+var RESERVED_AUTHORIZATION_PARAMETERS = /* @__PURE__ */ new Set([
+	"state",
+	"code_challenge",
+	"code_challenge_method",
+	"redirect_uri",
+	"client_id",
+	"response_type",
+	"request",
+	"request_uri",
+	"nonce"
+]);
 /**
 * Creates PKCE parameters for an OAuth flow.
+* For the verifier, challenge or state alone, use `createPkcePair` / `createState` from `/pkce`.
+* Adds `config.authorizationParameters` and `options.parameters`; a `scope` among them wins.
 *
 * @param config - OAuthConfig configuration including the redirect URI and scope.
+* @param options - Per-request extra parameters.
 * @returns A promise that resolves to an object containing:
 *  - code_verifier: The randomly generated PKCE code verifier.
 *  - code_challenge: The derived PKCE code challenge.
 *  - state: A random state to protect against CSRF.
 *  - parameters: A Record<string,string> with the assembled parameters.
+* @throws Error if an extra parameter is a reserved key (see `OAuthConfig.authorizationParameters`).
 */
-async function buildPKCEOptions(config) {
-	const code_verifier = openid.randomPKCECodeVerifier();
-	const code_challenge = await openid.calculatePKCECodeChallenge(code_verifier);
-	const state = openid.randomState();
+async function buildPKCEOptions(config, options = {}) {
+	const extra = {
+		...config.authorizationParameters,
+		...options.parameters
+	};
+	const reserved = Object.keys(extra).filter((key) => RESERVED_AUTHORIZATION_PARAMETERS.has(key));
+	if (reserved.length > 0) throw new Error(`Reserved authorization parameters can't be overridden: ${reserved.join(", ")}`);
+	const { verifier: code_verifier, challenge: code_challenge } = await createPkcePair();
+	const state = createState();
 	const parameters = {
 		redirect_uri: config.redirect_uri,
-		scope: config.scope ?? "openid profile email offline_access",
+		scope: joinScope(config.scope ?? "openid profile email offline_access"),
+		...extra,
 		code_challenge,
 		code_challenge_method: "S256",
 		state
 	};
-	logger.info({
+	logger.debug({
 		redirectUri: config.redirect_uri,
-		scope: parameters.scope
+		scope: parameters.scope,
+		extraParameters: Object.keys(extra)
 	}, "PKCE parameters generated");
 	return {
 		code_verifier,
@@ -177,13 +205,18 @@ async function exchangeAuthorizationCode(oauthConfig, callbackUrl, codeVerifier,
 * Extracts user information from an OIDC token response.
 * Decodes the ID token and extracts standard claims plus roles from a configurable claim.
 *
+* Decodes only: the signature, `iss`, `aud` and `exp` are not checked. Safe on tokens
+* straight from `exchangeAuthorizationCode`; verify any others first (e.g. jose `jwtVerify`).
+*
 * @param tokens - Token response from the OIDC provider
 * @param rolesClaim - Name of the claim containing user roles (default: 'roles')
 * @returns Extracted user information
 */
 function extractUserFromTokens(tokens, rolesClaim = "roles") {
 	if (!tokens.id_token) throw new Error("OIDC token response is missing id_token");
-	const idToken = decodeJwt(tokens.id_token);
+	return userFromClaims(decodeJwt(tokens.id_token), rolesClaim);
+}
+function userFromClaims(idToken, rolesClaim) {
 	const rawRoles = idToken[rolesClaim];
 	const nonArrayRoles = typeof rawRoles === "string" ? [rawRoles] : [];
 	const roles = Array.isArray(rawRoles) ? rawRoles : nonArrayRoles;
@@ -199,23 +232,17 @@ function extractUserFromTokens(tokens, rolesClaim = "roles") {
 		roles
 	};
 }
-/**
-* Builds a Session object from an OIDC token response.
-* Maps provider tokens and user claims into the internal Session format.
-*
-* @param tokens - Token response from the OIDC provider
-* @param rolesClaim - Name of the claim containing user roles (default: 'roles')
-* @returns A Session object ready to be encrypted and stored
-*/
-function buildSessionFromTokens(tokens, rolesClaim = "roles") {
+function buildSessionFromTokens(tokens, options = {}) {
+	const { rolesClaim = "roles", mapSession } = typeof options === "string" ? { rolesClaim: options } : options;
 	if (!tokens.access_token) throw new Error("OIDC token response is missing access_token");
-	const userInfo = extractUserFromTokens(tokens, rolesClaim);
+	const claims = tokens.id_token ? decodeJwt(tokens.id_token) : void 0;
+	const userInfo = claims && userFromClaims(claims, rolesClaim);
 	let scopes;
 	if (typeof tokens.scope === "string") {
 		const parsed = tokens.scope.split(" ").filter((s) => s.length > 0);
 		if (parsed.length > 0) scopes = parsed;
 	}
-	return {
+	const session = {
 		sid: newSessionId(),
 		tokens: {
 			accessToken: tokens.access_token,
@@ -223,13 +250,15 @@ function buildSessionFromTokens(tokens, rolesClaim = "roles") {
 			refreshToken: tokens.refresh_token,
 			idToken: tokens.id_token
 		},
-		user: {
+		user: userInfo && {
+			sub: userInfo.sub,
 			name: userInfo.name,
 			email: userInfo.email,
 			roles: userInfo.roles
 		},
 		scopes
 	};
+	return mapSession ? mapSession(tokens, claims, session) : session;
 }
 /**
 * Validates a return URL against open redirect attacks.
@@ -328,10 +357,10 @@ async function buildOidcLogoutUrl(oauthConfig, options) {
 /**
 * Performs OAuth 2.0 client credentials grant flow for machine-to-machine authentication.
 *
-* Uses client_secret_post against the given token endpoint. The endpoint must be
-* https — the request carries the client secret.
+* Authenticates with `config.clientAuth` (default client_secret_post). The
+* endpoint must be https — the request carries the client credentials.
 *
-* @param config - Client credentials configuration including token endpoint, client ID, and secret
+* @param config - Client credentials configuration: token endpoint, client ID and credentials
 * @returns Token response from the OAuth provider
 * @throws Error if the endpoint is not https, the request times out, or the grant fails
 *
@@ -347,10 +376,11 @@ async function buildOidcLogoutUrl(oauthConfig, options) {
 */
 async function clientCredentialsGrant(config) {
 	try {
+		const { clientSecret, clientAuthentication } = resolveClientAuth(config);
 		const openidConfig = new openid.Configuration({
 			issuer: config.issuer ?? new URL(config.tokenEndpoint).origin,
 			token_endpoint: config.tokenEndpoint
-		}, config.clientId, config.clientSecret, openid.ClientSecretPost(config.clientSecret));
+		}, config.clientId, clientSecret, clientAuthentication);
 		openidConfig.timeout = config.timeout ?? 30;
 		const tokens = await openid.clientCredentialsGrant(openidConfig, config.scope ? { scope: config.scope } : void 0);
 		logger.debug({ tokenEndpoint: config.tokenEndpoint }, "Client credentials grant successful");
@@ -363,7 +393,6 @@ async function clientCredentialsGrant(config) {
 		throw error;
 	}
 }
-//#endregion
-export { buildAuthorizationUrl, buildAuthorizationUrlWithPAR, buildOidcLogoutUrl, buildPKCEOptions, buildSessionFromTokens, clientCredentialsGrant, defaultScope, discoverAndBuildAuthorizationUrl, exchangeAuthorizationCode, extractUserFromTokens, refreshAccessToken, validateReturnUrl };
+export { buildAuthorizationUrl, buildAuthorizationUrlWithPAR, buildOidcLogoutUrl, buildPKCEOptions, buildSessionFromTokens, clientCredentialsGrant, defaultScope, discoverAndBuildAuthorizationUrl, exchangeAuthorizationCode, extractUserFromTokens, joinScope, refreshAccessToken, validateReturnUrl };
 
 //# sourceMappingURL=oauth.js.map