cynx-lib 1.3.28

package/ui/components/Toast.jsx

@@ -0,0 +1,106 @@
+import { useState, useEffect, useCallback } from 'react';
+import { createPortal } from 'react-dom';
+
+const STYLES = `
+#toast-root { position: fixed; top: 20px; right: 20px; display: flex; flex-direction: column; gap: 8px; z-index: 99999; }
+.toast {
+  background: var(--surface, #fff); border: 1px solid var(--border, #d7d8e0);
+  border-radius: var(--rads, 8px); padding: 10px 14px;
+  font-size: .78rem; display: flex; align-items: center; gap: 8px;
+  box-shadow: 0px 40px 100px 0px rgba(0,0,0,.15); max-width: 300px;
+  color: var(--primary-text, #0f111c); font-weight: 500;
+  animation: cx-toastSlide .18s ease;
+  cursor: pointer;
+}
+.toast.success  { border-left: 3px solid var(--success, #27ae60); }
+.toast.error { border-left: 3px solid var(--danger, #f64747); }
+.toast.ok  { border-left: 3px solid var(--success, #27ae60); }
+.toast.err { border-left: 3px solid var(--danger, #f64747); }
+@keyframes cx-toastSlide { from { opacity: 0; transform: translateX(16px); } to { opacity: 1; transform: translateX(0); } }
+`;
+
+let _id = 'cynx-toast-styles';
+function ensureStyles() {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(_id)) return;
+  const tag = document.createElement('style');
+  tag.id = _id;
+  tag.textContent = STYLES;
+  document.head.appendChild(tag);
+}
+
+// Auto-inject on module load
+if (typeof document !== 'undefined') ensureStyles();
+
+// ── Module-level state ────────────────────────────────────────────────────────
+let _toasts = [];
+let _listeners = new Set();
+
+function notify() {
+  const snapshot = [..._toasts];
+  _listeners.forEach(fn => fn(snapshot));
+}
+
+// Global toast — call from anywhere, no hook needed
+export function toast(msg, type = 'ok') {
+  ensureStyles();
+  const id = Date.now() + Math.random();
+  _toasts = [..._toasts, { id, msg, type }];
+  notify();
+  setTimeout(() => {
+    _toasts = _toasts.filter(t => t.id !== id);
+    notify();
+  }, 3500);
+}
+
+// ── Hook — for components that want reactive state ────────────────────────────
+export function useToast() {
+  const [toasts, setToasts] = useState(_toasts);
+
+  useEffect(() => {
+    _listeners.add(setToasts);
+    return () => _listeners.delete(setToasts);
+  }, []);
+
+  const remove = useCallback(id => {
+    _toasts = _toasts.filter(t => t.id !== id);
+    notify();
+  }, []);
+
+  return { toasts, toast, remove };
+}
+
+const POSITIONS = {
+  'top-right': { top: 20, right: 20, bottom: 'auto', left: 'auto' },
+  'top-left': { top: 20, left: 20, bottom: 'auto', right: 'auto' },
+  'top-center': { top: 20, left: '50%', transform: 'translateX(-50%)', bottom: 'auto', right: 'auto' },
+  'bottom-right': { bottom: 20, right: 20, top: 'auto', left: 'auto' },
+  'bottom-left': { bottom: 20, left: 20, top: 'auto', right: 'auto' },
+  'bottom-center': { bottom: 20, left: '50%', transform: 'translateX(-50%)', top: 'auto', right: 'auto' },
+  'top': { top: 20, right: 20, bottom: 'auto', left: 'auto' },
+  'bottom': { bottom: 20, right: 20, top: 'auto', left: 'auto' },
+};
+
+// ── Render component ──────────────────────────────────────────────────────────
+export function Toast({ toasts, remove, position = 'top-right', style = {} }) {
+  ensureStyles();
+  const internal = useToast();
+  const activeToasts = Array.isArray(toasts) ? toasts : internal.toasts;
+  const activeRemove = typeof remove === 'function' ? remove : internal.remove;
+  const posStyle = POSITIONS[position] || POSITIONS['top-right'];
+
+  return createPortal(
+    <div id="toast-root" style={{ ...posStyle, ...style }}>
+      {(activeToasts || []).map(t => (
+        <div key={t.id} className={`toast ${t.type}`} onClick={() => activeRemove(t.id)}>
+          {t.type === 'ok' || t.type === 'success'
+            ? <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="var(--success, #27ae60)" strokeWidth="2.5" strokeLinecap="round"><polyline points="20 6 9 17 4 12"/></svg>
+            : <svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="var(--danger, #f64747)" strokeWidth="2.5" strokeLinecap="round"><circle cx="12" cy="12" r="10"/><line x1="15" y1="9" x2="9" y2="15"/><line x1="9" y1="9" x2="15" y2="15"/></svg>
+          }
+          {t.msg}
+        </div>
+      ))}
+    </div>,
+    document.body
+  );
+}

package/ui/components/Toggle.jsx

@@ -0,0 +1,67 @@
+const SIZES = {
+  sm: { w: 28, h: 16, r: 8, dot: 12, off: 2, on: 14 },
+  md: { w: 34, h: 18, r: 9, dot: 14, off: 2, on: 18 },
+  lg: { w: 44, h: 24, r: 12, dot: 18, off: 3, on: 23 },
+};
+
+const COLORS = {
+  primary: 'var(--accent, #f99e2c)',
+  success: 'var(--s, #27ae60)',
+  warning: 'var(--w, #f59e0b)',
+  danger:  'var(--d, #f64747)',
+};
+
+const OFF_COLOR = 'var(--bd, #d7d8e0)';
+
+export default function Toggle({
+  checked = false,
+  onChange,
+  disabled = false,
+  size = 'md',
+  color = 'primary',
+  label = null,
+  labelStyle = {},
+  onClick = null,
+  className = '',
+  style = {},
+}) {
+  const s = SIZES[size] || SIZES.md;
+  const trackBg = checked ? (COLORS[color] || COLORS.primary) : OFF_COLOR;
+
+  return (
+    <label
+      className={className}
+      style={{
+        display:'inline-flex', alignItems:'center', gap:8,
+        cursor: disabled ? 'not-allowed' : 'pointer',
+        userSelect:'none', opacity: disabled ? .4 : 1,
+        ...style,
+      }}
+      onClick={onClick}
+    >
+      <input type="checkbox" checked={checked} disabled={disabled}
+        onChange={e => onChange?.(e.target.checked)}
+        style={{ position:'absolute', opacity:0, width:0, height:0 }} />
+      <span style={{
+        position:'relative', width: s.w, height: s.h, borderRadius: s.r,
+        background: trackBg, flexShrink: 0,
+        transition: 'background .25s ease',
+        boxShadow: 'var(--shadow, 0 1px 3px rgba(20,22,41,.1))',
+      }}>
+        <span style={{
+          position:'absolute', top:'50%',
+          transform: checked
+            ? 'translateY(-50%) scale(1)'
+            : 'translateY(-50%) scale(1)',
+          left: checked ? s.on : s.off,
+          width: s.dot, height: s.dot,
+          background: 'var(--surface,#fff)', borderRadius: '50%',
+          boxShadow: 'var(--shadow, 0 1px 3px rgba(0,0,0,.25))',
+          transition: 'left .3s cubic-bezier(.34,1.56,.64,1), transform .2s ease',
+          willChange: 'left',
+        }} />
+      </span>
+      {label && <span style={labelStyle}>{label}</span>}
+    </label>
+  );
+}

package/ui/components/UptimeBar.jsx

@@ -0,0 +1,135 @@
+import { useState, useRef } from 'react';
+
+const card = {
+  background: 'var(--surface,#fff)',
+  border: '1px solid var(--border, #e2e8f0)',
+  borderRadius: 'var(--rad, 10px)',
+  boxShadow: 'var(--shadow, 0 1px 3px rgba(0,0,0,.06), 0 1px 2px rgba(0,0,0,.04))',
+};
+
+export default function UptimeBar({
+  title,
+  subtitle,
+  items = [],
+  value,
+  leftLabel,
+  rightLabel,
+  legend,
+  showDot = true,
+  dotColor = 'var(--success, #27ae60)',
+  barHeight = 28,
+  barRadius = 3,
+  emptyColor = 'var(--grey-1, #f5f5f8)',
+  style,
+  renderTooltip,
+}) {
+  const [hovered, setHovered] = useState(null);
+  const [tooltipPos, setTooltipPos] = useState({ x: 0, y: 0 });
+  const containerRef = useRef(null);
+
+  function handleMouseEnter(e, idx) {
+    const rect = e.currentTarget.getBoundingClientRect();
+    const containerRect = containerRef.current.getBoundingClientRect();
+    setTooltipPos({
+      x: rect.left - containerRect.left + rect.width / 2,
+      y: rect.top - containerRect.top - 8,
+    });
+    setHovered(idx);
+  }
+
+  // Smart tooltip shift so edge items are never clipped
+  const tooltipShift = hovered !== null
+    ? (hovered > items.length - 8 ? '-92%' : hovered < 8 ? '-8%' : '-50%')
+    : '-50%';
+
+  return (
+    <div ref={containerRef} style={{ ...card, padding: '14px 18px 14px', position: 'relative', ...style }}>
+      {/* Header */}
+      {(title || subtitle || (Array.isArray(legend) && legend.length > 0)) && (
+        <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between', marginBottom: 12 }}>
+          <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+            {showDot && (
+              <span style={{
+                width: 8, height: 8, borderRadius: '50%',
+                background: dotColor, flexShrink: 0,
+              }} />
+            )}
+            {title && (
+              <span style={{ fontSize: '.78rem', fontWeight: 700, color: 'var(--primary-text, #0f172a)', letterSpacing: '-.01em' }}>
+                {title}
+              </span>
+            )}
+            {subtitle && (
+              <span style={{ fontSize: '.65rem', color: 'var(--muted, #797b8d)', fontWeight: 500 }}>
+                {subtitle}
+              </span>
+            )}
+          </div>
+          {/* Legend */}
+          {Array.isArray(legend) && legend.length > 0 && (
+            <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+              {legend.map((item, idx) => (
+                <div key={idx} style={{ display: 'flex', alignItems: 'center', gap: 4 }}>
+                  <span style={{ width: 7, height: 7, borderRadius: 2, background: item.color, flexShrink: 0 }} />
+                  <span style={{ fontSize: '.55rem', color: 'var(--muted, #797b8d)', fontWeight: 500 }}>{item.label}</span>
+                </div>
+              ))}
+            </div>
+          )}
+        </div>
+      )}
+
+      {/* Bars: purely renders precomputed items */}
+      <div style={{ display: 'flex', alignItems: 'flex-end', gap: 2, height: barHeight, marginBottom: 6 }}>
+        {items.map((item, i) => (
+          <div
+            key={item.id || i}
+            onMouseEnter={(e) => handleMouseEnter(e, i)}
+            onMouseLeave={() => setHovered(null)}
+            style={{
+              flex: 1,
+              height: '100%',
+              borderRadius: barRadius,
+              background: item.color || emptyColor,
+            }}
+          />
+        ))}
+      </div>
+
+      {/* Tooltip: renders caller content only */}
+      {hovered !== null && items[hovered] && (renderTooltip || items[hovered].tooltip) && (
+        <div style={{
+          position: 'absolute',
+          left: tooltipPos.x,
+          top: tooltipPos.y,
+          transform: `translate(${tooltipShift}, -100%)`,
+          background: 'var(--surface,#fff)',
+          border: '1px solid var(--border, #e2e8f0)',
+          borderRadius: 'var(--rads, 8px)',
+          boxShadow: 'var(--smd, 0 4px 12px rgba(0,0,0,.12))',
+          padding: '8px 12px',
+          pointerEvents: 'none',
+          zIndex: 1000,
+          whiteSpace: 'nowrap',
+        }}>
+          {renderTooltip
+            ? renderTooltip(items[hovered], hovered)
+            : typeof items[hovered].tooltip === 'function'
+            ? items[hovered].tooltip(items[hovered], hovered)
+            : items[hovered].tooltip}
+        </div>
+      )}
+
+      {/* Footer */}
+      <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'space-between' }}>
+        <span style={{ fontSize: '.58rem', color: 'var(--muted, #797b8d)', fontWeight: 500 }}>{leftLabel}</span>
+        {value && (
+          <span style={{ fontSize: '.78rem', fontWeight: 700, color: dotColor, fontFamily: 'var(--mono, ui-monospace, monospace)' }}>
+            {value}
+          </span>
+        )}
+        <span style={{ fontSize: '.58rem', color: 'var(--muted, #797b8d)', fontWeight: 500 }}>{rightLabel}</span>
+      </div>
+    </div>
+  );
+}

package/ui/components/XTable.jsx

@@ -0,0 +1,44 @@
+export function XTable({ children, style }) {
+  return <table style={{ width: '100%', borderCollapse: 'collapse', tableLayout: 'fixed', fontSize: '.8rem', ...style }}>{children}</table>;
+}
+export function XThead({ children }) { return <thead>{children}</thead>; }
+export function XTbody({ children }) { return <tbody>{children}</tbody>; }
+export function XTr({ children, onClick }) {
+  return <tr onClick={onClick} style={{ borderBottom: '1px solid var(--border-light, #ebebf0)', transition: 'background .12s', cursor: onClick ? 'pointer' : undefined }}>{children}</tr>;
+}
+export function XTh({ children, style }) {
+  return <th style={{ textAlign: 'left', padding: '8px 10px', fontSize: '.68rem', fontWeight: 600, textTransform: 'uppercase', letterSpacing: '.06em', color: 'var(--muted, #9b9daa)', borderBottom: '1px solid var(--border-light, #ebebf0)', ...style }}>{children}</th>;
+}
+export function XTd({ children, style, className = '', colSpan }) {
+  return <td style={{ padding: '9px 10px', verticalAlign: 'middle', color: 'var(--primary-text, #0f111c)', ...style }} colSpan={colSpan}>{children}</td>;
+}
+
+const SKELETON_STYLES = `
+@keyframes shimmer{0%{background-position:-600px 0}100%{background-position:600px 0}}
+@keyframes sk-shimmer{0%{background-position:-600px 0}100%{background-position:600px 0}}
+`;
+let _tbl_sk_id = 'cynx-table-skeleton-styles';
+function ensureSkeletonStyles() {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById(_tbl_sk_id)) return;
+  const tag = document.createElement('style');
+  tag.id = _tbl_sk_id;
+  tag.textContent = SKELETON_STYLES;
+  document.head.appendChild(tag);
+}
+if (typeof document !== 'undefined') ensureSkeletonStyles();
+
+export function SkeletonTable({ rows = 6, cols = 5 }) {
+  ensureSkeletonStyles();
+  return (
+    <div>
+      {Array.from({ length: rows }).map((_, i) => (
+        <div key={i} style={{ display: 'flex', gap: 8, padding: '8px 10px', borderBottom: '1px solid var(--border-light, #ebebf0)' }}>
+          {Array.from({ length: cols }).map((_, j) => (
+            <div key={j} style={{ height: 12, flex: 1, background: 'linear-gradient(90deg, var(--grey-1, #f5f5f8) 25%, var(--border-light, #ebebf0) 50%, var(--grey-1, #f5f5f8) 75%)', backgroundSize: '600px 100%', animation: 'shimmer 1.4s ease infinite', borderRadius: 'var(--radxs, 6px)' }} />
+          ))}
+        </div>
+      ))}
+    </div>
+  );
+}

package/ui/index.js

@@ -0,0 +1,97 @@
+// cynx/ui — shared component library
+import { default as _Button } from './components/Button.jsx';
+import { default as _Input } from './components/Input.jsx';
+import { default as _Toggle } from './components/Toggle.jsx';
+import { default as _Spinner, Spinner as _SpinnerNamed } from './components/Spinner.jsx';
+import { default as _TabBar } from './components/TabBar.jsx';
+import { default as _ImageUpload } from './components/ImageUpload.jsx';
+import { default as _ChipSelect } from './components/ChipSelect.jsx';
+import { default as _Checkbox } from './components/Checkbox.jsx';
+import { default as _AuthOverlay } from './components/AuthOverlay.jsx';
+import { default as _UptimeBar } from './components/UptimeBar.jsx';
+import { default as _LinearProgress } from './components/LinearProgress.jsx';
+import { default as _StatBarCard } from './components/StatBarCard.jsx';
+import { default as _StatsCard } from './components/StatsCard.jsx';
+import { default as _ActivityCard } from './components/ActivityCard.jsx';
+import { default as _HoverCard } from './components/HoverCard.jsx';
+import { default as _StatsBar } from './components/StatsBar.jsx';
+import { default as _Select } from './components/Select.jsx';
+import { default as _Badge } from './components/Badge.jsx';
+import { default as _PulseDot } from './components/PulseDot.jsx';
+import { default as _CircularProgress } from './components/CircularProgress.jsx';
+import { default as _Skeleton } from './components/Skeleton.jsx';
+import { Modal as _Modal, Confirm as _Confirm } from './components/Modal.jsx';
+import { toast as _toast, useToast as _useToast, Toast as _Toast } from './components/Toast.jsx';
+import { ConfirmRoot as _ConfirmRoot, confirm as _confirm } from './components/Confirm.jsx';
+import { Pagination as _Pagination } from './components/Pagination.jsx';
+import { DatePicker as _DatePicker } from './components/DatePicker.jsx';
+import { TimePicker as _TimePicker } from './components/TimePicker.jsx';
+import { ActionsMenu as _ActionsMenu } from './components/ActionsMenu.jsx';
+import { BrandingCard as _BrandingCard } from './components/BrandingCard.jsx';
+import { Dropzone as _Dropzone } from './components/Dropzone.jsx';
+import { Tabs as _Tabs } from './components/Tabs.jsx';
+import { SkeletonText as _SkeletonText, SkeletonCard as _SkeletonCard, SkeletonRows as _SkeletonRows, SkeletonStats as _SkeletonStats } from './components/Skeleton.jsx';
+import { XTable as _XTable, XThead as _XThead, XTbody as _XTbody, XTr as _XTr, XTh as _XTh, XTd as _XTd, SkeletonTable as _SkeletonTable } from './components/XTable.jsx';
+import { PageShell as _PageShell, TableCard as _TableCard, TableCardFilters as _TableCardFilters, TableCardBody as _TableCardBody, TableCardFooter as _TableCardFooter, CardHdr as _CardHdr, StatCard as _StatCard, StatCardSkeleton as _StatCardSkeleton } from './components/Card.jsx';
+
+import { default as _FilePicker } from './components/FilePicker.jsx';
+import { default as _Divider } from './components/Divider.jsx';
+import { default as _InfoBadge } from './components/InfoBadge.jsx';
+
+export const Button = _Button;
+export const FilePicker = _FilePicker;
+export const Divider = _Divider;
+export const InfoBadge = _InfoBadge;
+export const Input = _Input;
+export const Toggle = _Toggle;
+export const Spinner = _Spinner || _SpinnerNamed;
+export const TabBar = _TabBar;
+export const ImageUpload = _ImageUpload;
+export const ChipSelect = _ChipSelect;
+export const Checkbox = _Checkbox;
+export const AuthOverlay = _AuthOverlay;
+export const UptimeBar = _UptimeBar;
+export const LinearProgress = _LinearProgress;
+export const StatBarCard = _StatBarCard;
+export const StatsCard = _StatsCard;
+export const ActivityCard = _ActivityCard;
+export const HoverCard = _HoverCard;
+export const StatsBar = _StatsBar;
+export const Select = _Select;
+export const Badge = _Badge;
+export const PulseDot = _PulseDot;
+export const CircularProgress = _CircularProgress;
+export const Skeleton = _Skeleton;
+export const Modal = _Modal;
+export const Confirm = _Confirm;
+export const toast = _toast;
+export const useToast = _useToast;
+export const Toast = _Toast;
+export const ConfirmRoot = _ConfirmRoot;
+export const confirm = _confirm;
+export const Pagination = _Pagination;
+export const DatePicker = _DatePicker;
+export const TimePicker = _TimePicker;
+export const ActionsMenu = _ActionsMenu;
+export const BrandingCard = _BrandingCard;
+export const Dropzone = _Dropzone;
+export const Tabs = _Tabs;
+export const SkeletonText = _SkeletonText;
+export const SkeletonCard = _SkeletonCard;
+export const SkeletonRows = _SkeletonRows;
+export const SkeletonStats = _SkeletonStats;
+export const XTable = _XTable;
+export const XThead = _XThead;
+export const XTbody = _XTbody;
+export const XTr = _XTr;
+export const XTh = _XTh;
+export const XTd = _XTd;
+export const SkeletonTable = _SkeletonTable;
+export const PageShell = _PageShell;
+export const TableCard = _TableCard;
+export const TableCardFilters = _TableCardFilters;
+export const TableCardBody = _TableCardBody;
+export const TableCardFooter = _TableCardFooter;
+export const CardHdr = _CardHdr;
+export const StatCard = _StatCard;
+export const StatCardSkeleton = _StatCardSkeleton;

package/utils/index.js

@@ -0,0 +1,11 @@
+// cynx/utils — shared utility functions
+export * from './utils/uid.js';
+export * from './utils/realtime.js';
+export * from './utils/tz.js';
+export * from './utils/oidc.js';
+
+export { default as uidUtil } from './utils/uid.js';
+export { default as realtimeUtil } from './utils/realtime.js';
+export { default as tzUtil } from './utils/tz.js';
+export { default as oidcUtil } from './utils/oidc.js';
+

package/utils/utils/oidc.js

@@ -0,0 +1,209 @@
+/**
+ * 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,
+};