@payez/next-mvp 4.1.20 → 4.4.0

package/POST-INSTALL.md

@@ -0,0 +1,408 @@
+# Post-Install Debt
+
+**A running tab of everything a consuming site must do BY HAND after `npm install @payez/next-mvp`.**
+
+This file exists because "works out of the box" is the product claim and it is currently
+false. Every row below is work the package pushed onto the consumer. The tab is the backlog:
+the goal is to empty it, not to document it more thoroughly.
+
+Started 2026-08-26 from the UMI Browser (`umi_browser_website`, client 16) integration, where
+every single row was hit in one sitting. UMI is the honest measure of the out-of-box
+experience because nobody had pre-wired it — unlike idealresume.online and idealvibe.online,
+which were built alongside the package and quietly absorbed each of these as they appeared.
+
+**Add a row the moment you hand-write something the package could have shipped.** A step you
+only discover by hitting it is the same defect class this codebase keeps paying for: present,
+plausible and inert.
+
+---
+
+## Scoring
+
+- **P1** — site is broken or insecure until done, and nothing tells you
+- **P2** — site is degraded or wrong until done
+- **P3** — friction; you get there, but slower than you should
+
+**Fix class:**
+- `auto` — the package could just do this, no consumer action at all
+- `codemod` — a generator / `npx @payez/next-mvp init` could write it
+- `doc` — genuinely a consumer choice; it only needs to be findable
+
+---
+
+## The tab
+
+| # | What you must hand-write | P | Fix class | Status |
+|---|---|---|---|---|
+| 1 | 16 CSS variables in `globals.css` | P1 | auto | open |
+| 2 | `/api/auth/[...nextauth]` route file | P1 | codemod | open |
+| 3 | `/api/auth/settings` route file | P1 | codemod | open |
+| 4 | `/login` page mounting `ModeAwareLoginPage` | P1 | codemod | open |
+| 5 | `instrumentation.ts` + the node split | P1 | codemod | open |
+| 6 | `next.config.js` transpile + tracing keys | P1 | doc | open |
+| 7 | `--primary` vs `--color-primary` collision | P2 | auto | open |
+| 8 | `/test-env/*` mounts + `ENABLE_TEST_ROUTES` | P2 | doc | open |
+| 9 | Local user record (route + lib + hook) | P2 | codemod | open |
+| 10 | `server-auth.ts` wrapper | P3 | auto | open |
+| 11 | `REDIS_URL` and the required env set | P3 | doc | open |
+| 12 | `providers.tsx` provider nesting | P3 | codemod | open |
+| 13 | `/api/internal/session-data` — page ships, endpoint does not | P1 | auto | open |
+| 14 | **`routes/auth/nextauth` is a trap — do not mount it** | P1 | auto | open |
+| 15 | `id_token` dropped by a module-scoped ALS | P1 | auto | **CLOSED 4.3.4** |
+| 16 | Tenant-side: `VIBE_COLLECTION` is doing double duty | P2 | doc | open |
+| 17 | Tenant-side: vibe-client 0.2.3 sends the wrong filter shape | P2 | — | open (not this package) |
+
+**Nothing is closed yet. There is no `postinstall` script and no `init` command.**
+
+---
+
+## 1. Sixteen CSS variables, and `ThemeProvider` emits none of them — P1
+
+The worst row on the tab, because it is invisible: the site renders, it just looks wrong, and
+the fallbacks make it look *deliberately* wrong rather than unstyled.
+
+Measured 2026-08-26 against installed `dist`:
+
+```
+components/ and pages/ READ   16 CSS variables
+theme/ThemeProvider WRITES     0
+```
+
+The sixteen:
+
+```
+--background  --bg-card  --bg-default  --border  --border-default  --card
+--color-error --color-primary --foreground --input --muted --muted-foreground
+--primary --text-muted --text-primary --text-secondary
+```
+
+`ThemeProvider` takes a theme object and emits **nothing to CSS**. So all three sites
+independently hand-authored the same variable block in their own `globals.css` — three
+copies, already drifting.
+
+**Fix:** `ThemeProvider` maps the theme object onto these sixteen and sets them. That is the
+entire job it appears to exist to do. Until then a site that installs the package and uses a
+component gets silent fallbacks.
+
+## 2–4. The package exports routes and pages; you mount every one — P1
+
+`@payez/next-mvp` exports working handlers and pages. It cannot create files in your `app/`
+directory, so **every one of them is a 404 until you write a re-export by hand** — and
+nothing tells you which exist.
+
+UMI had **zero of them mounted** and looked like a working site. The login page rendered a
+demo gate against hardcoded strings; `/api/auth/*` did not exist at all, so the sign-in
+screen's request for what the client offers 404'd and it drew nothing.
+
+```
+app/api/auth/[...nextauth]/route.ts   export { GET, POST } from '@payez/next-mvp/routes/auth/nextauth';
+app/api/auth/settings/route.ts        export { GET }       from '@payez/next-mvp/routes/auth/settings';
+app/login/page.tsx                    ModeAwareLoginPage + your branding
+```
+
+**Fix:** `npx @payez/next-mvp init` writes these. Failing that, one page in the README that
+lists every mountable export — there is currently no such list anywhere.
+
+## 5. `instrumentation.ts`, and the part the template gets wrong — P1
+
+A template ships at `src/templates/instrumentation.ts` — the only template in the package —
+but you still copy it in by hand, and it is **not** the shape that works.
+
+Two things it does not tell you:
+
+- **`instrumentation.ts` is compiled for BOTH the node and edge runtimes.** `NEXT_RUNTIME` is
+  a *runtime* guard; imports resolve at *build* time, so node-only dependencies still get
+  traced into the edge bundle and the build fails. The working shape is a thin
+  `instrumentation.ts` that dynamic-imports `instrumentation-node.ts`.
+- **`await import()` does not stay dynamic under `module: CommonJS`.** TypeScript emits
+  `Promise.resolve().then(() => require(...))`, which is statically traced exactly like a
+  top-level import. Cost us three failed fixes.
+
+Also: the template's catch block used to log *"Will retry initialization on first request"*
+and continue. It does not retry. A site whose IDP handshake failed would serve requests
+with no auth config and say so nowhere. Now `process.exit(1)`.
+
+**Fix:** ship the two-file split as the template, and put both facts above in it as comments.
+
+## 6. `next.config.js` — two keys, and one that must never come back — P1
+
+```js
+transpilePackages: ['@payez/next-mvp'],
+outputFileTracingRoot: path.join(__dirname),
+```
+
+Mentioned in two docs, in passing, not as a required step.
+
+**Do not add a `webpack:` key to work around a bundler warning.** It disables Turbopack and
+turns a cosmetic warning into a hard `UnhandledSchemeError`. A note now sits in UMI's
+`next.config.js` saying so.
+
+**Related, and the reason a day was lost:** `next dev` uses **webpack** by default in Next
+15.5. Turbopack is opt-in via `--turbopack`. Assuming otherwise sent three bundler fixes at
+the wrong bundler.
+
+## 7. `--primary` and `--color-primary` are two names for one value — P2
+
+Components read both. Nothing defines the relationship. `TraditionalAuthSection`'s submit
+button hardcodes `var(--color-primary, #10b981)` — so a site that defines `--primary` and not
+`--color-primary` gets a **green** button no matter what its brand colour is. UMI is
+`#FF6B5B`; it defines both, as a workaround.
+
+This is the CLAUDE.md rule the package itself breaks: **one value gets one name.** Pick
+`--color-primary`, and drop the hardcoded emerald — a fallback that silently substitutes
+another product's brand colour is worse than no fallback.
+
+## 8. `/test-env/*` — four pages, a flag, and a trap — P2
+
+Four diagnostics ship (`TestEnvPage`, `JwtInspectPage`, `RefreshTokenPage`,
+`EmergencyLogoutPage`). Documented in **zero** docs. idealvibe mounts five routes; UMI mounted
+none and every URL 404'd.
+
+They are exported **only** as guarded server components — the raw client pages are not
+exported. The guard reads `ENABLE_TEST_ROUTES`, exact-match `'true'`, fail-closed, and returns
+a real 404 rather than a 403 so probing cannot confirm the route exists. All of that is
+correct and should not be softened.
+
+**The trap:** putting `'use client'` on the page file that re-exports the guard. Non-`NEXT_PUBLIC_`
+variables do not exist in the browser, so the guard reads `undefined` and denies **forever** —
+a gate that greps as present and protects nothing. Hit on 2026-08-26.
+
+These pages show a **live session token with a copy button**. `ENABLE_TEST_ROUTES=true` belongs
+in `.env.development` and nowhere else. Verified both ways on UMI: flag off, all four 404 while
+`/login` stays 200.
+
+**Fix:** document the four exports, the server-component requirement, and the flag — together,
+in one place, with the `'use client'` trap called out.
+
+## 9. The local user record — three files, written three times — P2
+
+The IDP owns identity; the tenant app needs its own row so application data can join to a user.
+The package ships **none** of it, so all three sites wrote the same three files:
+
+```
+app/api/auth/record-login/route.ts    upsert on sign-in
+app/lib/vibe-user.ts                  find-or-create by idp_user_id
+app/hooks/useLoginRecorder.ts         fire once per session
+```
+
+Two things every consumer must get right and has no way to know:
+
+- **Identity is `idp_user_id`, never email.** Email changes and gets reused; matching on it
+  silently merges two people.
+- **The effect needs a ref guard.** Without one, a re-render or Fast Refresh posts again —
+  harmless for the row, but it inflates `login_count`, which is then wrong in a way nobody
+  would think to question.
+
+The app-specific parts (tiers, credits, milestones — idealresume's runs to 1,567 lines) are
+genuinely the site's. The find-or-create core is not.
+
+## 10. `server-auth.ts` — a wrapper over one export — P3
+
+Every site writes the same ~60-line wrapper over `getFreshIdpToken` to assemble the refresh
+config from env and normalise the result. Package-side, this is a default config reader.
+
+## 11. Env vars — no single list, no startup validation of the set — P3
+
+`IDP_URL`, `CLIENT_ID`, `REFRESH_ENDPOINT`, `REDIS_URL`, `ENABLE_TEST_ROUTES`, plus the broker
+secret. `REDIS_URL` was missing from UMI and surfaced as an unrelated-looking failure.
+
+**`CLIENT_ID` is the only spelling.** Until 4.2.5 the package accepted `CLIENT_ID`,
+`NEXT_PUBLIC_CLIENT_ID` and `NEXT_CLIENT_ID` for one value; that cost a live defect. All six
+read sites are collapsed and `idp-client-config.ts` carries the banner. Do not reintroduce a
+second name here.
+
+**Fix:** ship `.env.example` with every variable, what reads it, and whether it is required.
+
+## 12. `providers.tsx` — nesting order matters and is unstated — P3
+
+```
+AuthProvider → LoginRecorderProvider → ThemeProvider
+```
+
+`ModeAwareLoginPage` reads `useAuthConfig()`, so without `AuthProvider` the sign-in screen
+renders **no controls at all** — no Google button, no email form — even while
+`/api/auth/settings` correctly reports `enabledProviders: ["google"]`. It fails as a blank
+card, which reads as a styling problem.
+
+**Do not set `mode` in a site's auth config.** What sign-in offers comes from the IDP via
+`/api/auth/settings` (4.3.0+). A site hardcoding its own auth mode is how a login screen and
+its own IDP end up disagreeing.
+
+## 13. The Session Inspector fetches an endpoint the package does not ship — P1
+
+`JwtInspectPage` fetches `/api/internal/session-data`. **No such handler exists in the
+package and none is exported.** Line 39 of the page says the quiet part — "reads them from
+the *consuming app's* `/api/internal/session-data` route" — which is a defensible design
+call (a session record's shape is the app's business) documented in the one place no
+consumer will ever read: the source of a page they did not write.
+
+**It fails invisibly**, which is the real defect. The page does:
+
+```ts
+fetch('/api/internal/session-data').then(r => r.ok ? r.json() : null).catch(() => {})
+```
+
+A 404 and a session with no data render **identically**: every field `N/A`, and
+`Error: N/A` underneath, which reads as "no error". The inspector looked like it was
+reporting a broken session. It was reporting a missing route. Found only by watching the
+network tab.
+
+UMI now owns `app/api/internal/session-data/route.ts`. Two things any implementation must
+get right:
+
+- **The 16 field names are a contract** (`JwtInspectPage` reads `ss.userId`, `ss.roles`,
+  `ss.idpAccessToken`, …). Rename one and that row silently goes `N/A` forever.
+- **It returns the live IDP access AND refresh token.** The package's own `better-auth.ts`
+  names this exact endpoint as the leak path it refuses to put `id_token` behind. UMI gates
+  it on `ENABLE_TEST_ROUTES` — same fail-closed exact-match, read at request time, 404 not
+  403. Verified both ways.
+
+**Fix:** either ship the route (it is mechanical — `getSession` + `getSession` from
+`lib/session-store`, both already exported), or make the page say `endpoint missing` instead
+of swallowing the 404. Preferably both.
+
+## 14. `routes/auth/nextauth` is a trap. Do not mount it. — P1
+
+**This one cost the most and looked the most correct.** The package ships
+`routes/auth/nextauth`, its own docblock calls it "Ready-to-Use", and its usage example is
+the obvious one-liner:
+
+```ts
+export { GET, POST } from '@payez/next-mvp/routes/auth/nextauth';   // WRONG
+```
+
+It signs users in. It never provisions them.
+
+```
+routes/auth/nextauth GET  ->  toNextJsHandler(auth)       — signs in. Stops.
+createAuthGetHandler GET  ->  ba.GET + IDP token exchange — signs in AND provisions.
+```
+
+Only `createAuthGetHandler` runs `exchangeOAuthForIdpTokens` after the OAuth callback. With
+the re-export, Better Auth creates a **perfectly convincing session** — cookie, user id,
+email, Google avatar — and the Redis record holding the IDP access token, refresh token and
+roles is **never written**.
+
+The damage surfaces nowhere near the cause:
+
+- `/test-env/jwt-inspect` → `NO_REDIS_SESSION`, no tokens, no roles
+- anything calling `getFreshIdpToken` → `NO_SESSION` **for a user who is visibly signed in**
+- `record-login` → 401, so the app never creates its local user row
+
+Correct wiring, and what idealvibe.online and idealresume.online **both** hand-write:
+
+```ts
+export const GET = createAuthGetHandler('/login');   // your login path
+export async function POST(request: Request) {
+  const ba = await getBetterAuthHandler();
+  return ba!.POST(request);
+}
+```
+
+Neither working site uses the re-export. That is not boilerplate they failed to factor out —
+it is the only wiring that works.
+
+**This row is also a correction to row 2 of this tab.** Row 2's advice — prefer the package
+re-export over copying another site's file — is right for `settings` and wrong here, and I
+followed it into this exact bug on UMI. A codemod that generates the "obvious" re-export
+would ship this defect to every new consumer.
+
+**Fix:** `routes/auth/nextauth` should either export the exchanging handler or refuse to
+exist. A "Ready-to-Use" export that yields a half-provisioned session is worse than no
+export, because it looks like the sanctioned path.
+
+## 15. `id_token` was dropped because the ALS was module-scoped — P1, CLOSED in 4.3.4
+
+The most expensive one, and the package's own fault end to end.
+
+`state` (the Better Auth instance) was moved to `globalThis` by 181814 **because this module
+loads more than once per process** — instrumentation and the auth route are separate chunks
+with separate registries. `idTokenScope`, the AsyncLocalStorage that carries the provider's
+raw `id_token` from `getUserInfo` to the IDP exchange, was left in module scope.
+
+So the two copies shared the instance and **not** the scope:
+
+```
+copy A builds the instance   -> the getUserInfo closure captures A's idTokenScope
+copy B serves the callback   -> createAuthGetHandler runs .run({}) on B's
+getUserInfo fires, reads A   -> getStore() undefined, `if (scope)` skips SILENTLY
+the exchange reads B         -> empty, so id_token is omitted from the body
+```
+
+Sign-in succeeds at every visible step — cookie, user id, email, avatar. The IDP then
+answers `401 UNVERIFIED_ASSERTION`, and its own log names the reason:
+`reason="id_token missing"` (idp.payez.net, correlationId 0HNO2755RESR1, 2026-08-26).
+
+**The consequence is a security control that shipped as a no-op.** 472fb75c added the raw
+`id_token` because `/api/ExternalAuth/oauth-callback` would mint an IDP access+refresh pair
+for any *asserted* email, on a public LoadBalancer — the only verifiable field in that body
+is the provider's signed token. Wherever this module double-loads, that fix never arrived.
+
+Fixed in 4.3.4: `idTokenScope` now lives on `globalThis` under the same pattern as `state`,
+and the silent `if (scope)` skip warns and names its two causes.
+
+**The lesson generalises past this bug: shared instance + per-copy request scope is the worst
+combination.** Everything looks wired, and the one field that proves identity is dropped. If
+any other module-scoped singleton in this package participates in a request, audit it the
+same way.
+
+## 16. Tenant-side: one env var, two unrelated jobs — P2
+
+Not this package's bug, but every consumer that has a marketing form will hit it.
+
+`createVibeClient` resolves the collection as
+`config.defaultCollection || process.env.VIBE_COLLECTION || 'vibe_app'`. The library default
+is already correct. UMI set `VIBE_COLLECTION=payez_contact_list` for its **waitlist form**,
+and that variable is global to the client — so it silently retargeted every collection call
+in the app, including user identity. Sign-in queried the waitlist's collection for a `users`
+table that does not live there.
+
+Same rule as `CLIENT_ID`, from the other direction: there, one value had three names; here,
+one name carries two values. Pin the collection at the call site.
+
+## 17. Tenant-side: vibe-client 0.2.3 sends a filter shape the API rejects — P2
+
+`list({ filter })` serialises through `convertFiltersToVibeFormat`, which returns an **array**
+`[{ field, operator, value }]`. `PayEz.Vibe.Public.Api` binds `filter` to a single
+`VibeFilterNode` **object** (`VibeQueryModels.cs:63`), so the request fails to deserialise
+before the query builder ever runs:
+
+```
+400 VALIDATION_ERROR  $.filter
+"The JSON value could not be converted to ...QueryBuilder.VibeFilterNode"
+```
+
+The API is not being arbitrary — `VibeQueryBuilder.cs:355` documents this exact query as
+supported (`{ "idp_user_id": { "eq": 22 } }`), and :94 accepts the flat
+`{ field, operator, value }` form too. The array wrapper is the whole defect, and the API
+change is deliberate.
+
+**This affects every filtered query from 0.2.3, on all three sites.** UMI was only the first
+to make one — measured in the IDP proxy logs, UMI's client was the sole source of `$.filter`
+400s in 24h while idealresume queried cleanly, because idealresume's calls in that window did
+not filter.
+
+UMI hand-rolls the single lookup against the proxy with the correct node, reusing the
+library's `resolveConfig()`. That is a workaround with a cost: it duplicates the HMAC recipe
+(`timestamp|method|endpoint`, key base64-decoded) because `generateHmacSignature` is not
+exported, so a signing change in the library breaks that call with a 401. **The real fix is a
+vibe-client release that emits a `VibeFilterNode`**; its source is not in this workspace.
+
+---
+
+## What the tab says about the package
+
+Fourteen rows; **eleven are `auto` or `codemod`** — the package could do them, or generate
+them, with no judgement call from the consumer. Only three are real consumer choices.
+
+The three P1 route/page rows share one root cause: **the package can export a thing but cannot
+mount it**, and nothing enumerates what is mountable. That is one fix, not three — a list, or
+an `init` command that writes the re-exports.
+
+Eight of the fourteen appear in **no doc at all**. `QUICK_START.md` is a stub with a single
+heading. Row 14 is worse than undocumented — the wrong path is the one with the usage example.
+
+The recurring shape, which is the same one this codebase keeps paying for: **things present,
+plausible and inert.** A `ThemeProvider` that provides no theme. A template whose comment
+promises a retry that never happens. A guard that greps as a gate and denies everything. An
+exported page nothing mounts. None of them announce themselves; all of them look done.

package/README.md

@@ -6,6 +6,13 @@ Drop-in authentication for Next.js. One package, zero secret management in produ
 npm install @payez/next-mvp next-auth
 ```
 
+> **Installing is not finishing.** There is no `postinstall` step and no generator, so the
+> package cannot mount its own routes or pages into your `app/` directory, and it does not
+> emit the CSS variables its components read. **[POST-INSTALL.md](./POST-INSTALL.md) is the
+> complete list of what you must still do by hand** — including three that leave the site
+> broken with nothing to tell you why: the auth routes, the login page, and the sixteen theme
+> variables. Read it before you conclude something is wrong with the package.
+
 ## How Secrets Work
 
 You never manage signing keys or OAuth credentials directly. The package resolves them automatically at startup based on your environment.

package/dist/api-handlers/account/recovery/initiate.js

@@ -2,20 +2,53 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.POST = POST;
 const server_1 = require("next/server");
+const idp_client_config_1 = require("../../../lib/idp-client-config");
+const client_key_1 = require("../../../lib/client-key");
 function getIdpUrl() {
     const url = process.env.IDP_URL;
     if (!url)
         throw new Error('[IDP_URL] FATAL: IDP_URL environment variable is REQUIRED.');
     return url;
 }
+/**
+ * RECOVERY CLIENT KEY — cards 268012 (S12) and 268410.
+ *
+ * These four proxies populated NONE of PayEzClientIdResolver's six slots, so
+ * RequirePayEzUnAuthorized 404'd the request BEFORE the action ran and no
+ * recovery token was ever minted. That is why S12 failed at step 1.
+ *
+ * NOT `ENV_CONFIG.CLIENT_ID`, which is what card 268012 originally prescribed.
+ * That variable is the ENVIRONMENT-SPECIFIC NUMERIC id, and the IDP accepts a
+ * numeric with NO existence check (RequirePayEzUnAuthorizedAttribute.cs:31-33)
+ * while it VALIDATES a slug (:41-47). Hardcoding the numeric here would have
+ * added four more sites to the 268410 family and made a stale id answer for
+ * the WRONG TENANT on a password-reset path, silently. Slug-preferring, with
+ * the numeric fallback logged, is the same resolver the other nine sites use.
+ *
+ * SERVER VALUE WINS: client_id is applied AFTER the caller's payload spread.
+ * These are unauthenticated recovery endpoints, so a browser-supplied
+ * client_id would be a tenant-targeting lever. The caller does not get to
+ * choose which tenant their password reset is addressed to.
+ */
+async function recoveryClientKey() {
+    try {
+        const config = await (0, idp_client_config_1.getIDPClientConfig)();
+        return (0, client_key_1.resolveClientKey)(config, 'account/recovery/initiate').key;
+    }
+    catch (e) {
+        console.error('[account/recovery/initiate] could not resolve IDP client config for client_id:', e);
+        return null;
+    }
+}
 async function POST(req) {
     const IDP_URL = getIdpUrl();
     try {
         const { email } = await req.json();
+        const clientKey = await recoveryClientKey();
         const upstream = await fetch(`${IDP_URL}/api/Account/recovery/initiate`, {
             method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({ email }),
+            headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+            body: JSON.stringify({ email, ...(clientKey ? { client_id: clientKey } : {}) }),
         });
         const data = await upstream.json().catch(() => ({}));
         return server_1.NextResponse.json(data, { status: upstream.status });

package/dist/api-handlers/account/recovery/send-code.d.ts

@@ -1,35 +1,2 @@
 import { NextRequest, NextResponse } from 'next/server';
-/**
- * Account recovery — send-code
- *
- * WHY THIS WAS REWRITTEN (2026-08-02, swept out of QAPert defect #7)
- * This handler read the caller's bearer straight off the inbound request:
- *
- *     const auth  = req.headers.get('authorization') || '';
- *     const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
- *     ... headers: { 'Authorization': `Bearer ${token}` }
- *
- * Browsers send a session COOKIE and no Authorization header, so `token` was
- * ALWAYS the empty string and this always called the IDP with a literal
- * "Bearer " and nothing after it.
- *
- * THAT IS WORSE THAN THE profile.ts VERSION OF THIS BUG, in two ways:
- *
- *   1. profile.ts at least 401'd when the header was missing. This one has no
- *      check at all — `|| ''` swallows the absence — so it proceeds to call
- *      upstream with an empty credential and returns the IDP's rejection as an
- *      opaque failure. The user sees recovery "not working", not "not
- *      authenticated", and the log shows an upstream error rather than an auth
- *      one. The defect hides itself.
- *   2. It is BOTH HALVES of account recovery — send-code and verify-code — so
- *      the entire recovery path is unreachable, not merely degraded. This is
- *      the flow a locked-out user reaches for, i.e. it fails exactly when it is
- *      the only thing left that could help them.
- *
- * Fixed the same way as profile.ts and masked-info.ts: idpFetchJSON resolves
- * the caller's token from the server-side session, so the cookie works and the
- * token is never handed to browser JavaScript.
- *
- * @package @payez/next-mvp
- */
 export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/account/recovery/send-code.js

@@ -4,6 +4,8 @@ exports.POST = POST;
 const server_1 = require("next/server");
 const idp_fetch_1 = require("../../../lib/idp-fetch");
 const env_1 = require("../../../config/env");
+const idp_client_config_1 = require("../../../lib/idp-client-config");
+const client_key_1 = require("../../../lib/client-key");
 /**
  * Account recovery — send-code
  *
@@ -37,6 +39,36 @@ const env_1 = require("../../../config/env");
  *
  * @package @payez/next-mvp
  */
+/**
+ * RECOVERY CLIENT KEY — cards 268012 (S12) and 268410.
+ *
+ * These four proxies populated NONE of PayEzClientIdResolver's six slots, so
+ * RequirePayEzUnAuthorized 404'd the request BEFORE the action ran and no
+ * recovery token was ever minted. That is why S12 failed at step 1.
+ *
+ * NOT `ENV_CONFIG.CLIENT_ID`, which is what card 268012 originally prescribed.
+ * That variable is the ENVIRONMENT-SPECIFIC NUMERIC id, and the IDP accepts a
+ * numeric with NO existence check (RequirePayEzUnAuthorizedAttribute.cs:31-33)
+ * while it VALIDATES a slug (:41-47). Hardcoding the numeric here would have
+ * added four more sites to the 268410 family and made a stale id answer for
+ * the WRONG TENANT on a password-reset path, silently. Slug-preferring, with
+ * the numeric fallback logged, is the same resolver the other nine sites use.
+ *
+ * SERVER VALUE WINS: client_id is applied AFTER the caller's payload spread.
+ * These are unauthenticated recovery endpoints, so a browser-supplied
+ * client_id would be a tenant-targeting lever. The caller does not get to
+ * choose which tenant their password reset is addressed to.
+ */
+async function recoveryClientKey() {
+    try {
+        const config = await (0, idp_client_config_1.getIDPClientConfig)();
+        return (0, client_key_1.resolveClientKey)(config, 'account/recovery/send-code').key;
+    }
+    catch (e) {
+        console.error('[account/recovery/send-code] could not resolve IDP client config for client_id:', e);
+        return null;
+    }
+}
 async function POST(req) {
     let payload = {};
     try {
@@ -45,10 +77,11 @@ async function POST(req) {
     catch {
         return server_1.NextResponse.json({ success: false, error: 'invalid_request', message: 'A JSON body is required' }, { status: 400 });
     }
+    const clientKey = await recoveryClientKey();
     const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/recovery/send-code`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload),
+        headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+        body: JSON.stringify({ ...payload, ...(clientKey ? { client_id: clientKey } : {}) }),
     });
     if (!result.ok) {
         return server_1.NextResponse.json({

package/dist/api-handlers/account/recovery/verify-code.d.ts

@@ -1,35 +1,2 @@
 import { NextRequest, NextResponse } from 'next/server';
-/**
- * Account recovery — verify-code
- *
- * WHY THIS WAS REWRITTEN (2026-08-02, swept out of QAPert defect #7)
- * This handler read the caller's bearer straight off the inbound request:
- *
- *     const auth  = req.headers.get('authorization') || '';
- *     const token = auth.startsWith('Bearer ') ? auth.slice(7) : '';
- *     ... headers: { 'Authorization': `Bearer ${token}` }
- *
- * Browsers send a session COOKIE and no Authorization header, so `token` was
- * ALWAYS the empty string and this always called the IDP with a literal
- * "Bearer " and nothing after it.
- *
- * THAT IS WORSE THAN THE profile.ts VERSION OF THIS BUG, in two ways:
- *
- *   1. profile.ts at least 401'd when the header was missing. This one has no
- *      check at all — `|| ''` swallows the absence — so it proceeds to call
- *      upstream with an empty credential and returns the IDP's rejection as an
- *      opaque failure. The user sees recovery "not working", not "not
- *      authenticated", and the log shows an upstream error rather than an auth
- *      one. The defect hides itself.
- *   2. It is BOTH HALVES of account recovery — send-code and verify-code — so
- *      the entire recovery path is unreachable, not merely degraded. This is
- *      the flow a locked-out user reaches for, i.e. it fails exactly when it is
- *      the only thing left that could help them.
- *
- * Fixed the same way as profile.ts and masked-info.ts: idpFetchJSON resolves
- * the caller's token from the server-side session, so the cookie works and the
- * token is never handed to browser JavaScript.
- *
- * @package @payez/next-mvp
- */
 export declare function POST(req: NextRequest): Promise<NextResponse<any>>;

package/dist/api-handlers/account/recovery/verify-code.js

@@ -4,6 +4,8 @@ exports.POST = POST;
 const server_1 = require("next/server");
 const idp_fetch_1 = require("../../../lib/idp-fetch");
 const env_1 = require("../../../config/env");
+const idp_client_config_1 = require("../../../lib/idp-client-config");
+const client_key_1 = require("../../../lib/client-key");
 /**
  * Account recovery — verify-code
  *
@@ -37,6 +39,36 @@ const env_1 = require("../../../config/env");
  *
  * @package @payez/next-mvp
  */
+/**
+ * RECOVERY CLIENT KEY — cards 268012 (S12) and 268410.
+ *
+ * These four proxies populated NONE of PayEzClientIdResolver's six slots, so
+ * RequirePayEzUnAuthorized 404'd the request BEFORE the action ran and no
+ * recovery token was ever minted. That is why S12 failed at step 1.
+ *
+ * NOT `ENV_CONFIG.CLIENT_ID`, which is what card 268012 originally prescribed.
+ * That variable is the ENVIRONMENT-SPECIFIC NUMERIC id, and the IDP accepts a
+ * numeric with NO existence check (RequirePayEzUnAuthorizedAttribute.cs:31-33)
+ * while it VALIDATES a slug (:41-47). Hardcoding the numeric here would have
+ * added four more sites to the 268410 family and made a stale id answer for
+ * the WRONG TENANT on a password-reset path, silently. Slug-preferring, with
+ * the numeric fallback logged, is the same resolver the other nine sites use.
+ *
+ * SERVER VALUE WINS: client_id is applied AFTER the caller's payload spread.
+ * These are unauthenticated recovery endpoints, so a browser-supplied
+ * client_id would be a tenant-targeting lever. The caller does not get to
+ * choose which tenant their password reset is addressed to.
+ */
+async function recoveryClientKey() {
+    try {
+        const config = await (0, idp_client_config_1.getIDPClientConfig)();
+        return (0, client_key_1.resolveClientKey)(config, 'account/recovery/verify-code').key;
+    }
+    catch (e) {
+        console.error('[account/recovery/verify-code] could not resolve IDP client config for client_id:', e);
+        return null;
+    }
+}
 async function POST(req) {
     let payload = {};
     try {
@@ -45,10 +77,11 @@ async function POST(req) {
     catch {
         return server_1.NextResponse.json({ success: false, error: 'invalid_request', message: 'A JSON body is required' }, { status: 400 });
     }
+    const clientKey = await recoveryClientKey();
     const result = await (0, idp_fetch_1.idpFetchJSON)(req, `${env_1.ENV_CONFIG.IDP_URL}/api/Account/recovery/verify-code`, {
         method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(payload),
+        headers: { 'Content-Type': 'application/json', ...(clientKey ? { 'X-Client-Id': clientKey } : {}) },
+        body: JSON.stringify({ ...payload, ...(clientKey ? { client_id: clientKey } : {}) }),
     });
     if (!result.ok) {
         return server_1.NextResponse.json({