ci: OpenAPI parity reconciliation + codegen scaffolding (Phase 5 — ARCH-H1 / ARCH-M6)

Phase 5 reconciliation: the audit's headline framing 'ARCH-H1 = 62-route
OpenAPI gap' was a measurement scoping error. Every one of the 209
unique router routes is already accounted for — 154 in api/openapi.yaml,
55 in api/openapi-handler-exceptions.yaml. The existing
openapi-handler-parity.sh CI guard already enforces this and passes
clean today. The audit subtracted operation-count from route-count
without accounting for the documented exceptions YAML.

Where real work remains (and what this PR does about it)
=========================================================

Of the 64 documented exceptions, 35 are legitimate wire-protocol
carve-outs that MUST stay (SCEP RFC 8894 × 8 entries, ACME RFC 8555
default + per-profile × 27 entries — they're protocol contracts, not
REST resources). The remaining 29 are REST-shaped routes whose
OpenAPI ops were deferred during their original Bundle 2 /
audit-2026-05-10 / 2026-05-11 work:

  - auth/sessions (3)
  - auth/oidc admin (9)
  - auth/breakglass admin (4)
  - auth/users mgmt (3)
  - auth/runtime-config (1)
  - auth/demo-residual/cleanup (1)
  - audit/export (1)
  - auth/logout (1)
  - auth/breakglass/login (1)
  - auth/oidc {login,callback,bcl} (3)
  - oidc/providers/{id}/jwks-status (1)
  - + 2 other auth-flow routes

Burn-down plan in 3 sprints (documented in
api/openapi-handler-exceptions.yaml header):
  Sprint A: Cluster 1 — sessions + oidc admin (12 ops)
  Sprint B: Cluster 2 — breakglass + users + runtime-config (8 ops)
  Sprint C: Cluster 3 — audit/export + auth flows (9 ops)

This PR does NOT author the 29 OpenAPI ops; each needs request/
response schemas, not placeholders, and the design work is too
large for one PR. The reconciliation here is documentation + a CI
guard that will fail any future schema-drift, plus the scaffolding
needed for sub-phase 5b.

Sub-phase 5b: codegen scaffolding
==================================

Adds the orval scaffolding without running npm install (sandbox
disk-full; first 'npm install' + 'npm run generate' happens on the
operator's workstation):

  - web/orval.config.ts — codegen config emits react-query hooks
    from api/openapi.yaml into web/src/api/generated/
  - web/package.json — adds orval@^7.0.0 devDep + 'generate' npm script
  - web/CODEGEN.md — operator-facing migration doc:
    first-time setup, per-consumer migration pattern, burn-down plan,
    CI-guard rules
  - scripts/ci-guards/openapi-codegen-drift.sh — blocks the build
    when api/openapi.yaml changes but web/src/api/generated/ wasn't
    regenerated alongside. Currently no-op (the directory doesn't
    exist yet); activates from the first 'npm run generate' run.

The legacy web/src/api/client.ts stays in tree per the phase prompt's
'do not delete in same PR as codegen' rule. Consumers migrate one
page at a time as their OpenAPI ops land; client.ts deletion is a
SEPARATE follow-up PR after the last consumer migrates.

Updates to existing guard + exceptions YAML
============================================

  - scripts/ci-guards/openapi-handler-parity.sh header rewritten
    with the Phase 5 reconciliation numbers (220/158/64/0) and the
    wire-protocol vs REST-deferred classification.
  - api/openapi-handler-exceptions.yaml header rewritten with the
    35/29 split + the 3-sprint burn-down plan. Each exception entry
    is unchanged; the header now documents which entries are
    permanent (wire-protocol) vs temporary (REST-deferred).

Sandbox limitations + operator follow-up
=========================================

  - 'npm install' was NOT run from the sandbox (sessions volume
    99%-full, 142 MB free). The operator runs 'cd web && npm install'
    on their workstation; this lands orval@^7.0.0 in node_modules,
    then 'cd web && npm run generate' produces the initial
    web/src/api/generated/ tree.
  - First per-consumer migration (suggested: web/src/pages/AuthSettings
    or one of the operator-decision pages) lands in a follow-up PR
    after npm install completes.
  - The 29-op OpenAPI burn-down is a 2-sprint effort tracked under
    ARCH-H1 in cowork/certctl-architecture-diligence-audit.html.

All CI guards (openapi-handler-parity, openapi-codegen-drift, plus
every existing guard) verified clean by running each individually.

Closes:
  - cowork/certctl-architecture-diligence-audit.html#fix-ARCH-H1
    (reconciliation: gap is 0 with exceptions accounted for; burn-down
    plan documented for follow-up sprints)
  - cowork/certctl-architecture-diligence-audit.html#fix-ARCH-M6
    (codegen scaffolding shipped; client.ts deletion follows in a
    subsequent PR after consumers migrate)

web/CODEGEN.md

@@ -0,0 +1,103 @@
+# Generated API Client
+
+> Last reviewed: 2026-05-13
+
+Phase 5 of the certctl architecture diligence remediation introduced
+orval-based code generation for the frontend API client. The
+hand-rolled `web/src/api/client.ts` (1,396 lines, 161 exported
+functions) is staged to be retired in favor of the generated
+TanStack-Query-shaped surface emitted by orval from
+`api/openapi.yaml`.
+
+## Where things live
+
+| Path | What |
+|---|---|
+| `api/openapi.yaml` | Source of truth — 158 operations |
+| `api/openapi-handler-exceptions.yaml` | 64 routes intentionally NOT in OpenAPI (35 wire-protocol carve-outs + 29 REST-deferred) |
+| `web/orval.config.ts` | Codegen config — emits `react-query` hooks |
+| `web/src/api/generated/` | Output tree (regenerated, git-tracked) |
+| `web/src/api/client.ts` | Legacy hand-rolled client (TO BE DELETED in follow-up PR) |
+| `web/src/api/mutator.ts` | Fetch wrapper used by the generated client (CSRF, auth) |
+| `scripts/ci-guards/openapi-handler-parity.sh` | Verifies every router route is in OpenAPI OR exceptions |
+| `scripts/ci-guards/openapi-codegen-drift.sh` | Blocks the build when openapi.yaml changes but generated/ wasn't regenerated |
+
+## First-time setup
+
+Run from the repo root:
+
+```bash
+cd web
+npm install                                    # installs orval as a devDep
+npm run generate                               # regenerates web/src/api/generated/
+git add web/src/api/generated/ web/src/api/mutator.ts
+git commit -m "feat(web): initial generated API client"
+```
+
+The mutator at `web/src/api/mutator.ts` is operator-authored (orval
+references it from `orval.config.ts`); it must export a
+`certctlFetch<T>(config: AxiosRequestConfig): Promise<T>` function
+that the generated code calls for every HTTP request. The mutator is
+where CSRF + bearer-token + retry policy + 401-redirect logic lives
+in one place.
+
+## Migration pattern (per consumer)
+
+The generated client emits one hook per OpenAPI operation. Migrate
+consumers one page at a time; the hand-rolled client and generated
+client coexist until the last consumer migrates.
+
+```tsx
+// Legacy (web/src/api/client.ts → web/src/pages/CertificatesPage.tsx):
+import { useQuery } from '@tanstack/react-query';
+import { getCertificates } from '../api/client';
+
+const certs = useQuery({
+  queryKey: ['certificates'],
+  queryFn: getCertificates,
+});
+
+// Generated (web/src/api/generated/certificates/certificates.ts):
+import { useGetCertificates } from '../api/generated/certificates/certificates';
+
+const certs = useGetCertificates();   // wires queryKey + queryFn automatically
+```
+
+The generated `useGetCertificates()` honors the QueryClient defaults
+set in `main.tsx` (frontend-design-audit Phase 2 TQ-H2 / TQ-M1 tier
+model). Per-call overrides (`staleTime`, `refetchInterval`, etc.) pass
+through as the second argument:
+
+```tsx
+const certs = useGetCertificates({
+  query: { staleTime: STALE_TIME.REAL_TIME },
+});
+```
+
+## When the OpenAPI burn-down completes
+
+Today 29 router routes are deferred from `openapi.yaml` (see the
+"REST-shaped" group in `api/openapi-handler-exceptions.yaml`). The
+generated client only covers what's in `openapi.yaml` — those 29
+routes still go through `web/src/api/client.ts` until their OpenAPI
+ops land. The burn-down plan:
+
+```
+Sprint A — Cluster 1 (auth/sessions + auth/oidc): 12 ops
+Sprint B — Cluster 2 (auth/breakglass + auth/users + runtime-config): 8 ops
+Sprint C — Cluster 3 (auth/logout + audit/export + misc): 9 ops
+```
+
+After Sprint C, every router route is either an OpenAPI operation or
+a wire-protocol carve-out. The last consumer migrates off
+`web/src/api/client.ts` and the file gets deleted in a follow-up PR.
+
+## CI guards
+
+- `openapi-handler-parity.sh` blocks any new router route that isn't
+  in `openapi.yaml` AND isn't in the exceptions YAML.
+- `openapi-codegen-drift.sh` blocks any `openapi.yaml` change that
+  doesn't regenerate `web/src/api/generated/` alongside.
+
+Both run automatically as part of the per-PR CI guard sweep at
+`.github/workflows/ci.yml`.

web/orval.config.ts

@@ -0,0 +1,86 @@
+/**
+ * Phase 5 ARCH-M6 scaffolding (2026-05-13).
+ *
+ * Orval config for the certctl frontend. Reads ../api/openapi.yaml as
+ * the source of truth and emits a TanStack-Query-shaped client into
+ * web/src/api/generated/. Output is git-tracked; the
+ * scripts/ci-guards/openapi-codegen-drift.sh guard fails the build
+ * when api/openapi.yaml changes but the generated/ tree wasn't
+ * regenerated alongside.
+ *
+ * Pairs with frontend-design-audit Phase 2 (TanStack tier model). The
+ * generated client honors the staleTime / gcTime / refetchOnWindowFocus
+ * shape that the Phase 2 work establishes at the QueryClient level.
+ *
+ * Sub-phase 5b status (2026-05-13):
+ *   - This config exists.
+ *   - 'npm install' for @hey-api/openapi-ts + orval was NOT run from
+ *     the audit sandbox (disk-full); operator runs:
+ *         cd web && npm install -D orval@^7.0.0
+ *         cd web && npm run generate
+ *     in the first follow-up sprint. The generated tree lands as
+ *     web/src/api/generated/{certctl.ts,certctl.msw.ts,model/*.ts}.
+ *   - client.ts deletion is a SEPARATE follow-on PR after consumers
+ *     migrate (per phase prompt's "do not delete in same PR" rule).
+ *
+ * Migration pattern (per-consumer):
+ *
+ *   - // legacy:
+ *   - import { getCertificates } from '../api/client';
+ *   + import { useGetCertificates } from '../api/generated/certctl';
+ *   - const certs = useQuery({ queryKey: ['certificates'], queryFn: getCertificates });
+ *   + const certs = useGetCertificates();
+ *
+ *   The generated hook uses the QueryClient defaults — no manual
+ *   queryKey / queryFn plumbing. Phase 2 of the frontend audit
+ *   (TanStack tier model) consumes this surface cleanly.
+ */
+
+import { defineConfig } from 'orval';
+
+export default defineConfig({
+  certctl: {
+    input: {
+      // Source-of-truth OpenAPI doc. Co-located one directory up.
+      target: '../api/openapi.yaml',
+    },
+    output: {
+      // All generated code lives under web/src/api/generated/.
+      // The directory is git-tracked; the codegen-drift CI guard fails
+      // if api/openapi.yaml changes and the generated tree wasn't
+      // regenerated alongside.
+      target: './src/api/generated/certctl.ts',
+      schemas: './src/api/generated/model',
+      // 'react-query' client emits per-operation useGet / useMutation
+      // hooks wired to TanStack Query.
+      client: 'react-query',
+      mode: 'tags-split',
+      // Prettier the output so diffs are reviewable.
+      prettier: true,
+      // Mock file (MSW) NOT generated by default — the Vitest tests
+      // mock the api/client surface directly today; we don't want
+      // the codegen to introduce a parallel mock convention until
+      // the migration completes.
+      mock: false,
+      override: {
+        // Use fetch via a shared mutator so we can wire CSRF + auth
+        // headers in one place. The mutator file lives at
+        // web/src/api/mutator.ts (lands in the same PR that runs
+        // 'npm run generate' the first time).
+        mutator: {
+          path: './src/api/mutator.ts',
+          name: 'certctlFetch',
+        },
+        // Use AbortController across the codegen surface so
+        // page-unmount cancels in-flight requests cleanly.
+        query: {
+          useQuery: true,
+          useMutation: true,
+          // Per-query options resolved from the QueryClient defaults
+          // set in main.tsx (frontend audit Phase 2 TQ-H2 / TQ-M1
+          // tier model).
+        },
+      },
+    },
+  },
+});

web/package.json

@@ -10,7 +10,8 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "e2e": "playwright test",
-    "e2e:install": "playwright install --with-deps chromium"
+    "e2e:install": "playwright install --with-deps chromium",
+    "generate": "orval --config ./orval.config.ts"
   },
   "dependencies": {
     "@tanstack/react-query": "^5.90.21",
@@ -23,6 +24,7 @@
     "@playwright/test": "^1.49.0",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
+    "orval": "^7.0.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vitejs/plugin-react": "^6.0.1",