@heavybit/pendoadmin-shared-lib 1.5.0 → 1.7.0

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,7 @@
 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";
 
 // ─── Types ──────────────────────────────────────────────
 
@@ -18,7 +19,7 @@ export interface RateLimitConfig {
   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;
 }
 
@@ -102,6 +103,15 @@ export function createRateLimiter(cfg: RateLimitConfig = {}): RateLimitResult {
 
 // ─── 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 } from "./create-rate-limiter.js";
 export type { RateLimitConfig, RateLimitResult } from "./create-rate-limiter.js";

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;
+    }
+  });
+});

package/tests/gateway-signature.test.mjs

@@ -0,0 +1,93 @@
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { signGatewayIdentity, verifyGatewayIdentity, isTrustedGatewayIdentity } from '../dist/common/index.js';
+
+// Shared with api-gateway/tests/utils/gateway-signature.test.ts: the gateway's
+// own signer must produce this exact signature.
+const VECTOR = {
+  secret: 'test-signing-secret',
+  nowMs: 1_790_000_000_000,
+  headers: {
+    'x-correlation-id': 'corr-1',
+    'x-user-id': 'user-1',
+    'x-user-email': 'alice@example.com',
+    'x-company-id': 'comp-1',
+    'x-company-slug': 'acme',
+    'x-user-roles': '["admin"]',
+    'x-user-permissions': '["users:list"]',
+    'x-is-superadmin': 'false',
+    'x-otp-verified': 'true',
+  },
+  signature: '681c8ff3354db858c618a257601cced23ed694f824db116eb200c724470fe55d',
+  timestamp: '1790000000',
+};
+
+const signed = (overrides = {}) => ({
+  ...VECTOR.headers,
+  'x-gateway-signature': VECTOR.signature,
+  'x-gateway-ts': VECTOR.timestamp,
+  ...overrides,
+});
+const verify = (headers, opts = {}) => verifyGatewayIdentity(headers, VECTOR.secret, { nowMs: VECTOR.nowMs, ...opts });
+
+describe('gateway signature', () => {
+  test('matches the api-gateway signer test vector', () => {
+    assert.deepEqual(signGatewayIdentity(VECTOR.headers, VECTOR.secret, VECTOR.nowMs), {
+      'x-gateway-signature': VECTOR.signature,
+      'x-gateway-ts': VECTOR.timestamp,
+    });
+  });
+
+  test('accepts a valid, fresh signature', () => {
+    assert.equal(verify(signed()), true);
+  });
+
+  test('rejects a missing or malformed signature', () => {
+    assert.equal(verify(VECTOR.headers), false);
+    assert.equal(verify(signed({ 'x-gateway-signature': 'nothex' })), false);
+    assert.equal(verify(signed({ 'x-gateway-ts': 'soon' })), false);
+  });
+
+  test('rejects tampered identity headers', () => {
+    assert.equal(verify(signed({ 'x-is-superadmin': 'true' })), false);
+    assert.equal(verify(signed({ 'x-company-id': 'other-company' })), false);
+    assert.equal(verify(signed({ 'x-user-permissions': '["*"]' })), false);
+  });
+
+  test('rejects a timestamp outside the ±60 s window', () => {
+    assert.equal(verify(signed(), { nowMs: VECTOR.nowMs + 61_000 }), false);
+    assert.equal(verify(signed(), { nowMs: VECTOR.nowMs - 61_000 }), false);
+    assert.equal(verify(signed(), { nowMs: VECTOR.nowMs + 59_000 }), true);
+  });
+
+  test('rejects a signature made with a different secret, or an empty secret', () => {
+    assert.equal(verifyGatewayIdentity(signed(), 'other-secret', { nowMs: VECTOR.nowMs }), false);
+    assert.equal(verifyGatewayIdentity(signed(), '', { nowMs: VECTOR.nowMs }), false);
+  });
+});
+
+describe('isTrustedGatewayIdentity', () => {
+  const saved = { secret: process.env.GATEWAY_SIGNING_SECRET, env: process.env.NODE_ENV };
+  beforeEach(() => { delete process.env.GATEWAY_SIGNING_SECRET; });
+  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('with a secret configured, requires a valid signature', () => {
+    process.env.GATEWAY_SIGNING_SECRET = VECTOR.secret;
+    const fresh = { ...VECTOR.headers, ...signGatewayIdentity(VECTOR.headers, VECTOR.secret) };
+    assert.equal(isTrustedGatewayIdentity(fresh), true);
+    assert.equal(isTrustedGatewayIdentity(VECTOR.headers), false);
+  });
+
+  test('without a secret, never trusts unsigned identity in production', () => {
+    process.env.NODE_ENV = 'production';
+    assert.equal(isTrustedGatewayIdentity(VECTOR.headers), false);
+  });
+
+  test('without a secret, trusts unsigned identity in local development', () => {
+    process.env.NODE_ENV = 'development';
+    assert.equal(isTrustedGatewayIdentity(VECTOR.headers), true);
+  });
+});

package/tests/nestjs-guards.test.mjs

@@ -0,0 +1,45 @@
+import 'reflect-metadata';
+import { test, describe, beforeEach, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { AuthGuard, PermissionGuard } from '../dist/nestjs/index.js';
+import { signGatewayIdentity } from '../dist/common/index.js';
+
+const SECRET = 'gateway-secret';
+const identity = { 'x-user-id': 'key-1', 'x-company-id': 'comp-1', 'x-user-roles': '["api-client"]', 'x-user-permissions': '["ussd.sessions:list"]', 'x-is-superadmin': 'false' };
+
+const reflector = (values = {}) => ({ getAllAndOverride: (key) => values[key] });
+const contextFor = (request) => ({
+  getHandler: () => null,
+  getClass: () => null,
+  switchToHttp: () => ({ getRequest: () => request }),
+});
+
+describe('NestJS AuthGuard + PermissionGuard', () => {
+  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('AuthGuard trusts signed gateway headers', async () => {
+    const request = { headers: { ...identity, ...signGatewayIdentity(identity, SECRET) } };
+    assert.equal(await new AuthGuard(reflector()).canActivate(contextFor(request)), true);
+    assert.equal(request.user.id, 'key-1');
+    assert.equal(request.gatewayVerified, true);
+  });
+
+  test('AuthGuard rejects forged superadmin headers', async () => {
+    const request = { headers: { ...identity, 'x-is-superadmin': 'true', 'x-gateway-auth': 'verified' } };
+    await assert.rejects(new AuthGuard(reflector()).canActivate(contextFor(request)), { status: 401 });
+    assert.equal(request.user, undefined);
+  });
+
+  test('PermissionGuard role bypass needs a verified signature, not the x-gateway-auth header', () => {
+    const guard = new PermissionGuard(reflector({ permissions: ['ussd.sessions:list'], roles: ['company_admin'] }));
+    const user = { id: 'key-1', roles: ['api-client'], permissions: ['ussd.sessions:list'], isSuperAdmin: false };
+
+    assert.throws(() => guard.canActivate(contextFor({ user, headers: { 'x-gateway-auth': 'verified' } })), { status: 403 });
+    assert.equal(guard.canActivate(contextFor({ user, headers: {}, gatewayVerified: true })), true);
+  });
+});

package/tests/permission.utils.test.mjs

@@ -0,0 +1,59 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { hasPermission, ALL_PERMISSIONS_SCOPE } from '../dist/common/index.js';
+import { requirePermission } from '../dist/express/index.js';
+
+const user = (permissions, isSuperAdmin = false) => ({ permissions, isSuperAdmin });
+
+describe('hasPermission', () => {
+  test('grants when any listed permission is held', () => {
+    assert.equal(hasPermission(user(['users:read']), 'users.security:read', 'users:read'), true);
+  });
+
+  test('denies when none of the permissions is held', () => {
+    assert.equal(hasPermission(user(['users:read']), 'users.security:read'), false);
+    assert.equal(hasPermission(user([]), 'users:read'), false);
+  });
+
+  test('super admins always pass', () => {
+    assert.equal(hasPermission(user([], true), 'anything'), true);
+  });
+
+  test("the '*' API-key scope grants every permission", () => {
+    assert.equal(ALL_PERMISSIONS_SCOPE, '*');
+    assert.equal(hasPermission(user(['*']), 'users.security:read'), true);
+  });
+
+  test('no user, or missing permissions array, is denied', () => {
+    assert.equal(hasPermission(null, 'users:read'), false);
+    assert.equal(hasPermission(undefined, 'users:read'), false);
+    assert.equal(hasPermission({ isSuperAdmin: false }, 'users:read'), false);
+  });
+
+  test('no permissions listed is denied for a normal user', () => {
+    assert.equal(hasPermission(user(['users:read'])), false);
+  });
+});
+
+describe('requirePermission uses the same rule', () => {
+  function run(reqUser, ...perms) {
+    const res = { code: 200, status(c) { this.code = c; return this; }, json() { return this; } };
+    let nextCalled = false;
+    requirePermission(...perms)({ user: reqUser }, res, () => { nextCalled = true; });
+    return { nextCalled, code: res.code };
+  }
+
+  test('401 without a user', () => {
+    assert.deepEqual(run(undefined, 'x'), { nextCalled: false, code: 401 });
+  });
+
+  test('403 without the permission', () => {
+    assert.deepEqual(run(user(['y']), 'x'), { nextCalled: false, code: 403 });
+  });
+
+  test('passes with the permission, the * scope, or as super admin', () => {
+    assert.equal(run(user(['x']), 'x').nextCalled, true);
+    assert.equal(run(user(['*']), 'x').nextCalled, true);
+    assert.equal(run(user([], true), 'x').nextCalled, true);
+  });
+});

package/tests/rate-limit-key.test.mjs

@@ -0,0 +1,25 @@
+import { test, describe, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import { defaultKeyExtractor } from '../dist/rate-limit/index.js';
+import { signGatewayIdentity } from '../dist/common/index.js';
+
+describe('defaultKeyExtractor', () => {
+  afterEach(() => { delete process.env.GATEWAY_SIGNING_SECRET; });
+
+  test('ignores an unsigned, caller-supplied x-user-id when a signing secret is set', () => {
+    process.env.GATEWAY_SIGNING_SECRET = 's';
+    assert.equal(defaultKeyExtractor({ ip: '81.2.69.160', headers: { 'x-user-id': 'rotating-1' } }), 'ip:81.2.69.160');
+  });
+
+  test('keys on the user id when the gateway signature verifies', () => {
+    process.env.GATEWAY_SIGNING_SECRET = 's';
+    const identity = { 'x-user-id': 'u1' };
+    const headers = { ...identity, ...signGatewayIdentity(identity, 's') };
+    assert.equal(defaultKeyExtractor({ ip: '10.0.0.1', headers }), 'user:u1');
+  });
+
+  test('falls back to "unknown" with no IP', () => {
+    process.env.GATEWAY_SIGNING_SECRET = 's';
+    assert.equal(defaultKeyExtractor({ headers: {} }), 'ip:unknown');
+  });
+});

package/tests/redact.test.mjs

@@ -0,0 +1,61 @@
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { redactSensitive, redactFormat, isSensitiveKey, REDACTED } from '../dist/logging/index.js';
+
+describe('redactSensitive', () => {
+  test('redacts credential keys at any depth, case- and separator-insensitively', () => {
+    const out = redactSensitive({
+      headers: { Authorization: 'Bearer abc.def', cookie: 'sid=1', 'x-internal-service-secret': 's' },
+      body: { email: 'a@b.c', password: 'hunter2', otp: '123456', pin: '0000' },
+      client_secret: 'cs', apiKey: 'k', smtpPassword: 'p', encryptionKey: 'e',
+      accessToken: 't', refresh_token: 'r', captchaToken: 'c',
+      nested: [{ privateKey: '-----BEGIN' }],
+    });
+    assert.equal(out.headers.Authorization, REDACTED);
+    assert.equal(out.headers.cookie, REDACTED);
+    assert.equal(out.headers['x-internal-service-secret'], REDACTED);
+    assert.equal(out.body.email, 'a@b.c');
+    for (const key of ['password', 'otp', 'pin']) assert.equal(out.body[key], REDACTED);
+    for (const key of ['client_secret', 'apiKey', 'smtpPassword', 'encryptionKey', 'accessToken', 'refresh_token', 'captchaToken']) {
+      assert.equal(out[key], REDACTED, key);
+    }
+    assert.equal(out.nested[0].privateKey, REDACTED);
+  });
+
+  test('keeps non-sensitive fields, including token counters', () => {
+    const out = redactSensitive({ userId: 'u1', promptTokens: 12, tokenType: 'Bearer', status: 200 });
+    assert.deepEqual(out, { userId: 'u1', promptTokens: 12, tokenType: 'Bearer', status: 200 });
+  });
+
+  test('masks bearer/basic credentials inside free text and error messages', () => {
+    assert.equal(redactSensitive('auth header was Bearer eyJhbGciOi.x.y'), `auth header was Bearer ${REDACTED}`);
+    const err = redactSensitive(new Error('upstream rejected Basic dXNlcjpwYXNz'));
+    assert.equal(err.message, `upstream rejected Basic ${REDACTED}`);
+  });
+
+  test('survives cycles without throwing', () => {
+    const a = { name: 'a' };
+    a.self = a;
+    assert.equal(redactSensitive(a).self, '[Circular]');
+  });
+
+  test('isSensitiveKey', () => {
+    assert.equal(isSensitiveKey('X-Gateway-Signature'), true);
+    assert.equal(isSensitiveKey('correlationId'), false);
+  });
+});
+
+describe('redactFormat', () => {
+  test('redacts log entry metadata and message', () => {
+    const info = redactFormat().transform({
+      level: 'error',
+      message: 'login failed for Bearer abc',
+      password: 'p',
+      request: { headers: { authorization: 'Bearer abc' } },
+    });
+    assert.equal(info.password, REDACTED);
+    assert.equal(info.request.headers.authorization, REDACTED);
+    assert.equal(info.message, `login failed for Bearer ${REDACTED}`);
+    assert.equal(info.level, 'error');
+  });
+});