Implemented the API Gateway race-condition

Author: Elsa-tech2026

backend/SECURITY_PERFORMANCE_IMPROVEMENTS_SUMMARY.md

@@ -1,3 +1,13 @@
+# API Gateway Security Patch
+
+API gateway timestamps are accepted only as canonical, unsigned decimal Unix seconds that fit within JavaScript's safe integer range. Values with a decimal, sign, hexadecimal prefix, trailing data, or unsafe magnitude are rejected before signature verification.
+
+Mutating signed requests use an atomic Redis `SET NX` reservation keyed by a SHA-256 digest of the API secret and signature. This closes the replay race between API Gateway instances. Configure `REDIS_URL` in multi-instance deployments; when configured Redis is unavailable, authentication fails closed with `API_GATEWAY_REPLAY_PROTECTION_UNAVAILABLE` (HTTP 503) rather than accepting a request without distributed replay protection.
+
+The API-key middleware only accepts a pre-populated merchant context from the trusted x402 bridge (`req.x402`). A merchant object by itself is never sufficient to bypass API-key lookup and expiry checks. Requests using API gateway signatures must continue to send `x-api-key`, `x-api-signature` (`sha256=` plus 64 lowercase hexadecimal characters), and `x-api-timestamp`.
+
+Regression coverage is provided by `src/lib/api-gateway-signature.test.js` and `src/lib/auth.test.js`. Run `npm test -- --run src/lib/api-gateway-signature.test.js src/lib/auth.test.js` from `backend/` to validate the patch.
+
 # Security and Performance Improvements Summary
 
 **Project**: Stellar Payment API - Transaction Signer & Ledger Monitor  

backend/src/lib/api-gateway-signature.js

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import { logger } from "./logger.js";
 import { apiGatewaySignatureCacheSize, apiGatewayReplayBlockedTotal } from "./metrics.js";
+import { connectRedisClient } from "./redis.js";
 
 const DEFAULT_SIGNATURE_WINDOW_SECONDS = 300;
 // Minimum HMAC secret length to prevent signing with trivially weak keys
@@ -262,6 +263,62 @@ function buildCanonicalPayload({ method, path, timestamp, body }) {
 // state-changing requests, where re-execution has a real side effect.
 const REPLAY_PROTECTED_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 
+function isReplayProtectedMethod(method) {
+  return REPLAY_PROTECTED_METHODS.has(String(method || "GET").toUpperCase());
+}
+
+function distributedReplayKey(secret, signatureHeader) {
+  return `api-gateway:replay:${crypto
+    .createHash("sha256")
+    .update(`${secret}:${signatureHeader}`, "utf8")
+    .digest("hex")}`;
+}
+
+/**
+ * Atomically reserve a mutating request signature across API instances.
+ * Redis SET NX is used when REDIS_URL is configured; the verifier's local
+ * cache remains the fallback for single-instance deployments.
+ */
+export async function reserveApiGatewaySignature({
+  secret,
+  signatureHeader,
+  method,
+  toleranceSeconds,
+  redisClient,
+}) {
+  if (!isReplayProtectedMethod(method)) return { reserved: true };
+
+  if (!process.env.REDIS_URL && !redisClient) return { reserved: true };
+
+  try {
+    const client = redisClient || (await connectRedisClient());
+    if (!client?.isOpen) {
+      throw new Error("Redis is unavailable for distributed replay protection");
+    }
+
+    const result = await client.set(
+      distributedReplayKey(secret, signatureHeader),
+      "1",
+      { NX: true, EX: Math.max(1, Math.ceil(toleranceSeconds)) },
+    );
+
+    if (result !== "OK") {
+      apiGatewayReplayBlockedTotal.inc();
+      logger.warn("Rejected replayed API gateway signature from distributed cache");
+      return { reserved: false, replay: true };
+    }
+
+    return { reserved: true };
+  } catch (err) {
+    logger.error({ err }, "Distributed API gateway replay protection unavailable");
+    return {
+      reserved: false,
+      code: "API_GATEWAY_REPLAY_PROTECTION_UNAVAILABLE",
+      reason: "API gateway replay protection is temporarily unavailable",
+    };
+  }
+}
+
 function signaturesEqual(a, b) {
   const aBuf = Buffer.from(a, "hex");
   const bBuf = Buffer.from(b, "hex");
@@ -381,13 +438,20 @@ export function verifyApiGatewayRequestSignature({
       return { valid: false, reason: "Missing or insufficient signature secret" };
     }
 
-    const timestamp = Number.parseInt(String(timestampHeader || ""), 10);
-    if (!Number.isFinite(timestamp)) {
+    const timestampValue = String(timestampHeader || "").trim();
+    if (!/^[0-9]+$/.test(timestampValue)) {
       recordApiGatewaySignatureAttempt(clientIp, false, now);
       _recordCircuitBreakerFailure(now);
       logger.warn({ timestampHeader, clientIp }, "Missing or invalid x-api-timestamp header");
       return { valid: false, reason: "Missing or invalid x-api-timestamp header" };
     }
+    const timestamp = Number(timestampValue);
+    if (!Number.isSafeInteger(timestamp)) {
+      recordApiGatewaySignatureAttempt(clientIp, false, now);
+      _recordCircuitBreakerFailure(now);
+      logger.warn({ clientIp }, "API gateway timestamp exceeds safe integer range");
+      return { valid: false, reason: "Missing or invalid x-api-timestamp header" };
+    }
 
     const deltaSeconds = Math.abs(Math.floor(now / 1000) - timestamp);
     if (deltaSeconds > toleranceSeconds) {
@@ -424,7 +488,7 @@ export function verifyApiGatewayRequestSignature({
     // that has already been used within its own tolerance window is a
     // replay of a captured request, not a legitimate second use. Scoped to
     // state-changing methods only - see REPLAY_PROTECTED_METHODS.
-    const isReplayProtected = REPLAY_PROTECTED_METHODS.has(String(method || "GET").toUpperCase());
+    const isReplayProtected = isReplayProtectedMethod(method);
     if (isReplayProtected && _isReplayedSignature(receivedSignature, now)) {
       recordApiGatewaySignatureAttempt(clientIp, false, now);
       _recordCircuitBreakerFailure(now);

backend/src/lib/api-gateway-signature.test.js

@@ -7,6 +7,7 @@ import {
   _apiGatewayRateLimitState,
   _verifiedSignatureCache,
   getApiGatewaySignatureCacheStats,
+  reserveApiGatewaySignature,
 } from "./api-gateway-signature.js";
 
 // All secrets must be >= 16 characters (MIN_SECRET_LENGTH enforcement, issue #767)
@@ -91,6 +92,76 @@ describe("api-gateway-signature", () => {
     expect(result.reason).toMatch(/invalid x-api-signature/i);
   });
 
+  it.each(["1713916800abc", "1713916800.5", "+1713916800", "0x6611f800"])(
+    "rejects non-canonical timestamp %s",
+    (timestampHeader) => {
+      const result = verifyApiGatewayRequestSignature({
+        secret: VALID_SECRET,
+        method: "GET",
+        path: "/health",
+        timestampHeader,
+        signatureHeader: "sha256=" + "a".repeat(64),
+        body: {},
+        now: 1713916800 * 1000,
+      });
+
+      expect(result.valid).toBe(false);
+      expect(result.reason).toMatch(/invalid x-api-timestamp/i);
+    },
+  );
+
+  describe("distributed replay reservation", () => {
+    it("atomically reserves a mutating signature with Redis SET NX", async () => {
+      const set = vi.fn().mockResolvedValue("OK");
+      const redisClient = { isOpen: true, set };
+
+      const result = await reserveApiGatewaySignature({
+        secret: VALID_SECRET,
+        signatureHeader: "sha256=" + "a".repeat(64),
+        method: "POST",
+        toleranceSeconds: 300,
+        redisClient,
+      });
+
+      expect(result).toEqual({ reserved: true });
+      expect(set).toHaveBeenCalledWith(
+        expect.stringMatching(/^api-gateway:replay:[a-f0-9]{64}$/),
+        "1",
+        { NX: true, EX: 300 },
+      );
+    });
+
+    it("rejects a signature when Redis reports that it is already reserved", async () => {
+      const redisClient = { isOpen: true, set: vi.fn().mockResolvedValue(null) };
+
+      const result = await reserveApiGatewaySignature({
+        secret: VALID_SECRET,
+        signatureHeader: "sha256=" + "b".repeat(64),
+        method: "POST",
+        toleranceSeconds: 300,
+        redisClient,
+      });
+
+      expect(result).toEqual({ reserved: false, replay: true });
+    });
+
+    it("fails closed when configured Redis is unavailable", async () => {
+      const redisClient = { isOpen: false, set: vi.fn() };
+
+      const result = await reserveApiGatewaySignature({
+        secret: VALID_SECRET,
+        signatureHeader: "sha256=" + "c".repeat(64),
+        method: "POST",
+        toleranceSeconds: 300,
+        redisClient,
+      });
+
+      expect(result.reserved).toBe(false);
+      expect(result.code).toBe("API_GATEWAY_REPLAY_PROTECTION_UNAVAILABLE");
+      expect(redisClient.set).not.toHaveBeenCalled();
+    });
+  });
+
   // ── Security audit: minimum secret length (#767) ──────────────────────────
 
   it("rejects signing with a secret shorter than the minimum length", () => {

backend/src/lib/auth.js

@@ -1,6 +1,9 @@
 import bcrypt from "bcryptjs";
 import { recordMerchantApiUsage } from "./api-usage.js";
-import { verifyApiGatewayRequestSignature } from "./api-gateway-signature.js";
+import {
+  reserveApiGatewaySignature,
+  verifyApiGatewayRequestSignature,
+} from "./api-gateway-signature.js";
 import { queryWithRetry } from "./db.js";
 
 const SALT_ROUNDS = 12;
@@ -73,14 +76,15 @@ export function createApiKeyAuth({
   supabaseClient = null, // unused for API key auth; retained for session-auth compat
   usageRecorder = recordMerchantApiUsage,
   verifyGatewaySignature = verifyApiGatewayRequestSignature,
+  reserveGatewaySignature = reserveApiGatewaySignature,
   requireSignature = false,
   merchantLookup = defaultMerchantLookup,
 } = {}) {
   return async function requireApiKeyAuth(req, res, next) {
     try {
       // Another auth layer (e.g. x402 token bridge) may have already attached a
       // merchant context. If so, honor it and continue.
-      if (req.merchant?.id) {
+      if (req.x402 && req.merchant?.id) {
         try {
           await usageRecorder({ merchantId: req.merchant.id, req });
         } catch (usageError) {
@@ -134,6 +138,26 @@ export function createApiKeyAuth({
             ...(signatureResult.rateLimitInfo && { rateLimitInfo: signatureResult.rateLimitInfo }),
           });
         }
+
+        const reservation = await reserveGatewaySignature({
+          secret: apiKey,
+          signatureHeader,
+          method: req.method,
+          toleranceSeconds: Number(
+            process.env.API_GATEWAY_SIGNATURE_TOLERANCE_SECONDS || 300,
+          ),
+        });
+        if (!reservation.reserved) {
+          return res.status(reservation.replay ? 401 : 503).json({
+            error: reservation.replay
+              ? "Invalid API gateway signature"
+              : "API gateway replay protection is temporarily unavailable",
+            code: reservation.replay
+              ? "API_GATEWAY_REPLAY_DETECTED"
+              : reservation.code,
+            ...(reservation.reason && { reason: reservation.reason }),
+          });
+        }
       }
 
       // Block IPs that have exceeded the failed-attempt threshold (#767)

backend/src/lib/auth.test.js

@@ -142,10 +142,62 @@ describe("createApiKeyAuth", () => {
       timestampHeader: "1713916800",
       signatureHeader: "sha256=abcd",
       body: { amount: 1 },
+      clientIp: "1.2.3.4",
     });
     expect(next).toHaveBeenCalledWith();
   });
 
+  it("does not trust a pre-populated merchant without x402 authentication", async () => {
+    merchantLookup.mockResolvedValue(null);
+    const req = createRequest({ "x-api-key": "invalid-key" }, { merchant: baseMerchant });
+
+    await middleware(req, res, next);
+
+    expect(merchantLookup).toHaveBeenCalledWith("invalid-key");
+    expect(usageRecorder).not.toHaveBeenCalled();
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(next).not.toHaveBeenCalled();
+  });
+
+  it("honors a merchant populated by the trusted x402 bridge", async () => {
+    const req = createRequest({}, { merchant: baseMerchant, x402: { tx_hash: "tx-1" } });
+
+    await middleware(req, res, next);
+
+    expect(merchantLookup).not.toHaveBeenCalled();
+    expect(usageRecorder).toHaveBeenCalledWith({ merchantId: baseMerchant.id, req });
+    expect(next).toHaveBeenCalledWith();
+  });
+
+  it("rejects a replay reported by the distributed signature reservation", async () => {
+    merchantLookup.mockResolvedValue(baseMerchant);
+    const reserveGatewaySignature = vi.fn().mockResolvedValue({
+      reserved: false,
+      replay: true,
+    });
+    middleware = createApiKeyAuth({
+      merchantLookup,
+      usageRecorder,
+      verifyGatewaySignature,
+      reserveGatewaySignature,
+    });
+    const req = createRequest({
+      "x-api-key": "signed-api-key",
+      "x-api-signature": "sha256=" + "a".repeat(64),
+      "x-api-timestamp": "1713916800",
+    });
+
+    await middleware(req, res, next);
+
+    expect(res.status).toHaveBeenCalledWith(401);
+    expect(res.json).toHaveBeenCalledWith({
+      error: "Invalid API gateway signature",
+      code: "API_GATEWAY_REPLAY_DETECTED",
+    });
+    expect(merchantLookup).not.toHaveBeenCalled();
+    expect(next).not.toHaveBeenCalled();
+  });
+
   it("rejects request when gateway signature verification fails", async () => {
     verifyGatewaySignature.mockReturnValue({
       valid: false,