@heavybit/pendoadmin-shared-lib 1.7.0 → 1.8.0

package/dist/index.d.ts

@@ -6,5 +6,6 @@ export * from './config/index.js';
 export * from './messaging/index.js';
 export * from './express/index.js';
 export * from './rate-limit/index.js';
+export * from './redis/index.js';
 export * from './scheduling/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,sBAAsB,CAAC;AAQrC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,cAAc,kBAAkB,CAAC;AAGjC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,sBAAsB,CAAC;AAQrC,cAAc,oBAAoB,CAAC;AAGnC,cAAc,uBAAuB,CAAC;AAGtC,cAAc,kBAAkB,CAAC;AAGjC,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -18,6 +18,8 @@ export * from './messaging/index.js';
 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';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,mBAAmB;AACnB,cAAc,mBAAmB,CAAC;AAElC,aAAa;AACb,cAAc,uBAAuB,CAAC;AAEtC,UAAU;AACV,cAAc,oBAAoB,CAAC;AAEnC,SAAS;AACT,cAAc,mBAAmB,CAAC;AAElC,YAAY;AACZ,cAAc,sBAAsB,CAAC;AAErC,2EAA2E;AAC3E,iFAAiF;AACjF,wEAAwE;AACxE,6EAA6E;AAE7E,kDAAkD;AAClD,cAAc,oBAAoB,CAAC;AAEnC,gBAAgB;AAChB,cAAc,uBAAuB,CAAC;AAEtC,aAAa;AACb,cAAc,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,QAAQ;AACR,cAAc,kBAAkB,CAAC;AAEjC,mBAAmB;AACnB,cAAc,mBAAmB,CAAC;AAElC,aAAa;AACb,cAAc,uBAAuB,CAAC;AAEtC,UAAU;AACV,cAAc,oBAAoB,CAAC;AAEnC,SAAS;AACT,cAAc,mBAAmB,CAAC;AAElC,YAAY;AACZ,cAAc,sBAAsB,CAAC;AAErC,2EAA2E;AAC3E,iFAAiF;AACjF,wEAAwE;AACxE,6EAA6E;AAE7E,kDAAkD;AAClD,cAAc,oBAAoB,CAAC;AAEnC,gBAAgB;AAChB,cAAc,uBAAuB,CAAC;AAEtC,2BAA2B;AAC3B,cAAc,kBAAkB,CAAC;AAEjC,aAAa;AACb,cAAc,uBAAuB,CAAC"}

package/dist/rate-limit/create-rate-limiter.d.ts

@@ -1,12 +1,19 @@
 import { Request, Response, NextFunction } from "express";
 import { RateLimiterAbstract } from "rate-limiter-flexible";
 import type Redis from "ioredis";
+import type { RedisKeyspace } from "../redis/keyspace.js";
 export interface RateLimitConfig {
     /** Max requests per window (default: 100) */
     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;
@@ -20,6 +27,12 @@ export interface RateLimitResult {
     middleware: (req: Request, res: Response, next: NextFunction) => Promise<void>;
 }
 export declare function createRateLimiter(cfg?: RateLimitConfig): RateLimitResult;
+/**
+ * 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 declare function resolveLimiterKeyPrefix(keyPrefix: string | undefined, keyspace: RedisKeyspace | undefined, usesRedis: boolean): string;
 /**
  * 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

package/dist/rate-limit/create-rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limit/create-rate-limiter.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAuC,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAKjC,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4FAA4F;IAC5F,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,oGAAoG;IACpG,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,OAAO,EAAE,mBAAmB,CAAC;IAC7B,yBAAyB;IACzB,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAID,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,eAAoB,GAAG,eAAe,CAmE5E;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAMxD"}
+{"version":3,"file":"create-rate-limiter.d.ts","sourceRoot":"","sources":["../../src/rate-limit/create-rate-limiter.ts"],"names":[],"mappings":"AAKA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAuC,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACjG,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AAEjC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAI1D,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,iGAAiG;IACjG,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iEAAiE;IACjE,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC;IAC3B,oGAAoG;IACpG,YAAY,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC9B,mDAAmD;IACnD,OAAO,EAAE,mBAAmB,CAAC;IAC7B,yBAAyB;IACzB,UAAU,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAChF;AAID,wBAAgB,iBAAiB,CAAC,GAAG,GAAE,eAAoB,GAAG,eAAe,CAoE5E;AAMD;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,QAAQ,EAAE,aAAa,GAAG,SAAS,EACnC,SAAS,EAAE,OAAO,GACjB,MAAM,CAMR;AAID;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAMxD"}

package/dist/rate-limit/create-rate-limiter.js

@@ -6,7 +6,8 @@ import { RateLimiterRedis, RateLimiterMemory } from "rate-limiter-flexible";
 import { isTrustedGatewayIdentity } from "../common/gateway-signature.js";
 // ─── Factory ────────────────────────────────────────────
 export function createRateLimiter(cfg = {}) {
-    const { maxRequests = 100, windowMs = 60_000, keyPrefix = "rl:service", redisClient = null, keyExtractor = defaultKeyExtractor, } = cfg;
+    const { maxRequests = 100, windowMs = 60_000, keyspace, redisClient = null, keyExtractor = defaultKeyExtractor, } = cfg;
+    const keyPrefix = resolveLimiterKeyPrefix(cfg.keyPrefix, keyspace, Boolean(redisClient));
     const durationSecs = Math.max(1, Math.round(windowMs / 1000));
     const memoryLimiter = new RateLimiterMemory({
         keyPrefix,
@@ -54,6 +55,21 @@ export function createRateLimiter(cfg = {}) {
     }
     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, keyspace, usesRedis) {
+    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 ───────────────────────────────────────────
 /**
  * The gateway user id only when its signature verifies — an unsigned

package/dist/rate-limit/create-rate-limiter.js.map

@@ -1 +1 @@
-{"version":3,"file":"create-rate-limiter.js","sourceRoot":"","sources":["../../src/rate-limit/create-rate-limiter.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"create-rate-limiter.js","sourceRoot":"","sources":["../../src/rate-limit/create-rate-limiter.ts"],"names":[],"mappings":"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"}

package/dist/rate-limit/index.d.ts

@@ -1,3 +1,3 @@
-export { createRateLimiter, defaultKeyExtractor } from "./create-rate-limiter.js";
+export { createRateLimiter, defaultKeyExtractor, resolveLimiterKeyPrefix } from "./create-rate-limiter.js";
 export type { RateLimitConfig, RateLimitResult } from "./create-rate-limiter.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/rate-limit/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAClF,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AAC3G,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/rate-limit/index.js

@@ -1,2 +1,2 @@
-export { createRateLimiter, defaultKeyExtractor } from "./create-rate-limiter.js";
+export { createRateLimiter, defaultKeyExtractor, resolveLimiterKeyPrefix } from "./create-rate-limiter.js";
 //# sourceMappingURL=index.js.map

package/dist/rate-limit/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/redis/index.d.ts

@@ -0,0 +1,3 @@
+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";
+//# sourceMappingURL=index.d.ts.map

package/dist/redis/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/redis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,aAAa,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC"}

package/dist/redis/index.js

@@ -0,0 +1,2 @@
+export { createRedisKeyspace, resolveRedisKeyApp, resolveRedisKeyEnv, encodeRedisKeyPart, hashRedisKeyPart, DEFAULT_REDIS_KEY_APP, DEFAULT_REDIS_KEY_ENV, } from "./keyspace.js";
+//# sourceMappingURL=index.js.map

package/dist/redis/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/redis/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,qBAAqB,GACtB,MAAM,eAAe,CAAC"}

package/dist/redis/keyspace.d.ts

@@ -0,0 +1,46 @@
+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>;
+export declare const DEFAULT_REDIS_KEY_APP = "pendoadmin";
+export declare const DEFAULT_REDIS_KEY_ENV = "dev";
+export declare function resolveRedisKeyApp(source?: EnvSource): string;
+/**
+ * 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 declare function resolveRedisKeyEnv(source?: EnvSource): string;
+/**
+ * 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 declare function encodeRedisKeyPart(part: RedisKeyPart): string;
+/** sha256 hex of a long or sensitive part (URLs, tokens). Never put a raw token in a key. */
+export declare function hashRedisKeyPart(value: string): string;
+export declare function createRedisKeyspace(options: RedisKeyspaceOptions): RedisKeyspace;
+export {};
+//# sourceMappingURL=keyspace.d.ts.map

package/dist/redis/keyspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyspace.d.ts","sourceRoot":"","sources":["../../src/redis/keyspace.ts"],"names":[],"mappings":"AAgBA,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,CAAC;AAE3C,MAAM,WAAW,oBAAoB;IACnC,kGAAkG;IAClG,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;OAGG;IACH,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,0FAA0F;IAC1F,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,YAAY,EAAE,GAAG,MAAM,CAAC;IACvD,kGAAkG;IAClG,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;CACnD;AAED,KAAK,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;AAIpD,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAClD,eAAO,MAAM,qBAAqB,QAAQ,CAAC;AAgB3C,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,SAAuB,GAAG,MAAM,CAE1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,GAAE,SAAuB,GAAG,MAAM,CAS1E;AAID;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAI7D;AAED,6FAA6F;AAC7F,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAID,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,oBAAoB,GAAG,aAAa,CAqBhF"}

package/dist/redis/keyspace.js

@@ -0,0 +1,82 @@
+// 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";
+// ─── 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, value) {
+    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 = process.env) {
+    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 = process.env) {
+    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) {
+    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) {
+    return createHash("sha256").update(value).digest("hex");
+}
+// ─── Factory ────────────────────────────────────────────
+export function createRedisKeyspace(options) {
+    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}`;
+        },
+    };
+}
+//# sourceMappingURL=keyspace.js.map

package/dist/redis/keyspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyspace.js","sourceRoot":"","sources":["../../src/redis/keyspace.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heavybit/pendoadmin-shared-lib",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "Shared library for PendoAdmin microservices",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -45,7 +45,8 @@
     "./rate-limit": "./dist/rate-limit/index.js",
     "./socket": "./dist/socket/index.js",
     "./tenant": "./dist/tenant/index.js",
-    "./scheduling": "./dist/scheduling/index.js"
+    "./scheduling": "./dist/scheduling/index.js",
+    "./redis": "./dist/redis/index.js"
   },
   "typesVersions": {
     "*": {
@@ -87,6 +88,9 @@
       ],
       "scheduling": [
         "dist/scheduling/index.d.ts"
+      ],
+      "redis": [
+        "dist/redis/index.d.ts"
       ]
     }
   },

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/rate-limit/create-rate-limiter.ts

@@ -7,6 +7,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";
+import type { RedisKeyspace } from "../redis/keyspace.js";
 
 // ─── Types ──────────────────────────────────────────────
 
@@ -15,7 +16,13 @@ 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;
@@ -36,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));
 
@@ -101,6 +109,27 @@ 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 ───────────────────────────────────────────
 
 /**

package/src/rate-limit/index.ts

@@ -1,2 +1,2 @@
-export { createRateLimiter, defaultKeyExtractor } 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/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');
+  });
+});