cynx-lib 1.3.34 → 1.3.36

package/utils/utils/oidc.js

@@ -1,209 +1,214 @@
-/**
- * cynx/utils — OpenID Connect & OAuth 2.0 Engine (oidc.js)
- *
- * Lightweight, zero-external-dependency OIDC/OAuth 2.0 client utility for Node.js / SSR.
- * Supports Discovery, PKCE (RFC 7636), signed state tokens (CSRF protection),
- * token exchange, and profile resolution.
- */
-
-import crypto from 'crypto';
-
-const DEFAULT_SECRET = (typeof process !== 'undefined' && (process.env?.OIDC_STATE_SECRET || process.env?.JWT_SECRET)) || 'cynx-oidc-state-secret-salt';
-
-/**
- * Generate a cryptographically signed state token with embedded payload and timestamp.
- * 
- * @param {object} [payload={}] Data to embed (e.g. { codeVerifier, returnTo })
- * @param {string} [secret] Custom HMAC signing secret
- * @returns {string} Signed state token in format "base64urlData.base64urlSig"
- */
-export function generateState(payload = {}, secret = DEFAULT_SECRET) {
-  const data = Buffer.from(JSON.stringify({ ...payload, ts: Date.now() })).toString('base64url');
-  const sig = crypto.createHmac('sha256', secret).update(data).digest('base64url');
-  return `${data}.${sig}`;
-}
-
-/**
- * Verify, parse, and consume a signed state token with replay & TTL validation.
- * 
- * @param {string} stateStr The state token received from redirect
- * @param {string} [secret] Custom HMAC signing secret
- * @param {number} [ttlMs=600000] Maximum token lifetime in ms (default: 10 minutes)
- * @returns {object|null} Decoded payload if valid and not expired, null otherwise
- */
-export function consumeState(stateStr, secret = DEFAULT_SECRET, ttlMs = 600_000) {
-  if (!stateStr || typeof stateStr !== 'string') return null;
-  const parts = stateStr.split('.');
-  if (parts.length !== 2) return null;
-  const [data, sig] = parts;
-  const expectedSig = crypto.createHmac('sha256', secret).update(data).digest('base64url');
-
-  if (sig.length !== expectedSig.length) return null;
-  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) return null;
-
-  try {
-    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
-    if (!payload.ts || Date.now() - payload.ts > ttlMs) return null;
-    return payload;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Generate a secure PKCE (Proof Key for Code Exchange) pair for Authorization Code flow.
- * 
- * @returns {{ codeVerifier: string, codeChallenge: string }}
- */
-export function generatePKCE() {
-  const codeVerifier = crypto.randomBytes(32).toString('base64url');
-  const codeChallenge = crypto.createHash('sha256')
-    .update(codeVerifier)
-    .digest('base64url');
-  return { codeVerifier, codeChallenge };
-}
-
-/**
- * Fetch and discover OpenID Connect provider configuration document.
- * 
- * @param {string} issuer Base issuer URL (e.g. "https://auth.example.com/realms/master")
- * @param {string} [discoveryPath='/.well-known/openid-configuration'] Custom discovery path
- * @returns {Promise<object>} Discovery metadata (authorization_endpoint, token_endpoint, etc.)
- */
-export async function discover(issuer, discoveryPath = '/.well-known/openid-configuration') {
-  let base = issuer.replace(/\/+$/, '');
-  let path = discoveryPath || '/.well-known/openid-configuration';
-  if (base.endsWith(path)) {
-    base = base.slice(0, -path.length).replace(/\/+$/, '');
-  }
-  if (!path.startsWith('/')) path = '/' + path;
-  const url = base + path;
-  const res = await fetch(url);
-  if (!res.ok) throw new Error(`OIDC Discovery failed: ${res.status} — ${url}`);
-  return res.json();
-}
-
-/**
- * Build the authorization redirect URL to initiate login.
- * 
- * @param {object} config
- * @param {string} config.issuer Issuer base URL
- * @param {string} config.clientId Client ID
- * @param {string} config.redirectUri Callback redirect URI
- * @param {string} [config.scopes='openid profile email'] Space-separated scopes
- * @param {boolean} [config.pkceEnabled=true] Whether PKCE is enabled
- * @param {string} [config.discoveryPath]
- * @param {string} state Signed state parameter
- * @param {string} [codeChallenge] PKCE code challenge
- * @returns {string} Full authorization URL
- */
-export function buildAuthorizeUrl(config, state, codeChallenge) {
-  const params = new URLSearchParams({
-    response_type: 'code',
-    client_id: config.clientId,
-    redirect_uri: config.redirectUri,
-    scope: config.scopes || 'openid profile email',
-    state,
-  });
-  if (config.pkceEnabled !== false && codeChallenge) {
-    params.set('code_challenge', codeChallenge);
-    params.set('code_challenge_method', 'S256');
-  }
-  const base = config.issuer.replace(/\/+$/, '');
-  return `${base}/authorize?${params.toString()}`;
-}
-
-/**
- * Exchange an authorization code for access, ID, and refresh tokens.
- * 
- * @param {object} config
- * @param {string} config.issuer Issuer base URL
- * @param {string} config.clientId Client ID
- * @param {string} [config.clientSecret] Client secret (for confidential clients)
- * @param {string} config.redirectUri Callback redirect URI
- * @param {boolean} [config.pkceEnabled=true]
- * @param {string} [config.discoveryPath]
- * @param {string} code Authorization code from callback
- * @param {string} [codeVerifier] PKCE code verifier
- * @returns {Promise<{ access_token: string, id_token?: string, refresh_token?: string, expires_in?: number, token_type?: string }>}
- */
-export async function exchangeCode(config, code, codeVerifier) {
-  const discoverDoc = await discover(config.issuer, config.discoveryPath);
-  const tokenUrl = discoverDoc.token_endpoint;
-
-  const body = new URLSearchParams({
-    grant_type: 'authorization_code',
-    code,
-    redirect_uri: config.redirectUri,
-    client_id: config.clientId,
-  });
-
-  if (config.clientSecret) {
-    body.set('client_secret', config.clientSecret);
-  }
-
-  if (config.pkceEnabled !== false && codeVerifier) {
-    body.set('code_verifier', codeVerifier);
-  }
-
-  const res = await fetch(tokenUrl, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-    body,
-  });
-
-  if (!res.ok) {
-    const err = await res.text();
-    throw new Error(`Token exchange failed: ${res.status} ${err}`);
-  }
-  return res.json();
-}
-
-/**
- * Fetch user profile from the UserInfo endpoint using an access token.
- * 
- * @param {object} config
- * @param {string} config.issuer Issuer base URL
- * @param {string} [config.discoveryPath]
- * @param {string} accessToken Bearer access token
- * @returns {Promise<object>} User claims and profile info
- */
-export async function getUserInfo(config, accessToken) {
-  const discoverDoc = await discover(config.issuer, config.discoveryPath);
-  const userinfoUrl = discoverDoc.userinfo_endpoint;
-  if (!userinfoUrl) throw new Error('No userinfo_endpoint in discovery document');
-
-  const res = await fetch(userinfoUrl, {
-    headers: { Authorization: `Bearer ${accessToken}` },
-  });
-
-  if (!res.ok) throw new Error(`Userinfo failed: ${res.status}`);
-  return res.json();
-}
-
-/**
- * Safely decode payload from an ID token (JWT) without verification.
- * 
- * @param {string} idToken Raw JWT id_token string
- * @returns {object} Decoded JSON payload claims
- */
-export function decodeIdToken(idToken) {
-  if (!idToken || typeof idToken !== 'string') throw new Error('Invalid id_token');
-  const parts = idToken.split('.');
-  if (parts.length !== 3) throw new Error('Invalid id_token format (expected 3 parts)');
-  const payload = Buffer.from(parts[1], 'base64url').toString('utf8');
-  return JSON.parse(payload);
-}
-
-// ─── MAIN EXPORT ────────────────────────────────────────────────────────────────
-
-export default {
-  generateState,
-  consumeState,
-  generatePKCE,
-  discover,
-  buildAuthorizeUrl,
-  exchangeCode,
-  getUserInfo,
-  decodeIdToken,
-};
+/**
+ * cynx/utils — OpenID Connect & OAuth 2.0 Engine (oidc.js)
+ *
+ * Lightweight, zero-external-dependency OIDC/OAuth 2.0 client utility for Node.js / SSR.
+ * Supports Discovery, PKCE (RFC 7636), signed state tokens (CSRF protection),
+ * token exchange, and profile resolution.
+ */
+
+import crypto from 'crypto';
+
+const DEFAULT_SECRET = (typeof process !== 'undefined' && (process.env?.OIDC_STATE_SECRET || process.env?.JWT_SECRET)) || 'cynx-oidc-state-secret-salt';
+
+/**
+ * Generate a cryptographically signed state token with embedded payload and timestamp.
+ * 
+ * @param {object} [payload={}] Data to embed (e.g. { codeVerifier, returnTo })
+ * @param {string} [secret] Custom HMAC signing secret
+ * @returns {string} Signed state token in format "base64urlData.base64urlSig"
+ */
+export function generateState(payload = {}, secret = DEFAULT_SECRET) {
+  const data = Buffer.from(JSON.stringify({ ...payload, ts: Date.now() })).toString('base64url');
+  const sig = crypto.createHmac('sha256', secret).update(data).digest('base64url');
+  return `${data}.${sig}`;
+}
+
+/**
+ * Verify, parse, and consume a signed state token with replay & TTL validation.
+ * 
+ * @param {string} stateStr The state token received from redirect
+ * @param {string} [secret] Custom HMAC signing secret
+ * @param {number} [ttlMs=600000] Maximum token lifetime in ms (default: 10 minutes)
+ * @returns {object|null} Decoded payload if valid and not expired, null otherwise
+ */
+export function consumeState(stateStr, secret = DEFAULT_SECRET, ttlMs = 600_000) {
+  if (!stateStr || typeof stateStr !== 'string') return null;
+  const parts = stateStr.split('.');
+  if (parts.length !== 2) return null;
+  const [data, sig] = parts;
+  const expectedSig = crypto.createHmac('sha256', secret).update(data).digest('base64url');
+
+  if (sig.length !== expectedSig.length) return null;
+  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expectedSig))) return null;
+
+  try {
+    const payload = JSON.parse(Buffer.from(data, 'base64url').toString('utf8'));
+    if (!payload.ts || Date.now() - payload.ts > ttlMs) return null;
+    return payload;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a secure PKCE (Proof Key for Code Exchange) pair for Authorization Code flow.
+ * 
+ * @returns {{ codeVerifier: string, codeChallenge: string }}
+ */
+export function generatePKCE() {
+  const codeVerifier = crypto.randomBytes(32).toString('base64url');
+  const codeChallenge = crypto.createHash('sha256')
+    .update(codeVerifier)
+    .digest('base64url');
+  return { codeVerifier, codeChallenge };
+}
+
+/**
+ * Fetch and discover OpenID Connect provider configuration document.
+ * 
+ * @param {string} issuer Base issuer URL (e.g. "https://auth.example.com/realms/master")
+ * @param {string} [discoveryPath='/.well-known/openid-configuration'] Custom discovery path
+ * @returns {Promise<object>} Discovery metadata (authorization_endpoint, token_endpoint, etc.)
+ */
+export async function discover(issuer, discoveryPath = '/.well-known/openid-configuration') {
+  let base = issuer.replace(/\/+$/, '');
+  let path = discoveryPath || '/.well-known/openid-configuration';
+  if (base.endsWith(path)) {
+    base = base.slice(0, -path.length).replace(/\/+$/, '');
+  }
+  if (!path.startsWith('/')) path = '/' + path;
+  const url = base + path;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`OIDC Discovery failed: ${res.status} — ${url}`);
+  return res.json();
+}
+
+/**
+ * Build the authorization redirect URL to initiate login.
+ * 
+ * @param {object} config
+ * @param {string} config.issuer Issuer base URL
+ * @param {string} config.clientId Client ID
+ * @param {string} config.redirectUri Callback redirect URI
+ * @param {string} [config.scopes='openid profile email'] Space-separated scopes
+ * @param {boolean} [config.pkceEnabled=true] Whether PKCE is enabled
+ * @param {string} [config.discoveryPath]
+ * @param {string} state Signed state parameter
+ * @param {string} [codeChallenge] PKCE code challenge
+ * @returns {string} Full authorization URL
+ */
+export function buildAuthorizeUrl(config, state, codeChallenge) {
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: config.clientId,
+    redirect_uri: config.redirectUri,
+    scope: config.scopes || 'openid profile email',
+    state,
+  });
+  if (config.pkceEnabled !== false && codeChallenge) {
+    params.set('code_challenge', codeChallenge);
+    params.set('code_challenge_method', 'S256');
+  }
+  const base = config.issuer.replace(/\/+$/, '');
+  return `${base}/authorize?${params.toString()}`;
+}
+
+/**
+ * Exchange an authorization code for access, ID, and refresh tokens.
+ * 
+ * @param {object} config
+ * @param {string} config.issuer Issuer base URL
+ * @param {string} config.clientId Client ID
+ * @param {string} [config.clientSecret] Client secret (for confidential clients)
+ * @param {string} config.redirectUri Callback redirect URI
+ * @param {boolean} [config.pkceEnabled=true]
+ * @param {string} [config.discoveryPath]
+ * @param {string} code Authorization code from callback
+ * @param {string} [codeVerifier] PKCE code verifier
+ * @returns {Promise<{ access_token: string, id_token?: string, refresh_token?: string, expires_in?: number, token_type?: string }>}
+ */
+export async function exchangeCode(config, code, codeVerifier) {
+  const discoverDoc = await discover(config.issuer, config.discoveryPath);
+  const tokenUrl = discoverDoc.token_endpoint;
+
+  const body = new URLSearchParams({
+    grant_type: 'authorization_code',
+    code,
+    redirect_uri: config.redirectUri,
+    client_id: config.clientId,
+  });
+
+  if (config.clientSecret) {
+    body.set('client_secret', config.clientSecret);
+  }
+
+  if (config.pkceEnabled !== false && codeVerifier) {
+    body.set('code_verifier', codeVerifier);
+  }
+
+  const res = await fetch(tokenUrl, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    body,
+  });
+
+  if (!res.ok) {
+    const err = await res.text();
+    throw new Error(`Token exchange failed: ${res.status} ${err}`);
+  }
+  return res.json();
+}
+
+/**
+ * Fetch user profile from the UserInfo endpoint using an access token.
+ * 
+ * @param {object} config
+ * @param {string} config.issuer Issuer base URL
+ * @param {string} [config.discoveryPath]
+ * @param {string} accessToken Bearer access token
+ * @returns {Promise<object>} User claims and profile info
+ */
+export async function getUserInfo(config, accessToken) {
+  const discoverDoc = await discover(config.issuer, config.discoveryPath);
+  const userinfoUrl = discoverDoc.userinfo_endpoint;
+  if (!userinfoUrl) throw new Error('No userinfo_endpoint in discovery document');
+
+  const res = await fetch(userinfoUrl, {
+    headers: { Authorization: `Bearer ${accessToken}` },
+  });
+
+  if (!res.ok) throw new Error(`Userinfo failed: ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Safely decode payload from an ID token (JWT) without verification.
+ * 
+ * @param {string} idToken Raw JWT id_token string
+ * @returns {object} Decoded JSON payload claims
+ */
+export function decodeIdToken(idToken) {
+  if (!idToken || typeof idToken !== 'string') throw new Error('Invalid id_token');
+  const parts = idToken.split('.');
+  if (parts.length !== 3) throw new Error('Invalid id_token format (expected 3 parts)');
+  const payload = Buffer.from(parts[1], 'base64url').toString('utf8');
+  return JSON.parse(payload);
+}
+
+export function storeVerifier() {
+  // Verifier is stored directly inside the signed state token or handled by PKCE
+}
+
+// ─── MAIN EXPORT ────────────────────────────────────────────────────────────────
+
+export default {
+  generateState,
+  storeVerifier,
+  consumeState,
+  generatePKCE,
+  discover,
+  buildAuthorizeUrl,
+  exchangeCode,
+  getUserInfo,
+  decodeIdToken,
+};