Merge pull request #701 from Jagadeeshftw/fix/681-idempotency-key-schema

fix: centralize idempotency key validation

Author: Jagadeeshftw

docs/utils/validation.md

@@ -12,6 +12,7 @@ exported:
 |---|---|---|
 | `StarknetAddress` | `z.ZodString` → transform | Parse + normalize a Starknet hex address |
 | `AgreementId` | `z.ZodString` | Parse a numeric-string agreement identifier |
+| `IdempotencyKeySchema` | `z.ZodString` | Validate bounded ASCII replay keys |
 | `parsePagination` | function | Clamp `limit`/`offset` query params to safe defaults |
 | `loggedParse` | function | Parse + log structured diagnostics on failure |
 | `formatValidationError` | function | Map a caught error to the standard API JSON shape |
@@ -118,6 +119,17 @@ AgreementId.parse("00042")  // "00042"
 AgreementId.parse("12ab")   // throws ZodError
 ```
 
+### `IdempotencyKeySchema`
+
+Idempotency keys must be 1–255 characters and contain only ASCII letters,
+digits, hyphens, or underscores. The same schema is used by rate-limit,
+billing, and diagnostics middleware so invalid keys bypass replay caching.
+
+```typescript
+IdempotencyKeySchema.parse("checkout_2026-07-30"); // accepted
+IdempotencyKeySchema.safeParse("key with spaces").success; // false
+```
+
 ## Pagination
 
 ### `parsePagination(query)` → `{ limit, offset }`

src/middleware/rate-limit.ts

@@ -4,6 +4,7 @@ import rateLimit, {
   ipKeyGenerator,
 } from "express-rate-limit";
 import type { Request, Response } from "express";
+import { IdempotencyKeySchema } from "../utils/validation.js";
 
 // ---------------------------------------------------------------------------
 // Idempotency-Key support
@@ -29,11 +30,7 @@ export const X_IDEMPOTENT_REPLAYED_HEADER = "X-Idempotent-Replayed";
 export function getIdempotencyKey(req: Request): string | undefined {
   const value = req.headers[IDEMPOTENCY_KEY_HEADER.toLowerCase()];
   if (typeof value !== "string" || value.length === 0) return undefined;
-  // Enforce a safe character set for idempotency keys: alphanumerics, hyphen, underscore.
-  // Reject keys containing whitespace or control characters to avoid injection risks.
-  const IDEMPOTENCY_KEY_REGEX = /^[A-Za-z0-9_-]{1,255}$/;
-  if (!IDEMPOTENCY_KEY_REGEX.test(value)) return undefined;
-  return value;
+  return IdempotencyKeySchema.safeParse(value).success ? value : undefined;
 }
 
 // ---------------------------------------------------------------------------

src/routes/billing.ts

@@ -24,6 +24,7 @@ import { z } from "zod";
 import { eq } from "drizzle-orm";
 import { db, schema } from "../db/index.js";
 import { env } from "../config.js";
+import { IdempotencyKeySchema } from "../utils/validation.js";
 
 export const billingRouter = express.Router();
 
@@ -117,7 +118,12 @@ export function withBillingIdempotency(
   handler: (req: Request, res: Response, next: NextFunction) => Promise<void> | void,
 ) {
   return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
-    const idempotencyKey = getHeader(req, "Idempotency-Key") ?? getHeader(req, "idempotency-key");
+    const rawIdempotencyKey =
+      getHeader(req, "Idempotency-Key") ?? getHeader(req, "idempotency-key");
+    const idempotencyKey =
+      rawIdempotencyKey && IdempotencyKeySchema.safeParse(rawIdempotencyKey).success
+        ? rawIdempotencyKey
+        : undefined;
     const method = req.method.toUpperCase();
 
     if (!idempotencyKey || ["GET", "HEAD", "OPTIONS"].includes(method)) {
@@ -230,9 +236,7 @@ export function computeBillingSummary(
  * @param parts - Ordered address parts: [street, city, state, zipCode, country].
  * @returns Comma-joined address string, or `null` if all parts are absent.
  */
-export function buildFullAddress(
-  parts: Array<string | null | undefined>,
-): string | null {
+export function buildFullAddress(parts: Array<string | null | undefined>): string | null {
   const present = parts.filter(Boolean) as string[];
   return present.length > 0 ? present.join(", ") : null;
 }

src/routes/diagnostics.ts

@@ -4,6 +4,7 @@ import { requireAuth, requireAdmin } from "../auth/middleware.js";
 import { db, getPoolStats, checkDbHealth } from "../db/index.js";
 import { sql } from "drizzle-orm";
 import { getCircuitBreakerSnapshots, provider } from "../starknet/client.js";
+import { IdempotencyKeySchema } from "../utils/validation.js";
 import {
   logDiagnosticsEvent,
   incDiagnosticsMetric,
@@ -50,8 +51,12 @@ export function withDiagnosticsIdempotency(
   handler: (req: Request, res: Response, next: NextFunction) => Promise<void> | void,
 ) {
   return async (req: Request, res: Response, next: NextFunction): Promise<void> => {
+    const rawIdempotencyKey = req.headers["idempotency-key"] || req.headers["Idempotency-Key"];
     const idempotencyKey =
-      req.headers["idempotency-key"] || req.headers["Idempotency-Key"];
+      typeof rawIdempotencyKey === "string" &&
+      IdempotencyKeySchema.safeParse(rawIdempotencyKey).success
+        ? rawIdempotencyKey
+        : undefined;
 
     if (!idempotencyKey || Array.isArray(idempotencyKey)) {
       await handler(req, res, next);

src/utils/validation.test.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import {
   StarknetAddress,
   AgreementId,
+  IdempotencyKeySchema,
   parsePagination,
   MAX_PAGE_LIMIT,
   DEFAULT_PAGE_LIMIT,
@@ -25,6 +26,20 @@ import {
 } from "./validation";
 import type { ValidationErrorMetric } from "./validation";
 
+describe("IdempotencyKeySchema", () => {
+  it("accepts bounded ASCII keys", () => {
+    expect(IdempotencyKeySchema.parse("checkout_2026-07-30")).toBe("checkout_2026-07-30");
+    expect(IdempotencyKeySchema.parse("a".repeat(255))).toHaveLength(255);
+  });
+
+  it.each(["", " ", "key with spaces", "key/slash", "a".repeat(256)])(
+    "rejects unsafe key %j",
+    (value) => {
+      expect(IdempotencyKeySchema.safeParse(value).success).toBe(false);
+    },
+  );
+});
+
 // --------------------------------------------------------------------------
 // ValidationError
 // --------------------------------------------------------------------------
@@ -41,9 +56,7 @@ describe("ValidationError", () => {
     expect(err.name).toBe("ValidationError");
     expect(err.validator).toBe("test");
     expect(err.message).toBe("something went wrong");
-    expect(err.issues).toEqual([
-      { path: ["name"], message: "too short", code: "too_small" },
-    ]);
+    expect(err.issues).toEqual([{ path: ["name"], message: "too short", code: "too_small" }]);
     expect(err.input).toBe("ab");
   });
 
@@ -802,8 +815,8 @@ describe("formatValidationError", () => {
 // ---- mapZodError ----
 
 describe("mapZodError", () => {
-  it("returns custom code for checksum fail",()=>{
-    try{
+  it("returns custom code for checksum fail", () => {
+    try {
       StarknetAddress.parse("0x4718F5a0FC34Cc1AF16A1cdee98ffB20C31f5cd61d6ab07201858f4287c938d");
     } catch (e) {
       const mapped = mapZodError(e);

src/utils/validation.ts

@@ -435,6 +435,17 @@ export const AgreementId = z
   .trim()
   .regex(/^\d+$/, "agreement_id must be a numeric string");
 
+/**
+ * Shared schema for request idempotency keys.
+ *
+ * Keeping this constraint in one place prevents middleware from accepting
+ * different key formats and avoids storing whitespace or control characters
+ * in replay caches.
+ */
+export const IdempotencyKeySchema = z
+  .string()
+  .regex(/^[A-Za-z0-9_-]{1,255}$/, "Invalid idempotency key");
+
 export const MAX_PAGE_LIMIT = 100;
 
 export const DEFAULT_PAGE_LIMIT = 50;