@roboteby/parry 1.1.0-rc.1

package/src/admin/auth/admin-auth.js

@@ -0,0 +1,176 @@
+'use strict';
+
+const { unauthorized, forbidden } = require('../response');
+const { authenticateToken } = require('./strategies/token');
+const { authenticateIpAllowlist } = require('./strategies/ip-allowlist');
+const { authenticateTrustedProxy } = require('./strategies/trusted-proxy');
+const { authenticateCombined } = require('./strategies/combined');
+const { authenticateNone } = require('./strategies/none');
+const { authenticateCloudflareAccess } = require('./strategies/cloudflare-access');
+const { authenticateAlbAuth } = require('./strategies/alb-auth');
+
+function requireAdminAuth(options = {}, context = null) {
+  if (typeof options.auth === 'function') return createLegacyCallbackMiddleware(options.auth);
+
+  if (options.requireAuth && !options.auth) {
+    return function missingAuthMiddleware(_req, res) {
+      return unauthorized(res);
+    };
+  }
+
+  const contextAuth = context?.config?.admin?.auth;
+  const authConfig = isAuthConfig(options.auth) ? options.auth : contextAuth;
+  if (!authConfig) return (_req, _res, next) => next();
+
+  return createAdminAuthMiddleware(authConfig, {
+    ...context,
+    admin: context?.config?.admin,
+  });
+}
+
+function createAdminAuthMiddleware(config, context = {}) {
+  validateAdminAuthConfig(config, context);
+
+  return function adminAuthMiddleware(req, res, next) {
+    return Promise.resolve(authenticateAdminRequest(req, config, context))
+      .then((result) => {
+        if (result.ok) {
+          req.parryAdmin = result.admin;
+          return next();
+        }
+
+        if (result.statusCode === 403) return forbidden(res);
+        return unauthorized(res);
+      })
+      .catch((error) => next(error));
+  };
+}
+
+async function authenticateAdminRequest(req, config, context = {}) {
+  const mode = normalizeMode(config?.mode);
+
+  if (mode === 'token') return authenticateToken(req, config, context);
+  if (mode === 'ip-allowlist') return authenticateIpAllowlist(req, config, context);
+  if (mode === 'trusted-proxy') return authenticateTrustedProxy(req, config, context);
+  if (mode === 'cloudflare-access') {
+    return authenticateCloudflareAccess(req, { ...config, mode }, context);
+  }
+  if (mode === 'alb-auth' || mode === 'cognito-alb') {
+    return authenticateAlbAuth(req, { ...config, mode }, context);
+  }
+  if (mode === 'combined') return authenticateCombined(req, config, context);
+  if (mode === 'none') return authenticateNone(req, config, context);
+
+  throw new Error(`Unsupported Admin API auth mode: ${mode}`);
+}
+
+function validateAdminAuthConfig(config, context = {}) {
+  const mode = normalizeMode(config?.mode);
+
+  if (mode === 'token' && !hasNonEmptyString(config.token)) {
+    throw new Error('Admin API token auth requires a non-empty token.');
+  }
+
+  if (mode === 'ip-allowlist' && !hasNonEmptyArray(config.allowedIps)) {
+    throw new Error('Admin API ip-allowlist auth requires allowedIps.');
+  }
+
+  if (mode === 'trusted-proxy' && !hasNonEmptyArray(config.trustedProxies)) {
+    throw new Error('Admin API trusted-proxy auth requires trustedProxies.');
+  }
+
+  if (mode === 'cloudflare-access' || mode === 'alb-auth' || mode === 'cognito-alb') {
+    validateExternalAuthConfig(mode, config);
+  }
+
+  if (mode === 'combined') {
+    const hasAllowAny = hasNonEmptyArray(config.allowAny);
+    const hasRequireAll = hasNonEmptyArray(config.requireAll);
+    if (hasAllowAny && hasRequireAll) {
+      throw new Error('Admin API combined auth accepts either allowAny or requireAll, not both.');
+    }
+    if (!hasAllowAny && !hasRequireAll) {
+      throw new Error('Admin API combined auth requires allowAny or requireAll.');
+    }
+    const children = hasAllowAny ? config.allowAny : config.requireAll;
+    for (const child of children) {
+      if (normalizeMode(child?.mode) === 'combined') {
+        throw new Error('Admin API combined auth cannot contain nested combined strategies.');
+      }
+      validateAdminAuthConfig(child, context);
+    }
+  }
+
+  if (
+    mode === 'none' &&
+    process.env.NODE_ENV === 'production' &&
+    !config.allowInsecureAdminApi &&
+    !context?.admin?.allowInsecureAdminApi
+  ) {
+    throw new Error('Admin API auth mode "none" is not allowed in production.');
+  }
+}
+
+function validateExternalAuthConfig(mode, config) {
+  if (config.verifyJwt === true) {
+    throw new Error(
+      `Admin API auth mode "${mode}" does not implement cryptographic JWT/JWKS verification in this version.`
+    );
+  }
+
+  const hasTrustedProxies = hasNonEmptyArray(config.trustedProxies);
+  const hasSharedSecret = hasNonEmptyString(config.proxySharedSecret);
+
+  if (!hasTrustedProxies && !hasSharedSecret) {
+    throw new Error(`Admin API auth mode "${mode}" requires trustedProxies or proxySharedSecret.`);
+  }
+}
+
+function createLegacyCallbackMiddleware(authCallback) {
+  return async function legacyAdminAuthMiddleware(req, res, next) {
+    try {
+      const allowed = await authCallback(req);
+      if (!allowed) return unauthorized(res);
+
+      req.parryAdmin = {
+        authenticated: true,
+        strategy: 'callback',
+        subject: 'callback',
+        email: null,
+        roles: [],
+        ip: req.ip || req.socket?.remoteAddress || 'unknown',
+      };
+      return next();
+    } catch (_error) {
+      return unauthorized(res);
+    }
+  };
+}
+
+function isAuthConfig(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeMode(mode) {
+  const normalized = String(mode || 'token')
+    .trim()
+    .toLowerCase();
+  if (normalized === 'alb-cognito') return 'cognito-alb';
+  return normalized;
+}
+
+function hasNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function hasNonEmptyArray(value) {
+  return Array.isArray(value) && value.length > 0;
+}
+
+module.exports = {
+  createAdminAuthMiddleware,
+  authenticateAdminRequest,
+  requireAdminAuth,
+  validateAdminAuthConfig,
+  normalizeMode,
+};

package/src/admin/auth/index.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const {
+  createAdminAuthMiddleware,
+  authenticateAdminRequest,
+  requireAdminAuth,
+} = require('./admin-auth');
+
+module.exports = {
+  createAdminAuthMiddleware,
+  authenticateAdminRequest,
+  requireAdminAuth,
+};

package/src/admin/auth/strategies/alb-auth.js

@@ -0,0 +1,49 @@
+'use strict';
+
+const { readHeader } = require('../utils/header-utils');
+const { success, unauthorized, forbidden } = require('../utils/result');
+const {
+  authenticateTrustedBoundary,
+  normalizeEmail,
+  normalizeSubject,
+  emailMatchesAllowlist,
+  subjectMatchesAllowlist,
+  hasEmailAllowlist,
+  decodeJwtClaimsUnsafe,
+  extractEmailFromClaims,
+} = require('../utils/external-identity');
+
+function authenticateAlbAuth(req, config) {
+  const boundary = authenticateTrustedBoundary(req, config);
+  if (!boundary.ok) return boundary;
+
+  const userHeader = config.userHeader || 'x-amzn-oidc-identity';
+  const dataHeader = config.dataHeader || 'x-amzn-oidc-data';
+  const subject = normalizeSubject(readHeader(req, userHeader));
+  if (!subject) return unauthorized();
+
+  if (!subjectMatchesAllowlist(subject, config.allowedSubjects)) return forbidden();
+
+  const claims = decodeJwtClaimsUnsafe(readHeader(req, dataHeader));
+  const email =
+    extractEmailFromClaims(claims) ||
+    normalizeEmail(readHeader(req, config.emailHeader || 'x-amzn-oidc-email'));
+
+  if (hasEmailAllowlist(config) && !emailMatchesAllowlist(email, config)) return forbidden();
+
+  const strategy = config.mode === 'cognito-alb' ? 'cognito-alb' : 'alb-auth';
+
+  return success(
+    req,
+    strategy,
+    {
+      subject,
+      email: email || null,
+      roles: [],
+      ip: boundary.ip,
+    },
+    config
+  );
+}
+
+module.exports = { authenticateAlbAuth };

package/src/admin/auth/strategies/cloudflare-access.js

@@ -0,0 +1,34 @@
+'use strict';
+
+const { readHeader } = require('../utils/header-utils');
+const { success, unauthorized, forbidden } = require('../utils/result');
+const {
+  authenticateTrustedBoundary,
+  normalizeEmail,
+  emailMatchesAllowlist,
+} = require('../utils/external-identity');
+
+function authenticateCloudflareAccess(req, config) {
+  const boundary = authenticateTrustedBoundary(req, config);
+  if (!boundary.ok) return boundary;
+
+  const emailHeader = config.emailHeader || 'cf-access-authenticated-user-email';
+  const email = normalizeEmail(readHeader(req, emailHeader));
+  if (!email) return unauthorized();
+
+  if (!emailMatchesAllowlist(email, config)) return forbidden();
+
+  return success(
+    req,
+    'cloudflare-access',
+    {
+      subject: email,
+      email,
+      roles: [],
+      ip: boundary.ip,
+    },
+    config
+  );
+}
+
+module.exports = { authenticateCloudflareAccess };

package/src/admin/auth/strategies/combined.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const { success } = require('../utils/result');
+
+async function authenticateCombined(req, config, context) {
+  const allowAny = Array.isArray(config.allowAny) ? config.allowAny : null;
+  const requireAll = Array.isArray(config.requireAll) ? config.requireAll : null;
+
+  if (allowAny) return authenticateAny(req, allowAny, context);
+  return authenticateAll(req, requireAll || [], context);
+}
+
+async function authenticateAny(req, strategies, context) {
+  let sawForbidden = false;
+  const { authenticateAdminRequest } = require('../admin-auth');
+
+  for (const strategyConfig of strategies) {
+    const result = await authenticateAdminRequest(req, strategyConfig, context);
+    if (result.ok) {
+      return success(req, 'combined', {
+        ...result.admin,
+        strategy: 'combined',
+        subject: result.admin.subject,
+      });
+    }
+    if (result.statusCode === 403) sawForbidden = true;
+  }
+
+  return sawForbidden ? { ok: false, statusCode: 403 } : { ok: false, statusCode: 401 };
+}
+
+async function authenticateAll(req, strategies, context) {
+  const { authenticateAdminRequest } = require('../admin-auth');
+  let lastAdmin = null;
+
+  for (const strategyConfig of strategies) {
+    const result = await authenticateAdminRequest(req, strategyConfig, context);
+    if (!result.ok) return result;
+    lastAdmin = result.admin;
+  }
+
+  return success(req, 'combined', {
+    ...lastAdmin,
+    strategy: 'combined',
+    subject: lastAdmin?.subject || 'combined',
+    roles: lastAdmin?.roles || [],
+  });
+}
+
+module.exports = { authenticateCombined };

package/src/admin/auth/strategies/ip-allowlist.js

@@ -0,0 +1,13 @@
+'use strict';
+
+const { getClientIp, isIpAllowed } = require('../../../express/ip-resolver');
+const { success, forbidden } = require('../utils/result');
+
+function authenticateIpAllowlist(req, config) {
+  const ip = getClientIp(req, config);
+  if (!isIpAllowed(ip, config.allowedIps)) return forbidden();
+
+  return success(req, 'ip-allowlist', { subject: `ip:${ip}`, ip }, config);
+}
+
+module.exports = { authenticateIpAllowlist };

package/src/admin/auth/strategies/none.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const { getClientIp } = require('../../../express/ip-resolver');
+const { success } = require('../utils/result');
+
+let warned = false;
+
+function authenticateNone(req, config) {
+  if (!warned) {
+    warned = true;
+    console.warn(
+      '[parry] Admin API auth mode "none" is insecure and intended only for local development.'
+    );
+  }
+
+  const ip = getClientIp(req, config);
+  return success(req, 'none', { subject: 'insecure-none', ip }, config);
+}
+
+module.exports = { authenticateNone };

package/src/admin/auth/strategies/token.js

@@ -0,0 +1,25 @@
+'use strict';
+
+const { getClientIp } = require('../../../express/ip-resolver');
+const { readHeader } = require('../utils/header-utils');
+const { safeCompare } = require('../utils/constant-time');
+const { success, unauthorized, forbidden } = require('../utils/result');
+
+function authenticateToken(req, config) {
+  const headerName = config.header || 'x-parry-admin-token';
+  const supplied = readHeader(req, headerName);
+  if (!supplied) return unauthorized();
+  if (!safeCompare(String(config.token), String(supplied))) return forbidden();
+
+  return success(
+    req,
+    'token',
+    {
+      subject: 'local-token',
+      ip: getClientIp(req, config),
+    },
+    config
+  );
+}
+
+module.exports = { authenticateToken };

package/src/admin/auth/strategies/trusted-proxy.js

@@ -0,0 +1,52 @@
+'use strict';
+
+const { getClientIp, getDirectIp, isTrustedProxy } = require('../../../express/ip-resolver');
+const { safeCompare } = require('../utils/constant-time');
+const {
+  readHeader,
+  hasHeader,
+  headerEquals,
+  sanitizeHeaderValue,
+  parseRoles,
+} = require('../utils/header-utils');
+const { success, unauthorized, forbidden } = require('../utils/result');
+
+function authenticateTrustedProxy(req, config) {
+  const directIp = getDirectIp(req);
+  if (!isTrustedProxy(directIp, config.trustedProxies || [])) return forbidden();
+
+  const requiredHeaders = config.requiredHeaders || {};
+  for (const [headerName, expectedValue] of Object.entries(requiredHeaders)) {
+    if (!hasHeader(req, headerName)) return unauthorized();
+    if (!headerEquals(req, headerName, expectedValue)) return forbidden();
+  }
+
+  if (config.proxySharedSecret) {
+    const headerName = config.proxySharedSecretHeader || 'x-parry-proxy-secret';
+    const supplied = readHeader(req, headerName);
+    if (!supplied) return unauthorized();
+    if (!safeCompare(String(config.proxySharedSecret), String(supplied))) return forbidden();
+  }
+
+  const user = sanitizeHeaderValue(readHeader(req, config.userHeader || 'x-parry-admin-user'));
+  const email = sanitizeHeaderValue(readHeader(req, config.emailHeader || 'x-parry-admin-email'));
+  const roles = parseRoles(readHeader(req, config.rolesHeader || 'x-parry-admin-roles'));
+  const clientIp = getClientIp(req, {
+    ...config,
+    trustProxyHeaders: true,
+  });
+
+  return success(
+    req,
+    'trusted-proxy',
+    {
+      subject: user ? `proxy:${user}` : email ? `proxy:${email}` : `proxy:${clientIp}`,
+      email: email || null,
+      roles,
+      ip: clientIp,
+    },
+    config
+  );
+}
+
+module.exports = { authenticateTrustedProxy };

package/src/admin/auth/utils/constant-time.js

@@ -0,0 +1,18 @@
+'use strict';
+
+const crypto = require('crypto');
+
+function safeCompare(expected, actual) {
+  if (typeof expected !== 'string' || typeof actual !== 'string') return false;
+  if (!expected || !actual) return false;
+
+  const expectedHash = hash(expected);
+  const actualHash = hash(actual);
+  return crypto.timingSafeEqual(expectedHash, actualHash);
+}
+
+function hash(value) {
+  return crypto.createHash('sha256').update(value, 'utf8').digest();
+}
+
+module.exports = { safeCompare };

package/src/admin/auth/utils/external-identity.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const { getClientIp, getDirectIp, isTrustedProxy } = require('../../../express/ip-resolver');
+const { safeCompare } = require('./constant-time');
+const { readHeader, sanitizeHeaderValue } = require('./header-utils');
+const { unauthorized, forbidden } = require('./result');
+
+function authenticateTrustedBoundary(req, config = {}) {
+  const trustedProxies = Array.isArray(config.trustedProxies) ? config.trustedProxies : [];
+  const hasTrustedProxyBoundary = trustedProxies.length > 0;
+  const hasSharedSecretBoundary = hasNonEmptyString(config.proxySharedSecret);
+
+  if (!hasTrustedProxyBoundary && !hasSharedSecretBoundary) return forbidden();
+
+  const directIp = getDirectIp(req);
+  const trustedProxyMatched = hasTrustedProxyBoundary && isTrustedProxy(directIp, trustedProxies);
+
+  if (trustedProxyMatched) {
+    const supplied = hasSharedSecretBoundary
+      ? readHeader(req, config.proxySharedSecretHeader || 'x-parry-proxy-secret')
+      : '';
+    if (supplied && !safeCompare(String(config.proxySharedSecret), String(supplied))) {
+      return forbidden();
+    }
+    return {
+      ok: true,
+      ip: getClientIp(req, {
+        ...config,
+        trustProxyHeaders: true,
+      }),
+    };
+  }
+
+  if (hasSharedSecretBoundary) {
+    const headerName = config.proxySharedSecretHeader || 'x-parry-proxy-secret';
+    const supplied = readHeader(req, headerName);
+    if (!supplied) return unauthorized();
+    if (!safeCompare(String(config.proxySharedSecret), String(supplied))) return forbidden();
+    return {
+      ok: true,
+      ip: getClientIp(req, {
+        ...config,
+        trustProxyHeaders: true,
+      }),
+    };
+  }
+
+  return forbidden();
+}
+
+function normalizeEmail(value) {
+  const email = sanitizeHeaderValue(value, 320).toLowerCase();
+  if (!email) return '';
+
+  const atIndex = email.indexOf('@');
+  if (atIndex <= 0 || atIndex !== email.lastIndexOf('@') || atIndex === email.length - 1) {
+    return '';
+  }
+
+  return email;
+}
+
+function normalizeSubject(value) {
+  return sanitizeHeaderValue(value, 256);
+}
+
+function normalizeList(values, options = {}) {
+  const lowercase = options.lowercase !== false;
+  const list = Array.isArray(values) ? values : [];
+  return list
+    .map((value) => sanitizeHeaderValue(value, 320))
+    .map((value) => (lowercase ? value.toLowerCase() : value))
+    .filter(Boolean);
+}
+
+function emailMatchesAllowlist(email, config = {}) {
+  const normalizedEmail = normalizeEmail(email);
+  const allowedEmails = normalizeList(config.allowedEmails);
+  const allowedDomains = normalizeList(config.allowedDomains).map((domain) =>
+    domain.startsWith('@') ? domain.slice(1) : domain
+  );
+  const hasEmailRules = allowedEmails.length > 0 || allowedDomains.length > 0;
+
+  if (!hasEmailRules) return true;
+  if (!normalizedEmail) return false;
+  if (allowedEmails.includes(normalizedEmail)) return true;
+
+  const domain = normalizedEmail.slice(normalizedEmail.indexOf('@') + 1);
+  return allowedDomains.includes(domain);
+}
+
+function subjectMatchesAllowlist(subject, allowedSubjects) {
+  const normalizedSubject = normalizeSubject(subject);
+  const allowed = normalizeList(allowedSubjects, { lowercase: false });
+  if (allowed.length === 0) return true;
+  if (!normalizedSubject) return false;
+  return allowed.includes(normalizedSubject);
+}
+
+function hasEmailAllowlist(config = {}) {
+  return (
+    (Array.isArray(config.allowedEmails) && config.allowedEmails.length > 0) ||
+    (Array.isArray(config.allowedDomains) && config.allowedDomains.length > 0)
+  );
+}
+
+function decodeJwtClaimsUnsafe(jwt) {
+  const raw = String(jwt || '').trim();
+  if (!raw || raw.length > 32_768) return null;
+
+  const parts = raw.split('.');
+  if (parts.length < 2) return null;
+
+  try {
+    const payload = base64UrlDecode(parts[1]);
+    if (payload.length > 16_384) return null;
+    const parsed = JSON.parse(payload);
+    return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+  } catch (_error) {
+    return null;
+  }
+}
+
+function extractEmailFromClaims(claims) {
+  if (!claims || typeof claims !== 'object') return '';
+
+  return (
+    normalizeEmail(claims.email) ||
+    normalizeEmail(claims.upn) ||
+    normalizeEmail(claims.preferred_username)
+  );
+}
+
+function base64UrlDecode(value) {
+  const normalized = String(value || '')
+    .replace(/-/g, '+')
+    .replace(/_/g, '/');
+  const padded = normalized.padEnd(normalized.length + ((4 - (normalized.length % 4)) % 4), '=');
+  return Buffer.from(padded, 'base64').toString('utf8');
+}
+
+function hasNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+module.exports = {
+  authenticateTrustedBoundary,
+  normalizeEmail,
+  normalizeSubject,
+  normalizeList,
+  emailMatchesAllowlist,
+  subjectMatchesAllowlist,
+  hasEmailAllowlist,
+  decodeJwtClaimsUnsafe,
+  extractEmailFromClaims,
+};

package/src/admin/auth/utils/header-utils.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { getHeader } = require('../../../express/ip-resolver');
+
+function readHeader(req, name) {
+  return getHeader(req.headers || {}, name);
+}
+
+function hasHeader(req, name) {
+  const value = readHeader(req, name);
+  return typeof value === 'string' && value.length > 0;
+}
+
+function headerEquals(req, name, expected) {
+  const actual = readHeader(req, name);
+  return String(actual || '') === String(expected || '');
+}
+
+function sanitizeHeaderValue(value, maxLength = 200) {
+  return String(value || '')
+    .replace(/[\r\n]/g, ' ')
+    .trim()
+    .slice(0, maxLength);
+}
+
+function parseRoles(value) {
+  return String(value || '')
+    .split(',')
+    .map((role) => sanitizeHeaderValue(role, 80))
+    .filter(Boolean);
+}
+
+module.exports = {
+  readHeader,
+  hasHeader,
+  headerEquals,
+  sanitizeHeaderValue,
+  parseRoles,
+};

package/src/admin/auth/utils/result.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const { getClientIp } = require('../../../express/ip-resolver');
+
+function success(req, strategy, details = {}, options = {}) {
+  const ip = details.ip || getClientIp(req, options);
+
+  return {
+    ok: true,
+    admin: {
+      authenticated: true,
+      strategy,
+      subject: details.subject || strategy,
+      email: details.email || null,
+      roles: Array.isArray(details.roles) ? details.roles : [],
+      ip,
+    },
+  };
+}
+
+function unauthorized() {
+  return {
+    ok: false,
+    statusCode: 401,
+    code: 'ADMIN_UNAUTHORIZED',
+    message: 'Admin API authentication required',
+  };
+}
+
+function forbidden() {
+  return {
+    ok: false,
+    statusCode: 403,
+    code: 'ADMIN_FORBIDDEN',
+    message: 'Admin API access denied',
+  };
+}
+
+module.exports = { success, unauthorized, forbidden };