Merge pull request #98 from UrumiAI/fix/qty-caps

[Service] Wire-level qty upper bounds on cart lines and /inventory/reserve

Author: vedanshujain

.changeset/qty-upper-bound.md

@@ -0,0 +1,37 @@
+---
+"@urumi/service": minor
+---
+
+Wire-level upper bounds on the three unbounded `qty` sites (service-hardening plan §4):
+`POST /carts/:cartId/lines`, `PATCH /carts/:cartId/lines/:lineId`, and
+`POST /inventory/reserve`. Today `qty: 1e9` (or `Number.MAX_SAFE_INTEGER`) is a "valid" wire
+request — only the store's arithmetic ever rejects it — so an absurd value reaches the store
+before anything says no. A zod `.max()` makes "how much may one request ask for" an explicit,
+documented, tested part of the contract instead of an accident of IEEE-754, and rejects it
+early and cheaply (400 at the schema boundary, before any store call and before any row is
+written).
+
+At `0.x`, changesets map a **minor** bump to a breaking change (there is no major to take yet —
+semver's `0.x` carve-out). The `minor` here IS the breaking bump, not a feature bump.
+
+**BREAKING (wire-visible):** previously-accepted requests now fail — `qty > 10_000`
+(`CART_LINE_MAX_QTY`, new exported constant) on `POST /carts/:cartId/lines` and
+`PATCH /carts/:cartId/lines/:lineId`, and `qty > 1_000_000_000` (`RESERVE_MAX_QTY`, new
+exported constant, aligned with the existing admin `stockMovementBody` cap) on
+`POST /inventory/reserve`, now return **400** `{error: "invalid request body", issues: [...]}`
+where they were previously accepted and processed. Both caps are two different numbers,
+deliberately: cart lines are the shopper-facing, anonymous-internet-caller surface (10k is
+already absurd for a storefront line); `/inventory/reserve` is the raw inventory primitive (a
+machine caller), whose natural peer is the admin stock-movement cap. Both are wire-only
+(zod, `schemas.ts`) — the domain already enforces the positive-integer bound
+(`domain/src/inventory/use-cases.ts`) as defense-in-depth; no domain or port change.
+
+**Scope — read before assuming this closes the abuse surface:** this cap does **not** stop
+junk-`failed`-reservation-row amplification or general write amplification on
+`POST /inventory/reserve` / `POST /carts/:id/lines`. That is bound by **request count**, not
+qty magnitude — a caller sending 10,000 requests at `qty: 9,999` (comfortably under either cap)
+mints exactly as many junk rows as one request at `qty: 1e9` did before this change. The real
+mitigation is rate limiting / abuse control on these two unauthenticated write endpoints, which
+this repo does not have. Follow-up filed and tracked at
+[UrumiAI/otta.sh#91](https://github.com/UrumiAI/otta.sh/issues/91) — do not read this PR as a
+DoS fix.

packages/service/src/schemas.ts

@@ -1,10 +1,31 @@
 import { z } from "zod";
 
+// Wire-level qty caps (service-hardening plan §4). Two different numbers,
+// deliberately: `/inventory/reserve` is the raw inventory primitive (a
+// machine caller, behind the write gate when configured) and is aligned with
+// the admin `stockMovementBody` cap below; cart lines are the shopper-facing,
+// anonymous-internet-caller surface and get a much tighter bound. Both are
+// WIRE-ONLY (zod) — the domain enforces the positive-integer bound too
+// (defense-in-depth; `domain/src/inventory/use-cases.ts`) — this caps the
+// wire value and makes "how much may one request ask for" an explicit, tested
+// part of the contract instead of an accident of IEEE-754 (today `qty: 1e9` /
+// `Number.MAX_SAFE_INTEGER` is a "valid" request that only the store's
+// arithmetic rejects).
+//
+// IMPORTANT — this is NOT a rate limit and does not fix junk-`failed`-
+// reservation-row amplification: that is bound by request COUNT, not qty
+// magnitude (10,000 requests at qty:9,999 each mint as many failed rows as
+// one request at qty:1e9). See the follow-up issue for rate-limiting
+// `POST /inventory/reserve` and `POST /carts/:id/lines`:
+// https://github.com/UrumiAI/otta.sh/issues/91
+export const CART_LINE_MAX_QTY = 10_000;
+export const RESERVE_MAX_QTY = 1_000_000_000;
+
 // Zod request bodies mirroring the inventory port 1:1 (§0.6). `Idempotency-Key`
 // travels as a header, not in the body.
 export const reserveBody = z.object({
 	sku: z.string().min(1),
-	qty: z.number().int().positive(),
+	qty: z.number().int().positive().max(RESERVE_MAX_QTY),
 });
 
 export const commitBody = z.object({
@@ -26,7 +47,7 @@ export const createCartBody = z.object({
 
 export const addLineBody = z.object({
 	sku: z.string().min(1),
-	qty: z.number().int().positive(),
+	qty: z.number().int().positive().max(CART_LINE_MAX_QTY),
 	// Phase 4: the product this line references. Optional for backward-compat with
 	// bare Phase-3 adds; REQUIRED to later check out (an order needs a priced
 	// product). When present, the service resolves the fulfillment kind from
@@ -35,7 +56,7 @@ export const addLineBody = z.object({
 });
 
 export const patchLineBody = z.object({
-	qty: z.number().int().positive(),
+	qty: z.number().int().positive().max(CART_LINE_MAX_QTY),
 });
 
 // Path-parameter sanity (N3): ids are opaque tokens — non-empty, bounded, and

packages/service/test/qty-bounds.test.ts

@@ -0,0 +1,230 @@
+import {
+	CountingIdGen,
+	FakeEmailSender,
+	FixedClock,
+	InMemoryAddressStore,
+	InMemoryCartStore,
+	InMemoryCouponStore,
+	InMemoryCredentialVerifier,
+	InMemoryCustomerStore,
+	InMemoryEntitlementStore,
+	InMemoryInventoryStore,
+	InMemoryOrderNotesStore,
+	InMemoryOrderStore,
+	InMemoryPaymentEventStore,
+	InMemoryProductCommerceStore,
+	InMemoryReportingStore,
+	InMemorySessionStore,
+	InMemorySettingsStore,
+	InMemoryShippingRulesStore,
+	InMemoryTaxRulesStore,
+} from "@urumi/domain/testing";
+import { StripePaymentGateway } from "@urumi/payments-stripe";
+import type { Hono } from "hono";
+import { describe, expect, test, vi } from "vitest";
+import { createApp } from "../src/app.js";
+import { CART_LINE_MAX_QTY, RESERVE_MAX_QTY } from "../src/schemas.js";
+
+// PR C — wire-level qty caps (service-hardening plan §4). Zod-only bounds on
+// the three qty sites that previously accepted any positive safe integer
+// (including 1e9): `addLineBody`/`patchLineBody` get a shopper-facing
+// CART_LINE_MAX_QTY (10,000); `reserveBody` gets the same 1,000,000,000 cap as
+// the admin `stockMovementBody` precedent (the raw inventory primitive, a
+// machine caller). The cap is a wire bound only — an over-cap request never
+// reaches the store, so no reservation row (successful or failed) is minted.
+// This does NOT fix junk-row/request-count amplification (see the linked
+// follow-up issue); it only closes the "qty: 1e9 is a valid wire request" gap.
+interface TestApp {
+	app: Hono;
+	inventory: InMemoryInventoryStore;
+}
+
+function makeApp(): TestApp {
+	const clock = new FixedClock(new Date("2026-07-26T00:00:00.000Z"));
+	const inventory = new InMemoryInventoryStore({
+		idGen: new CountingIdGen("res"),
+		clock,
+		seed: [{ sku: "SKU-1", onHand: 20_000 }],
+	});
+	const cartStore = new InMemoryCartStore({
+		idGen: new CountingIdGen("cart"),
+		reservationState: (id) => {
+			try {
+				return inventory.reservationState(id);
+			} catch {
+				return undefined;
+			}
+		},
+		releaseHold: (id) => {
+			void inventory.release(id);
+		},
+	});
+	const productCommerce = new InMemoryProductCommerceStore({
+		clock,
+		inventoryOnHand: (s) => inventory.onHand(s),
+	});
+	const idGen = new CountingIdGen("id");
+	const customerStore = new InMemoryCustomerStore({ idGen, clock });
+	const app = createApp({
+		store: inventory,
+		productCommerce,
+		cartStore,
+		orderStore: new InMemoryOrderStore({ idGen, clock }),
+		orderNotesStore: new InMemoryOrderNotesStore({ idGen, clock }),
+		entitlementStore: new InMemoryEntitlementStore({ idGen, clock }),
+		paymentEventStore: new InMemoryPaymentEventStore(),
+		shippingRules: new InMemoryShippingRulesStore(),
+		taxRules: new InMemoryTaxRulesStore(),
+		couponStore: new InMemoryCouponStore({ idGen, clock }),
+		reportingStore: new InMemoryReportingStore(),
+		settingsStore: new InMemorySettingsStore(),
+		customerStore,
+		addressStore: new InMemoryAddressStore({ idGen, clock }),
+		sessionStore: new InMemorySessionStore({ idGen, clock }),
+		credentialVerifier: new InMemoryCredentialVerifier({ customerStore, idGen, clock }),
+		emailSender: new FakeEmailSender(),
+		idGen,
+		gateways: { stripe: new StripePaymentGateway({ webhookSecret: "whsec_gate_test", clock }) },
+		clock,
+	});
+	return { app, inventory };
+}
+
+const json = { "content-type": "application/json" };
+
+async function newCart(app: Hono): Promise<string> {
+	const res = await app.request("/carts", { method: "POST", headers: json, body: "{}" });
+	expect(res.status).toBe(201);
+	const body = (await res.json()) as { cartId: string };
+	return body.cartId;
+}
+
+describe("PR C — cart line qty cap (CART_LINE_MAX_QTY)", () => {
+	test("POST /carts/:id/lines over cap is 400 with a structured error body", async () => {
+		const { app } = makeApp();
+		const cartId = await newCart(app);
+
+		const res = await app.request(`/carts/${cartId}/lines`, {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": "k1" },
+			body: JSON.stringify({ sku: "SKU-1", qty: CART_LINE_MAX_QTY + 1 }),
+		});
+
+		expect(res.status).toBe(400);
+		const body = (await res.json()) as { error: string; issues: unknown };
+		expect(body.error).toBe("invalid request body");
+		expect(body.issues).toBeDefined();
+	});
+
+	test("...and the store is never touched: reserve() not called, onHand unchanged", async () => {
+		const { app, inventory } = makeApp();
+		const cartId = await newCart(app);
+		const reserveSpy = vi.spyOn(inventory, "reserve");
+		const before = inventory.onHand("SKU-1");
+
+		const res = await app.request(`/carts/${cartId}/lines`, {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": "k1b" },
+			body: JSON.stringify({ sku: "SKU-1", qty: CART_LINE_MAX_QTY + 1 }),
+		});
+
+		expect(res.status).toBe(400);
+		expect(reserveSpy).not.toHaveBeenCalled();
+		expect(inventory.onHand("SKU-1")).toBe(before);
+	});
+
+	test("POST /carts/:id/lines at the CART_LINE_MAX_QTY boundary succeeds (200)", async () => {
+		const { app } = makeApp();
+		const cartId = await newCart(app);
+
+		const res = await app.request(`/carts/${cartId}/lines`, {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": "k2" },
+			body: JSON.stringify({ sku: "SKU-1", qty: CART_LINE_MAX_QTY }),
+		});
+
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as { ok: boolean };
+		expect(body.ok).toBe(true);
+	});
+
+	async function existingLineId(app: Hono, cartId: string, key: string): Promise<string> {
+		const addRes = await app.request(`/carts/${cartId}/lines`, {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": key },
+			body: JSON.stringify({ sku: "SKU-1", qty: 1 }),
+		});
+		const addBody = (await addRes.json()) as { line: { lineId: string } };
+		return addBody.line.lineId;
+	}
+
+	test("PATCH /carts/:id/lines/:lineId over cap is 400", async () => {
+		const { app } = makeApp();
+		const cartId = await newCart(app);
+		const lineId = await existingLineId(app, cartId, "k3");
+
+		const overCap = await app.request(`/carts/${cartId}/lines/${lineId}`, {
+			method: "PATCH",
+			headers: { ...json, "Idempotency-Key": "k4" },
+			body: JSON.stringify({ qty: CART_LINE_MAX_QTY + 1 }),
+		});
+		expect(overCap.status).toBe(400);
+	});
+
+	test("PATCH /carts/:id/lines/:lineId at the cap is 200", async () => {
+		const { app } = makeApp();
+		const cartId = await newCart(app);
+		const lineId = await existingLineId(app, cartId, "k3b");
+
+		const atCap = await app.request(`/carts/${cartId}/lines/${lineId}`, {
+			method: "PATCH",
+			headers: { ...json, "Idempotency-Key": "k5" },
+			body: JSON.stringify({ qty: CART_LINE_MAX_QTY }),
+		});
+		expect(atCap.status).toBe(200);
+	});
+
+	test("the exact QA repro — qty: 1e9 on a cart line — is now 400", async () => {
+		const { app } = makeApp();
+		const cartId = await newCart(app);
+
+		const res = await app.request(`/carts/${cartId}/lines`, {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": "k6" },
+			body: JSON.stringify({ sku: "SKU-1", qty: 1e9 }),
+		});
+
+		expect(res.status).toBe(400);
+	});
+});
+
+describe("PR C — POST /inventory/reserve qty cap (RESERVE_MAX_QTY, aligned with stockMovementBody)", () => {
+	test("qty: 1_000_000_001 is 400, reserve never called", async () => {
+		const { app, inventory } = makeApp();
+		const reserveSpy = vi.spyOn(inventory, "reserve");
+
+		const res = await app.request("/inventory/reserve", {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": "k7" },
+			body: JSON.stringify({ sku: "SKU-1", qty: RESERVE_MAX_QTY + 1 }),
+		});
+
+		expect(res.status).toBe(400);
+		expect(reserveSpy).not.toHaveBeenCalled();
+	});
+
+	test("qty: 1_000_000_000 reaches the store (200, OUT_OF_STOCK since it exceeds seeded on-hand)", async () => {
+		const { app } = makeApp();
+
+		const res = await app.request("/inventory/reserve", {
+			method: "POST",
+			headers: { ...json, "Idempotency-Key": "k8" },
+			body: JSON.stringify({ sku: "SKU-1", qty: RESERVE_MAX_QTY }),
+		});
+
+		expect(res.status).toBe(200);
+		const body = (await res.json()) as { ok: boolean; reason?: string };
+		expect(body.ok).toBe(false);
+		expect(body.reason).toBe("OUT_OF_STOCK");
+	});
+});