@heavybit/pendoadmin-shared-lib 1.6.0 → 1.7.0

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