fix(GRO-2299): redact googleMapsApiKey from PATCH /api/admin/settings response

The PATCH handler returned the full businessSettings row via .returning(),
echoing the encrypted googleMapsApiKey ciphertext back to the caller. Wrap the
return in the existing redactSettings() helper (after a !updated guard) so
redaction is applied symmetrically with the GET projection (GRO-2294).

- src/routes/settings.ts: guard + redactSettings(updated) on PATCH return
- src/__tests__/settings.test.ts: assert PATCH omits googleMapsApiKey
  (existing-row and auto-create-then-update branches)
- UAT_PLAYBOOK.md §13 TC-API-13.2: assert PATCH response omits the secret

Co-Authored-By: Paperclip <noreply@paperclip.ing>

.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "gitea": {
+      "type": "http",
+      "url": "https://git-mcp.farh.net/mcp",
+      "headers": {
+        "Authorization": "Bearer ${GITEA_TOKEN}"
+      }
+    }
+  }
+}

UAT_PLAYBOOK.md

@@ -133,6 +133,7 @@ Geocoding turns a client's street address into `latitude`/`longitude` + `geocode
 | TC-API-2.11 | Geocode endpoint is manager-only | As **groomer** or **receptionist**, `POST /api/clients/{id}/geocode` | 403 Forbidden (role not permitted) |
 | TC-API-2.12 | Batch geocode un-geocoded clients | As manager, `POST /api/clients/geocode-batch?limit=10` on a DB with un-geocoded clients | 200 OK; body `{ provider, processed, geocoded, unresolved, errors, remaining, outcomes[] }`. `processed` ≤ 10; `remaining` reflects un-geocoded clients beyond this batch. Re-run while `remaining > 0` to finish (throttled to provider rate limit) |
 | TC-API-2.13 | Batch geocode — invalid limit | As manager, `POST /api/clients/geocode-batch?limit=0` (or non-numeric) | 400 `{ error: "limit must be a positive integer" }` |
+| TC-API-2.13a | Batch geocode — `?limit` cap enforced (GRO-2294) | As manager, `POST /api/clients/geocode-batch?limit=100000` on a DB with un-geocoded clients | 200 OK; the request is **clamped to the documented max of 500** — `processed` ≤ 500 (never the raw 100000). A fractional `?limit` (e.g. `49.9`) is floored to `49`. Confirms a manager cannot hold one synchronous request open / accrue unbounded Google API cost via an oversized limit |
 | TC-API-2.14 | Batch geocode — manager-only | As groomer/receptionist, `POST /api/clients/geocode-batch` | 403 Forbidden |
 | TC-API-2.15 | Auto-geocode on create | As manager/receptionist, `POST /api/clients` with a valid `address` | 201 Created; response includes a `geocoding` object (`status: "geocoded"` for a resolvable address) and the persisted client carries `latitude`/`longitude`/`geocodedAt`. Creating without an address succeeds with no `geocoding` field |
 | TC-API-2.16 | Auto-geocode on address update | As manager/receptionist, `PATCH /api/clients/{id}` changing `address` to a new valid value | 200 OK; response includes a `geocoding` object and refreshed coordinates. Patching unrelated fields (e.g. `name`) does NOT re-geocode (no `geocoding` field) |
@@ -165,6 +166,8 @@ Geocoding turns a client's street address into `latitude`/`longitude` + `geocode
 | TC-API-3.19b | Get pet profile summary — customer cross-tenant blocked (GRO-2013) | Sign in as `uat-customer@groombook.dev`; reuse the customer's sessionId from TC-API-3.19a; `GET /api/pets/{otherClientPetId}/profile-summary` for a pet owned by a different client (`c0000002-...` or any non-customer pet) | 403 Forbidden (owner-bypass requires session.clientId === pet.clientId) |
 | TC-API-3.19c | Get pet profile summary — customer without portal session header | Same as TC-API-3.19a but omit the `X-Impersonation-Session-Id` header | 403 Forbidden (no owner-bypass without valid portal session) |
 | TC-API-3.19d | Get pet profile summary — owner-bypass writes audit row (GRO-2063) | Same setup as TC-API-3.19a (sign in as `uat-customer@groombook.dev`, establish a portal session for the customer's own clientId, call `GET /api/pets/{ownPetId}/profile-summary` with `X-Impersonation-Session-Id: {sessionId}` and a 200 OK response). Then call `GET /api/impersonation/sessions/{sessionId}/audit-log` and confirm there is exactly one entry with `action === "read_profile_summary"`, `pageVisited` matching the profile-summary path, and `metadata` containing `petId` and `actorStaffId` for the customer. Repeat TC-API-3.19b (cross-tenant attempt) and confirm NO new `read_profile_summary` row was written for the cross-tenant attempt. | 200 OK on the profile-summary call AND an audit log entry is present with the correct shape (defense-in-depth audit row; bypass attempts against other clients must NOT log) |
+| TC-UAT-2 | Groomer accesses linked pet profile summary (GRO-2100) | Sign in as `uat-groomer@groombook.dev`; `GET /api/pets/c0000001-0000-0000-0000-000000000002/profile-summary` (UAT Pup Alpha — linked via deterministic completed appointment `a0000001-0000-0000-0000-000000000001`, service `b0000001-…-0001` "Bath & Brush", `startTime` ~7 days ago) | 200 OK, `recentGroomingHistory[]` non-empty (>=1 entry), `visitCount >= 1`, `upcomingAppointment` null (the seeded appointment is in the past) |
+| TC-UAT-3 | Groomer blocked from unlinked pet profile summary (GRO-2100) | Sign in as `uat-groomer@groombook.dev`; `GET /api/pets/c0000001-0000-0000-0000-000000000003/profile-summary` (UAT Pup Beta — intentionally UNLINKED; no appointment row references this pet's clientId+groomerId combo) | 403 Forbidden (RBAC `groomer` role lacks the appointment-linkage grant for this pet). NOTE: if 404 is returned instead of 403, file a separate RBAC defect (not against the seed) — see GRO-2100 verification note |
 | TC-API-3.29 | Get pet profile summary — unknown UUID returns 404 (GRO-2014) | GET /api/pets/00000000-0000-0000-0000-000000000001/profile-summary while authenticated (any role) | 404 Not Found with body `{"error":"Not found"}` (was empty-body 500 in GRO-2014) |
 | TC-API-3.30 | Get pet profile summary — malformed UUID returns 404 (GRO-2014) | GET /api/pets/not-a-uuid/profile-summary while authenticated | 404 Not Found with body `{"error":"Not found"}` (was empty-body 500 in GRO-2014 — Postgres uuid cast failure) |
 | TC-API-3.31 | Get pet profile summary — never empty-body 500 (GRO-2014) | GET /api/pets/{anyId}/profile-summary across the test sweep | No response has status 500 with an empty body. Any 500 must include a JSON body `{"error":"Internal Server Error"}` |
@@ -329,8 +332,8 @@ This means:
 
 | # | Scenario | Steps | Expected |
 |---|----------|-------|----------|
-| TC-API-13.1 | Get business settings | GET /api/admin/settings | 200 OK, business settings returned |
-| TC-API-13.2 | Update business settings | PATCH /api/admin/settings with updated values | 200 OK, settings updated |
+| TC-API-13.1 | Get business settings | GET /api/admin/settings | 200 OK, business settings returned. Response body **must NOT include `googleMapsApiKey`** — the encrypted secret is redacted from the projection (GRO-2294, defense-in-depth); non-secret fields (`businessName`, colors, `routeOptimizationProvider`, etc.) are still present |
+| TC-API-13.2 | Update business settings | PATCH /api/admin/settings with updated values | 200 OK, settings updated. Response body **must NOT include `googleMapsApiKey`** — the encrypted secret is redacted from the PATCH response symmetrically with the GET projection (GRO-2299, defense-in-depth); non-secret updated fields are still returned |
 | TC-API-13.3 | Upload logo | POST /api/admin/settings/logo/upload with file | 200 OK, logo uploaded and stored |
 | TC-API-13.4 | View logo | GET /api/admin/settings/logo | 200 OK, logo image returned |
 | TC-API-13.5 | Delete logo | DELETE /api/admin/settings/logo | 200 OK, logo removed |
@@ -406,6 +409,29 @@ Builds on §4.16. After optimization each consecutive leg carries a travel `buff
 | TC-API-17.7 | Reorder invalid routeId | `PATCH /api/routes/not-a-uuid/reorder` | 400 `{ error: "routeId must be a UUID" }` |
 | TC-API-17.8 | Groomer cannot reorder another's route | As groomer, reorder a route owned by a different groomer | 403 Forbidden (`groomers may only access their own route`) |
 
+### 4.18 Route Optimization — Navigation Export (GRO-2157, Phase 2.3)
+
+Builds on §4.16/§4.17. Two read-only endpoints turn an optimized route into a native-navigation deep-link URL the frontend opens on the groomer's phone:
+
+- `GET /api/routes/:routeId/export/google-maps` → Google Maps URLs API link (`https://www.google.com/maps/dir/?api=1&travelmode=driving&origin=…&destination=…&waypoints=…`)
+- `GET /api/routes/:routeId/export/apple-maps` → Apple Maps URL scheme (`maps://?saddr=…&daddr=<first>+to:<next>…&dirflg=d`)
+
+Both use the stops' stored `latitude`/`longitude` in `stopOrder`: **origin = first stop, destination = last stop, the rest are ordered intermediate waypoints**. Each response body is `{ platform, url, stopCount, waypointCount }` where `waypointCount` = stops minus origin and destination. Waypoint limits are validated per platform: **Google Maps ≤ 9**, **Apple Maps ≤ 15** intermediate waypoints; over-limit routes return 400. **Auth: manager (any route) or groomer (own route only); receptionists have no access.**
+
+| ID | Scenario | Steps | Expected |
+|----|----------|-------|----------|
+| TC-API-18.1 | Google Maps export of a multi-stop route | As manager, optimize a multi-stop day (§4.16), then `GET /api/routes/{routeId}/export/google-maps` | 200 OK; `platform:"google-maps"`, `url` starts `https://www.google.com/maps/dir/?api=1`, contains `travelmode=driving`, `origin`/`destination` are the first/last stop coords, `waypoints` lists the middle stops in order (pipe-separated). `stopCount` = total stops, `waypointCount` = `stopCount − 2` |
+| TC-API-18.2 | Apple Maps export of a multi-stop route | As manager, `GET /api/routes/{routeId}/export/apple-maps` for the same route | 200 OK; `platform:"apple-maps"`, `url` starts `maps://?saddr=`, `daddr` chains the remaining stops with `+to:`, ends `&dirflg=d`; `stopCount`/`waypointCount` as above |
+| TC-API-18.3 | Single-stop route | Export a route (google-maps and apple-maps) that has exactly one stop | 200 OK; `waypointCount:0`. Google url has `destination` and no `waypoints=`; Apple url is `maps://?daddr=<coord>&dirflg=d` (no `saddr`) |
+| TC-API-18.4 | Empty route rejected | Export a route with no stops (a fresh `draft` route) | 400 `{ error: "route has no stops to export" }` |
+| TC-API-18.5 | Google waypoint limit | Export (google-maps) a route with >11 stops (>9 intermediate waypoints) | 400 with an `error` mentioning Google Maps' limit of 9 |
+| TC-API-18.6 | Apple waypoint limit | Export (apple-maps) a route with >17 stops (>15 intermediate waypoints) | 400 with an `error` mentioning Apple Maps' limit of 15 |
+| TC-API-18.7 | Unknown route | `GET /api/routes/{randomUuid}/export/google-maps` | 404 `{ error: "Route not found" }` |
+| TC-API-18.8 | Invalid routeId | `GET /api/routes/not-a-uuid/export/apple-maps` | 400 `{ error: "routeId must be a UUID" }` |
+| TC-API-18.9 | Groomer exports own route | As **groomer**, export a route owned by self | 200 OK; deep-link returned |
+| TC-API-18.10 | Groomer cannot export another's route | As groomer, export a route owned by a different groomer | 403 Forbidden (`groomers may only access their own route`) |
+| TC-API-18.11 | Receptionist denied | As **receptionist**, export any route | 403 Forbidden (role not permitted) |
+
 ## Pass/Fail Criteria
 
 **Pass:**

src/__tests__/geocodeBatchLimit.test.ts

@@ -0,0 +1,89 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+// GRO-2294: the POST /clients/geocode-batch handler must clamp ?limit to the
+// documented maximum (500) before invoking the geocoding service. We mock the
+// service to capture the exact limit the route forwards.
+
+const geocodeUngeocodedClients = vi.fn(async () => ({
+  totalRemaining: 0,
+  processed: 0,
+  geocoded: 0,
+  failed: 0,
+  remaining: 0,
+}));
+
+vi.mock("../services/clientGeocoding.js", () => ({
+  geocodeUngeocodedClients,
+  geocodeClient: vi.fn(),
+  resolveClientGeocodingProvider: vi.fn(),
+}));
+
+vi.mock("@groombook/db", () => {
+  const tableProxy = (name: string) =>
+    new Proxy(
+      { _name: name },
+      { get: (_t, p) => (p === "_name" ? name : { table: name, column: p }) }
+    );
+  return {
+    getDb: () => ({}),
+    clients: tableProxy("clients"),
+    appointments: tableProxy("appointments"),
+    and: vi.fn(),
+    eq: vi.fn(),
+    or: vi.fn(),
+    exists: vi.fn(),
+  };
+});
+
+const { clientsRouter } = await import("../routes/clients.js");
+
+const app = new Hono();
+app.route("/clients", clientsRouter);
+
+function postBatch(query: string) {
+  return app.request(`/clients/geocode-batch${query}`, { method: "POST" });
+}
+
+describe("POST /clients/geocode-batch — ?limit cap (GRO-2294)", () => {
+  beforeEach(() => {
+    geocodeUngeocodedClients.mockClear();
+  });
+
+  it("defaults to 50 when no ?limit is supplied", async () => {
+    const res = await postBatch("");
+    expect(res.status).toBe(200);
+    expect(geocodeUngeocodedClients).toHaveBeenCalledWith(expect.anything(), 50);
+  });
+
+  it("passes through a value within the cap", async () => {
+    const res = await postBatch("?limit=120");
+    expect(res.status).toBe(200);
+    expect(geocodeUngeocodedClients).toHaveBeenCalledWith(expect.anything(), 120);
+  });
+
+  it("clamps an over-cap value to 500", async () => {
+    const res = await postBatch("?limit=100000");
+    expect(res.status).toBe(200);
+    expect(geocodeUngeocodedClients).toHaveBeenCalledWith(expect.anything(), 500);
+  });
+
+  it("floors a fractional value before clamping", async () => {
+    const res = await postBatch("?limit=49.9");
+    expect(res.status).toBe(200);
+    expect(geocodeUngeocodedClients).toHaveBeenCalledWith(expect.anything(), 49);
+  });
+
+  it("rejects a non-positive limit with 400", async () => {
+    const res = await postBatch("?limit=0");
+    expect(res.status).toBe(400);
+    expect(geocodeUngeocodedClients).not.toHaveBeenCalled();
+  });
+
+  it("rejects a non-numeric limit with 400", async () => {
+    const res = await postBatch("?limit=abc");
+    expect(res.status).toBe(400);
+    expect(geocodeUngeocodedClients).not.toHaveBeenCalled();
+  });
+});

src/__tests__/navigationExport.test.ts

@@ -0,0 +1,140 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildGoogleMapsUrl,
+  buildAppleMapsUrl,
+  buildNavigationUrl,
+  intermediateWaypointCount,
+  GOOGLE_MAPS_MAX_WAYPOINTS,
+  APPLE_MAPS_MAX_WAYPOINTS,
+  type NavigationStop,
+} from "../services/navigationExport.js";
+
+function stops(n: number): NavigationStop[] {
+  return Array.from({ length: n }, (_, i) => ({
+    latitude: 47 + i / 100,
+    longitude: -122 - i / 100,
+    label: `Stop ${i + 1}`,
+  }));
+}
+
+describe("intermediateWaypointCount", () => {
+  it("excludes origin and destination", () => {
+    expect(intermediateWaypointCount(0)).toBe(0);
+    expect(intermediateWaypointCount(1)).toBe(0);
+    expect(intermediateWaypointCount(2)).toBe(0);
+    expect(intermediateWaypointCount(5)).toBe(3);
+  });
+});
+
+describe("buildGoogleMapsUrl", () => {
+  it("rejects an empty route", () => {
+    const r = buildGoogleMapsUrl([]);
+    expect(r).toEqual({ error: "route has no stops to export", status: 400 });
+  });
+
+  it("builds a single-stop link (destination only, no waypoints)", () => {
+    const r = buildGoogleMapsUrl(stops(1));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.platform).toBe("google-maps");
+    expect(r.stopCount).toBe(1);
+    expect(r.waypointCount).toBe(0);
+    expect(r.url).toContain("https://www.google.com/maps/dir/?");
+    expect(r.url).toContain("api=1");
+    expect(r.url).toContain("travelmode=driving");
+    expect(r.url).toContain("origin=47%2C-122");
+    expect(r.url).toContain("destination=47%2C-122");
+    expect(r.url).not.toContain("waypoints=");
+  });
+
+  it("builds origin/destination only for two stops", () => {
+    const r = buildGoogleMapsUrl(stops(2));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.waypointCount).toBe(0);
+    expect(r.url).not.toContain("waypoints=");
+    expect(r.url).toContain("origin=47%2C-122");
+    expect(r.url).toContain("destination=47.01%2C-122.01");
+  });
+
+  it("includes intermediate waypoints in order, pipe-separated", () => {
+    const r = buildGoogleMapsUrl(stops(4));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.stopCount).toBe(4);
+    expect(r.waypointCount).toBe(2);
+    // waypoints param holds stops[1] and stops[2], pipe-joined (encoded %7C)
+    const url = new URL(r.url);
+    expect(url.searchParams.get("origin")).toBe("47,-122");
+    expect(url.searchParams.get("destination")).toBe("47.03,-122.03");
+    expect(url.searchParams.get("waypoints")).toBe(
+      "47.01,-122.01|47.02,-122.02"
+    );
+  });
+
+  it("accepts a route at exactly the waypoint limit", () => {
+    const r = buildGoogleMapsUrl(stops(GOOGLE_MAPS_MAX_WAYPOINTS + 2));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.waypointCount).toBe(GOOGLE_MAPS_MAX_WAYPOINTS);
+  });
+
+  it("rejects a route over the waypoint limit", () => {
+    const r = buildGoogleMapsUrl(stops(GOOGLE_MAPS_MAX_WAYPOINTS + 3));
+    expect("error" in r).toBe(true);
+    if ("error" in r) {
+      expect(r.status).toBe(400);
+      expect(r.error).toContain(`${GOOGLE_MAPS_MAX_WAYPOINTS}`);
+    }
+  });
+});
+
+describe("buildAppleMapsUrl", () => {
+  it("rejects an empty route", () => {
+    const r = buildAppleMapsUrl([]);
+    expect(r).toEqual({ error: "route has no stops to export", status: 400 });
+  });
+
+  it("builds a destination-only link for one stop", () => {
+    const r = buildAppleMapsUrl(stops(1));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.platform).toBe("apple-maps");
+    expect(r.url).toBe("maps://?daddr=47,-122&dirflg=d");
+    expect(r.url).not.toContain("saddr=");
+  });
+
+  it("chains destinations with +to: for multiple stops", () => {
+    const r = buildAppleMapsUrl(stops(3));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.stopCount).toBe(3);
+    expect(r.waypointCount).toBe(1);
+    expect(r.url).toBe(
+      "maps://?saddr=47,-122&daddr=47.01,-122.01+to:47.02,-122.02&dirflg=d"
+    );
+  });
+
+  it("accepts a route at exactly the waypoint limit", () => {
+    const r = buildAppleMapsUrl(stops(APPLE_MAPS_MAX_WAYPOINTS + 2));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.waypointCount).toBe(APPLE_MAPS_MAX_WAYPOINTS);
+  });
+
+  it("rejects a route over the waypoint limit", () => {
+    const r = buildAppleMapsUrl(stops(APPLE_MAPS_MAX_WAYPOINTS + 3));
+    expect("error" in r).toBe(true);
+    if ("error" in r) {
+      expect(r.status).toBe(400);
+      expect(r.error).toContain(`${APPLE_MAPS_MAX_WAYPOINTS}`);
+    }
+  });
+});
+
+describe("buildNavigationUrl", () => {
+  it("dispatches to the google-maps builder", () => {
+    const r = buildNavigationUrl("google-maps", stops(2));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.platform).toBe("google-maps");
+  });
+
+  it("dispatches to the apple-maps builder", () => {
+    const r = buildNavigationUrl("apple-maps", stops(2));
+    if ("error" in r) throw new Error(r.error);
+    expect(r.platform).toBe("apple-maps");
+  });
+});

src/__tests__/portalWaitlistDuplicate.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+// GRO-2235: a duplicate active waitlist entry violates the partial unique index
+// idx_waitlist_active_unique. postgres-js surfaces it as SQLSTATE 23505 — the
+// handler must return a friendly 409, not a generic 500. The first insert still
+// returns 201, and unrelated errors still surface as 500.
+
+const CLIENT_ID = "550e8400-e29b-41d4-a716-446655440001";
+const SESSION_ID = "770e8400-e29b-41d4-a716-446655440003";
+const PET_ID = "880e8400-e29b-41d4-a716-446655440004";
+const SERVICE_ID = "990e8400-e29b-41d4-a716-446655440005";
+
+const futureDate = () => new Date(Date.now() + 30 * 60 * 1000);
+
+const ACTIVE_SESSION = {
+  id: SESSION_ID,
+  clientId: CLIENT_ID,
+  status: "active" as const,
+  reason: "manual",
+  startedAt: new Date(),
+  expiresAt: futureDate(),
+  createdAt: new Date(),
+};
+
+// Behaviour knob for the waitlist insert: "ok" returns a row, "duplicate" throws
+// a postgres-js-shaped unique-violation, "other" throws an unrelated error.
+let waitlistInsertMode: "ok" | "duplicate" | "other" = "ok";
+
+function resetMock() {
+  waitlistInsertMode = "ok";
+}
+
+function tableProxy(name: string) {
+  return new Proxy(
+    { _name: name },
+    { get: (t, p) => (p === "_name" ? name : { table: name, column: p }) }
+  );
+}
+
+vi.mock("@groombook/db", () => {
+  function makeChainable(data: unknown[]): unknown {
+    const arr = [...data];
+    const chain = new Proxy(arr, {
+      get(target, prop) {
+        if (prop === "where" || prop === "orderBy" || prop === "limit") {
+          return () => chain;
+        }
+        // @ts-expect-error proxy
+        return target[prop];
+      },
+    });
+    return chain;
+  }
+
+  const impersonationSessions = tableProxy("impersonationSessions");
+  const waitlistEntries = tableProxy("waitlistEntries");
+  const impersonationAuditLogs = tableProxy("impersonationAuditLogs");
+
+  return {
+    getDb: () => ({
+      select: () => ({
+        from: (table: { _name: string }) => {
+          if (table._name === "impersonationSessions") {
+            return makeChainable([ACTIVE_SESSION]);
+          }
+          return makeChainable([]);
+        },
+      }),
+      insert: (table: { _name: string }) => ({
+        values: (vals: Record<string, unknown>) => ({
+          returning: () => {
+            if (table._name === "waitlistEntries") {
+              if (waitlistInsertMode === "duplicate") {
+                throw Object.assign(new Error("duplicate key value"), { code: "23505" });
+              }
+              if (waitlistInsertMode === "other") {
+                throw Object.assign(new Error("not null violation"), { code: "23502" });
+              }
+              return [{ id: "entry-1", ...vals }];
+            }
+            // impersonationAuditLogs and anything else: succeed silently.
+            return [{ id: "audit-1", ...vals }];
+          },
+        }),
+      }),
+      update: () => ({
+        set: () => ({ where: () => Promise.resolve() }),
+      }),
+    }),
+    impersonationSessions,
+    waitlistEntries,
+    impersonationAuditLogs,
+    appointments: tableProxy("appointments"),
+    clients: tableProxy("clients"),
+    pets: tableProxy("pets"),
+    services: tableProxy("services"),
+    staff: tableProxy("staff"),
+    invoices: tableProxy("invoices"),
+    invoiceLineItems: tableProxy("invoiceLineItems"),
+    eq: vi.fn(),
+    and: vi.fn(),
+    inArray: vi.fn(),
+  };
+});
+
+const { portalRouter } = await import("../routes/portal.js");
+
+const app = new Hono();
+app.route("/portal", portalRouter);
+
+function postWaitlist(body: unknown) {
+  return app.request("/portal/waitlist", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      "X-Impersonation-Session-Id": SESSION_ID,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+const VALID_BODY = {
+  petId: PET_ID,
+  serviceId: SERVICE_ID,
+  preferredDate: "2026-07-01",
+  preferredTime: "09:00",
+};
+
+beforeEach(() => resetMock());
+
+describe("POST /portal/waitlist duplicate handling (GRO-2235)", () => {
+  it("returns 201 for the first insert", async () => {
+    waitlistInsertMode = "ok";
+    const res = await postWaitlist(VALID_BODY);
+    expect(res.status).toBe(201);
+  });
+
+  it("returns 409 with a friendly message for a duplicate (23505)", async () => {
+    waitlistInsertMode = "duplicate";
+    const res = await postWaitlist(VALID_BODY);
+    expect(res.status).toBe(409);
+    const json = (await res.json()) as { error: string };
+    expect(json.error).toBe(
+      "You already have a booking for this pet at that date and time."
+    );
+  });
+
+  it("still surfaces unrelated DB errors as 500", async () => {
+    waitlistInsertMode = "other";
+    const res = await postWaitlist(VALID_BODY);
+    expect(res.status).toBe(500);
+  });
+});

src/__tests__/settings.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { Hono } from "hono";
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+// GRO-2294: GET /api/admin/settings must not return the encrypted
+// googleMapsApiKey ciphertext, on either the existing-row or auto-create branch.
+
+let selectRows: Record<string, unknown>[] = [];
+let insertReturning: Record<string, unknown>[] = [];
+let updateReturning: Record<string, unknown>[] = [];
+
+function makeChainable(data: unknown[]): unknown {
+  const arr = [...data];
+  const chain = new Proxy(arr, {
+    get(target, prop) {
+      if (prop === "where" || prop === "orderBy" || prop === "limit") {
+        return () => chain;
+      }
+      // @ts-expect-error proxy passthrough
+      return target[prop];
+    },
+  });
+  return chain;
+}
+
+vi.mock("@groombook/db", () => {
+  const businessSettings = new Proxy(
+    { _name: "business_settings" },
+    { get: (_t, p) => (p === "_name" ? "business_settings" : { column: p }) }
+  );
+  return {
+    getDb: () => ({
+      select: () => ({ from: () => makeChainable(selectRows) }),
+      insert: () => ({
+        values: () => ({ returning: () => insertReturning }),
+      }),
+      update: () => ({
+        set: () => ({ where: () => ({ returning: () => updateReturning }) }),
+      }),
+    }),
+    businessSettings,
+    eq: vi.fn(),
+  };
+});
+
+vi.mock("../lib/s3.js", () => ({
+  getPresignedUploadUrl: vi.fn(),
+  deleteObject: vi.fn(),
+  putObject: vi.fn(),
+  getObject: vi.fn(),
+}));
+
+const { settingsRouter } = await import("../routes/settings.js");
+
+const app = new Hono();
+app.route("/settings", settingsRouter);
+
+// PATCH /settings is guarded by requireSuperUser(), which reads the staff record
+// from context. Inject a super-user staff row so the handler runs.
+const patchApp = new Hono<{
+  Variables: { staff: { id: string; isSuperUser: boolean } };
+}>();
+patchApp.use("*", async (c, next) => {
+  c.set("staff", { id: "staff-1", isSuperUser: true });
+  await next();
+});
+patchApp.route("/settings", settingsRouter);
+
+const FULL_ROW = {
+  id: "settings-uuid-1",
+  businessName: "GroomBook",
+  primaryColor: "#4f8a6f",
+  accentColor: "#8b7355",
+  routeOptimizationProvider: "google",
+  googleMapsApiKey: "ENCRYPTED::super-secret-ciphertext",
+  createdAt: new Date(),
+  updatedAt: new Date(),
+};
+
+describe("GET /settings — googleMapsApiKey redaction (GRO-2294)", () => {
+  beforeEach(() => {
+    selectRows = [];
+    insertReturning = [];
+  });
+
+  it("omits googleMapsApiKey from an existing settings row", async () => {
+    selectRows = [{ ...FULL_ROW }];
+    const res = await app.request("/settings", { method: "GET" });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("googleMapsApiKey");
+    // Non-secret fields are still returned.
+    expect(body.businessName).toBe("GroomBook");
+    expect(body.routeOptimizationProvider).toBe("google");
+  });
+
+  it("omits googleMapsApiKey from the auto-create branch", async () => {
+    selectRows = [];
+    insertReturning = [{ ...FULL_ROW, id: "settings-uuid-new" }];
+    const res = await app.request("/settings", { method: "GET" });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("googleMapsApiKey");
+    expect(body.id).toBe("settings-uuid-new");
+  });
+});
+
+describe("PATCH /settings — googleMapsApiKey redaction (GRO-2299)", () => {
+  beforeEach(() => {
+    selectRows = [];
+    insertReturning = [];
+    updateReturning = [];
+  });
+
+  function patchRequest(body: Record<string, unknown>) {
+    return patchApp.request("/settings", {
+      method: "PATCH",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(body),
+    });
+  }
+
+  it("omits googleMapsApiKey from the PATCH response", async () => {
+    selectRows = [{ ...FULL_ROW }];
+    updateReturning = [{ ...FULL_ROW, businessName: "Updated Name" }];
+    const res = await patchRequest({ businessName: "Updated Name" });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("googleMapsApiKey");
+    // Non-secret updated fields are still returned.
+    expect(body.businessName).toBe("Updated Name");
+    expect(body.routeOptimizationProvider).toBe("google");
+  });
+
+  it("omits googleMapsApiKey on the auto-create-then-update branch", async () => {
+    selectRows = [];
+    insertReturning = [{ ...FULL_ROW, id: "settings-uuid-new" }];
+    updateReturning = [{ ...FULL_ROW, id: "settings-uuid-new" }];
+    const res = await patchRequest({ primaryColor: "#123456" });
+    expect(res.status).toBe(200);
+    const body = (await res.json()) as Record<string, unknown>;
+    expect(body).not.toHaveProperty("googleMapsApiKey");
+    expect(body.id).toBe("settings-uuid-new");
+  });
+});

src/routes/clients.ts

@@ -12,6 +12,12 @@ import {
 
 export const clientsRouter = new Hono<AppEnv>();
 
+// Batch-geocode bounds (GRO-2294): default 50, hard cap 500. The cap bounds how
+// long one synchronous request stays open and the per-request external API cost
+// when routeOptimizationProvider = "google".
+const GEOCODE_BATCH_DEFAULT_LIMIT = 50;
+const GEOCODE_BATCH_MAX_LIMIT = 500;
+
 type ClientRow = typeof clients.$inferSelect;
 
 /**
@@ -185,12 +191,15 @@ clientsRouter.post("/:clientId/geocode", async (c) => {
 clientsRouter.post("/geocode-batch", async (c) => {
   const db = getDb();
   const limitRaw = c.req.query("limit");
-  let limit = 50;
+  let limit = GEOCODE_BATCH_DEFAULT_LIMIT;
   if (limitRaw !== undefined) {
     limit = Number(limitRaw);
     if (!Number.isFinite(limit) || limit <= 0) {
       return c.json({ error: "limit must be a positive integer" }, 400);
     }
+    // Clamp to the documented maximum to bound synchronous request duration
+    // and (for the Google provider) per-request external API cost.
+    limit = Math.min(Math.floor(limit), GEOCODE_BATCH_MAX_LIMIT);
   }
   const summary = await geocodeUngeocodedClients(db, limit);
   return c.json(summary);

src/routes/portal.ts

@@ -596,16 +596,32 @@ portalRouter.post(
     const body = c.req.valid("json");
     const clientId = c.get("portalClientId");
 
-    const [entry] = await db
-      .insert(waitlistEntries)
-      .values({
-        clientId,
-        petId: body.petId,
-        serviceId: body.serviceId,
-        preferredDate: body.preferredDate,
-        preferredTime: normalizeTime(body.preferredTime),
-      })
-      .returning();
+    let entry;
+    try {
+      [entry] = await db
+        .insert(waitlistEntries)
+        .values({
+          clientId,
+          petId: body.petId,
+          serviceId: body.serviceId,
+          preferredDate: body.preferredDate,
+          preferredTime: normalizeTime(body.preferredTime),
+        })
+        .returning();
+    } catch (err) {
+      // An exact duplicate active waitlist entry violates the partial unique
+      // index idx_waitlist_active_unique (client_id, pet_id, service_id,
+      // preferred_date, preferred_time WHERE status='active'). postgres-js
+      // surfaces this as SQLSTATE 23505 — return a friendly 409 rather than a
+      // generic 500 (GRO-2235). Unrelated errors still surface as 500.
+      if ((err as { code?: string })?.code === "23505") {
+        return c.json(
+          { error: "You already have a booking for this pet at that date and time." },
+          409
+        );
+      }
+      throw err;
+    }
 
     return c.json(entry, 201);
   }

src/routes/routes.ts

@@ -1,4 +1,4 @@
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import { zValidator } from "@hono/zod-validator";
 import { z } from "zod/v3";
 import {
@@ -24,6 +24,11 @@ import {
   type RouteStopInput,
   type StopConflictFlags,
 } from "../services/routeOptimization.js";
+import {
+  buildNavigationUrl,
+  type NavigationPlatform,
+  type NavigationStop,
+} from "../services/navigationExport.js";
 
 export const routesRouter = new Hono<AppEnv>();
 
@@ -460,3 +465,65 @@ routesRouter.patch(
     });
   }
 );
+
+/**
+ * GET /:routeId/export/:platform — build a native-navigation deep-link URL for an
+ * optimized route. Origin = first stop, destination = last stop, the rest carried
+ * as ordered intermediate waypoints. Waypoint count is validated against the
+ * platform's limit. Auth: manager (any route) or groomer (own route only).
+ */
+async function handleNavigationExport(
+  c: Context<AppEnv>,
+  platform: NavigationPlatform
+) {
+  const db = getDb();
+  const routeId = c.req.param("routeId");
+  if (!routeId || !z.string().uuid().safeParse(routeId).success) {
+    return c.json({ error: "routeId must be a UUID" }, 400);
+  }
+
+  const [route] = await db
+    .select()
+    .from(groomerRoutes)
+    .where(eq(groomerRoutes.id, routeId));
+  if (!route) {
+    return c.json({ error: "Route not found" }, 404);
+  }
+
+  // Reuse the groomer-own / manager authorization rule against the route owner.
+  const resolved = resolveTargetStaffId(c.get("staff"), route.staffId);
+  if ("error" in resolved) {
+    return c.json({ error: resolved.error }, resolved.status);
+  }
+
+  const stops = await loadRouteStops(db, routeId);
+  if (stops.length === 0) {
+    return c.json({ error: "route has no stops to export" }, 400);
+  }
+
+  const navStops: NavigationStop[] = stops.map((s) => ({
+    latitude: s.latitude,
+    longitude: s.longitude,
+    label: s.clientName,
+  }));
+
+  const result = buildNavigationUrl(platform, navStops);
+  if ("error" in result) {
+    return c.json({ error: result.error }, result.status);
+  }
+
+  return c.json({
+    platform: result.platform,
+    url: result.url,
+    stopCount: result.stopCount,
+    waypointCount: result.waypointCount,
+  });
+}
+
+routesRouter.get("/:routeId/export/google-maps", (c) =>
+  handleNavigationExport(c, "google-maps")
+);
+
+routesRouter.get("/:routeId/export/apple-maps", (c) =>
+  handleNavigationExport(c, "apple-maps")
+);

src/routes/settings.ts

@@ -7,6 +7,17 @@ import { requireSuperUser } from "../middleware/rbac.js";
 
 export const settingsRouter = new Hono();
 
+type BusinessSettingsRow = typeof businessSettings.$inferSelect;
+
+// Strip the encrypted googleMapsApiKey ciphertext from settings responses
+// (GRO-2294, defense-in-depth). The secret is never needed client-side; it is
+// only written via the dedicated provider-config endpoint.
+function redactSettings(row: BusinessSettingsRow) {
+  const rest: Partial<BusinessSettingsRow> = { ...row };
+  delete rest.googleMapsApiKey;
+  return rest;
+}
+
 // GET /api/admin/settings — return current business settings
 settingsRouter.get("/", async (c) => {
   const db = getDb();
@@ -14,9 +25,10 @@ settingsRouter.get("/", async (c) => {
   if (!row) {
     // Auto-create default settings if none exist
     const [created] = await db.insert(businessSettings).values({}).returning();
-    return c.json(created);
+    if (!created) throw new Error("Failed to create default settings");
+    return c.json(redactSettings(created));
   }
-  return c.json(row);
+  return c.json(redactSettings(row));
 });
 
 const hexColorRegex = /^#[0-9a-fA-F]{6}$/;
@@ -53,7 +65,8 @@ settingsRouter.patch(
       .where(eq(businessSettings.id, settingsId))
       .returning();
 
-    return c.json(updated);
+    if (!updated) throw new Error("Failed to update settings");
+    return c.json(redactSettings(updated));
   }
 );
 

src/services/navigationExport.ts

@@ -0,0 +1,155 @@
+// Navigation export — turn an optimized groomer route into a deep-link URL that
+// opens the device's native navigation app (Google Maps / Apple Maps).
+//
+// A route is exported as: origin = first stop, destination = last stop, with the
+// in-between stops carried as ordered intermediate waypoints. Each platform caps
+// how many intermediate waypoints a deep link may carry, so callers must validate
+// the route length before handing the URL to the client.
+
+/**
+ * Max intermediate waypoints a Google Maps URLs API deep link supports
+ * (`https://www.google.com/maps/dir/?api=1&...&waypoints=...`). Google documents
+ * a ceiling of 9 waypoints between origin and destination.
+ */
+export const GOOGLE_MAPS_MAX_WAYPOINTS = 9;
+
+/**
+ * Max intermediate waypoints we allow in an Apple Maps `maps://` deep link. Apple's
+ * URL scheme chains destinations with `+to:` but does not publish a hard cap; 15 is
+ * a conservative practical limit that keeps the URL well under length limits.
+ */
+export const APPLE_MAPS_MAX_WAYPOINTS = 15;
+
+export type NavigationPlatform = "google-maps" | "apple-maps";
+
+/** A single ordered point on the route. `label` is optional, for display only. */
+export interface NavigationStop {
+  latitude: number;
+  longitude: number;
+  label?: string | null;
+}
+
+export interface NavigationExportSuccess {
+  platform: NavigationPlatform;
+  url: string;
+  /** Total stops included (origin + waypoints + destination). */
+  stopCount: number;
+  /** Intermediate waypoints only (excludes origin and destination). */
+  waypointCount: number;
+}
+
+export interface NavigationExportError {
+  error: string;
+  status: 400;
+}
+
+export type NavigationExportResult =
+  | NavigationExportSuccess
+  | NavigationExportError;
+
+function isError(r: NavigationExportResult): r is NavigationExportError {
+  return "error" in r;
+}
+
+/** Intermediate waypoints = every stop that is neither origin nor destination. */
+export function intermediateWaypointCount(stopCount: number): number {
+  return Math.max(0, stopCount - 2);
+}
+
+function coord(stop: NavigationStop): string {
+  return `${stop.latitude},${stop.longitude}`;
+}
+
+/**
+ * Builds a Google Maps URLs API driving deep link. On mobile this opens the
+ * native Google Maps app; on desktop it opens maps.google.com.
+ */
+export function buildGoogleMapsUrl(
+  stops: NavigationStop[]
+): NavigationExportResult {
+  if (stops.length === 0) {
+    return { error: "route has no stops to export", status: 400 };
+  }
+  const waypointCount = intermediateWaypointCount(stops.length);
+  if (waypointCount > GOOGLE_MAPS_MAX_WAYPOINTS) {
+    return {
+      error: `route has ${waypointCount} intermediate waypoints, exceeding Google Maps' limit of ${GOOGLE_MAPS_MAX_WAYPOINTS}`,
+      status: 400,
+    };
+  }
+
+  const origin = stops[0]!;
+  const destination = stops[stops.length - 1]!;
+  const params = new URLSearchParams();
+  params.set("api", "1");
+  params.set("travelmode", "driving");
+  params.set("origin", coord(origin));
+  params.set("destination", coord(destination));
+  if (stops.length > 2) {
+    const mids = stops
+      .slice(1, -1)
+      .map(coord)
+      .join("|");
+    params.set("waypoints", mids);
+  }
+
+  return {
+    platform: "google-maps",
+    url: `https://www.google.com/maps/dir/?${params.toString()}`,
+    stopCount: stops.length,
+    waypointCount,
+  };
+}
+
+/**
+ * Builds an Apple Maps `maps://` driving deep link. The first stop is the source
+ * (`saddr`); the remaining stops are chained as destinations with `+to:` (`daddr`).
+ * Built by hand because the `+to:` separators are part of Apple's scheme and must
+ * not be percent-encoded.
+ */
+export function buildAppleMapsUrl(
+  stops: NavigationStop[]
+): NavigationExportResult {
+  if (stops.length === 0) {
+    return { error: "route has no stops to export", status: 400 };
+  }
+  const waypointCount = intermediateWaypointCount(stops.length);
+  if (waypointCount > APPLE_MAPS_MAX_WAYPOINTS) {
+    return {
+      error: `route has ${waypointCount} intermediate waypoints, exceeding Apple Maps' limit of ${APPLE_MAPS_MAX_WAYPOINTS}`,
+      status: 400,
+    };
+  }
+
+  const params: string[] = ["dirflg=d"];
+  if (stops.length === 1) {
+    // Single stop: destination only, no source.
+    params.unshift(`daddr=${coord(stops[0]!)}`);
+  } else {
+    const daddr = stops
+      .slice(1)
+      .map(coord)
+      .join("+to:");
+    params.unshift(`daddr=${daddr}`);
+    params.unshift(`saddr=${coord(stops[0]!)}`);
+  }
+
+  return {
+    platform: "apple-maps",
+    url: `maps://?${params.join("&")}`,
+    stopCount: stops.length,
+    waypointCount,
+  };
+}
+
+/** Dispatches to the correct builder for the requested platform. */
+export function buildNavigationUrl(
+  platform: NavigationPlatform,
+  stops: NavigationStop[]
+): NavigationExportResult {
+  return platform === "google-maps"
+    ? buildGoogleMapsUrl(stops)
+    : buildAppleMapsUrl(stops);
+}
+
+export { isError as isNavigationExportError };