@heavybit/pendoadmin-shared-lib 1.6.0 → 1.8.0

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

package/tests/redis-keyspace.test.mjs

@@ -0,0 +1,149 @@
+import { test, describe, afterEach } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  createRedisKeyspace,
+  resolveRedisKeyEnv,
+  resolveRedisKeyApp,
+  encodeRedisKeyPart,
+  hashRedisKeyPart,
+} from '../dist/redis/index.js';
+import { resolveLimiterKeyPrefix } from '../dist/rate-limit/index.js';
+
+const ENV_KEYS = ['NODE_ENV', 'REDIS_KEY_ENV', 'REDIS_KEY_APP', 'CACHE_KEY_PREFIX'];
+const saved = Object.fromEntries(ENV_KEYS.map((k) => [k, process.env[k]]));
+function restoreEnv() {
+  for (const k of ENV_KEYS) {
+    if (saved[k] === undefined) delete process.env[k];
+    else process.env[k] = saved[k];
+  }
+}
+
+describe('resolveRedisKeyEnv', () => {
+  test('prefers REDIS_KEY_ENV over CACHE_KEY_PREFIX', () => {
+    assert.equal(resolveRedisKeyEnv({ REDIS_KEY_ENV: 'prod', CACHE_KEY_PREFIX: 'other' }), 'prod');
+  });
+
+  test('falls back to CACHE_KEY_PREFIX', () => {
+    assert.equal(resolveRedisKeyEnv({ CACHE_KEY_PREFIX: 'staging', NODE_ENV: 'staging' }), 'staging');
+  });
+
+  test('defaults to dev outside deployed environments', () => {
+    assert.equal(resolveRedisKeyEnv({ NODE_ENV: 'development' }), 'dev');
+    assert.equal(resolveRedisKeyEnv({ NODE_ENV: 'test' }), 'dev');
+    assert.equal(resolveRedisKeyEnv({}), 'dev');
+  });
+
+  test('refuses to start in production or staging without an explicit env', () => {
+    assert.throws(() => resolveRedisKeyEnv({ NODE_ENV: 'production' }), /REDIS_KEY_ENV or CACHE_KEY_PREFIX/);
+    assert.throws(() => resolveRedisKeyEnv({ NODE_ENV: 'staging', REDIS_KEY_ENV: '  ' }), /must be set/);
+  });
+
+  test('rejects env values that are not kebab-case segments', () => {
+    assert.throws(() => resolveRedisKeyEnv({ REDIS_KEY_ENV: 'prod:x' }), /invalid env/);
+    assert.throws(() => resolveRedisKeyEnv({ REDIS_KEY_ENV: 'Prod' }), /invalid env/);
+  });
+});
+
+describe('resolveRedisKeyApp', () => {
+  test('defaults to pendoadmin and validates overrides', () => {
+    assert.equal(resolveRedisKeyApp({}), 'pendoadmin');
+    assert.equal(resolveRedisKeyApp({ REDIS_KEY_APP: 'pendo-admin' }), 'pendo-admin');
+    assert.throws(() => resolveRedisKeyApp({ REDIS_KEY_APP: 'pendo admin' }), /invalid app/);
+  });
+});
+
+describe('createRedisKeyspace', () => {
+  afterEach(restoreEnv);
+
+  test('builds {app}:{env}:{service}:{purpose}:{parts}', () => {
+    const ks = createRedisKeyspace({ service: 'api-gateway', env: 'prod' });
+    assert.equal(ks.prefix, 'pendoadmin:prod:api-gateway:');
+    assert.equal(ks.cacheEnvironment, 'pendoadmin:prod:api-gateway');
+    assert.equal(ks.key('authz', 'u1'), 'pendoadmin:prod:api-gateway:authz:u1');
+    assert.equal(ks.key('authz', 'apikey', 42), 'pendoadmin:prod:api-gateway:authz:apikey:42');
+    assert.equal(ks.key('gwcache'), 'pendoadmin:prod:api-gateway:gwcache');
+  });
+
+  test('resolves app and env from process.env when not given', () => {
+    process.env.NODE_ENV = 'staging';
+    process.env.CACHE_KEY_PREFIX = 'staging';
+    delete process.env.REDIS_KEY_ENV;
+    delete process.env.REDIS_KEY_APP;
+    assert.equal(createRedisKeyspace({ service: 'sms' }).prefix, 'pendoadmin:staging:sms:');
+  });
+
+  test('staging and prod keyspaces never produce the same key', () => {
+    const prod = createRedisKeyspace({ service: 'sms', env: 'prod' });
+    const staging = createRedisKeyspace({ service: 'sms', env: 'staging' });
+    assert.notEqual(prod.key('cache', 'x'), staging.key('cache', 'x'));
+  });
+
+  test('throws at creation in production without an env', () => {
+    process.env.NODE_ENV = 'production';
+    delete process.env.REDIS_KEY_ENV;
+    delete process.env.CACHE_KEY_PREFIX;
+    assert.throws(() => createRedisKeyspace({ service: 'sms' }), /must be set/);
+  });
+
+  test('a part containing ":" cannot fake extra segments', () => {
+    const ks = createRedisKeyspace({ service: 'auth-admin', env: 'prod' });
+    const key = ks.key('rl', 'a:b');
+    assert.equal(key, 'pendoadmin:prod:auth-admin:rl:a%3Ab');
+    assert.equal(key.split(':').length, 5);
+  });
+
+  test('rejects invalid service and purpose segments', () => {
+    assert.throws(() => createRedisKeyspace({ service: 'API_Gateway', env: 'prod' }), /invalid service/);
+    const ks = createRedisKeyspace({ service: 'sms', env: 'prod' });
+    assert.throws(() => ks.key('gw:cache'), /invalid purpose/);
+    assert.throws(() => ks.pattern('*'), /invalid purpose/);
+    assert.throws(() => ks.key('cache', ''), /must not be empty/);
+  });
+
+  test('patterns are always anchored on the full prefix', () => {
+    const ks = createRedisKeyspace({ service: 'api-gateway', env: 'prod' });
+    assert.equal(ks.pattern('gwcache'), 'pendoadmin:prod:api-gateway:gwcache:*');
+    assert.equal(ks.pattern('authz', 'apikey:*'), 'pendoadmin:prod:api-gateway:authz:apikey:*');
+    assert.ok(!ks.pattern('authz').startsWith('*'));
+  });
+});
+
+describe('part encoding and hashing', () => {
+  test('encodes separators, whitespace and SCAN glob characters', () => {
+    assert.equal(encodeRedisKeyPart('a b'), 'a%20b');
+    assert.equal(encodeRedisKeyPart('a|b'), 'a%7Cb');
+    assert.equal(encodeRedisKeyPart('x*y?[z]'), 'x%2Ay%3F%5Bz%5D');
+    assert.equal(encodeRedisKeyPart(7), '7');
+  });
+
+  test('hashes to sha256 hex and never echoes the input', () => {
+    const h = hashRedisKeyPart('/api/v1/users?token=secret');
+    assert.match(h, /^[0-9a-f]{64}$/);
+    assert.ok(!h.includes('secret'));
+    assert.equal(h, hashRedisKeyPart('/api/v1/users?token=secret'));
+  });
+});
+
+describe('resolveLimiterKeyPrefix', () => {
+  afterEach(restoreEnv);
+  const ks = createRedisKeyspace({ service: 'api-gateway', env: 'prod' });
+
+  test('uses the keyspace with keyPrefix as the limiter name', () => {
+    assert.equal(resolveLimiterKeyPrefix('sensitive', ks, true), 'pendoadmin:prod:api-gateway:rl:sensitive');
+    assert.equal(resolveLimiterKeyPrefix(undefined, ks, true), 'pendoadmin:prod:api-gateway:rl:default');
+  });
+
+  test('refuses an unscoped Redis limiter in production and staging', () => {
+    process.env.NODE_ENV = 'production';
+    assert.throws(() => resolveLimiterKeyPrefix('rl:x', undefined, true), /keyspace is required/);
+    process.env.NODE_ENV = 'staging';
+    assert.throws(() => resolveLimiterKeyPrefix(undefined, undefined, true), /keyspace is required/);
+  });
+
+  test('keeps the legacy raw prefix for in-memory or local use', () => {
+    process.env.NODE_ENV = 'production';
+    assert.equal(resolveLimiterKeyPrefix(undefined, undefined, false), 'rl:service');
+    process.env.NODE_ENV = 'development';
+    assert.equal(resolveLimiterKeyPrefix('rl:x', undefined, true), 'rl:x');
+  });
+});