@adaptic/backend-legacy 0.0.996 → 0.0.998

package/esm/middleware/__tests__/rate-limit-test-utils.mjs

@@ -0,0 +1,85 @@
+import { vi } from 'vitest';
+import jwt from 'jsonwebtoken';
+/**
+ * Shared fixtures for the rate-limiter test files (audit
+ * B01-backend-legacy-08). Pure helpers only — each test file remains
+ * responsible for setting `process.env.JWT_SECRET` via `vi.hoisted` BEFORE its
+ * first import pulls in `config/jwtConfig` (which reads the env at load time).
+ */
+/** Window used by every test config. */
+export const WINDOW_MS = 60_000;
+/**
+ * Builds a small test limiter config.
+ *
+ * @param overrides - Field overrides applied over the defaults.
+ * @returns A complete {@link RateLimitConfig}.
+ */
+export function makeConfig(overrides = {}) {
+    return {
+        name: 'graphql',
+        windowMs: WINDOW_MS,
+        maxAuthenticated: 100,
+        maxUnauthenticated: 2,
+        standardHeaders: true,
+        message: { errors: [{ message: 'Too many requests' }] },
+        ...overrides,
+    };
+}
+/**
+ * Creates a mock response whose header/status/json calls are observable —
+ * the shadow contract is proven by these spies staying untouched.
+ *
+ * @returns The {@link MockResponse}.
+ */
+export function makeRes() {
+    const setHeader = vi.fn();
+    const json = vi.fn();
+    const status = vi.fn(() => ({ json }));
+    const res = { setHeader, status, json };
+    return { res, setHeader, status, json };
+}
+/**
+ * Creates a mock request. Defaults to an anonymous POST from a fixed IP.
+ *
+ * @param overrides - Request field overrides (headers, ip, method, …).
+ * @returns A Request usable by the limiter middleware.
+ */
+export function makeReq(overrides = {}) {
+    return {
+        method: 'POST',
+        headers: {},
+        ip: '203.0.113.10',
+        socket: { remoteAddress: '203.0.113.10' },
+        ...overrides,
+    };
+}
+/**
+ * Reads the current value of a limiter counter for a label pair.
+ *
+ * @param counter - The prom-client counter to read.
+ * @param labels - The limiter/tier label pair identifying the series.
+ * @returns The current value (0 when the series does not exist yet).
+ */
+export async function counterValue(counter, labels) {
+    const metric = await counter.get();
+    const sample = metric.values.find((v) => v.labels.limiter === labels.limiter && v.labels.tier === labels.tier);
+    return sample?.value ?? 0;
+}
+/**
+ * Signs a real HS256 user JWT with the ambient `JWT_SECRET` (the same secret
+ * `config/jwtConfig` resolved at load), so the tier resolver verifies it.
+ *
+ * @param sub - Subject claim for the token.
+ * @returns A signed JWT string.
+ */
+export function signUserToken(sub) {
+    const secret = process.env.JWT_SECRET;
+    if (!secret) {
+        throw new Error('JWT_SECRET must be set by the test file before signing');
+    }
+    return jwt.sign({ sub, roles: ['user'] }, secret, {
+        algorithm: 'HS256',
+        expiresIn: '1h',
+    });
+}
+//# sourceMappingURL=rate-limit-test-utils.js.map

package/esm/middleware/rate-limiter.d.ts

@@ -1,16 +1,93 @@
 import { Request, Response, NextFunction } from 'express';
+import { Counter, Gauge } from 'prom-client';
+/**
+ * Environment variable gating 429 enforcement. When set to `true`/`1`, the
+ * limiters block over-limit requests with HTTP 429. Unset or any other value
+ * keeps them in SHADOW mode (observe + count + always proceed).
+ */
+export declare const CORTEX_RATE_LIMIT_ENFORCE_ENV = "CORTEX_RATE_LIMIT_ENFORCE";
+/**
+ * Whether rate-limit 429 enforcement is ON. Read fresh on each request (a cheap
+ * env read) so the shadow→enforce graduation can be flipped operationally
+ * without a restart. Defaults to OFF (shadow) for any unset/unrecognised value.
+ *
+ * @param env - Environment source (defaults to `process.env`); injectable for tests.
+ * @returns `true` only when the flag is explicitly `true`/`1`.
+ */
+export declare function isRateLimitEnforced(env?: Record<string, string | undefined>): boolean;
+/**
+ * Counts requests that rate limiting WOULD block (HTTP 429) while in SHADOW
+ * mode. This is the signal proving whether flipping
+ * `CORTEX_RATE_LIMIT_ENFORCE` to enforce would reject legitimate traffic.
+ * Labelled by the `limiter` name (`graphql`/`auth`) and the request `tier`
+ * (`auth`/`anon`). Real enforce-mode denials count on
+ * {@link cortexRateLimitBlockedTotal} instead, keeping the observed-only and
+ * actually-blocked series distinct (audit B01-backend-legacy-14).
+ */
+export declare const cortexRateLimitWouldBlockTotal: Counter<"limiter" | "tier">;
+/**
+ * Counts requests actually blocked with HTTP 429 in ENFORCE mode. Kept as a
+ * separate series from {@link cortexRateLimitWouldBlockTotal} so shadow
+ * observations and real blocks never mix (audit B01-backend-legacy-14).
+ */
+export declare const cortexRateLimitBlockedTotal: Counter<"limiter" | "tier">;
+/**
+ * Tracked bucket-key cardinality per limiter store. Bounds memory ahead of the
+ * trust-proxy fix, after which the identifier derives from X-Forwarded-For and
+ * an attacker rotating spoofed values could otherwise mint unbounded entries
+ * (audit B01-backend-legacy-12).
+ */
+export declare const cortexRateLimitStoreKeys: Gauge<"limiter">;
+/** Configuration for one rate limiter instance. */
+export interface RateLimitConfig {
+    /** Stable limiter identifier used as the `limiter` metric label. */
+    name: string;
+    windowMs: number;
+    maxAuthenticated: number;
+    maxUnauthenticated: number;
+    message: {
+        errors: Array<{
+            message: string;
+        }>;
+    };
+    standardHeaders?: boolean;
+    legacyHeaders?: boolean;
+    /** Cap on distinct bucket keys (defaults to {@link DEFAULT_MAX_TRACKED_KEYS}). */
+    maxTrackedKeys?: number;
+}
+/**
+ * Creates an in-memory rate limiter middleware with separate limits for
+ * verified (auth) and anonymous requests.
+ *
+ * Bucketing: verified callers are keyed per principal (`sub:<sub>`); anonymous
+ * callers are keyed by client IP, which resolves correctly behind the LB only
+ * with `trust proxy` configured in server.ts (audit B01-backend-legacy-02).
+ * The `auth` tier requires actual offline verification — a fabricated
+ * JWT-shaped header no longer earns the higher budget (B01-backend-legacy-09).
+ * CORS preflights (`OPTIONS`) are never counted (B01-backend-legacy-11).
+ *
+ * Response headers (enforce mode only, when standardHeaders is enabled):
+ *   X-RateLimit-Limit     - maximum requests allowed in the current window
+ *   X-RateLimit-Remaining - requests remaining in the current window
+ *   X-RateLimit-Reset     - seconds until the current window resets
+ *   Retry-After           - seconds to wait before retrying (only on 429)
+ *
+ * @param config - Rate limit configuration.
+ * @returns Express middleware function.
+ */
+export declare function createRateLimiter(config: RateLimitConfig): (req: Request, res: Response, next: NextFunction) => void;
 /**
  * Rate limiter for GraphQL endpoint.
  *
- * Authenticated requests:   1000 requests per 15 minutes (configurable via RATE_LIMIT_MAX)
- * Unauthenticated requests: 200 requests per 15 minutes (configurable via RATE_LIMIT_MAX_UNAUTH)
+ * Verified requests:  1000 requests per 15 minutes (configurable via RATE_LIMIT_MAX)
+ * Anonymous requests: 200 requests per 15 minutes (configurable via RATE_LIMIT_MAX_UNAUTH)
  */
 export declare const graphqlRateLimiter: (req: Request, res: Response, next: NextFunction) => void;
 /**
  * Rate limiter for authentication endpoints.
  *
- * Authenticated requests:   50 requests per 15 minutes
- * Unauthenticated requests: 20 requests per 15 minutes
+ * Verified requests:  50 requests per 15 minutes
+ * Anonymous requests: 20 requests per 15 minutes
  */
 export declare const authRateLimiter: (req: Request, res: Response, next: NextFunction) => void;
 //# sourceMappingURL=rate-limiter.d.ts.map

package/esm/middleware/rate-limiter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/rate-limiter.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAyG1D;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QA9ChB,OAAO,OAAO,QAAQ,QAAQ,YAAY,KAAG,IAuD1D,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QA/Db,OAAO,OAAO,QAAQ,QAAQ,YAAY,KAAG,IAsE1D,CAAC"}
+{"version":3,"file":"rate-limiter.d.ts","sourceRoot":"","sources":["../../../src/middleware/rate-limiter.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAK7C;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,8BAA8B,CAAC;AAEzE;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,OAAO,CAGT;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,8BAA8B,6BAKzC,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,6BAKtC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,wBAAwB,kBAKnC,CAAC;AAeH,mDAAmD;AACnD,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,gBAAgB,EAAE,MAAM,CAAC;IACzB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,EAAE;QAAE,MAAM,EAAE,KAAK,CAAC;YAAE,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;IAChD,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,kFAAkF;IAClF,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAOD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,eAAe,GACtB,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,KAAK,IAAI,CAgG3D;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAxGtB,OAAO,OAAO,QAAQ,QAAQ,YAAY,KAAK,IAkHtD,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,eAAe,QA1HnB,OAAO,OAAO,QAAQ,QAAQ,YAAY,KAAK,IAkItD,CAAC"}

package/esm/middleware/rate-limiter.js.map

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

package/esm/middleware/rate-limiter.mjs

@@ -1,75 +1,179 @@
-// Integration: add to server.ts - app.use('/graphql', graphqlRateLimiter) and app.use('/auth', authRateLimiter)
+// CORTEX-P0-001: mounted in server.ts as
+//   app.use('/graphql', cors, graphqlRateLimiter, …)  // GraphQL surface (after CORS)
+//   app.use('/api', authRateLimiter)                  // authenticated Express surface
+// SHADOW-FIRST: 429 enforcement is gated behind CORTEX_RATE_LIMIT_ENFORCE.
+// While OFF (default), the limiters observe + count requests that WOULD be
+// blocked but never touch the response — live behaviour is byte-identical.
+import { Counter, Gauge } from 'prom-client';
+import { metricsRegistry } from '../config/metrics.mjs';
+import { logger } from '../utils/logger.mjs';
+import { resolveRateTier } from './rate-tier.mjs';
 /**
- * Checks whether a request carries a valid-looking authentication token.
- * Does not verify the token -- only checks for its presence in the
- * Authorization header as a Bearer token with three dot-separated parts
- * (standard JWT structure).
+ * Environment variable gating 429 enforcement. When set to `true`/`1`, the
+ * limiters block over-limit requests with HTTP 429. Unset or any other value
+ * keeps them in SHADOW mode (observe + count + always proceed).
  */
-function isAuthenticated(req) {
-    const authHeader = req.headers.authorization || '';
-    if (!authHeader.startsWith('Bearer ')) {
-        return false;
-    }
-    const token = authHeader.slice(7);
-    // Only count 3-segment JWT-shaped tokens as "authenticated" for rate-limit
-    // tiering. Opaque OAuth access tokens (e.g. `ya29.…`) are rejected by the
-    // verifier downstream — treating them as authenticated here would let a
-    // caller spamming opaque tokens enjoy the higher auth-tier limits.
-    return token.split('.').length === 3;
+export const CORTEX_RATE_LIMIT_ENFORCE_ENV = 'CORTEX_RATE_LIMIT_ENFORCE';
+/**
+ * Whether rate-limit 429 enforcement is ON. Read fresh on each request (a cheap
+ * env read) so the shadow→enforce graduation can be flipped operationally
+ * without a restart. Defaults to OFF (shadow) for any unset/unrecognised value.
+ *
+ * @param env - Environment source (defaults to `process.env`); injectable for tests.
+ * @returns `true` only when the flag is explicitly `true`/`1`.
+ */
+export function isRateLimitEnforced(env = process.env) {
+    const raw = (env[CORTEX_RATE_LIMIT_ENFORCE_ENV] ?? '').trim().toLowerCase();
+    return raw === 'true' || raw === '1';
 }
 /**
- * Creates a simple in-memory rate limiter middleware with separate limits
- * for authenticated and unauthenticated requests.
+ * Counts requests that rate limiting WOULD block (HTTP 429) while in SHADOW
+ * mode. This is the signal proving whether flipping
+ * `CORTEX_RATE_LIMIT_ENFORCE` to enforce would reject legitimate traffic.
+ * Labelled by the `limiter` name (`graphql`/`auth`) and the request `tier`
+ * (`auth`/`anon`). Real enforce-mode denials count on
+ * {@link cortexRateLimitBlockedTotal} instead, keeping the observed-only and
+ * actually-blocked series distinct (audit B01-backend-legacy-14).
+ */
+export const cortexRateLimitWouldBlockTotal = new Counter({
+    name: 'cortex_rate_limit_would_block_total',
+    help: 'Requests rate limiting would block (429), by limiter and tier (shadow mode only; real denials count on cortex_rate_limit_blocked_total)',
+    labelNames: ['limiter', 'tier'],
+    registers: [metricsRegistry],
+});
+/**
+ * Counts requests actually blocked with HTTP 429 in ENFORCE mode. Kept as a
+ * separate series from {@link cortexRateLimitWouldBlockTotal} so shadow
+ * observations and real blocks never mix (audit B01-backend-legacy-14).
+ */
+export const cortexRateLimitBlockedTotal = new Counter({
+    name: 'cortex_rate_limit_blocked_total',
+    help: 'Requests actually blocked with HTTP 429, by limiter and tier (enforce mode only)',
+    labelNames: ['limiter', 'tier'],
+    registers: [metricsRegistry],
+});
+/**
+ * Tracked bucket-key cardinality per limiter store. Bounds memory ahead of the
+ * trust-proxy fix, after which the identifier derives from X-Forwarded-For and
+ * an attacker rotating spoofed values could otherwise mint unbounded entries
+ * (audit B01-backend-legacy-12).
+ */
+export const cortexRateLimitStoreKeys = new Gauge({
+    name: 'cortex_rate_limit_store_keys',
+    help: 'Current tracked bucket-key cardinality per limiter store',
+    labelNames: ['limiter'],
+    registers: [metricsRegistry],
+});
+/** Sweep cadence for expired bucket entries. */
+const STORE_SWEEP_INTERVAL_MS = 60_000;
+/**
+ * Default cap on distinct bucket keys per limiter store. Past the cap, new
+ * identifiers aggregate into a shared per-tier overflow bucket instead of
+ * allocating — bounding memory under identifier-rotation abuse.
+ */
+const DEFAULT_MAX_TRACKED_KEYS = 100_000;
+/** Bucket-key prefix used once the store cardinality cap is reached. */
+const OVERFLOW_KEY_PREFIX = 'overflow';
+/**
+ * Creates an in-memory rate limiter middleware with separate limits for
+ * verified (auth) and anonymous requests.
  *
- * Response headers (when standardHeaders is enabled):
+ * Bucketing: verified callers are keyed per principal (`sub:<sub>`); anonymous
+ * callers are keyed by client IP, which resolves correctly behind the LB only
+ * with `trust proxy` configured in server.ts (audit B01-backend-legacy-02).
+ * The `auth` tier requires actual offline verification — a fabricated
+ * JWT-shaped header no longer earns the higher budget (B01-backend-legacy-09).
+ * CORS preflights (`OPTIONS`) are never counted (B01-backend-legacy-11).
+ *
+ * Response headers (enforce mode only, when standardHeaders is enabled):
  *   X-RateLimit-Limit     - maximum requests allowed in the current window
  *   X-RateLimit-Remaining - requests remaining in the current window
  *   X-RateLimit-Reset     - seconds until the current window resets
  *   Retry-After           - seconds to wait before retrying (only on 429)
  *
- * @param config - Rate limit configuration
- * @returns Express middleware function
+ * @param config - Rate limit configuration.
+ * @returns Express middleware function.
  */
-function createRateLimiter(config) {
-    const store = {};
-    // Clean up expired entries every minute
+export function createRateLimiter(config) {
+    const store = new Map();
+    const maxTrackedKeys = config.maxTrackedKeys ?? DEFAULT_MAX_TRACKED_KEYS;
+    // Sweep expired entries every minute. `unref()` so an importing process
+    // (tests, one-off scripts) is never kept alive by the sweeper
+    // (audit B01-backend-legacy-12).
     setInterval(() => {
         const now = Date.now();
-        Object.keys(store).forEach((key) => {
-            if (store[key].resetTime < now) {
-                delete store[key];
+        for (const [key, entry] of store) {
+            if (entry.resetTime < now) {
+                store.delete(key);
             }
-        });
-    }, 60000);
+        }
+        cortexRateLimitStoreKeys.set({ limiter: config.name }, store.size);
+    }, STORE_SWEEP_INTERVAL_MS).unref();
     return (req, res, next) => {
-        const identifier = req.ip || req.connection.remoteAddress || 'unknown';
-        const authenticated = isAuthenticated(req);
-        const effectiveMax = authenticated
-            ? config.maxAuthenticated
-            : config.maxUnauthenticated;
-        const storeKey = `${identifier}:${authenticated ? 'auth' : 'anon'}`;
+        // CORS preflights carry no credentials and must not consume rate budget
+        // (audit B01-backend-legacy-11).
+        if (req.method === 'OPTIONS') {
+            next();
+            return;
+        }
+        const { tier, principalKey } = resolveRateTier(req);
+        const identifier = principalKey ?? req.ip ?? req.socket.remoteAddress ?? 'unknown';
+        const effectiveMax = tier === 'auth' ? config.maxAuthenticated : config.maxUnauthenticated;
+        let storeKey = `${identifier}:${tier}`;
         const now = Date.now();
-        if (!store[storeKey] || store[storeKey].resetTime < now) {
-            store[storeKey] = {
-                count: 1,
-                resetTime: now + config.windowMs,
-            };
+        // Cardinality cap: aggregate novel identifiers into a shared per-tier
+        // overflow bucket rather than growing without bound
+        // (audit B01-backend-legacy-12).
+        if (!store.has(storeKey) && store.size >= maxTrackedKeys) {
+            storeKey = `${OVERFLOW_KEY_PREFIX}:${tier}`;
+        }
+        const existing = store.get(storeKey);
+        let current;
+        if (!existing || existing.resetTime < now) {
+            current = { count: 1, resetTime: now + config.windowMs };
+            store.set(storeKey, current);
         }
         else {
-            store[storeKey].count += 1;
+            existing.count += 1;
+            current = existing;
         }
-        const current = store[storeKey];
         const remaining = Math.max(0, effectiveMax - current.count);
         const resetSeconds = Math.ceil((current.resetTime - now) / 1000);
-        // Add rate limit headers
+        const overLimit = current.count > effectiveMax;
+        // SHADOW mode (default): observe + count over-limit requests but NEVER touch
+        // the response — no rate-limit headers, no 429. This keeps live behaviour
+        // byte-identical until CORTEX_RATE_LIMIT_ENFORCE is flipped on.
+        if (!isRateLimitEnforced()) {
+            if (overLimit) {
+                cortexRateLimitWouldBlockTotal.inc({ limiter: config.name, tier });
+                // Log only the FIRST over-limit request per (bucket, window) — the
+                // counter carries per-request cardinality; unthrottled logging floods
+                // Cloud Logging and buries real warnings (audit B01-backend-legacy-10).
+                if (current.count === effectiveMax + 1) {
+                    logger.warn('[cortex-rate-limit] shadow would-block (allowing)', {
+                        limiter: config.name,
+                        identifier,
+                        tier,
+                        count: current.count,
+                        limit: effectiveMax,
+                        resetSeconds,
+                    });
+                }
+            }
+            next();
+            return;
+        }
+        // ENFORCE mode: emit the informational rate-limit headers and block
+        // over-limit requests with HTTP 429.
         if (config.standardHeaders !== false) {
             res.setHeader('X-RateLimit-Limit', effectiveMax.toString());
             res.setHeader('X-RateLimit-Remaining', remaining.toString());
             res.setHeader('X-RateLimit-Reset', resetSeconds.toString());
         }
-        if (current.count > effectiveMax) {
+        if (overLimit) {
             // Include Retry-After header on 429 responses (RFC 6585 / RFC 7231)
             res.setHeader('Retry-After', resetSeconds.toString());
+            cortexRateLimitBlockedTotal.inc({ limiter: config.name, tier });
             res.status(429).json(config.message);
             return;
         }
@@ -79,10 +183,11 @@ function createRateLimiter(config) {
 /**
  * Rate limiter for GraphQL endpoint.
  *
- * Authenticated requests:   1000 requests per 15 minutes (configurable via RATE_LIMIT_MAX)
- * Unauthenticated requests: 200 requests per 15 minutes (configurable via RATE_LIMIT_MAX_UNAUTH)
+ * Verified requests:  1000 requests per 15 minutes (configurable via RATE_LIMIT_MAX)
+ * Anonymous requests: 200 requests per 15 minutes (configurable via RATE_LIMIT_MAX_UNAUTH)
  */
 export const graphqlRateLimiter = createRateLimiter({
+    name: 'graphql',
     windowMs: 15 * 60 * 1000, // 15 minutes
     maxAuthenticated: parseInt(process.env.RATE_LIMIT_MAX || '1000', 10),
     maxUnauthenticated: parseInt(process.env.RATE_LIMIT_MAX_UNAUTH || '200', 10),
@@ -95,10 +200,11 @@ export const graphqlRateLimiter = createRateLimiter({
 /**
  * Rate limiter for authentication endpoints.
  *
- * Authenticated requests:   50 requests per 15 minutes
- * Unauthenticated requests: 20 requests per 15 minutes
+ * Verified requests:  50 requests per 15 minutes
+ * Anonymous requests: 20 requests per 15 minutes
  */
 export const authRateLimiter = createRateLimiter({
+    name: 'auth',
     windowMs: 15 * 60 * 1000, // 15 minutes
     maxAuthenticated: 50,
     maxUnauthenticated: 20,

package/esm/middleware/rate-tier.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Rate-limit tier resolution (audit B01-backend-legacy-09).
+ *
+ * The rate limiter previously granted the 5x-higher authenticated tier to any
+ * request carrying a 3-dot-segment `Bearer` header — a trivially fabricated
+ * shape (`Bearer a.b.c`). This module keys the tier off ACTUAL verification
+ * instead, using the two offline-verifiable credential classes:
+ *
+ *   1. `SERVER_AUTH_TOKEN` exact match (the engine / server-to-server path).
+ *   2. App-issued HS256 JWTs verified against the shared `jwtSecret`.
+ *
+ * Google ID tokens (RS256, JWKS-verified) cannot be verified synchronously
+ * without a network dependency in the request hot path; they are deliberately
+ * tiered as `anon`. This is a metrics-only inaccuracy while the limiter is in
+ * shadow mode — before any enforce graduation, either extend this resolver
+ * with an async JWKS-backed path or raise the anon ceiling to cover browser
+ * traffic (tracked in the B01-02 graduation checklist).
+ *
+ * Verified results are memoised in a bounded, TTL'd cache keyed by the token's
+ * SHA-256 (raw tokens are never retained) so the per-request cost is one hash.
+ */
+import type { Request } from 'express';
+/** Rate-limit tier: `auth` = verified caller budget, `anon` = default budget. */
+export type RateTier = 'auth' | 'anon';
+/**
+ * Outcome of tier resolution for one request.
+ */
+export interface RateTierResolution {
+    /** The tier the request's rate budget is drawn from. */
+    readonly tier: RateTier;
+    /**
+     * Stable per-principal bucket key (`sub:<sub>`) for verified callers, so
+     * authenticated traffic is bucketed per principal rather than per IP
+     * (audit B01-backend-legacy-02). `null` for anonymous callers — the limiter
+     * falls back to the client IP.
+     */
+    readonly principalKey: string | null;
+}
+/**
+ * Clears the memoised token-verdict cache. Test-only.
+ *
+ * @internal exported for testing
+ */
+export declare function _resetRateTierCacheForTests(): void;
+/**
+ * Resolves the rate-limit tier and principal bucket key for a request.
+ *
+ * Cheap on the hot path: one SHA-256 over the token plus a bounded map lookup;
+ * the HMAC verification runs at most once per token per TTL window.
+ *
+ * @param req - Incoming Express request.
+ * @returns The request's {@link RateTierResolution}; `anon` when no `Bearer`
+ *   token is present or the token cannot be verified offline.
+ */
+export declare function resolveRateTier(req: Request): RateTierResolution;
+//# sourceMappingURL=rate-tier.d.ts.map

package/esm/middleware/rate-tier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-tier.d.ts","sourceRoot":"","sources":["../../../src/middleware/rate-tier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,iFAAiF;AACjF,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;AAEvC;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CACtC;AAiBD;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,IAAI,CAElD;AAiCD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,kBAAkB,CA6BhE"}

package/esm/middleware/rate-tier.js.map

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

package/esm/middleware/rate-tier.mjs

@@ -0,0 +1,103 @@
+/**
+ * Rate-limit tier resolution (audit B01-backend-legacy-09).
+ *
+ * The rate limiter previously granted the 5x-higher authenticated tier to any
+ * request carrying a 3-dot-segment `Bearer` header — a trivially fabricated
+ * shape (`Bearer a.b.c`). This module keys the tier off ACTUAL verification
+ * instead, using the two offline-verifiable credential classes:
+ *
+ *   1. `SERVER_AUTH_TOKEN` exact match (the engine / server-to-server path).
+ *   2. App-issued HS256 JWTs verified against the shared `jwtSecret`.
+ *
+ * Google ID tokens (RS256, JWKS-verified) cannot be verified synchronously
+ * without a network dependency in the request hot path; they are deliberately
+ * tiered as `anon`. This is a metrics-only inaccuracy while the limiter is in
+ * shadow mode — before any enforce graduation, either extend this resolver
+ * with an async JWKS-backed path or raise the anon ceiling to cover browser
+ * traffic (tracked in the B01-02 graduation checklist).
+ *
+ * Verified results are memoised in a bounded, TTL'd cache keyed by the token's
+ * SHA-256 (raw tokens are never retained) so the per-request cost is one hash.
+ */
+import { createHash } from 'crypto';
+import jwt from 'jsonwebtoken';
+import { jwtSecret } from '../config/jwtConfig.mjs';
+/** Bound on memoised token verdicts; oldest entries evicted first. */
+const TIER_CACHE_MAX_ENTRIES = 2048;
+/** Memoised verdicts expire after one rate-limit window (15 minutes). */
+const TIER_CACHE_TTL_MS = 15 * 60 * 1000;
+const ANON_RESOLUTION = { tier: 'anon', principalKey: null };
+const tierCache = new Map();
+/**
+ * Clears the memoised token-verdict cache. Test-only.
+ *
+ * @internal exported for testing
+ */
+export function _resetRateTierCacheForTests() {
+    tierCache.clear();
+}
+/**
+ * Verifies a bearer token offline and classifies its rate tier.
+ *
+ * @param token - Raw bearer token value (after the `Bearer ` prefix).
+ * @returns The resolved tier; `anon` for anything that fails verification.
+ */
+function verifyTier(token) {
+    const serverAuthToken = process.env.SERVER_AUTH_TOKEN;
+    if (typeof serverAuthToken === 'string' &&
+        serverAuthToken.length > 0 &&
+        token === serverAuthToken) {
+        return { tier: 'auth', principalKey: 'sub:server' };
+    }
+    try {
+        // HS256 pinned for the same alg-confusion reasons as the token-verifier.
+        const payload = jwt.verify(token, jwtSecret, { algorithms: ['HS256'] });
+        if (typeof payload !== 'string' && typeof payload.sub === 'string') {
+            return { tier: 'auth', principalKey: `sub:${payload.sub}` };
+        }
+        return ANON_RESOLUTION;
+    }
+    catch {
+        // Unverifiable (bad signature, expired, RS256 Google ID token, garbage
+        // shape) — treated as anonymous for tier purposes. Never throws upward:
+        // the limiter must not be able to fail a request.
+        return ANON_RESOLUTION;
+    }
+}
+/**
+ * Resolves the rate-limit tier and principal bucket key for a request.
+ *
+ * Cheap on the hot path: one SHA-256 over the token plus a bounded map lookup;
+ * the HMAC verification runs at most once per token per TTL window.
+ *
+ * @param req - Incoming Express request.
+ * @returns The request's {@link RateTierResolution}; `anon` when no `Bearer`
+ *   token is present or the token cannot be verified offline.
+ */
+export function resolveRateTier(req) {
+    const authHeader = req.headers.authorization ?? '';
+    if (!authHeader.startsWith('Bearer ')) {
+        return ANON_RESOLUTION;
+    }
+    const token = authHeader.slice('Bearer '.length).trim();
+    if (token.length === 0) {
+        return ANON_RESOLUTION;
+    }
+    const cacheKey = createHash('sha256').update(token).digest('hex');
+    const now = Date.now();
+    const cached = tierCache.get(cacheKey);
+    if (cached && cached.expiresAt > now) {
+        return cached.resolution;
+    }
+    const resolution = verifyTier(token);
+    if (tierCache.size >= TIER_CACHE_MAX_ENTRIES) {
+        // Map preserves insertion order — evict the oldest entry.
+        const oldestKey = tierCache.keys().next().value;
+        if (oldestKey !== undefined) {
+            tierCache.delete(oldestKey);
+        }
+    }
+    tierCache.set(cacheKey, { resolution, expiresAt: now + TIER_CACHE_TTL_MS });
+    return resolution;
+}
+//# sourceMappingURL=rate-tier.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adaptic/backend-legacy",
-  "version": "0.0.996",
+  "version": "0.0.998",
   "description": "Backend executable CRUD functions with dynamic variables construction, and type definitions for the Adaptic AI platform.",
   "type": "module",
   "types": "index.d.ts",