From e0ac65b8efe2126968fd01f3dac0fbee4b89ef34 Mon Sep 17 00:00:00 2001
From: snackman <samgold24@gmail.com>
Date: Sat, 6 Jun 2026 02:57:46 -0400
Subject: [PATCH] hardening: security headers/CSP, rate limiting, audit
 logging, service-role audit
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Production security hardening pass (Phase 7), layered on top of the existing
RLS + session-gated auth without weakening any auth/money/RLS correctness.
Zero new npm dependency; build + Vitest stay green with zero env vars.

- Security headers + CSP (src/lib/security/headers.ts, wired via next.config.ts
  headers()): strict static CSP (default-src 'self', object-src 'none',
  frame-ancestors 'none', enumerated connect/frame/script-src for Supabase +
  Stripe + Base RPC, upgrade-insecure-requests) + HSTS, X-Content-Type-Options,
  X-Frame-Options, Referrer-Policy, Permissions-Policy, COOP. No-nonce trade-off
  documented (middleware matches protected surfaces only).
- Rate limiting (src/lib/security/{rate-limit,http}.ts): zero-dep in-memory
  fixed-window limiter + route guard returning 429 + Retry-After. Applied to
  PIN, customer magic-link (per IP+email), order create, payment, refund.
  No-op under tests / RATE_LIMIT_DISABLED so CI + dev never throttle.
- Audit logging (src/lib/security/audit.ts + expanded AuditAction): tenant-
  scoped, fail-open coverage for staff/admin sign-in, PIN switch, refund/void,
  menu 86, Connect change, subscription change, tenant go-live.
- Service-role audit (PRODUCTION_READINESS §11d): inventory confirms the
  service-role key is used only by the driver, every tenant query carries an
  explicit tenant_id/location_id filter. Fixed an authz gap: the refund
  endpoint had NO auth (any caller could refund any payment) — now requires
  tenant membership; Connect start now requires owner|manager.
- Input validation (src/lib/security/validate.ts): 256 KB body cap (413),
  non-negative integer money guards, bounded id/email guards on the money +
  auth routes.
- Tests: rate limiter, HTTP guard/no-op, validators, CSP/headers, audit
  (incl. fail-open). 150 tests pass; typecheck + lint + build green, zero env.
- Threat model: plans/arrabbiata-71129-phase-7-security-hardening.md.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 docs/PRODUCTION_READINESS.md                  | 145 ++++++++++++++++++
 next.config.ts                                |  12 ++
 ...bbiata-71129-phase-7-security-hardening.md |  63 ++++++++
 src/app/api/admin/overrides/route.ts          |  31 +++-
 src/app/api/billing/route.ts                  |  37 ++++-
 src/app/api/connect/route.ts                  |  26 +++-
 src/app/api/orders/route.ts                   |  16 +-
 src/app/api/payments/refund/route.ts          |  52 ++++++-
 src/app/api/payments/route.ts                 |  28 +++-
 src/app/api/shop/auth/magic-link/route.ts     |  25 ++-
 src/app/api/signup/route.ts                   |  23 ++-
 src/app/api/terminal/pin/route.ts             |  25 ++-
 src/app/auth/callback/route.ts                |  38 +++++
 src/lib/db/saas-types.ts                      |  26 +++-
 src/lib/security/audit.test.ts                |  49 ++++++
 src/lib/security/audit.ts                     |  70 +++++++++
 src/lib/security/headers.test.ts              |  51 ++++++
 src/lib/security/headers.ts                   | 129 ++++++++++++++++
 src/lib/security/http.test.ts                 |  42 +++++
 src/lib/security/http.ts                      |  96 ++++++++++++
 src/lib/security/index.ts                     |  11 ++
 src/lib/security/rate-limit.test.ts           |  78 ++++++++++
 src/lib/security/rate-limit.ts                | 138 +++++++++++++++++
 src/lib/security/validate.test.ts             |  86 +++++++++++
 src/lib/security/validate.ts                  |  85 ++++++++++
 25 files changed, 1337 insertions(+), 45 deletions(-)
 create mode 100644 plans/arrabbiata-71129-phase-7-security-hardening.md
 create mode 100644 src/lib/security/audit.test.ts
 create mode 100644 src/lib/security/audit.ts
 create mode 100644 src/lib/security/headers.test.ts
 create mode 100644 src/lib/security/headers.ts
 create mode 100644 src/lib/security/http.test.ts
 create mode 100644 src/lib/security/http.ts
 create mode 100644 src/lib/security/index.ts
 create mode 100644 src/lib/security/rate-limit.test.ts
 create mode 100644 src/lib/security/rate-limit.ts
 create mode 100644 src/lib/security/validate.test.ts
 create mode 100644 src/lib/security/validate.ts

diff --git a/docs/PRODUCTION_READINESS.md b/docs/PRODUCTION_READINESS.md
index 547687b..a767a05 100644
--- a/docs/PRODUCTION_READINESS.md
+++ b/docs/PRODUCTION_READINESS.md
@@ -344,3 +344,148 @@ secrets**). Everything is optional; the app builds + the suite passes with none.
 - [ ] Hardware field test (reader, printer, drawer, tablet) — separate from this
       code phase.
 - [ ] Re-run the full Vitest suite + production build with the live env; both green.
+
+---
+
+## 11. Security hardening (headers/CSP, rate limiting, audit, service-role)
+
+Defense-in-depth added in the hardening pass, layered on top of (never replacing)
+RLS + the session-gated auth model. All of it is **zero-env safe** (build + Vitest
+green with no env) and adds **no new npm dependency**. Code lives under
+`src/lib/security/*`; the threat model is in
+`plans/arrabbiata-71129-phase-7-security-hardening.md`.
+
+### 11a. Security headers + Content-Security-Policy
+
+Applied to **every** route via `next.config.ts` `headers()` (source
+`src/lib/security/headers.ts`), so `/shop`, `/`, and static routes are covered too
+(middleware only matches the protected surfaces). Static values — no env reads.
+
+| Header | Value (summary) | Defends |
+|---|---|---|
+| `Content-Security-Policy` | `default-src 'self'`; enumerated `script/style/img/font/connect/frame/worker/manifest-src`; `object-src 'none'`; `base-uri 'self'`; `form-action 'self'`; `frame-ancestors 'none'`; `upgrade-insecure-requests` | XSS, injection, clickjacking, downgrade |
+| `Strict-Transport-Security` | `max-age=63072000; includeSubDomains; preload` | HTTPS downgrade/MITM (inert on localhost) |
+| `X-Content-Type-Options` | `nosniff` | MIME-sniffing |
+| `X-Frame-Options` | `DENY` | clickjacking (legacy companion to `frame-ancestors`) |
+| `Referrer-Policy` | `strict-origin-when-cross-origin` | referrer leakage |
+| `Permissions-Policy` | `camera=()`, `microphone=()`, `geolocation=()`, `payment=(self)`, `usb=()`, … | feature abuse |
+| `Cross-Origin-Opener-Policy` | `same-origin` | cross-origin tab interference |
+
+**CSP nonce/hashing approach — documented trade-off.** The policy is **static**
+(no per-request nonce). Next.js App Router injects framework **inline** runtime
+scripts on every page; a nonce-based `script-src` would require minting a nonce in
+middleware and threading it through the document, but this app's middleware
+intentionally matches the protected surfaces only (`/admin|/terminal|/kitchen|
+/platform`) — `/shop`, `/`, and statically-rendered routes are not matched, so a
+nonce cannot be applied uniformly without broadening the matcher (out of scope and
+it would break static optimisation). We therefore allow `script-src 'self'
+'unsafe-inline'` (+ Stripe origins). This is weaker than a nonce, but the app
+ships **no author-controlled inline scripts** (no inline `<script>`, no
+`dangerouslySetInnerHTML`), so the practical XSS surface is small, and every other
+directive is locked down. **Upgrade path:** mint a nonce in middleware, broaden the
+matcher to all routes, set `script-src 'self' 'nonce-…' 'strict-dynamic'`, and pass
+the nonce into the root layout. `connect-src`/`frame-src` are a superset of mock-
+and live-mode origins (Supabase REST+WSS, Stripe API/JS, Base RPC) so a later env
+flip needs no header change. The PWA service worker is covered by `worker-src
+'self' blob:`.
+
+> **Go-live check:** load the deployed preview, open devtools → Network → the
+> document response, confirm the headers above are present, and watch the Console
+> for any CSP violation while exercising terminal/shop/admin (esp. Stripe.js +
+> Supabase Realtime). If a needed origin is blocked, add it to the relevant
+> directive in `headers.ts` (do not loosen `script-src`).
+
+### 11b. Rate limiting
+
+Zero-dependency in-memory **fixed-window** limiter (`src/lib/security/rate-limit.ts`)
++ a route-handler guard (`enforceRateLimit` in `http.ts`) that derives the client
+IP from `x-forwarded-for`/`x-real-ip`, limits per-IP (and per-account/email where
+sensible), and returns **429 + `Retry-After` + `RateLimit-*`** headers. **No-op
+when disabled** (`RATE_LIMIT_DISABLED`) or under tests (`VITEST`/`NODE_ENV=test`),
+so CI/dev never throttle.
+
+| Endpoint | Bucket (limit / 60s) | Keys |
+|---|---|---|
+| `POST /api/terminal/pin` | `pin` (8) | IP |
+| `POST /api/shop/auth/magic-link` | `auth` (10) | IP + email |
+| `POST /api/orders` | `orders` (60) | IP |
+| `POST /api/payments` | `payments` (30) | IP |
+| `POST /api/payments/refund` | `payments` (30) | IP |
+
+**Coverage note for tenant/platform login:** the `/login` + `/platform/login`
+forms call Supabase Auth **directly from the browser** (`signInWithOtp`/
+`signInWithPassword`) — there is no first-party server endpoint to limit, and
+Supabase enforces its own auth rate limits. The customer **magic-link** flow does
+go through a server route and is limited above; the staff **PIN** path (the only
+first-party credential check) is limited strictly.
+
+**Caveat:** the store is **process-local**, so on serverless each instance keeps
+its own window and the effective global limit scales with instance count. This is
+a deliberate no-new-dep trade-off; for a hard global limit, swap `defaultLimiter`
+for a shared store (Redis/Upstash) — call sites are unchanged.
+
+### 11c. Audit logging (broadened)
+
+Coverage of the existing append-only, tenant-scoped `audit_log` is broadened beyond
+platform impersonation/lifecycle via a fail-open helper (`recordAudit` in
+`src/lib/security/audit.ts` — it never throws, so a logging failure can't break the
+primary action). New `AuditAction` values + where they are written:
+
+| Action | Written at | Tenant-scoped |
+|---|---|---|
+| `auth_sign_in` | `/auth/callback` after a successful code exchange (one entry per membership; platform admins get a null-tenant entry; customers not audited) | yes (per membership) |
+| `staff_pin_switch` | `/api/terminal/pin` on a verified PIN switch | yes |
+| `payment_refund` / `payment_void` | `/api/payments/refund` (void = fully refunded) | yes |
+| `menu_86` | `/api/admin/overrides` when availability is set false | yes |
+| `connect_change` | `/api/connect` on Connect onboarding start/refresh | yes |
+| `subscription_change` | `/api/billing` on subscribe / tier change / status advance | yes |
+| `tenant_go_live` | `/api/signup` `go_live` | yes |
+| `membership_change` | *reserved* — no dedicated member-management route yet; action defined for when one lands | yes |
+
+Pre-existing (unchanged): `impersonate_start/end`, `tenant_suspend/reactivate`,
+`subscription_override`. All surface read-only in `/platform`.
+
+### 11d. Service-role key inventory + review (T8)
+
+The service-role key (`SUPABASE_SERVICE_ROLE_KEY`) **bypasses RLS**, so every use
+must be a trusted server op with an explicit tenant filter. Inventory after review:
+
+- **Single construction site:** `src/lib/db/supabase.ts` →
+  `readSupabaseConfig()` builds **one** `@supabase/supabase-js` client, preferring
+  the service-role key (falling back to anon) on the server. This is the live
+  `PosDriver`. It is the **only** code that reads the service-role key (verified by
+  grep: the only other hit is a doc comment in `src/lib/auth/api.ts`).
+- **Justification:** the driver implements the full server-side data contract
+  (route handlers / RSC) for background + cross-cutting writes (order intake,
+  payment persistence, reports) where there is no end-user RLS session; RLS remains
+  the DB backstop and the **session is the gate** (route guards in
+  `src/lib/auth/api.ts` re-check membership against the request's tenant).
+- **Tenant-scoping audit (the key risk):** every tenant-scoped read/write in the
+  driver carries an explicit `.eq("tenant_id", …)` (and `.eq("location_id", …)`
+  where applicable): tenants/locations/menu/orders/payments/inventory/staff/shifts/
+  reports/settings/subscriptions/onboarding/audit all filter by tenant. By-id
+  lookups used internally (`getOrder`, `getPayment`, `getStaffById`,
+  `getDrawerReconciliation`) are reached only after the route layer has authorized
+  the caller for that object's tenant. **No un-scoped tenant query was found.**
+- **User-scoped (RLS) path is used where it belongs:** the auth flows use
+  `getServerSupabase()` (anon key + the user's session cookie → RLS-enforced), **not**
+  the service-role client — the correct split. `pin_hash` is only carried on the
+  server PIN-verification path (`getStaffById`) and stripped from list/upsert
+  results.
+- **Finding / fix:** `POST /api/payments/refund` previously performed a refund from
+  a client-supplied `paymentId` with **no authorization** — any caller could refund
+  any payment. Fixed: it now loads the payment, derives its tenant, and requires
+  `requireTenantMember(tenant)` before refunding (and audits the result).
+  `POST /api/connect` similarly gained an `owner|manager` check (money-routing).
+- **Go-live:** keep the service-role key server-only (never `NEXT_PUBLIC_*`); store
+  it in a secret manager; rotate on exposure. The driver's tenant-filter invariant
+  is the load-bearing control — keep it covered by `tenant-isolation.test.ts`.
+
+### 11e. Input validation (T9)
+
+Dependency-free guards (`src/lib/security/validate.ts`): `readJsonBody` enforces a
+**256 KB** body cap (413) before/after decode and rejects empty/invalid JSON (400);
+`isMoneyCents` rejects negative/NaN/fractional/absurd amounts; `isClientId` bounds
+length + allowlists charset; `isEmail` bounds + shape-checks. Wired into the
+order/payment/refund/PIN/magic-link routes (the money + auth paths). Existing
+domain-level validation (scheduling, zone gates, idempotency) is unchanged.
diff --git a/next.config.ts b/next.config.ts
index 8eb9c11..f7efb38 100644
--- a/next.config.ts
+++ b/next.config.ts
@@ -1,12 +1,24 @@
 import path from "node:path";
 import type { NextConfig } from "next";
 import withSerwistInit from "@serwist/next";
+import { SECURITY_HEADERS } from "./src/lib/security/headers";
 
 const nextConfig: NextConfig = {
   reactStrictMode: true,
   // Pin the workspace root to this project. A stray lockfile in a parent
   // directory can otherwise cause Next to infer the wrong root for file tracing.
   outputFileTracingRoot: path.join(__dirname),
+  // Security headers + CSP applied to EVERY route (Phase 7 hardening). Static
+  // (no env reads) so the zero-env build is unaffected; see
+  // src/lib/security/headers.ts for the CSP design + no-nonce trade-off.
+  async headers() {
+    return [
+      {
+        source: "/:path*",
+        headers: SECURITY_HEADERS,
+      },
+    ];
+  },
 };
 
 /**
diff --git a/plans/arrabbiata-71129-phase-7-security-hardening.md b/plans/arrabbiata-71129-phase-7-security-hardening.md
new file mode 100644
index 0000000..314772a
--- /dev/null
+++ b/plans/arrabbiata-71129-phase-7-security-hardening.md
@@ -0,0 +1,63 @@
+# Phase 7 — Production Security Hardening
+
+> Security-hardening pass on the multi-tenant SaaS pizzeria POS. Adds defense-in-depth
+> on top of the existing RLS + session-gated auth, without weakening any existing
+> auth/money/RLS correctness. Everything stays **zero-env safe** (build + Vitest green
+> with no environment variables) and adds **no new npm dependency**.
+
+## Scope
+
+In: security headers + CSP, rate limiting, broadened audit logging, service-role
+inventory/review, input validation hardening, threat-model doc.
+
+Out (owned by other agents / out of this pass): the realtime layer
+(`src/lib/realtime/*`), Playwright/E2E, any `package.json` change, any change to
+RLS policies or the money/auth correctness model.
+
+## Threat model addressed
+
+| # | Threat | Vector | Mitigation in this pass |
+|---|---|---|---|
+| T1 | **XSS / script injection** | Reflected/stored script, malicious 3rd-party script, inline injection | Strict **CSP** (`default-src 'self'`, `object-src 'none'`, enumerated `script/connect/frame-src`), `X-Content-Type-Options: nosniff`. App ships **no** author inline scripts / `dangerouslySetInnerHTML`. |
+| T2 | **Clickjacking** | App framed by an attacker page to trick staff clicks | `frame-ancestors 'none'` (CSP) + legacy `X-Frame-Options: DENY`. |
+| T3 | **Protocol downgrade / MITM** | Plain-HTTP interception, mixed content | `Strict-Transport-Security` (2y, preload, subdomains) + `upgrade-insecure-requests`. Inert on localhost. |
+| T4 | **Referrer / capability leakage** | URLs + powerful browser features leaking to 3rd parties | `Referrer-Policy: strict-origin-when-cross-origin`; `Permissions-Policy` denies camera/mic/geo/usb, `payment=(self)`. |
+| T5 | **Credential brute-force** | Automated guessing of staff **PIN**, magic-link spam / email-bombing | Per-IP (+ per-account where sensible) **rate limiting** on PIN, magic-link, returning **429 + Retry-After**. |
+| T6 | **Order / payment abuse** | Automated order spam, card-testing via repeated charge/refund attempts | Rate limiting on order-create + payment + refund endpoints. |
+| T7 | **Repudiation / lack of traceability** | Sensitive action taken with no trail (refund, 86, Connect change, sign-in, go-live) | Broadened **audit_log** coverage, tenant-scoped, append-only, surfaced in `/platform`. |
+| T8 | **Service-role over-reach** | Service-role key bypasses RLS; a missing tenant filter = cross-tenant leak | **Inventory + review** of every service-role call site (all in the driver); confirmed every tenant-scoped query carries an explicit `tenant_id`/`location_id` filter. Documented in PRODUCTION_READINESS §11. |
+| T9 | **Malformed / oversized input** | Junk payloads, negative/NaN money, giant bodies (DoS) | Hardened validators (money = non-negative int cents; bounded ids/emails) + a **256 KB body cap** on sensitive routes (413). |
+| T10 | **Broken object-level authZ** | Acting on another tenant's object by id (notably the refund endpoint had **no** auth) | Refund + Connect endpoints now resolve the target's tenant and require `requireTenantMember`/`owner|manager`. |
+
+## Design decisions
+
+- **No new dependency.** Rate limiting is a zero-dep in-memory fixed-window
+  limiter (`src/lib/security/rate-limit.ts`). Validation uses dependency-free
+  guards (no zod). CSP/headers are static.
+- **Zero-env / test no-op.** Rate limiting is disabled under `VITEST` /
+  `NODE_ENV=test` / `RATE_LIMIT_DISABLED`, so the suite + local dev never trip a
+  limit. The limiter + validators + audit are unit-tested directly regardless.
+- **Static CSP, no nonce** (trade-off documented in `src/lib/security/headers.ts`
+  and PRODUCTION_READINESS §11): middleware runs on protected surfaces only, so a
+  per-request nonce can't be applied uniformly without broadening the matcher
+  (out of scope). `script-src` therefore allows `'unsafe-inline'`; every other
+  vector is locked down and the app ships no author inline scripts.
+- **Audit is fail-open.** `recordAudit` never throws — a logging hiccup must not
+  fail a refund or a login. It is tenant-scoped via the existing `audit_log`.
+- **Process-local rate limiter caveat:** on serverless each instance has its own
+  window, so the global limit scales with concurrency. Acceptable for blunting a
+  single-source brute-force without an external store; swap `defaultLimiter` for
+  a shared store later with no call-site change.
+
+## Files
+
+New: `src/lib/security/{rate-limit,http,audit,validate,headers,index}.ts` (+ tests).
+Edited: `next.config.ts` (headers), `src/lib/db/saas-types.ts` (AuditAction),
+and the sensitive routes (orders, payments, payments/refund, terminal/pin,
+shop/auth/magic-link, admin/overrides, connect, billing, signup, auth/callback).
+
+## Verification
+
+`npm run typecheck && npm run lint && npm run build && npm run test:run` all green
+with **no env vars**. New tests cover the limiter, the HTTP guard/no-op,
+validators, CSP/headers, and the audit helper (incl. fail-open).
diff --git a/src/app/api/admin/overrides/route.ts b/src/app/api/admin/overrides/route.ts
index 37aef20..83c687d 100644
--- a/src/app/api/admin/overrides/route.ts
+++ b/src/app/api/admin/overrides/route.ts
@@ -16,6 +16,7 @@ import {
   type OverrideTargetType,
 } from "@/lib/db";
 import { requireTenantRole } from "@/lib/auth/api";
+import { recordAudit } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -40,7 +41,12 @@ export async function POST(request: Request) {
   } catch {
     return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
   }
-  if (!body.tenant_id || !body.location_id || !body.target_type || !body.target_id) {
+  if (
+    !body.tenant_id ||
+    !body.location_id ||
+    !body.target_type ||
+    !body.target_id
+  ) {
     return NextResponse.json(
       { error: "tenant_id, location_id, target_type, target_id are required." },
       { status: 422 },
@@ -49,6 +55,18 @@ export async function POST(request: Request) {
   const auth = await requireTenantRole(body.tenant_id, ["owner", "manager"]);
   if (!auth.ok) return auth.res;
   const override = await getPosDriver().upsertOverride(body);
+
+  // Audit a menu "86" (availability turned off) — a sensitive, customer-visible
+  // catalogue change worth a tenant-scoped trail.
+  if (body.available === false) {
+    await recordAudit({
+      actor: { id: auth.user.id, label: auth.user.email },
+      action: "menu_86",
+      tenantId: body.tenant_id,
+      detail: `86'd ${body.target_type} ${body.target_id} at location ${body.location_id}.`,
+    });
+  }
+
   return NextResponse.json({ override }, { status: 201 });
 }
 
@@ -56,7 +74,9 @@ export async function DELETE(request: Request) {
   const { searchParams } = new URL(request.url);
   const tenantId = searchParams.get("tenantId");
   const locationId = searchParams.get("locationId");
-  const targetType = searchParams.get("targetType") as OverrideTargetType | null;
+  const targetType = searchParams.get(
+    "targetType",
+  ) as OverrideTargetType | null;
   const targetId = searchParams.get("targetId");
   if (!tenantId || !locationId || !targetType || !targetId) {
     return NextResponse.json(
@@ -66,6 +86,11 @@ export async function DELETE(request: Request) {
   }
   const auth = await requireTenantRole(tenantId, ["owner", "manager"]);
   if (!auth.ok) return auth.res;
-  await getPosDriver().clearOverride(tenantId, locationId, targetType, targetId);
+  await getPosDriver().clearOverride(
+    tenantId,
+    locationId,
+    targetType,
+    targetId,
+  );
   return NextResponse.json({ ok: true });
 }
diff --git a/src/app/api/billing/route.ts b/src/app/api/billing/route.ts
index 401d4f1..9377e86 100644
--- a/src/app/api/billing/route.ts
+++ b/src/app/api/billing/route.ts
@@ -17,17 +17,31 @@ import { getPosDriver, type PlanTier, type SubscriptionStatus } from "@/lib/db";
 import { getPlans } from "@/lib/saas/plans";
 import { resolveEntitlements } from "@/lib/saas/entitlements";
 import { subscribeTenant, isBillingSimulated } from "@/lib/billing/service";
+import { getCurrentUser } from "@/lib/auth/session";
+import { recordAudit } from "@/lib/security";
 
 export const runtime = "nodejs";
 
+/** Best-effort tenant-scoped audit of a subscription/billing change. */
+async function auditBilling(tenantId: string, detail: string): Promise<void> {
+  const actor = await getCurrentUser();
+  await recordAudit({
+    actor: {
+      id: actor?.id ?? "system",
+      label: actor?.email ?? "billing",
+    },
+    action: "subscription_change",
+    tenantId,
+    detail,
+  });
+}
+
 export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
   const tenantId = searchParams.get("tenantId");
   const driver = getPosDriver();
   const plans = getPlans();
-  const subscription = tenantId
-    ? await driver.getSubscription(tenantId)
-    : null;
+  const subscription = tenantId ? await driver.getSubscription(tenantId) : null;
   const entitlements = resolveEntitlements(subscription);
   return NextResponse.json({
     plans,
@@ -52,7 +66,10 @@ export async function POST(request: Request) {
     return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
   }
   if (!body.tenantId) {
-    return NextResponse.json({ error: "tenantId is required." }, { status: 422 });
+    return NextResponse.json(
+      { error: "tenantId is required." },
+      { status: 422 },
+    );
   }
   const driver = getPosDriver();
 
@@ -74,6 +91,10 @@ export async function POST(request: Request) {
           { status: 404 },
         );
       }
+      await auditBilling(
+        body.tenantId,
+        `Subscription status advanced to ${body.status}.`,
+      );
       return NextResponse.json({ subscription: updated });
     }
 
@@ -95,6 +116,10 @@ export async function POST(request: Request) {
       );
       // Mark the plan step complete on the wizard if mid-onboarding.
       await driver.completeOnboardingStep(body.tenantId, "plan");
+      await auditBilling(
+        body.tenantId,
+        `Subscription tier changed ${existing.tier} → ${body.tier}.`,
+      );
       return NextResponse.json({
         subscription: switched,
         checkoutUrl: null,
@@ -123,6 +148,10 @@ export async function POST(request: Request) {
     });
     const subscription = await driver.upsertSubscription(result.subscription);
     await driver.completeOnboardingStep(body.tenantId, "plan");
+    await auditBilling(
+      body.tenantId,
+      `Subscribed to ${body.tier} plan${result.simulated ? " (simulated)" : ""}.`,
+    );
 
     return NextResponse.json({
       subscription,
diff --git a/src/app/api/connect/route.ts b/src/app/api/connect/route.ts
index cfa9728..f066318 100644
--- a/src/app/api/connect/route.ts
+++ b/src/app/api/connect/route.ts
@@ -20,6 +20,8 @@ import {
   fetchConnectStatus,
   isSimulated,
 } from "@/lib/payments/connect";
+import { requireTenantRole } from "@/lib/auth/api";
+import { recordAudit } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -62,6 +64,11 @@ export async function POST(request: Request) {
     );
   }
 
+  // Only an owner|manager of the tenant may start/modify Connect onboarding —
+  // this controls where the tenant's card revenue settles.
+  const auth = await requireTenantRole(body.tenantId, ["owner", "manager"]);
+  if (!auth.ok) return auth.res;
+
   const driver = getPosDriver();
   try {
     // Reuse an existing account if onboarding was already started.
@@ -93,10 +100,25 @@ export async function POST(request: Request) {
       refreshUrl,
     );
 
-    return NextResponse.json({ account, onboardingUrl, simulated: isSimulated() });
+    // Audit the Connect change (tenant-scoped) — a money-routing-sensitive op.
+    await recordAudit({
+      actor: { id: auth.user.id, label: auth.user.email },
+      action: "connect_change",
+      tenantId: body.tenantId,
+      detail: `Stripe Connect onboarding ${isSimulated() ? "(simulated) " : ""}started/refreshed; account ${account.account_id}, status ${account.status}.`,
+    });
+
+    return NextResponse.json({
+      account,
+      onboardingUrl,
+      simulated: isSimulated(),
+    });
   } catch (err) {
     return NextResponse.json(
-      { error: err instanceof Error ? err.message : "Connect onboarding failed." },
+      {
+        error:
+          err instanceof Error ? err.message : "Connect onboarding failed.",
+      },
       { status: 502 },
     );
   }
diff --git a/src/app/api/orders/route.ts b/src/app/api/orders/route.ts
index 8698a52..58dcd11 100644
--- a/src/app/api/orders/route.ts
+++ b/src/app/api/orders/route.ts
@@ -13,6 +13,7 @@
 import { NextResponse } from "next/server";
 import { getPosDriver, type CreateOrderInput } from "@/lib/db";
 import { requireTenantMember } from "@/lib/auth/api";
+import { enforceRateLimit, readJsonBody } from "@/lib/security";
 import {
   captureError,
   childLogger,
@@ -42,15 +43,18 @@ export async function POST(request: Request) {
   const log = childLogger({ requestId, route: "POST /api/orders" });
   const headers = traceResponseHeaders(requestId);
 
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
+  // Rate-limit order creation per IP to blunt automated order spam / abuse.
+  const limited = enforceRateLimit(request, "orders");
+  if (limited) return limited;
+
+  const parsed = await readJsonBody(request);
+  if (!parsed.ok) {
     return NextResponse.json(
-      { error: "Invalid JSON body." },
-      { status: 400, headers },
+      { error: parsed.error },
+      { status: parsed.status, headers },
     );
   }
+  const body = parsed.body;
 
   if (!isValidPayload(body)) {
     return NextResponse.json(
diff --git a/src/app/api/payments/refund/route.ts b/src/app/api/payments/refund/route.ts
index efcd208..23cecaa 100644
--- a/src/app/api/payments/refund/route.ts
+++ b/src/app/api/payments/refund/route.ts
@@ -10,6 +10,13 @@ import { NextResponse } from "next/server";
 import { refundPayment } from "@/lib/payments/service";
 import { getOrderBalance } from "@/lib/payments/service";
 import { getPosDriver } from "@/lib/db";
+import { requireTenantMember } from "@/lib/auth/api";
+import {
+  enforceRateLimit,
+  isMoneyCents,
+  readJsonBody,
+  recordAudit,
+} from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -20,19 +27,41 @@ interface RefundBody {
 }
 
 export async function POST(request: Request) {
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
+  // Refunds move money out — rate-limit + audit every one.
+  const limited = enforceRateLimit(request, "payments");
+  if (limited) return limited;
+
+  const parsed = await readJsonBody(request);
+  if (!parsed.ok) {
+    return NextResponse.json(
+      { error: parsed.error },
+      { status: parsed.status },
+    );
   }
-  const b = body as RefundBody;
+  const b = parsed.body as RefundBody;
   if (!b || typeof b.paymentId !== "string") {
     return NextResponse.json(
       { error: "paymentId is required." },
       { status: 422 },
     );
   }
+  if (b.amountCents !== undefined && !isMoneyCents(b.amountCents)) {
+    return NextResponse.json(
+      { error: "amountCents must be a non-negative integer." },
+      { status: 422 },
+    );
+  }
+
+  const driver = getPosDriver();
+
+  // The refund targets a specific payment; resolve it first so we can authorize
+  // the caller against THAT payment's tenant (not a client-supplied tenant).
+  const existingPayment = await driver.getPayment(b.paymentId);
+  if (!existingPayment) {
+    return NextResponse.json({ error: "Payment not found." }, { status: 404 });
+  }
+  const auth = await requireTenantMember(existingPayment.tenant_id);
+  if (!auth.ok) return auth.res;
 
   try {
     const payment = await refundPayment({
@@ -46,9 +75,18 @@ export async function POST(request: Request) {
         { status: 404 },
       );
     }
-    const driver = getPosDriver();
     const order = await driver.getOrder(payment.order_id);
     const balance = order ? await getOrderBalance(order) : 0;
+
+    // Audit the refund (tenant-scoped). Fully-refunded ⇒ a void of the tender.
+    const fullyRefunded = payment.refunded_cents >= payment.amount_cents;
+    await recordAudit({
+      actor: { id: auth.user.id, label: auth.user.email },
+      action: fullyRefunded ? "payment_void" : "payment_refund",
+      tenantId: payment.tenant_id,
+      detail: `Refunded ${b.amountCents ?? payment.amount_cents}¢ on payment ${payment.id} (order ${payment.order_id})${b.reason ? ` — ${b.reason}` : ""}.`,
+    });
+
     return NextResponse.json({
       payment,
       balanceCents: balance,
diff --git a/src/app/api/payments/route.ts b/src/app/api/payments/route.ts
index 5af2119..cdf9b2d 100644
--- a/src/app/api/payments/route.ts
+++ b/src/app/api/payments/route.ts
@@ -16,6 +16,7 @@ import { NextResponse } from "next/server";
 import { getPosDriver } from "@/lib/db";
 import type { PaymentRailKey } from "@/lib/payments/PaymentRail";
 import { takePayment, getOrderBalance } from "@/lib/payments/service";
+import { enforceRateLimit, isMoneyCents, readJsonBody } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -41,18 +42,28 @@ function isValid(body: unknown): body is TakePaymentBody {
     typeof b.tenantId === "string" &&
     typeof b.locationId === "string" &&
     typeof b.rail === "string" &&
-    typeof b.amountCents === "number" &&
+    // Amount + optional tip must be non-negative integer cents (reject NaN /
+    // negative / fractional / absurd values before they reach the rail).
+    isMoneyCents(b.amountCents) &&
+    (b.tipCents === undefined || isMoneyCents(b.tipCents)) &&
+    (b.cashTenderedCents === undefined || isMoneyCents(b.cashTenderedCents)) &&
     typeof b.currency === "string"
   );
 }
 
 export async function POST(request: Request) {
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
+  // Rate-limit payment capture per IP to blunt charge-spam / card-testing abuse.
+  const limited = enforceRateLimit(request, "payments");
+  if (limited) return limited;
+
+  const parsed = await readJsonBody(request);
+  if (!parsed.ok) {
+    return NextResponse.json(
+      { error: parsed.error },
+      { status: parsed.status },
+    );
   }
+  const body = parsed.body;
   if (!isValid(body)) {
     return NextResponse.json(
       { error: "Malformed payment payload." },
@@ -106,7 +117,10 @@ export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
   const orderId = searchParams.get("orderId");
   if (!orderId) {
-    return NextResponse.json({ error: "orderId is required." }, { status: 400 });
+    return NextResponse.json(
+      { error: "orderId is required." },
+      { status: 400 },
+    );
   }
   const driver = getPosDriver();
   const order = await driver.getOrder(orderId);
diff --git a/src/app/api/shop/auth/magic-link/route.ts b/src/app/api/shop/auth/magic-link/route.ts
index 4f764bd..08f7782 100644
--- a/src/app/api/shop/auth/magic-link/route.ts
+++ b/src/app/api/shop/auth/magic-link/route.ts
@@ -22,6 +22,7 @@ import {
   getServerSupabase,
   isSupabaseAuthConfigured,
 } from "@/lib/auth/supabase-server";
+import { enforceRateLimit, isEmail, readJsonBody } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -34,20 +35,30 @@ interface Body {
 function isValid(body: unknown): body is Body {
   if (!body || typeof body !== "object") return false;
   const b = body as Record<string, unknown>;
-  return typeof b.locationSlug === "string" && typeof b.email === "string";
+  return typeof b.locationSlug === "string" && isEmail(b.email);
 }
 
 export async function POST(request: Request) {
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
+  const parsed = await readJsonBody(request);
+  if (!parsed.ok) {
+    return NextResponse.json(
+      { error: parsed.error },
+      { status: parsed.status },
+    );
   }
+  const body = parsed.body;
   if (!isValid(body)) {
-    return NextResponse.json({ error: "email is required." }, { status: 422 });
+    return NextResponse.json(
+      { error: "A valid email is required." },
+      { status: 422 },
+    );
   }
 
+  // Rate-limit magic-link sends per IP and per target email to blunt
+  // email-bombing / enumeration. (Auth bucket: strict.)
+  const limited = enforceRateLimit(request, "auth", { keys: [body.email] });
+  if (limited) return limited;
+
   const driver = getPosDriver();
   const location = await driver.getLocationBySlug(body.locationSlug);
   if (!location) {
diff --git a/src/app/api/signup/route.ts b/src/app/api/signup/route.ts
index 646ee85..25a2398 100644
--- a/src/app/api/signup/route.ts
+++ b/src/app/api/signup/route.ts
@@ -16,6 +16,8 @@
  */
 import { NextResponse } from "next/server";
 import { getPosDriver } from "@/lib/db";
+import { getCurrentUser } from "@/lib/auth/session";
+import { recordAudit } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -23,7 +25,10 @@ export async function GET(request: Request) {
   const { searchParams } = new URL(request.url);
   const tenantId = searchParams.get("tenantId");
   if (!tenantId) {
-    return NextResponse.json({ error: "tenantId is required." }, { status: 400 });
+    return NextResponse.json(
+      { error: "tenantId is required." },
+      { status: 400 },
+    );
   }
   const driver = getPosDriver();
   const [tenant, onboarding, locations, subscription, connect] =
@@ -81,7 +86,10 @@ export async function POST(request: Request) {
           ownerEmail,
         });
         const onboarding = await driver.getOnboarding(tenant.id);
-        return NextResponse.json({ tenant, owner, onboarding }, { status: 201 });
+        return NextResponse.json(
+          { tenant, owner, onboarding },
+          { status: 201 },
+        );
       }
 
       case "add_location": {
@@ -128,6 +136,17 @@ export async function POST(request: Request) {
         }
         const onboarding = await driver.goLive(body.tenantId);
         const tenant = await driver.getTenant(body.tenantId);
+        // Audit tenant go-live (lifecycle) — best-effort actor from session.
+        const actor = await getCurrentUser();
+        await recordAudit({
+          actor: {
+            id: actor?.id ?? "system",
+            label: actor?.email ?? "self-serve onboarding",
+          },
+          action: "tenant_go_live",
+          tenantId: body.tenantId,
+          detail: `Tenant "${tenant?.name ?? body.tenantId}" went live.`,
+        });
         return NextResponse.json({ ok: true, onboarding, tenant });
       }
 
diff --git a/src/app/api/terminal/pin/route.ts b/src/app/api/terminal/pin/route.ts
index 11a1937..562e782 100644
--- a/src/app/api/terminal/pin/route.ts
+++ b/src/app/api/terminal/pin/route.ts
@@ -21,6 +21,7 @@ import { getPosDriver } from "@/lib/db";
 import { getCurrentUser } from "@/lib/auth/session";
 import { tenantsForSurface } from "@/lib/auth/roles";
 import { isValidPinFormat, verifyPin } from "@/lib/auth/pin";
+import { enforceRateLimit, readJsonBody, recordAudit } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -67,18 +68,24 @@ function isValid(b: unknown): b is Body {
 }
 
 export async function POST(request: Request) {
+  // Brute-force defence on PIN verification — strict per-IP rate limit.
+  const limited = enforceRateLimit(request, "pin");
+  if (limited) return limited;
+
   // The device session authorizes WHICH tenant the PIN switch applies to.
   const user = await getCurrentUser();
   if (!user) {
     return NextResponse.json({ error: "Not signed in." }, { status: 401 });
   }
 
-  let body: unknown;
-  try {
-    body = await request.json();
-  } catch {
-    return NextResponse.json({ error: "Invalid JSON body." }, { status: 400 });
+  const parsed = await readJsonBody(request);
+  if (!parsed.ok) {
+    return NextResponse.json(
+      { error: parsed.error },
+      { status: parsed.status },
+    );
   }
+  const body = parsed.body;
   if (!isValid(body) || !isValidPinFormat(body.pin)) {
     return NextResponse.json({ error: "Invalid PIN." }, { status: 401 });
   }
@@ -106,6 +113,14 @@ export async function POST(request: Request) {
     return NextResponse.json({ error: "Incorrect PIN." }, { status: 401 });
   }
 
+  // Audit the active-staff switch (tenant-scoped) — who took over the till.
+  await recordAudit({
+    actor: { id: user.id, label: user.email },
+    action: "staff_pin_switch",
+    tenantId: matched.tenant_id,
+    detail: `Active staff switched to ${matched.name} (${matched.role}).`,
+  });
+
   // Success: return only non-sensitive identity for attribution (no hash).
   return NextResponse.json({
     activeStaff: {
diff --git a/src/app/auth/callback/route.ts b/src/app/auth/callback/route.ts
index 3827f5f..f4a4db6 100644
--- a/src/app/auth/callback/route.ts
+++ b/src/app/auth/callback/route.ts
@@ -8,6 +8,8 @@
  */
 import { NextResponse } from "next/server";
 import { getServerSupabase } from "@/lib/auth/supabase-server";
+import { getPosDriver } from "@/lib/db";
+import { recordAudit } from "@/lib/security";
 
 export const runtime = "nodejs";
 
@@ -24,6 +26,42 @@ export async function GET(request: Request) {
       dest.searchParams.set("error", "link_invalid");
       return NextResponse.redirect(dest);
     }
+
+    // Audit the successful staff/admin sign-in, tenant-scoped per membership.
+    // Platform admins with no tenant membership get a single null-tenant entry.
+    // (Customer sign-ins — no membership, not admin — are not audited here.)
+    try {
+      const {
+        data: { user },
+      } = await supabase.auth.getUser();
+      if (user) {
+        const driver = getPosDriver();
+        const [memberships, isAdmin] = await Promise.all([
+          driver.listMembershipsForUser(user.id),
+          driver.isPlatformAdmin(user.id),
+        ]);
+        const label = user.email ?? user.id;
+        if (memberships.length > 0) {
+          for (const m of memberships) {
+            await recordAudit({
+              actor: { id: user.id, label },
+              action: "auth_sign_in",
+              tenantId: m.tenant_id,
+              detail: `Signed in (role ${m.role}).`,
+            });
+          }
+        } else if (isAdmin) {
+          await recordAudit({
+            actor: { id: user.id, label },
+            action: "auth_sign_in",
+            tenantId: null,
+            detail: "Platform admin signed in.",
+          });
+        }
+      }
+    } catch {
+      // Auditing must never block login — swallow.
+    }
   }
 
   // Safe-list the redirect to same-origin internal paths only.
diff --git a/src/lib/db/saas-types.ts b/src/lib/db/saas-types.ts
index ee0d322..3d2f492 100644
--- a/src/lib/db/saas-types.ts
+++ b/src/lib/db/saas-types.ts
@@ -139,13 +139,35 @@ export interface TenantOnboarding {
 // Audit log (platform-operator actions, incl. impersonation)
 // ----------------------------------------------------------------------------
 
-/** Category of an audited platform action. */
+/**
+ * Category of an audited action. Beyond the original platform-operator actions
+ * (impersonation, tenant lifecycle), Phase 7 hardening broadens coverage to
+ * other sensitive, tenant-scoped operations: staff/admin sign-in, role &
+ * membership changes, payment refunds/voids, menu 86 (availability), Stripe
+ * Connect changes, and subscription/billing changes. Every entry is written
+ * through the existing append-only `audit_log` table and stays tenant-scoped
+ * (the `tenant_id` column), so `/platform` surfaces a single traceable trail.
+ */
 export type AuditAction =
+  // Platform-operator actions (original).
   | "impersonate_start"
   | "impersonate_end"
   | "tenant_suspend"
   | "tenant_reactivate"
-  | "subscription_override";
+  | "subscription_override"
+  // Auth / access (Phase 7).
+  | "auth_sign_in"
+  | "staff_pin_switch"
+  | "membership_change"
+  // Money (Phase 7).
+  | "payment_refund"
+  | "payment_void"
+  // Menu / catalogue (Phase 7).
+  | "menu_86"
+  // Tenant lifecycle / integrations (Phase 7).
+  | "connect_change"
+  | "subscription_change"
+  | "tenant_go_live";
 
 /**
  * An append-only audit entry written when a platform operator takes a
diff --git a/src/lib/security/audit.test.ts b/src/lib/security/audit.test.ts
new file mode 100644
index 0000000..92c3841
--- /dev/null
+++ b/src/lib/security/audit.test.ts
@@ -0,0 +1,49 @@
+import { describe, it, expect } from "vitest";
+import { recordAudit } from "./audit";
+import { getPosDriver, DEMO_TENANT_ID } from "@/lib/db";
+
+describe("recordAudit", () => {
+  it("appends a tenant-scoped entry via the active driver", async () => {
+    const entry = await recordAudit({
+      actor: { id: "u1", label: "owner@example.com" },
+      action: "payment_refund",
+      tenantId: DEMO_TENANT_ID,
+      detail: "Refunded 500¢ on payment p1.",
+    });
+    expect(entry).not.toBeNull();
+    expect(entry?.tenant_id).toBe(DEMO_TENANT_ID);
+    expect(entry?.action).toBe("payment_refund");
+
+    const log = await getPosDriver().listAuditLog(DEMO_TENANT_ID);
+    expect(log.some((e) => e.id === entry?.id)).toBe(true);
+  });
+
+  it("truncates an oversized detail string", async () => {
+    const entry = await recordAudit({
+      actor: { id: "u1", label: "x" },
+      action: "menu_86",
+      tenantId: DEMO_TENANT_ID,
+      detail: "z".repeat(5000),
+    });
+    expect(entry?.detail?.length).toBeLessThanOrEqual(500);
+  });
+
+  it("is fail-open: returns null instead of throwing on a driver error", async () => {
+    const driver = getPosDriver();
+    const original = driver.appendAuditLog;
+    // Force a failure in the append path.
+    driver.appendAuditLog = async () => {
+      throw new Error("db down");
+    };
+    try {
+      const entry = await recordAudit({
+        actor: { id: "u1", label: "x" },
+        action: "auth_sign_in",
+        tenantId: DEMO_TENANT_ID,
+      });
+      expect(entry).toBeNull();
+    } finally {
+      driver.appendAuditLog = original;
+    }
+  });
+});
diff --git a/src/lib/security/audit.ts b/src/lib/security/audit.ts
new file mode 100644
index 0000000..0dc8d87
--- /dev/null
+++ b/src/lib/security/audit.ts
@@ -0,0 +1,70 @@
+/**
+ * Audit-logging helper (Phase 7 hardening).
+ *
+ * A thin, **fail-open** wrapper over the existing `PosDriver.appendAuditLog` /
+ * `audit_log` table. It broadens audit coverage from platform-operator actions
+ * (impersonation, tenant lifecycle) to other sensitive, tenant-scoped actions —
+ * staff/admin sign-in, role/membership changes, payment refunds/voids, menu 86,
+ * Connect changes, and tenant/subscription lifecycle.
+ *
+ * Design:
+ *   - **Tenant-scoped.** Every entry carries `tenant_id`, so `/platform` and
+ *     `listAuditLog(tenantId)` show one coherent, per-tenant trail.
+ *   - **Never breaks the primary action.** Auditing is observability, not the
+ *     business operation: a failure to write the log is captured (structured
+ *     error) but swallowed, so a logging hiccup can't fail a refund or a login.
+ *   - **Zero-env safe.** Uses the active driver (mock by default), so it works
+ *     in the no-env build/suite exactly like the rest of the app.
+ */
+import { getPosDriver } from "@/lib/db";
+import type { AuditAction, AuditLogEntry } from "@/lib/db";
+import { captureError } from "@/lib/observability";
+
+export interface AuditActor {
+  /** The acting user's id (session user id, or a system marker). */
+  id: string;
+  /** Human-readable label captured at write time (typically the email). */
+  label: string;
+}
+
+export interface AuditInput {
+  actor: AuditActor;
+  action: AuditAction;
+  /** Target tenant — keeps the entry tenant-scoped. Null for platform-global. */
+  tenantId: string | null;
+  /** Free-form context (reason, amount, ids). Truncated defensively. */
+  detail?: string | null;
+}
+
+/** Cap detail length so an oversized/abusive string can't bloat the table. */
+const MAX_DETAIL = 500;
+
+/**
+ * Append a tenant-scoped audit entry. Resolves to the written entry, or `null`
+ * if the write failed (which is logged but never thrown). Awaiting it is
+ * optional — callers may fire-and-forget after the primary action succeeds.
+ */
+export async function recordAudit(
+  input: AuditInput,
+): Promise<AuditLogEntry | null> {
+  try {
+    const driver = getPosDriver();
+    const detail =
+      input.detail == null ? null : String(input.detail).slice(0, MAX_DETAIL);
+    return await driver.appendAuditLog({
+      actor_user_id: input.actor.id,
+      actor_label: input.actor.label,
+      action: input.action,
+      tenant_id: input.tenantId,
+      detail,
+    });
+  } catch (err) {
+    // Audit is fail-open: log the failure, never break the caller's action.
+    captureError(err, {
+      scope: "audit",
+      action: input.action,
+      tenantId: input.tenantId ?? undefined,
+    });
+    return null;
+  }
+}
diff --git a/src/lib/security/headers.test.ts b/src/lib/security/headers.test.ts
new file mode 100644
index 0000000..23cd062
--- /dev/null
+++ b/src/lib/security/headers.test.ts
@@ -0,0 +1,51 @@
+import { describe, it, expect } from "vitest";
+import {
+  CONTENT_SECURITY_POLICY,
+  CSP_DIRECTIVES,
+  SECURITY_HEADERS,
+} from "./headers";
+
+describe("CSP", () => {
+  it("locks down the dangerous defaults", () => {
+    expect(CSP_DIRECTIVES["default-src"]).toEqual(["'self'"]);
+    expect(CSP_DIRECTIVES["object-src"]).toEqual(["'none'"]);
+    expect(CSP_DIRECTIVES["frame-ancestors"]).toEqual(["'none'"]);
+    expect(CSP_DIRECTIVES["base-uri"]).toEqual(["'self'"]);
+    expect(CSP_DIRECTIVES["form-action"]).toEqual(["'self'"]);
+  });
+
+  it("allows the Supabase + Stripe runtime integrations in connect-src", () => {
+    const connect = (CSP_DIRECTIVES["connect-src"] ?? []).join(" ");
+    expect(connect).toContain("https://*.supabase.co");
+    expect(connect).toContain("wss://*.supabase.co");
+    expect(connect).toContain("https://api.stripe.com");
+  });
+
+  it("serializes to a single-line policy with all directives", () => {
+    for (const key of Object.keys(CSP_DIRECTIVES)) {
+      expect(CONTENT_SECURITY_POLICY).toContain(key);
+    }
+    expect(CONTENT_SECURITY_POLICY).toContain("upgrade-insecure-requests");
+    expect(CONTENT_SECURITY_POLICY).not.toContain("\n");
+  });
+});
+
+describe("SECURITY_HEADERS", () => {
+  const byKey = Object.fromEntries(
+    SECURITY_HEADERS.map((h) => [h.key, h.value]),
+  );
+
+  it("includes the standard hardening headers", () => {
+    expect(byKey["Content-Security-Policy"]).toBe(CONTENT_SECURITY_POLICY);
+    expect(byKey["X-Content-Type-Options"]).toBe("nosniff");
+    expect(byKey["X-Frame-Options"]).toBe("DENY");
+    expect(byKey["Referrer-Policy"]).toBe("strict-origin-when-cross-origin");
+    expect(byKey["Strict-Transport-Security"]).toContain("max-age=");
+    expect(byKey["Permissions-Policy"]).toContain("camera=()");
+  });
+
+  it("has no duplicate header keys", () => {
+    const keys = SECURITY_HEADERS.map((h) => h.key);
+    expect(new Set(keys).size).toBe(keys.length);
+  });
+});
diff --git a/src/lib/security/headers.ts b/src/lib/security/headers.ts
new file mode 100644
index 0000000..035344a
--- /dev/null
+++ b/src/lib/security/headers.ts
@@ -0,0 +1,129 @@
+/**
+ * Security headers + Content-Security-Policy (Phase 7 hardening).
+ *
+ * Emitted for every route via `next.config.ts` `headers()`. Kept in `src/lib`
+ * (not inline in the config) so it can be reasoned about + unit-tested and so
+ * the CSP source list lives in one place.
+ *
+ * ── CSP approach (no nonce) ────────────────────────────────────────────────
+ * The app is Next.js 15 App Router + a Serwist service worker + Supabase Auth +
+ * Stripe (Terminal/Checkout) + (optionally) crypto RPC endpoints. Next's App
+ * Router injects framework **inline** bootstrap/flight scripts on every page.
+ * A nonce-based `script-src` would require minting a per-request nonce in
+ * middleware and threading it through the document — but this app's middleware
+ * intentionally runs on the protected surfaces ONLY (`/admin|/terminal|/kitchen|
+ * /platform`); `/shop`, `/`, and statically-rendered routes are not matched, so
+ * a nonce can't be applied uniformly without broadening middleware (out of
+ * scope, and it would also break static optimisation).
+ *
+ * We therefore ship a **static** CSP applied at the edge via `headers()`:
+ *   - `script-src` allows `'self'` + `'unsafe-inline'` (required for Next's
+ *     inline runtime scripts without a nonce) + Stripe's JS origins. This is the
+ *     documented trade-off: `'unsafe-inline'` for scripts is weaker than a
+ *     nonce, but every other vector is locked down and the app ships no
+ *     author-controlled inline scripts (no `dangerouslySetInnerHTML`, no inline
+ *     `<script>`), so the practical XSS surface is small. To upgrade to nonces
+ *     later, mint a nonce in middleware, broaden the matcher to all routes, set
+ *     `script-src 'self' 'nonce-…' 'strict-dynamic'`, and pass the nonce to the
+ *     root layout.
+ *   - `style-src` allows `'unsafe-inline'` for styled-jsx / inline style attrs.
+ *   - `connect-src`/`frame-src`/`img-src` enumerate the runtime integrations
+ *     (Supabase, Stripe, crypto RPC, blob/data for the PWA + receipts).
+ *   - `frame-ancestors 'none'` (clickjacking) — paired with `X-Frame-Options`.
+ *   - `object-src 'none'`, `base-uri 'self'`, `form-action 'self'`,
+ *     `upgrade-insecure-requests`.
+ *
+ * Everything here is STATIC — no env vars are read — so the zero-env build is
+ * unaffected. We intentionally widen `connect-src`/`frame-src` to the whole
+ * `*.supabase.co` / Stripe / common Base-RPC origins rather than reading env at
+ * build time, so a later env flip needs no header change.
+ */
+
+/** Build the CSP string from a directive map. */
+function serializeCsp(directives: Record<string, string[]>): string {
+  return Object.entries(directives)
+    .map(([k, v]) => (v.length ? `${k} ${v.join(" ")}` : k))
+    .join("; ");
+}
+
+/**
+ * The Content-Security-Policy directive set. Exported for testing/inspection.
+ * Origins are intentionally a superset of what any single deployment uses so
+ * the same policy works in mock-mode and live-mode without env-dependent edits.
+ */
+export const CSP_DIRECTIVES: Record<string, string[]> = {
+  "default-src": ["'self'"],
+  // Next App Router emits inline runtime scripts; Stripe.js + Terminal are
+  // loaded from Stripe origins. 'unsafe-inline' here is the documented no-nonce
+  // trade-off (see file header).
+  "script-src": [
+    "'self'",
+    "'unsafe-inline'",
+    "https://js.stripe.com",
+    "https://*.js.stripe.com",
+  ],
+  // Allow Next/styled-jsx + Tailwind inline styles + Google Fonts stylesheet.
+  "style-src": ["'self'", "'unsafe-inline'", "https://fonts.googleapis.com"],
+  "img-src": ["'self'", "data:", "blob:", "https:"],
+  "font-src": ["'self'", "data:", "https://fonts.gstatic.com"],
+  // Runtime XHR/fetch/websocket targets: Supabase (REST + Realtime WSS),
+  // Stripe API, and common Base-network RPC endpoints for onchain USDC.
+  "connect-src": [
+    "'self'",
+    "https://*.supabase.co",
+    "wss://*.supabase.co",
+    "https://api.stripe.com",
+    "https://*.stripe.com",
+    "https://mainnet.base.org",
+    "https://sepolia.base.org",
+    "https://*.base.org",
+  ],
+  // Stripe embeds its payment/Checkout iframes; nothing else may frame-in.
+  "frame-src": ["'self'", "https://js.stripe.com", "https://*.stripe.com"],
+  "worker-src": ["'self'", "blob:"],
+  "manifest-src": ["'self'"],
+  "object-src": ["'none'"],
+  "base-uri": ["'self'"],
+  "form-action": ["'self'"],
+  // Clickjacking defence (modern; X-Frame-Options is the legacy companion).
+  "frame-ancestors": ["'none'"],
+  "upgrade-insecure-requests": [],
+};
+
+/** The serialized CSP header value. */
+export const CONTENT_SECURITY_POLICY = serializeCsp(CSP_DIRECTIVES);
+
+/** Permissions-Policy: deny powerful features the POS does not use. */
+const PERMISSIONS_POLICY = [
+  "camera=()",
+  "microphone=()",
+  "geolocation=()",
+  "payment=(self)",
+  "usb=()",
+  "interest-cohort=()",
+].join(", ");
+
+export interface SecurityHeader {
+  key: string;
+  value: string;
+}
+
+/**
+ * The full set of security headers applied to every response. HSTS is included;
+ * it is inert over plain HTTP (browsers ignore it) so it is safe on localhost
+ * and only takes effect once served over HTTPS (Vercel/prod).
+ */
+export const SECURITY_HEADERS: SecurityHeader[] = [
+  { key: "Content-Security-Policy", value: CONTENT_SECURITY_POLICY },
+  {
+    key: "Strict-Transport-Security",
+    value: "max-age=63072000; includeSubDomains; preload",
+  },
+  { key: "X-Content-Type-Options", value: "nosniff" },
+  { key: "X-Frame-Options", value: "DENY" },
+  { key: "Referrer-Policy", value: "strict-origin-when-cross-origin" },
+  { key: "Permissions-Policy", value: PERMISSIONS_POLICY },
+  // Spectre-class isolation hints (safe defaults; do not break same-origin).
+  { key: "X-DNS-Prefetch-Control", value: "off" },
+  { key: "Cross-Origin-Opener-Policy", value: "same-origin" },
+];
diff --git a/src/lib/security/http.test.ts b/src/lib/security/http.test.ts
new file mode 100644
index 0000000..3452577
--- /dev/null
+++ b/src/lib/security/http.test.ts
@@ -0,0 +1,42 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { clientIp, enforceRateLimit } from "./http";
+import { defaultLimiter } from "./rate-limit";
+
+function req(headers: Record<string, string> = {}): Request {
+  return new Request("https://pos.example/api/x", { method: "POST", headers });
+}
+
+describe("clientIp", () => {
+  it("takes the first hop of x-forwarded-for", () => {
+    expect(
+      clientIp(new Headers({ "x-forwarded-for": "1.2.3.4, 5.6.7.8" })),
+    ).toBe("1.2.3.4");
+  });
+
+  it("falls back to x-real-ip then 'unknown'", () => {
+    expect(clientIp(new Headers({ "x-real-ip": "9.9.9.9" }))).toBe("9.9.9.9");
+    expect(clientIp(new Headers())).toBe("unknown");
+  });
+});
+
+describe("enforceRateLimit", () => {
+  beforeEach(() => {
+    defaultLimiter.clear();
+  });
+
+  it("is a no-op under tests — never throttles the zero-env suite/build", () => {
+    // VITEST is set in this environment ⇒ rateLimitEnabled() is false, so even a
+    // flood from one IP against the strictest bucket must always proceed (null).
+    for (let i = 0; i < 1000; i++) {
+      expect(
+        enforceRateLimit(req({ "x-forwarded-for": "1.1.1.1" }), "pin"),
+      ).toBe(null);
+    }
+  });
+
+  it("returns null (proceed) for a single well-formed request", () => {
+    expect(enforceRateLimit(req({ "x-real-ip": "3.3.3.3" }), "orders")).toBe(
+      null,
+    );
+  });
+});
diff --git a/src/lib/security/http.ts b/src/lib/security/http.ts
new file mode 100644
index 0000000..b9697c4
--- /dev/null
+++ b/src/lib/security/http.ts
@@ -0,0 +1,96 @@
+/**
+ * HTTP glue for rate limiting (Phase 7 hardening).
+ *
+ * Turns the pure {@link RateLimiter} into a drop-in route-handler guard:
+ *   - derives a best-effort client IP from proxy headers (Vercel sets
+ *     `x-forwarded-for` / `x-real-ip`);
+ *   - applies the named rule to one or more identity keys (per-IP and, where
+ *     sensible, per-account) — the strictest result wins;
+ *   - returns a ready `429` `NextResponse` with `Retry-After` + `RateLimit-*`
+ *     headers when blocked, or `null` to proceed.
+ *
+ * No-op when {@link rateLimitEnabled} is false (tests / disabled), so the
+ * zero-env build + Vitest suite are never throttled.
+ */
+import { NextResponse } from "next/server";
+import {
+  defaultLimiter,
+  rateLimitEnabled,
+  RATE_LIMIT_RULES,
+  type RateLimitBucket,
+  type RateLimitResult,
+} from "./rate-limit";
+
+/** Best-effort client IP from proxy headers; falls back to a constant. */
+export function clientIp(headers: Headers): string {
+  const fwd = headers.get("x-forwarded-for");
+  if (fwd) {
+    // First hop is the original client; the rest are proxies.
+    const first = fwd.split(",")[0]?.trim();
+    if (first) return first;
+  }
+  return headers.get("x-real-ip")?.trim() || "unknown";
+}
+
+/** Attach `RateLimit-*` headers (draft IETF naming) to a response/headers bag. */
+function applyHeaders(headers: Headers, r: RateLimitResult): void {
+  headers.set("RateLimit-Limit", String(r.limit));
+  headers.set("RateLimit-Remaining", String(r.remaining));
+  headers.set(
+    "RateLimit-Reset",
+    String(Math.ceil((r.resetAt - Date.now()) / 1000)),
+  );
+}
+
+export interface RateLimitOptions {
+  /** Extra identity keys to limit on (e.g. an email/account/staff id). */
+  keys?: Array<string | null | undefined>;
+}
+
+/**
+ * Enforce the `bucket` rule for `request`. Returns a `429` response to return
+ * as-is when any identity key is over the limit, else `null` (proceed).
+ *
+ * Always limits per-IP; additional `keys` (e.g. the login email) are limited
+ * under the same rule so an attacker can't dodge the IP limit by rotating IPs
+ * against one account, nor pivot across accounts from one IP.
+ */
+export function enforceRateLimit(
+  request: Request,
+  bucket: RateLimitBucket,
+  options: RateLimitOptions = {},
+): NextResponse | null {
+  if (!rateLimitEnabled()) return null;
+
+  const rule = RATE_LIMIT_RULES[bucket];
+  const ip = clientIp(request.headers);
+  const identities = [
+    `${bucket}:ip:${ip}`,
+    ...(options.keys ?? [])
+      .filter((k): k is string => typeof k === "string" && k.length > 0)
+      .map((k) => `${bucket}:key:${k.toLowerCase()}`),
+  ];
+
+  let blocked: RateLimitResult | null = null;
+  let tightest: RateLimitResult | null = null;
+  for (const id of identities) {
+    const res = defaultLimiter.check(id, rule);
+    if (!tightest || res.remaining < tightest.remaining) tightest = res;
+    if (!res.allowed) blocked = res;
+  }
+
+  if (blocked) {
+    const res = NextResponse.json(
+      { error: "Too many requests. Please slow down and try again shortly." },
+      { status: 429 },
+    );
+    res.headers.set("Retry-After", String(blocked.retryAfterSeconds));
+    applyHeaders(res.headers, blocked);
+    return res;
+  }
+
+  // Not blocked: nothing to return. (Informational headers are most useful on
+  // the 429; we keep the success path header-free to avoid coupling callers.)
+  void tightest;
+  return null;
+}
diff --git a/src/lib/security/index.ts b/src/lib/security/index.ts
new file mode 100644
index 0000000..2406e57
--- /dev/null
+++ b/src/lib/security/index.ts
@@ -0,0 +1,11 @@
+/**
+ * Security hardening surface (Phase 7). One import for the rate limiter, the
+ * route-handler rate-limit guard, the tenant-scoped audit helper, the input
+ * validators, and the security-header/CSP definitions. Everything here is
+ * env-optional and no-op-safe with zero configuration.
+ */
+export * from "./rate-limit";
+export * from "./http";
+export * from "./audit";
+export * from "./validate";
+export * from "./headers";
diff --git a/src/lib/security/rate-limit.test.ts b/src/lib/security/rate-limit.test.ts
new file mode 100644
index 0000000..f1df26d
--- /dev/null
+++ b/src/lib/security/rate-limit.test.ts
@@ -0,0 +1,78 @@
+import { describe, it, expect } from "vitest";
+import { RateLimiter, RATE_LIMIT_RULES } from "./rate-limit";
+
+describe("RateLimiter", () => {
+  it("allows requests up to the limit, then blocks", () => {
+    const rl = new RateLimiter(() => 1_000);
+    const rule = { limit: 3, windowMs: 60_000 };
+    expect(rl.check("k", rule).allowed).toBe(true);
+    expect(rl.check("k", rule).allowed).toBe(true);
+    const third = rl.check("k", rule);
+    expect(third.allowed).toBe(true);
+    expect(third.remaining).toBe(0);
+    const fourth = rl.check("k", rule);
+    expect(fourth.allowed).toBe(false);
+    expect(fourth.retryAfterSeconds).toBeGreaterThanOrEqual(1);
+  });
+
+  it("reports decreasing remaining and a stable reset within a window", () => {
+    let now = 0;
+    const rl = new RateLimiter(() => now);
+    const rule = { limit: 5, windowMs: 10_000 };
+    const a = rl.check("k", rule);
+    expect(a.remaining).toBe(4);
+    expect(a.resetAt).toBe(10_000);
+    now = 5_000;
+    const b = rl.check("k", rule);
+    expect(b.remaining).toBe(3);
+    expect(b.resetAt).toBe(10_000); // same window
+  });
+
+  it("resets the window after it elapses", () => {
+    let now = 0;
+    const rl = new RateLimiter(() => now);
+    const rule = { limit: 1, windowMs: 1_000 };
+    expect(rl.check("k", rule).allowed).toBe(true);
+    expect(rl.check("k", rule).allowed).toBe(false);
+    now = 1_001; // window elapsed
+    const after = rl.check("k", rule);
+    expect(after.allowed).toBe(true);
+    expect(after.resetAt).toBe(1_001 + 1_000);
+  });
+
+  it("tracks keys independently", () => {
+    const rl = new RateLimiter(() => 0);
+    const rule = { limit: 1, windowMs: 1_000 };
+    expect(rl.check("a", rule).allowed).toBe(true);
+    expect(rl.check("b", rule).allowed).toBe(true); // different key, fresh
+    expect(rl.check("a", rule).allowed).toBe(false);
+  });
+
+  it("reset() forgets a key so the next caller starts fresh", () => {
+    const rl = new RateLimiter(() => 0);
+    const rule = { limit: 1, windowMs: 1_000 };
+    expect(rl.check("a", rule).allowed).toBe(true);
+    expect(rl.check("a", rule).allowed).toBe(false);
+    rl.reset("a");
+    expect(rl.check("a", rule).allowed).toBe(true);
+  });
+
+  it("retryAfterSeconds reflects time left in the window", () => {
+    let now = 0;
+    const rl = new RateLimiter(() => now);
+    const rule = { limit: 1, windowMs: 30_000 };
+    rl.check("k", rule); // consume
+    now = 5_000;
+    const blocked = rl.check("k", rule);
+    expect(blocked.allowed).toBe(false);
+    // 25s left → ceil(25000/1000) = 25
+    expect(blocked.retryAfterSeconds).toBe(25);
+  });
+
+  it("named rules are sane (positive limits + windows)", () => {
+    for (const rule of Object.values(RATE_LIMIT_RULES)) {
+      expect(rule.limit).toBeGreaterThan(0);
+      expect(rule.windowMs).toBeGreaterThan(0);
+    }
+  });
+});
diff --git a/src/lib/security/rate-limit.ts b/src/lib/security/rate-limit.ts
new file mode 100644
index 0000000..976e6b9
--- /dev/null
+++ b/src/lib/security/rate-limit.ts
@@ -0,0 +1,138 @@
+/**
+ * Lightweight in-memory rate limiter (Phase 7 hardening).
+ *
+ * Zero-dependency, fixed-window per-key limiter for blunting brute-force /
+ * abuse on sensitive endpoints (auth, order creation, payments). It is
+ * deliberately simple and process-local:
+ *
+ *   - **No new dependency.** A `Map<string, window>` with periodic pruning.
+ *   - **No-op-safe by default.** Disabled when `RATE_LIMIT_DISABLED` is truthy
+ *     OR when running under a test runner (`VITEST`/`NODE_ENV==="test"`), so the
+ *     build, the Vitest suite, and local dev all stay green with zero env. The
+ *     limiter itself is still unit-tested directly via {@link RateLimiter}.
+ *   - **Process-local caveat.** On serverless (Vercel) each instance keeps its
+ *     own window, so the effective limit scales with concurrency. This is a
+ *     deliberate trade-off to avoid an external store (Redis/Upstash) and a new
+ *     dependency; it still meaningfully blunts a single-source brute-force. For
+ *     a hard global limit, swap `defaultStore` for a shared store later — the
+ *     call sites do not change.
+ *
+ * Identity: callers pass a key (typically `"<bucket>:<ip>"` and/or
+ * `"<bucket>:<account>"`). The HTTP glue in `http.ts` derives the client IP
+ * from proxy headers and returns a ready-to-send `429` with `Retry-After` +
+ * `RateLimit-*` headers.
+ */
+
+export interface RateLimitRule {
+  /** Max requests permitted within the window. */
+  limit: number;
+  /** Window length in milliseconds. */
+  windowMs: number;
+}
+
+export interface RateLimitResult {
+  /** Whether this request is allowed (false ⇒ caller should return 429). */
+  allowed: boolean;
+  /** Configured ceiling for the window. */
+  limit: number;
+  /** Requests remaining in the current window (never negative). */
+  remaining: number;
+  /** Epoch millis when the current window resets. */
+  resetAt: number;
+  /** Seconds until reset — for the `Retry-After` header (>= 1 when blocked). */
+  retryAfterSeconds: number;
+}
+
+interface Window {
+  count: number;
+  resetAt: number;
+}
+
+/**
+ * A fixed-window counter keyed by an arbitrary string. Pure and deterministic
+ * given an injected clock, so it is straightforward to unit-test.
+ */
+export class RateLimiter {
+  private readonly windows = new Map<string, Window>();
+  private lastPrune = 0;
+
+  constructor(private readonly now: () => number = Date.now) {}
+
+  /**
+   * Record a hit for `key` under `rule` and report whether it is allowed.
+   * The window is created on first hit and reset once it elapses.
+   */
+  check(key: string, rule: RateLimitRule): RateLimitResult {
+    const t = this.now();
+    this.maybePrune(t);
+
+    let win = this.windows.get(key);
+    if (!win || win.resetAt <= t) {
+      win = { count: 0, resetAt: t + rule.windowMs };
+      this.windows.set(key, win);
+    }
+
+    win.count += 1;
+    const allowed = win.count <= rule.limit;
+    const remaining = Math.max(0, rule.limit - win.count);
+    const retryAfterSeconds = allowed
+      ? 0
+      : Math.max(1, Math.ceil((win.resetAt - t) / 1000));
+
+    return {
+      allowed,
+      limit: rule.limit,
+      remaining,
+      resetAt: win.resetAt,
+      retryAfterSeconds,
+    };
+  }
+
+  /** Forget a key (e.g. on a successful login, to not penalise the next user). */
+  reset(key: string): void {
+    this.windows.delete(key);
+  }
+
+  /** Test/maintenance helper: drop all state. */
+  clear(): void {
+    this.windows.clear();
+    this.lastPrune = 0;
+  }
+
+  /** Drop elapsed windows at most ~once per window to bound memory. */
+  private maybePrune(t: number): void {
+    if (t - this.lastPrune < 30_000) return;
+    this.lastPrune = t;
+    for (const [k, w] of this.windows) {
+      if (w.resetAt <= t) this.windows.delete(k);
+    }
+  }
+}
+
+/** Named limits for the sensitive surfaces. Tuned to be generous for humans. */
+export const RATE_LIMIT_RULES = {
+  /** Auth: login / magic-link / PIN — strict, per IP and per account. */
+  auth: { limit: 10, windowMs: 60_000 } satisfies RateLimitRule,
+  /** PIN verification — extra strict (4-8 digit space is small). */
+  pin: { limit: 8, windowMs: 60_000 } satisfies RateLimitRule,
+  /** Order creation — high ceiling (a busy terminal places many). */
+  orders: { limit: 60, windowMs: 60_000 } satisfies RateLimitRule,
+  /** Payment capture / refund — moderate. */
+  payments: { limit: 30, windowMs: 60_000 } satisfies RateLimitRule,
+} as const;
+
+export type RateLimitBucket = keyof typeof RATE_LIMIT_RULES;
+
+/** Shared process-local limiter for the app's HTTP glue. */
+export const defaultLimiter = new RateLimiter();
+
+/**
+ * Whether rate limiting is active. Disabled under tests and when explicitly
+ * turned off, so the zero-env build/suite/dev never trip a limit. The limiter
+ * class is still unit-tested directly regardless of this flag.
+ */
+export function rateLimitEnabled(): boolean {
+  if (process.env.RATE_LIMIT_DISABLED) return false;
+  if (process.env.NODE_ENV === "test" || process.env.VITEST) return false;
+  return true;
+}
diff --git a/src/lib/security/validate.test.ts b/src/lib/security/validate.test.ts
new file mode 100644
index 0000000..2987cc3
--- /dev/null
+++ b/src/lib/security/validate.test.ts
@@ -0,0 +1,86 @@
+import { describe, it, expect } from "vitest";
+import {
+  readJsonBody,
+  isMoneyCents,
+  isClientId,
+  isEmail,
+  isNonEmptyString,
+  MAX_BODY_BYTES,
+} from "./validate";
+
+function jsonReq(body: string, headers: Record<string, string> = {}): Request {
+  return new Request("https://pos.example/api/x", {
+    method: "POST",
+    headers: { "content-type": "application/json", ...headers },
+    body,
+  });
+}
+
+describe("readJsonBody", () => {
+  it("parses valid JSON", async () => {
+    const r = await readJsonBody(jsonReq('{"a":1}'));
+    expect(r).toEqual({ ok: true, body: { a: 1 } });
+  });
+
+  it("rejects invalid JSON with 400", async () => {
+    const r = await readJsonBody(jsonReq("{not json"));
+    expect(r).toMatchObject({ ok: false, status: 400 });
+  });
+
+  it("rejects an empty body with 400", async () => {
+    const r = await readJsonBody(jsonReq("   "));
+    expect(r).toMatchObject({ ok: false, status: 400 });
+  });
+
+  it("rejects via Content-Length when oversized (413, cheap path)", async () => {
+    const r = await readJsonBody(
+      jsonReq("{}", { "content-length": String(MAX_BODY_BYTES + 1) }),
+    );
+    expect(r).toMatchObject({ ok: false, status: 413 });
+  });
+
+  it("rejects an actually-oversized decoded body (413)", async () => {
+    const big = JSON.stringify({ x: "a".repeat(MAX_BODY_BYTES) });
+    // Omit content-length so the decoded re-check is what trips.
+    const req = new Request("https://pos.example/api/x", {
+      method: "POST",
+      body: big,
+    });
+    const r = await readJsonBody(req);
+    expect(r).toMatchObject({ ok: false, status: 413 });
+  });
+});
+
+describe("scalar guards", () => {
+  it("isMoneyCents accepts non-negative integers only", () => {
+    expect(isMoneyCents(0)).toBe(true);
+    expect(isMoneyCents(1500)).toBe(true);
+    expect(isMoneyCents(-1)).toBe(false);
+    expect(isMoneyCents(1.5)).toBe(false);
+    expect(isMoneyCents(NaN)).toBe(false);
+    expect(isMoneyCents("100")).toBe(false);
+    expect(isMoneyCents(1e12)).toBe(false); // beyond max
+  });
+
+  it("isClientId enforces a bounded allowlisted charset", () => {
+    expect(isClientId("550e8400-e29b-41d4-a716-446655440000")).toBe(true);
+    expect(isClientId("abc_DEF-123")).toBe(true);
+    expect(isClientId("short")).toBe(false); // < 8
+    expect(isClientId("has space chars")).toBe(false);
+    expect(isClientId("inject'); drop")).toBe(false);
+    expect(isClientId(123 as unknown)).toBe(false);
+  });
+
+  it("isEmail accepts plausible emails, rejects junk + overlong", () => {
+    expect(isEmail("a@b.co")).toBe(true);
+    expect(isEmail("nope")).toBe(false);
+    expect(isEmail("a@b")).toBe(false);
+    expect(isEmail(`${"a".repeat(255)}@b.co`)).toBe(false);
+  });
+
+  it("isNonEmptyString respects bounds", () => {
+    expect(isNonEmptyString("x")).toBe(true);
+    expect(isNonEmptyString("")).toBe(false);
+    expect(isNonEmptyString("y".repeat(2000), 1024)).toBe(false);
+  });
+});
diff --git a/src/lib/security/validate.ts b/src/lib/security/validate.ts
new file mode 100644
index 0000000..86a6bfb
--- /dev/null
+++ b/src/lib/security/validate.ts
@@ -0,0 +1,85 @@
+/**
+ * Input-validation helpers (Phase 7 hardening).
+ *
+ * Dependency-free guards (no zod — the constraint is to avoid new deps) for the
+ * sensitive order/payment/auth routes. They harden the existing hand-written
+ * type guards by rejecting malformed, out-of-range, and **oversized** payloads
+ * BEFORE they reach the domain layer.
+ *
+ * `readJsonBody` additionally enforces a byte cap so a giant body can't be used
+ * to exhaust memory/CPU; it returns a typed result the caller turns into a 400.
+ */
+
+/** Default max request-body size (256 KB) — generous for an order, tiny for abuse. */
+export const MAX_BODY_BYTES = 256 * 1024;
+
+export type JsonResult =
+  | { ok: true; body: unknown }
+  | { ok: false; status: number; error: string };
+
+/**
+ * Parse a JSON request body with a hard size cap. Prefers the `Content-Length`
+ * header for a cheap early reject, then re-checks the actual decoded length
+ * (the header can lie / be absent on chunked bodies).
+ */
+export async function readJsonBody(
+  request: Request,
+  maxBytes: number = MAX_BODY_BYTES,
+): Promise<JsonResult> {
+  const declared = request.headers.get("content-length");
+  if (declared && Number(declared) > maxBytes) {
+    return { ok: false, status: 413, error: "Request body too large." };
+  }
+  let text: string;
+  try {
+    text = await request.text();
+  } catch {
+    return { ok: false, status: 400, error: "Could not read request body." };
+  }
+  // Byte length (UTF-8 aware) — re-check after decoding.
+  if (Buffer.byteLength(text, "utf8") > maxBytes) {
+    return { ok: false, status: 413, error: "Request body too large." };
+  }
+  if (text.trim().length === 0) {
+    return { ok: false, status: 400, error: "Empty request body." };
+  }
+  try {
+    return { ok: true, body: JSON.parse(text) };
+  } catch {
+    return { ok: false, status: 400, error: "Invalid JSON body." };
+  }
+}
+
+// -- Scalar guards -----------------------------------------------------------
+
+export function isNonEmptyString(v: unknown, maxLen = 1024): v is string {
+  return typeof v === "string" && v.length > 0 && v.length <= maxLen;
+}
+
+/** A finite, non-negative, integer amount of money in minor units (cents). */
+export function isMoneyCents(v: unknown, max = 100_000_000): v is number {
+  return typeof v === "number" && Number.isInteger(v) && v >= 0 && v <= max;
+}
+
+/**
+ * A plausible client/UUID id: bounded length, allowlisted charset only
+ * (alphanumerics, hyphen, underscore). This both rejects control characters /
+ * whitespace and keeps ids safe to log + use as map keys.
+ */
+export function isClientId(v: unknown): v is string {
+  return (
+    typeof v === "string" &&
+    v.length >= 8 &&
+    v.length <= 128 &&
+    /^[A-Za-z0-9_-]+$/.test(v)
+  );
+}
+
+/** A minimal, length-bounded email shape (server is the source of truth). */
+export function isEmail(v: unknown, maxLen = 254): v is string {
+  return (
+    typeof v === "string" &&
+    v.length <= maxLen &&
+    /^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(v.trim())
+  );
+}