@heavybit/pendoadmin-shared-lib 1.6.0 → 1.8.0

package/src/express/auth.middleware.ts

@@ -1,5 +1,6 @@
 import type { Request, Response, NextFunction } from 'express';
 import { verifyToken, extractBearerToken } from '../common/jwt.utils.js';
+import { isTrustedGatewayIdentity, isDirectJwtFallbackAllowed } from '../common/gateway-signature.js';
 import { GATEWAY_HEADERS, type IAuthUser } from '../types/index.js';
 
 /** Parse a header value that may be a JSON array string or comma-separated. */
@@ -21,83 +22,64 @@ declare global {
   }
 }
 
+/** The caller from signed gateway headers, or null when absent or unsigned/forged. */
+function userFromGatewayHeaders(req: Request): IAuthUser | null {
+  const userId = req.headers[GATEWAY_HEADERS.USER_ID] as string;
+  if (!userId || !isTrustedGatewayIdentity(req.headers)) return null;
+  return {
+    id: userId,
+    email: req.headers[GATEWAY_HEADERS.USER_EMAIL] as string || '',
+    companyId: req.headers[GATEWAY_HEADERS.COMPANY_ID] as string || '',
+    roles: parseArrayHeader(req.headers[GATEWAY_HEADERS.USER_ROLES] as string),
+    permissions: parseArrayHeader(req.headers[GATEWAY_HEADERS.USER_PERMISSIONS] as string),
+    isSuperAdmin: req.headers[GATEWAY_HEADERS.IS_SUPERADMIN] === 'true',
+  };
+}
+
+/** The caller from a bearer JWT — development only (direct service access). */
+function userFromBearerToken(req: Request, jwtSecret?: string): IAuthUser | null {
+  if (!jwtSecret || !isDirectJwtFallbackAllowed()) return null;
+  const token = extractBearerToken(req.headers.authorization);
+  if (!token) return null;
+  try {
+    const payload = verifyToken(token, jwtSecret);
+    return {
+      id: payload.sub,
+      email: payload.email,
+      companyId: payload.companyId,
+      roles: payload.roles || [],
+      permissions: payload.permissions || [],
+      isSuperAdmin: payload.isSuperAdmin || false,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Auth middleware for downstream services (behind API gateway).
- * Reads user context from gateway-injected headers.
- * Falls back to JWT validation if headers are missing (direct access).
+ * Reads user context from gateway-injected headers, trusted only with a valid
+ * gateway signature (GATEWAY_SIGNING_SECRET). Outside production it falls back
+ * to direct JWT validation for local development.
  */
 export function authenticateFromGateway(jwtSecret?: string) {
-  return (req: Request, _res: Response, next: NextFunction): void => {
-    // Method 1: Read gateway-injected headers
-    const userId = req.headers[GATEWAY_HEADERS.USER_ID] as string;
-    if (userId) {
-      req.user = {
-        id: userId,
-        email: req.headers[GATEWAY_HEADERS.USER_EMAIL] as string || '',
-        companyId: req.headers[GATEWAY_HEADERS.COMPANY_ID] as string || '',
-        roles: parseArrayHeader(req.headers[GATEWAY_HEADERS.USER_ROLES] as string),
-        permissions: parseArrayHeader(req.headers[GATEWAY_HEADERS.USER_PERMISSIONS] as string),
-        isSuperAdmin: req.headers[GATEWAY_HEADERS.IS_SUPERADMIN] === 'true',
-      };
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const user = userFromGatewayHeaders(req) ?? userFromBearerToken(req, jwtSecret);
+    if (user) {
+      req.user = user;
       return next();
     }
-
-    // Method 2: Direct JWT validation (for development / direct access)
-    if (jwtSecret) {
-      const token = extractBearerToken(req.headers.authorization);
-      if (token) {
-        try {
-          const payload = verifyToken(token, jwtSecret);
-          req.user = {
-            id: payload.sub,
-            email: payload.email,
-            companyId: payload.companyId,
-            roles: payload.roles || [],
-            permissions: payload.permissions || [],
-            isSuperAdmin: payload.isSuperAdmin || false,
-          };
-          return next();
-        } catch {
-          // Fall through to 401
-        }
-      }
-    }
-
-    _res.status(401).json({ success: false, message: 'Authentication required' });
+    res.status(401).json({ success: false, message: 'Authentication required' });
   };
 }
 
 /**
- * Optional auth — attaches user if present, continues if not.
+ * Optional auth — attaches user if present (and trusted), continues if not.
  */
 export function optionalAuthFromGateway(jwtSecret?: string) {
   return (req: Request, _res: Response, next: NextFunction): void => {
-    const userId = req.headers[GATEWAY_HEADERS.USER_ID] as string;
-    if (userId) {
-      req.user = {
-        id: userId,
-        email: req.headers[GATEWAY_HEADERS.USER_EMAIL] as string || '',
-        companyId: req.headers[GATEWAY_HEADERS.COMPANY_ID] as string || '',
-        roles: parseArrayHeader(req.headers[GATEWAY_HEADERS.USER_ROLES] as string),
-        permissions: parseArrayHeader(req.headers[GATEWAY_HEADERS.USER_PERMISSIONS] as string),
-        isSuperAdmin: req.headers[GATEWAY_HEADERS.IS_SUPERADMIN] === 'true',
-      };
-    } else if (jwtSecret) {
-      const token = extractBearerToken(req.headers.authorization);
-      if (token) {
-        try {
-          const payload = verifyToken(token, jwtSecret);
-          req.user = {
-            id: payload.sub,
-            email: payload.email,
-            companyId: payload.companyId,
-            roles: payload.roles || [],
-            permissions: payload.permissions || [],
-            isSuperAdmin: payload.isSuperAdmin || false,
-          };
-        } catch { /* ignore */ }
-      }
-    }
+    const user = userFromGatewayHeaders(req) ?? userFromBearerToken(req, jwtSecret);
+    if (user) req.user = user;
     next();
   };
 }

package/src/index.ts

@@ -27,5 +27,8 @@ export * from './express/index.js';
 // Rate limiting
 export * from './rate-limit/index.js';
 
+// Redis key namespace (G5)
+export * from './redis/index.js';
+
 // Scheduling
 export * from './scheduling/index.js';

package/src/logging/index.ts

@@ -2,6 +2,9 @@ import winston from 'winston';
 import DailyRotateFile from 'winston-daily-rotate-file';
 import { mkdirSync } from 'fs';
 import { resolve } from 'path';
+import { redactFormat } from './redact.js';
+
+export { redactFormat, redactSensitive, isSensitiveKey, REDACTED } from './redact.js';
 
 const { combine, timestamp, json, errors, colorize, printf, splat } = winston.format;
 
@@ -118,7 +121,8 @@ export function createLogger(service: string, level?: string): winston.Logger {
   return winston.createLogger({
     level: resolvedLevel,
     defaultMeta: { service },
-    format: combine(errors({ stack: true }), splat(), timestamp()),
+    // redactFormat runs after splat so metadata passed as extra arguments is covered too.
+    format: combine(errors({ stack: true }), splat(), redactFormat(), timestamp()),
     transports,
   });
 }
@@ -137,7 +141,7 @@ export function createAuditLogger(service: string): winston.Logger {
   return winston.createLogger({
     level: 'info',
     defaultMeta: { service, type: 'audit' },
-    format: combine(splat(), timestamp(), json()),
+    format: combine(splat(), redactFormat(), timestamp(), json()),
     transports,
   });
 }

package/src/logging/redact.ts

@@ -0,0 +1,84 @@
+import winston from 'winston';
+
+export const REDACTED = '[REDACTED]';
+
+// Exact keys (compared lower-cased, with '-' and '_' removed) and key fragments
+// whose values must never reach a log: credentials, tokens, OTPs, secrets.
+const EXACT_KEYS = new Set([
+  'authorization',
+  'proxyauthorization',
+  'cookie',
+  'setcookie',
+  'password',
+  'passwd',
+  'currentpassword',
+  'newpassword',
+  'apikey',
+  'otp',
+  'pin',
+  'smtppassword',
+  'encryptionkey',
+  'privatekey',
+  'xinternalservicesecret',
+  'xgatewaysignature',
+]);
+const KEY_FRAGMENTS = ['secret', 'password', 'passphrase', 'credential'];
+// accessToken, refresh_token, captchaToken… but not counters like promptTokens.
+const KEY_SUFFIXES = ['token'];
+
+const MAX_DEPTH = 8;
+
+/** True for keys whose values are redacted (case/separator-insensitive). */
+export function isSensitiveKey(key: string): boolean {
+  const normalized = key.toLowerCase().replace(/[-_]/g, '');
+  return EXACT_KEYS.has(normalized)
+    || KEY_FRAGMENTS.some((fragment) => normalized.includes(fragment))
+    || KEY_SUFFIXES.some((suffix) => normalized.endsWith(suffix));
+}
+
+// Bearer/Basic credentials embedded in free text (e.g. a logged header line or error message).
+const INLINE_CREDENTIAL = /\b(Bearer|Basic)\s+[A-Za-z0-9\-._~+/]+=*/g;
+
+function redactString(value: string): string {
+  return value.replace(INLINE_CREDENTIAL, `$1 ${REDACTED}`);
+}
+
+/**
+ * Deep copy of `value` with sensitive keys replaced by [REDACTED] and inline
+ * bearer/basic credentials masked. Errors keep their message and stack.
+ * Handles cycles and caps depth.
+ */
+export function redactSensitive(value: unknown, depth = 0, seen: WeakSet<object> = new WeakSet()): unknown {
+  if (typeof value === 'string') return redactString(value);
+  if (value === null || typeof value !== 'object') return value;
+  if (depth >= MAX_DEPTH) return '[Truncated]';
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+
+  if (Array.isArray(value)) return value.map((item) => redactSensitive(item, depth + 1, seen));
+  if (value instanceof Date || Buffer.isBuffer(value)) return value;
+
+  const source = value as Record<string, unknown>;
+  const result: Record<string, unknown> = {};
+  if (value instanceof Error) {
+    result.name = value.name;
+    result.message = redactString(value.message);
+    if (value.stack) result.stack = redactString(value.stack);
+  }
+  for (const key of Object.keys(source)) {
+    result[key] = isSensitiveKey(key) ? REDACTED : redactSensitive(source[key], depth + 1, seen);
+  }
+  return result;
+}
+
+/**
+ * Winston format that redacts every log entry's message and metadata in place.
+ * Winston's internal Symbol keys (level/message/splat) are left untouched.
+ */
+export const redactFormat = winston.format((info) => {
+  for (const key of Object.keys(info)) {
+    if (key === 'level') continue;
+    info[key] = isSensitiveKey(key) ? REDACTED : redactSensitive(info[key]);
+  }
+  return info;
+});

package/src/nestjs/auth.guard.ts

@@ -6,6 +6,7 @@ import {
 } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { verifyToken } from '../common/jwt.utils.js';
+import { isTrustedGatewayIdentity, isDirectJwtFallbackAllowed } from '../common/gateway-signature.js';
 import { GATEWAY_HEADERS, type IAuthUser } from '../types/index.js';
 
 /** Parse a header value that may be a JSON array string or comma-separated. */
@@ -20,6 +21,9 @@ function parseArrayHeader(value: string | undefined): string[] {
 
 export const IS_PUBLIC_KEY = 'isPublic';
 
+/** Request property AuthGuard sets when the caller came from signed gateway headers. */
+export const GATEWAY_VERIFIED_FLAG = 'gatewayVerified';
+
 /**
  * NestJS Guard: validates JWT or trusts gateway-injected headers.
  */
@@ -36,9 +40,10 @@ export class AuthGuard implements CanActivate {
 
     const request = context.switchToHttp().getRequest();
 
-    // Trust gateway-injected headers first
+    // Trust gateway-injected headers only with a valid gateway signature
     const gatewayUserId = request.headers[GATEWAY_HEADERS.USER_ID];
-    if (gatewayUserId) {
+    if (gatewayUserId && isTrustedGatewayIdentity(request.headers)) {
+      request[GATEWAY_VERIFIED_FLAG] = true;
       request.user = {
         id: gatewayUserId,
         companyId: request.headers[GATEWAY_HEADERS.COMPANY_ID] || undefined,
@@ -51,7 +56,11 @@ export class AuthGuard implements CanActivate {
       return true;
     }
 
-    // Fallback to direct JWT validation
+    // Fallback to direct JWT validation — development only; production
+    // requests must arrive through the gateway.
+    if (!isDirectJwtFallbackAllowed()) {
+      throw new UnauthorizedException('Authentication required');
+    }
     const authHeader = request.headers.authorization;
     if (!authHeader?.startsWith('Bearer ')) {
       throw new UnauthorizedException('Missing authentication token');

package/src/nestjs/permission.guard.ts

@@ -10,7 +10,7 @@ import {
   REQUIRE_ALL_KEY,
   ROLES_KEY,
 } from './permission.decorator.js';
-import { IS_PUBLIC_KEY } from './auth.guard.js';
+import { IS_PUBLIC_KEY, GATEWAY_VERIFIED_FLAG } from './auth.guard.js';
 import type { IAuthUser } from '../types/index.js';
 
 /**
@@ -40,10 +40,10 @@ export class PermissionGuard implements CanActivate {
     if (user.isSuperAdmin) return true;
 
     // M2M / gateway-authenticated clients: the gateway already verified the JWT
-    // and injected headers. Requiring human roles on top of scoped permissions
-    // is overly restrictive for API access.
-    const isGatewayAuth =
-      request.headers?.['x-gateway-auth'] === 'verified';
+    // and signed the injected headers (AuthGuard checked the signature).
+    // Requiring human roles on top of scoped permissions is overly restrictive
+    // for API access.
+    const isGatewayAuth = request[GATEWAY_VERIFIED_FLAG] === true;
 
     // Check permissions first — they are the primary authorization mechanism
     const requiredPermissions = this.reflector.getAllAndOverride<string[]>(

package/src/rate-limit/create-rate-limiter.ts

@@ -6,6 +6,8 @@
 import { Request, Response, NextFunction } from "express";
 import { RateLimiterRedis, RateLimiterMemory, RateLimiterAbstract } from "rate-limiter-flexible";
 import type Redis from "ioredis";
+import { isTrustedGatewayIdentity } from "../common/gateway-signature.js";
+import type { RedisKeyspace } from "../redis/keyspace.js";
 
 // ─── Types ──────────────────────────────────────────────
 
@@ -14,11 +16,17 @@ export interface RateLimitConfig {
   maxRequests?: number;
   /** Window duration in milliseconds (default: 60 000) */
   windowMs?: number;
-  /** Redis key prefix — use unique per service to avoid collisions (default: "rl:service") */
+  /**
+   * Service keyspace (G5). With it, keys are `{app}:{env}:{service}:rl:{keyPrefix}:…`
+   * and `keyPrefix` is only the limiter name. Required with a Redis client
+   * in NODE_ENV production/staging.
+   */
+  keyspace?: RedisKeyspace;
+  /** Limiter name with a keyspace; the raw Redis key prefix without one (default: "rl:service") */
   keyPrefix?: string;
   /** Optional Redis client — falls back to in-memory if omitted */
   redisClient?: Redis | null;
-  /** Extract the rate-limit key from the request. Default: X-User-Id header → IP → "unknown" */
+  /** Extract the rate-limit key from the request. Default: signed gateway user id → IP → "unknown" */
   keyExtractor?: (req: Request) => string;
 }
 
@@ -35,10 +43,11 @@ export function createRateLimiter(cfg: RateLimitConfig = {}): RateLimitResult {
   const {
     maxRequests = 100,
     windowMs = 60_000,
-    keyPrefix = "rl:service",
+    keyspace,
     redisClient = null,
     keyExtractor = defaultKeyExtractor,
   } = cfg;
+  const keyPrefix = resolveLimiterKeyPrefix(cfg.keyPrefix, keyspace, Boolean(redisClient));
 
   const durationSecs = Math.max(1, Math.round(windowMs / 1000));
 
@@ -100,8 +109,38 @@ export function createRateLimiter(cfg: RateLimitConfig = {}): RateLimitResult {
   return { limiter, middleware };
 }
 
+// ─── Key prefix ─────────────────────────────────────────
+
+const DEPLOYED_NODE_ENVS = new Set(["production", "staging"]);
+
+/**
+ * With a keyspace: `{prefix}rl:{name}`. Without one the legacy raw prefix is
+ * kept for in-memory or local use only — staging and production share Redis
+ * with each other and with other apps, so unscoped Redis keys are refused there.
+ */
+export function resolveLimiterKeyPrefix(
+  keyPrefix: string | undefined,
+  keyspace: RedisKeyspace | undefined,
+  usesRedis: boolean,
+): string {
+  if (keyspace) return keyspace.key("rl", keyPrefix || "default");
+  if (usesRedis && DEPLOYED_NODE_ENVS.has(process.env.NODE_ENV ?? "")) {
+    throw new Error("createRateLimiter: a keyspace is required for Redis-backed limiters in production/staging");
+  }
+  return keyPrefix || "rl:service";
+}
+
 // ─── Defaults ───────────────────────────────────────────
 
-function defaultKeyExtractor(req: Request): string {
-  return (req.headers["x-user-id"] as string) || req.ip || "unknown";
+/**
+ * The gateway user id only when its signature verifies — an unsigned
+ * x-user-id is caller-controlled, and a fresh value per request would get a
+ * fresh budget. Otherwise the client IP.
+ */
+export function defaultKeyExtractor(req: Request): string {
+  const userId = req.headers["x-user-id"];
+  if (typeof userId === "string" && userId && isTrustedGatewayIdentity(req.headers)) {
+    return `user:${userId}`;
+  }
+  return `ip:${req.ip || "unknown"}`;
 }

package/src/rate-limit/index.ts

@@ -1,2 +1,2 @@
-export { createRateLimiter } from "./create-rate-limiter.js";
+export { createRateLimiter, defaultKeyExtractor, resolveLimiterKeyPrefix } from "./create-rate-limiter.js";
 export type { RateLimitConfig, RateLimitResult } from "./create-rate-limiter.js";

package/src/redis/index.ts

@@ -0,0 +1,10 @@
+export {
+  createRedisKeyspace,
+  resolveRedisKeyApp,
+  resolveRedisKeyEnv,
+  encodeRedisKeyPart,
+  hashRedisKeyPart,
+  DEFAULT_REDIS_KEY_APP,
+  DEFAULT_REDIS_KEY_ENV,
+} from "./keyspace.js";
+export type { RedisKeyspace, RedisKeyspaceOptions, RedisKeyPart } from "./keyspace.js";

package/src/redis/keyspace.ts

@@ -0,0 +1,127 @@
+// pendoadmin-shared-lib/src/redis/keyspace.ts
+//
+// One Redis installation is shared by other applications and by PendoAdmin
+// staging and production, so every PendoAdmin key is namespaced by app,
+// environment and owning service:
+//
+//   {app}:{env}:{service}:{purpose}[:{part}...]
+//   e.g. pendoadmin:prod:api-gateway:authz:018ea4b0-…
+//
+// Build every key and SCAN pattern through createRedisKeyspace(); never
+// hand-write prefixes (tracker decisions G5 / D39).
+
+import { createHash } from "node:crypto";
+
+// ─── Types ──────────────────────────────────────────────
+
+export type RedisKeyPart = string | number;
+
+export interface RedisKeyspaceOptions {
+  /** Canonical owning service name (the service that writes the key), e.g. "api-gateway", "sms". */
+  service: string;
+  /** Defaults to REDIS_KEY_APP, then "pendoadmin". */
+  app?: string;
+  /** Defaults to resolveRedisKeyEnv(). */
+  env?: string;
+}
+
+export interface RedisKeyspace {
+  readonly app: string;
+  readonly env: string;
+  readonly service: string;
+  /** `{app}:{env}:{service}:` — every key and pattern starts with this. */
+  readonly prefix: string;
+  /**
+   * The prefix without its trailing ':' — pass as `environment` to
+   * @heavybit/cache-package so its `${environment}|k:v` keys are anchored too.
+   */
+  readonly cacheEnvironment: string;
+  /** `{prefix}{purpose}[:{part}...]`, each part encoded so it can't fake extra segments. */
+  key(purpose: string, ...parts: RedisKeyPart[]): string;
+  /** SCAN pattern anchored on the prefix: `{prefix}{purpose}:{suffix}` (suffix defaults to "*"). */
+  pattern(purpose: string, suffix?: string): string;
+}
+
+type EnvSource = Record<string, string | undefined>;
+
+// ─── Constants ──────────────────────────────────────────
+
+export const DEFAULT_REDIS_KEY_APP = "pendoadmin";
+export const DEFAULT_REDIS_KEY_ENV = "dev";
+
+/** NODE_ENV values that must name their key environment explicitly. */
+const DEPLOYED_NODE_ENVS = new Set(["production", "staging"]);
+
+const SEGMENT_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+// ─── Segment resolution ─────────────────────────────────
+
+function assertSegment(kind: string, value: string): string {
+  if (!SEGMENT_RE.test(value)) {
+    throw new Error(`Redis keyspace: invalid ${kind} "${value}" (lower-case kebab-case [a-z0-9-] only)`);
+  }
+  return value;
+}
+
+export function resolveRedisKeyApp(source: EnvSource = process.env): string {
+  return assertSegment("app", source.REDIS_KEY_APP?.trim() || DEFAULT_REDIS_KEY_APP);
+}
+
+/**
+ * REDIS_KEY_ENV, else CACHE_KEY_PREFIX ("prod" / "staging" in compose), else
+ * "dev". Throws in NODE_ENV production/staging when neither is set, so a
+ * deployed service can never write unscoped or "dev" keys.
+ */
+export function resolveRedisKeyEnv(source: EnvSource = process.env): string {
+  const explicit = source.REDIS_KEY_ENV?.trim() || source.CACHE_KEY_PREFIX?.trim();
+  if (explicit) return assertSegment("env", explicit);
+
+  const nodeEnv = source.NODE_ENV?.trim() ?? "";
+  if (DEPLOYED_NODE_ENVS.has(nodeEnv)) {
+    throw new Error(`Redis keyspace: REDIS_KEY_ENV or CACHE_KEY_PREFIX must be set when NODE_ENV=${nodeEnv}`);
+  }
+  return DEFAULT_REDIS_KEY_ENV;
+}
+
+// ─── Part encoding ──────────────────────────────────────
+
+/**
+ * Percent-encodes a variable key part. Beyond encodeURIComponent this also
+ * encodes the glob characters SCAN patterns interpret, so a part can never
+ * add segments or widen a pattern.
+ */
+export function encodeRedisKeyPart(part: RedisKeyPart): string {
+  const value = String(part);
+  if (!value) throw new Error("Redis keyspace: key parts must not be empty");
+  return encodeURIComponent(value).replace(/[*?[\]!'()]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+
+/** sha256 hex of a long or sensitive part (URLs, tokens). Never put a raw token in a key. */
+export function hashRedisKeyPart(value: string): string {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+// ─── Factory ────────────────────────────────────────────
+
+export function createRedisKeyspace(options: RedisKeyspaceOptions): RedisKeyspace {
+  const app = options.app !== undefined ? assertSegment("app", options.app) : resolveRedisKeyApp();
+  const env = options.env !== undefined ? assertSegment("env", options.env) : resolveRedisKeyEnv();
+  const service = assertSegment("service", options.service);
+  const cacheEnvironment = `${app}:${env}:${service}`;
+  const prefix = `${cacheEnvironment}:`;
+
+  return {
+    app,
+    env,
+    service,
+    prefix,
+    cacheEnvironment,
+    key(purpose, ...parts) {
+      const head = `${prefix}${assertSegment("purpose", purpose)}`;
+      return parts.length ? `${head}:${parts.map(encodeRedisKeyPart).join(":")}` : head;
+    },
+    pattern(purpose, suffix = "*") {
+      return `${prefix}${assertSegment("purpose", purpose)}:${suffix}`;
+    },
+  };
+}

package/src/types/index.ts

@@ -283,4 +283,6 @@ export const GATEWAY_HEADERS = {
   IS_SUPERADMIN: 'x-is-superadmin',
   CORRELATION_ID: 'x-correlation-id',
   SERVICE_NAME: 'x-service-name',
+  GATEWAY_SIGNATURE: 'x-gateway-signature',
+  GATEWAY_TIMESTAMP: 'x-gateway-ts',
 } as const;

package/tests/auth-middleware.test.mjs

@@ -0,0 +1,91 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { authenticateFromGateway, optionalAuthFromGateway } from '../dist/express/index.js';
+import { signGatewayIdentity, signAccessToken } from '../dist/common/index.js';
+
+const SECRET = 'gateway-secret';
+const JWT_SECRET = 'jwt-secret';
+const identity = {
+  'x-user-id': 'user-1',
+  'x-company-id': 'comp-1',
+  'x-user-roles': '["admin"]',
+  'x-user-permissions': '["users:list"]',
+  'x-is-superadmin': 'false',
+};
+
+function run(middleware, headers) {
+  const req = { headers };
+  const res = { statusCode: 0, body: null, status(c) { this.statusCode = c; return this; }, json(b) { this.body = b; return this; } };
+  let nextCalled = false;
+  middleware(req, res, () => { nextCalled = true; });
+  return { req, res, nextCalled };
+}
+
+describe('authenticateFromGateway', () => {
+  const saved = { secret: process.env.GATEWAY_SIGNING_SECRET, env: process.env.NODE_ENV };
+  beforeEach(() => { process.env.GATEWAY_SIGNING_SECRET = SECRET; process.env.NODE_ENV = 'production'; });
+  afterEach(() => {
+    if (saved.secret === undefined) delete process.env.GATEWAY_SIGNING_SECRET; else process.env.GATEWAY_SIGNING_SECRET = saved.secret;
+    if (saved.env === undefined) delete process.env.NODE_ENV; else process.env.NODE_ENV = saved.env;
+  });
+
+  test('accepts signed gateway headers and populates req.user', () => {
+    const headers = { ...identity, ...signGatewayIdentity(identity, SECRET) };
+    const { req, nextCalled } = run(authenticateFromGateway(JWT_SECRET), headers);
+    assert.equal(nextCalled, true);
+    assert.equal(req.user.id, 'user-1');
+    assert.equal(req.user.companyId, 'comp-1');
+    assert.deepEqual(req.user.permissions, ['users:list']);
+  });
+
+  test('rejects forged (unsigned) headers with 401', () => {
+    const { res, nextCalled } = run(authenticateFromGateway(JWT_SECRET), { ...identity, 'x-is-superadmin': 'true', 'x-gateway-auth': 'verified' });
+    assert.equal(nextCalled, false);
+    assert.equal(res.statusCode, 401);
+  });
+
+  test('rejects a signed request whose headers were altered afterwards', () => {
+    const headers = { ...identity, ...signGatewayIdentity(identity, SECRET), 'x-is-superadmin': 'true' };
+    const { res } = run(authenticateFromGateway(JWT_SECRET), headers);
+    assert.equal(res.statusCode, 401);
+  });
+
+  test('rejects an expired signature', () => {
+    const headers = { ...identity, ...signGatewayIdentity(identity, SECRET, Date.now() - 5 * 60_000) };
+    const { res } = run(authenticateFromGateway(JWT_SECRET), headers);
+    assert.equal(res.statusCode, 401);
+  });
+
+  test('ignores the direct-JWT fallback in production', () => {
+    const token = signAccessToken({ sub: 'user-1', email: 'a@b.c', roles: [], permissions: [] }, JWT_SECRET);
+    const { res } = run(authenticateFromGateway(JWT_SECRET), { authorization: `Bearer ${token}` });
+    assert.equal(res.statusCode, 401);
+  });
+
+  test('allows the direct-JWT fallback outside production', () => {
+    process.env.NODE_ENV = 'development';
+    const token = signAccessToken({ sub: 'user-9', email: 'a@b.c', roles: [], permissions: [] }, JWT_SECRET);
+    const { req, nextCalled } = run(authenticateFromGateway(JWT_SECRET), { authorization: `Bearer ${token}` });
+    assert.equal(nextCalled, true);
+    assert.equal(req.user.id, 'user-9');
+  });
+
+  test('production without a signing secret fails closed', () => {
+    delete process.env.GATEWAY_SIGNING_SECRET;
+    const { res } = run(authenticateFromGateway(JWT_SECRET), identity);
+    assert.equal(res.statusCode, 401);
+  });
+});
+
+describe('optionalAuthFromGateway', () => {
+  test('leaves forged headers anonymous', () => {
+    process.env.GATEWAY_SIGNING_SECRET = SECRET;
+    try {
+      const { req, nextCalled } = run(optionalAuthFromGateway(), { ...identity });
+      assert.equal(nextCalled, true);
+      assert.equal(req.user, undefined);
+    } finally {
+      delete process.env.GATEWAY_SIGNING_SECRET;
+    }
+  });
+});