s3db.js 13.4.0 → 13.6.0

package/src/plugins/identity/oidc-discovery.js

@@ -0,0 +1,285 @@
+/**
+ * OIDC Discovery - OpenID Connect Discovery Document Generator
+ *
+ * Generates .well-known/openid-configuration and JWKS endpoints
+ * Implements OpenID Connect Discovery 1.0 specification
+ */
+
+/**
+ * Generate OpenID Connect Discovery Document
+ * @param {Object} options - Configuration options
+ * @param {string} options.issuer - Issuer URL (e.g., 'https://sso.example.com')
+ * @param {Array} options.grantTypes - Supported grant types
+ * @param {Array} options.responseTypes - Supported response types
+ * @param {Array} options.scopes - Supported scopes
+ * @returns {Object} OIDC Discovery document
+ */
+export function generateDiscoveryDocument(options = {}) {
+  const {
+    issuer,
+    grantTypes = ['authorization_code', 'client_credentials', 'refresh_token'],
+    responseTypes = ['code', 'token', 'id_token', 'code id_token', 'code token', 'id_token token', 'code id_token token'],
+    scopes = ['openid', 'profile', 'email', 'offline_access']
+  } = options;
+
+  if (!issuer) {
+    throw new Error('Issuer URL is required for OIDC discovery');
+  }
+
+  // Remove trailing slash from issuer
+  const baseUrl = issuer.replace(/\/$/, '');
+
+  return {
+    issuer: baseUrl,
+    authorization_endpoint: `${baseUrl}/auth/authorize`,
+    token_endpoint: `${baseUrl}/auth/token`,
+    userinfo_endpoint: `${baseUrl}/auth/userinfo`,
+    jwks_uri: `${baseUrl}/.well-known/jwks.json`,
+    registration_endpoint: `${baseUrl}/auth/register`,
+    introspection_endpoint: `${baseUrl}/auth/introspect`,
+    revocation_endpoint: `${baseUrl}/auth/revoke`,
+    end_session_endpoint: `${baseUrl}/auth/logout`,
+
+    // Supported features
+    scopes_supported: scopes,
+    response_types_supported: responseTypes,
+    response_modes_supported: ['query', 'fragment', 'form_post'],
+    grant_types_supported: grantTypes,
+    subject_types_supported: ['public'],
+    id_token_signing_alg_values_supported: ['RS256'],
+    token_endpoint_auth_methods_supported: [
+      'client_secret_basic',
+      'client_secret_post',
+      'none'
+    ],
+
+    // Claims
+    claims_supported: [
+      'sub',
+      'iss',
+      'aud',
+      'exp',
+      'iat',
+      'auth_time',
+      'nonce',
+      'email',
+      'email_verified',
+      'name',
+      'given_name',
+      'family_name',
+      'picture',
+      'locale'
+    ],
+
+    // Code challenge methods (PKCE)
+    code_challenge_methods_supported: ['plain', 'S256'],
+
+    // UI locales
+    ui_locales_supported: ['en', 'pt-BR'],
+
+    // Service documentation
+    service_documentation: `${baseUrl}/docs`,
+
+    // Additional metadata
+    claim_types_supported: ['normal'],
+    claims_parameter_supported: false,
+    request_parameter_supported: false,
+    request_uri_parameter_supported: false,
+    require_request_uri_registration: false,
+
+    // Discovery document version
+    version: '1.0'
+  };
+}
+
+/**
+ * Validate OAuth2/OIDC claims in JWT payload
+ * @param {Object} payload - JWT payload
+ * @param {Object} options - Validation options
+ * @param {string} options.issuer - Expected issuer
+ * @param {string} options.audience - Expected audience
+ * @param {number} options.clockTolerance - Clock skew tolerance in seconds (default: 60)
+ * @returns {Object} { valid: boolean, error: string|null }
+ */
+export function validateClaims(payload, options = {}) {
+  const {
+    issuer,
+    audience,
+    clockTolerance = 60
+  } = options;
+
+  const now = Math.floor(Date.now() / 1000);
+
+  // Check required claims
+  if (!payload.sub) {
+    return { valid: false, error: 'Missing required claim: sub' };
+  }
+
+  if (!payload.iat) {
+    return { valid: false, error: 'Missing required claim: iat' };
+  }
+
+  if (!payload.exp) {
+    return { valid: false, error: 'Missing required claim: exp' };
+  }
+
+  // Validate issuer
+  if (issuer && payload.iss !== issuer) {
+    return {
+      valid: false,
+      error: `Invalid issuer. Expected: ${issuer}, Got: ${payload.iss}`
+    };
+  }
+
+  // Validate audience
+  if (audience) {
+    const audiences = Array.isArray(payload.aud) ? payload.aud : [payload.aud];
+
+    if (!audiences.includes(audience)) {
+      return {
+        valid: false,
+        error: `Invalid audience. Expected: ${audience}, Got: ${audiences.join(', ')}`
+      };
+    }
+  }
+
+  // Validate expiration with clock tolerance
+  if (payload.exp < (now - clockTolerance)) {
+    return { valid: false, error: 'Token has expired' };
+  }
+
+  // Validate not before (if present)
+  if (payload.nbf && payload.nbf > (now + clockTolerance)) {
+    return { valid: false, error: 'Token not yet valid (nbf)' };
+  }
+
+  // Validate issued at (basic sanity check - not in future)
+  if (payload.iat > (now + clockTolerance)) {
+    return { valid: false, error: 'Token issued in the future' };
+  }
+
+  return { valid: true, error: null };
+}
+
+/**
+ * Extract user claims from user object for ID token
+ * @param {Object} user - User object from database
+ * @param {Array} scopes - Requested scopes
+ * @returns {Object} User claims
+ */
+export function extractUserClaims(user, scopes = []) {
+  const claims = {
+    sub: user.id // Subject - user ID
+  };
+
+  // Add email claims if 'email' scope requested
+  if (scopes.includes('email') && user.email) {
+    claims.email = user.email;
+    claims.email_verified = user.emailVerified || false;
+  }
+
+  // Add profile claims if 'profile' scope requested
+  if (scopes.includes('profile')) {
+    if (user.name) claims.name = user.name;
+    if (user.givenName) claims.given_name = user.givenName;
+    if (user.familyName) claims.family_name = user.familyName;
+    if (user.picture) claims.picture = user.picture;
+    if (user.locale) claims.locale = user.locale;
+    if (user.zoneinfo) claims.zoneinfo = user.zoneinfo;
+    if (user.birthdate) claims.birthdate = user.birthdate;
+    if (user.gender) claims.gender = user.gender;
+  }
+
+  return claims;
+}
+
+/**
+ * Parse scope string into array
+ * @param {string} scopeString - Space-separated scopes (e.g., 'openid profile email')
+ * @returns {Array} Array of scopes
+ */
+export function parseScopes(scopeString) {
+  if (!scopeString || typeof scopeString !== 'string') {
+    return [];
+  }
+
+  return scopeString
+    .trim()
+    .split(/\s+/)
+    .filter(s => s.length > 0);
+}
+
+/**
+ * Validate requested scopes against supported scopes
+ * @param {Array} requestedScopes - Scopes requested by client
+ * @param {Array} supportedScopes - Scopes supported by server
+ * @returns {Object} { valid: boolean, error: string|null, scopes: Array }
+ */
+export function validateScopes(requestedScopes, supportedScopes) {
+  if (!Array.isArray(requestedScopes)) {
+    requestedScopes = parseScopes(requestedScopes);
+  }
+
+  // Check if all requested scopes are supported
+  const invalidScopes = requestedScopes.filter(scope => !supportedScopes.includes(scope));
+
+  if (invalidScopes.length > 0) {
+    return {
+      valid: false,
+      error: `Unsupported scopes: ${invalidScopes.join(', ')}`,
+      scopes: []
+    };
+  }
+
+  return {
+    valid: true,
+    error: null,
+    scopes: requestedScopes
+  };
+}
+
+/**
+ * Generate authorization code (random string)
+ * @param {number} length - Code length (default: 32)
+ * @returns {string} Authorization code
+ */
+export function generateAuthCode(length = 32) {
+  const chars = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~';
+  let code = '';
+
+  for (let i = 0; i < length; i++) {
+    code += chars.charAt(Math.floor(Math.random() * chars.length));
+  }
+
+  return code;
+}
+
+/**
+ * Generate client ID
+ * @returns {string} Client ID (UUID-like)
+ */
+export function generateClientId() {
+  return crypto.randomUUID();
+}
+
+/**
+ * Generate client secret
+ * @param {number} length - Secret length (default: 64)
+ * @returns {string} Client secret
+ */
+export function generateClientSecret(length = 64) {
+  return crypto.randomBytes(length / 2).toString('hex');
+}
+
+import crypto from 'crypto';
+
+export default {
+  generateDiscoveryDocument,
+  validateClaims,
+  extractUserClaims,
+  parseScopes,
+  validateScopes,
+  generateAuthCode,
+  generateClientId,
+  generateClientSecret
+};

package/src/plugins/identity/rsa-keys.js

@@ -0,0 +1,323 @@
+/**
+ * RSA Key Management for OAuth2/OIDC
+ *
+ * Manages RS256 key pairs for signing and verifying JWTs
+ * Zero external dependencies - uses Node.js crypto only
+ */
+
+import { generateKeyPairSync, createSign, createVerify, createHash } from 'crypto';
+
+/**
+ * Generate RSA key pair for RS256
+ * @param {number} modulusLength - Key size in bits (default: 2048)
+ * @returns {Object} { publicKey, privateKey, kid }
+ */
+export function generateKeyPair(modulusLength = 2048) {
+  const { publicKey, privateKey } = generateKeyPairSync('rsa', {
+    modulusLength,
+    publicKeyEncoding: {
+      type: 'spki',
+      format: 'pem'
+    },
+    privateKeyEncoding: {
+      type: 'pkcs8',
+      format: 'pem'
+    }
+  });
+
+  // Generate key ID (kid) from public key fingerprint
+  const kid = createHash('sha256')
+    .update(publicKey)
+    .digest('hex')
+    .substring(0, 16);
+
+  return {
+    publicKey,
+    privateKey,
+    kid,
+    algorithm: 'RS256',
+    use: 'sig',
+    createdAt: new Date().toISOString()
+  };
+}
+
+/**
+ * Convert PEM public key to JWK format
+ * @param {string} publicKeyPem - PEM formatted public key
+ * @param {string} kid - Key ID
+ * @returns {Object} JWK (JSON Web Key)
+ */
+export function pemToJwk(publicKeyPem, kid) {
+  // Extract key components using Node.js crypto
+  const keyObject = createPublicKey(publicKeyPem);
+  const exported = keyObject.export({ format: 'jwk' });
+
+  return {
+    kty: 'RSA',
+    use: 'sig',
+    alg: 'RS256',
+    kid,
+    n: exported.n,  // modulus
+    e: exported.e   // exponent
+  };
+}
+
+/**
+ * Create RS256 JWT token
+ * @param {Object} payload - Token payload
+ * @param {string} privateKey - PEM formatted private key
+ * @param {string} kid - Key ID
+ * @param {string} expiresIn - Token expiration (e.g., '15m')
+ * @returns {string} JWT token
+ */
+export function createRS256Token(payload, privateKey, kid, expiresIn = '15m') {
+  // Parse expiresIn
+  const match = expiresIn.match(/^(\d+)([smhd])$/);
+  if (!match) {
+    throw new Error('Invalid expiresIn format. Use: 60s, 30m, 24h, 7d');
+  }
+
+  const [, value, unit] = match;
+  const multipliers = { s: 1, m: 60, h: 3600, d: 86400 };
+  const expiresInSeconds = parseInt(value) * multipliers[unit];
+
+  const header = {
+    alg: 'RS256',
+    typ: 'JWT',
+    kid
+  };
+
+  const now = Math.floor(Date.now() / 1000);
+
+  const data = {
+    ...payload,
+    iat: now,
+    exp: now + expiresInSeconds
+  };
+
+  // Encode header and payload
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
+  const encodedPayload = Buffer.from(JSON.stringify(data)).toString('base64url');
+
+  // Sign with RSA private key
+  const sign = createSign('RSA-SHA256');
+  sign.update(`${encodedHeader}.${encodedPayload}`);
+  sign.end();
+
+  const signature = sign.sign(privateKey, 'base64url');
+
+  return `${encodedHeader}.${encodedPayload}.${signature}`;
+}
+
+/**
+ * Verify RS256 JWT token
+ * @param {string} token - JWT token
+ * @param {string} publicKey - PEM formatted public key
+ * @returns {Object|null} Decoded payload or null if invalid
+ */
+export function verifyRS256Token(token, publicKey) {
+  try {
+    const parts = token.split('.');
+    if (parts.length !== 3) {
+      return null;
+    }
+
+    const [encodedHeader, encodedPayload, signature] = parts;
+
+    // Verify signature
+    const verify = createVerify('RSA-SHA256');
+    verify.update(`${encodedHeader}.${encodedPayload}`);
+    verify.end();
+
+    const isValid = verify.verify(publicKey, signature, 'base64url');
+
+    if (!isValid) {
+      return null;
+    }
+
+    // Decode header and payload
+    const header = JSON.parse(Buffer.from(encodedHeader, 'base64url').toString());
+    const payload = JSON.parse(Buffer.from(encodedPayload, 'base64url').toString());
+
+    // Verify algorithm
+    if (header.alg !== 'RS256') {
+      return null;
+    }
+
+    // Check expiration
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp && payload.exp < now) {
+      return null; // Expired
+    }
+
+    return {
+      header,
+      payload
+    };
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Get key ID (kid) from JWT token header
+ * @param {string} token - JWT token
+ * @returns {string|null} Key ID or null
+ */
+export function getKidFromToken(token) {
+  try {
+    const [encodedHeader] = token.split('.');
+    const header = JSON.parse(Buffer.from(encodedHeader, 'base64url').toString());
+    return header.kid || null;
+  } catch (err) {
+    return null;
+  }
+}
+
+/**
+ * Import createPublicKey for JWK conversion
+ */
+import { createPublicKey } from 'crypto';
+
+/**
+ * Key Manager class - manages key rotation and storage
+ */
+export class KeyManager {
+  constructor(keyResource) {
+    this.keyResource = keyResource;
+    this.currentKey = null;
+    this.keys = new Map(); // kid → key
+  }
+
+  /**
+   * Initialize key manager - load or generate keys
+   */
+  async initialize() {
+    // Try to load existing keys
+    const existingKeys = await this.keyResource.list();
+
+    if (existingKeys.length > 0) {
+      // Load keys into memory
+      for (const keyRecord of existingKeys) {
+        this.keys.set(keyRecord.kid, {
+          publicKey: keyRecord.publicKey,
+          privateKey: keyRecord.privateKey,
+          kid: keyRecord.kid,
+          createdAt: keyRecord.createdAt,
+          active: keyRecord.active
+        });
+
+        if (keyRecord.active) {
+          this.currentKey = keyRecord;
+        }
+      }
+    }
+
+    // If no active key, generate one
+    if (!this.currentKey) {
+      await this.rotateKey();
+    }
+  }
+
+  /**
+   * Rotate keys - generate new key pair
+   */
+  async rotateKey() {
+    const keyPair = generateKeyPair();
+
+    // Mark old keys as inactive
+    const oldKeys = await this.keyResource.query({ active: true });
+    for (const oldKey of oldKeys) {
+      await this.keyResource.update(oldKey.id, { active: false });
+    }
+
+    // Store new key
+    const keyRecord = await this.keyResource.insert({
+      kid: keyPair.kid,
+      publicKey: keyPair.publicKey,
+      privateKey: keyPair.privateKey,
+      algorithm: keyPair.algorithm,
+      use: keyPair.use,
+      active: true,
+      createdAt: keyPair.createdAt
+    });
+
+    this.currentKey = keyRecord;
+    this.keys.set(keyRecord.kid, keyRecord);
+
+    return keyRecord;
+  }
+
+  /**
+   * Get current active key
+   */
+  getCurrentKey() {
+    return this.currentKey;
+  }
+
+  /**
+   * Get key by kid
+   */
+  getKey(kid) {
+    return this.keys.get(kid);
+  }
+
+  /**
+   * Get all public keys in JWKS format
+   */
+  async getJWKS() {
+    const keys = Array.from(this.keys.values()).map(key => ({
+      kty: 'RSA',
+      use: 'sig',
+      alg: 'RS256',
+      kid: key.kid,
+      ...pemToJwk(key.publicKey, key.kid)
+    }));
+
+    return { keys };
+  }
+
+  /**
+   * Create JWT with current active key
+   */
+  createToken(payload, expiresIn = '15m') {
+    if (!this.currentKey) {
+      throw new Error('No active key available');
+    }
+
+    return createRS256Token(
+      payload,
+      this.currentKey.privateKey,
+      this.currentKey.kid,
+      expiresIn
+    );
+  }
+
+  /**
+   * Verify JWT token
+   */
+  async verifyToken(token) {
+    const kid = getKidFromToken(token);
+
+    if (!kid) {
+      return null;
+    }
+
+    const key = this.getKey(kid);
+
+    if (!key) {
+      return null;
+    }
+
+    return verifyRS256Token(token, key.publicKey);
+  }
+}
+
+export default {
+  generateKeyPair,
+  pemToJwk,
+  createRS256Token,
+  verifyRS256Token,
+  getKidFromToken,
+  KeyManager
+};