@ai-matrx/data 0.17.0 → 0.17.1

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.17.1
+
+Automatic changed-only republish (docs/metadata drift since the last tag — see
+`git diff npm/data/v0.17.0..npm/data/v0.17.1 -- apps/shared/data`).
+No source changes intended and no consumer action required.
+
 ## 0.17.0 — 2026-09-20
 
 ### The proxy's identity resolve is local, bounded, and never a logout (`./next`)

package/README.md

@@ -118,12 +118,33 @@ export const supabaseNext = createNextSupabase<Database>({
 | Proxy / middleware | `await supabaseNext.middlewareSession({ host, requestCookies, createResponse, createRedirect })` |
 
 `middlewareSession` is the whole auth pass in one call and returns
-`{ user, client, response, redirect(url) }`. It owns: legacy-key migration (absent-only,
-so a live session is never overwritten), the "nothing may run between `createServerClient`
-and `getUser()`" rule made structural, persisting a migrated session under the current
-key, clearing the superseded key at the scope this host issued it on, no-store response
-headers on any cookie-bearing response, and cookie carry-over onto redirects. Dropping any
-one of those logs users out at random — which is how each was found.
+`{ user, client, response, redirect(url), splitCookieJar, ambiguousAuthCookies,
+authUnavailable }`. It owns: legacy-key migration (absent-only, so a live session is never
+overwritten), the "nothing may run between `createServerClient` and the identity resolve"
+rule made structural, persisting a migrated session under the current key, clearing the
+superseded key at the scope this host issued it on, no-store response headers on any
+cookie-bearing response, and cookie carry-over onto redirects. Dropping any one of those
+logs users out at random — which is how each was found.
+
+**The identity resolve is `getClaims()`, never `getUser()`, and it is BOUNDED.**
+`getUser()` sends a request to the Auth server for every JWT; `getClaims()` verifies the
+access token against the project's JWKS with WebCrypto — locally, usually with no network
+call, and just as trusted, because the signature is checked. It needs an **asymmetric**
+signing key on the project (ECC/RSA); with a symmetric secret it degrades to a
+`getUser()`-shaped request per call, still correct but with none of the saving. A 2.5s
+budget (`AbortSignal.timeout` on `/auth/v1/` calls only) means a stalled auth server costs
+one request its identity instead of costing the page its response — on Vercel, where Next
+16 forces this pass into a Node Lambda with a hard task cap, the unbounded version returned
+`504 MIDDLEWARE_INVOCATION_TIMEOUT` to real people.
+
+🚨 **`authUnavailable` is the consumer's obligation.** It means the authority could not be
+REACHED, which is NOT "signed out": `user` is `null`, but no auth cookie was written,
+expired or healed and the superseded key was not cleared. **Read it before treating
+`user === null` as signed out** — a host that bounces to `/login` on a null user must skip
+that bounce when the flag is set, or a 2.5s network blink signs people out mid-session.
+A call site needing `created_at`, `identities`, `last_sign_in_at`, `factors` or
+`*_confirmed_at` must keep `getUser()` elsewhere: the JWT carries none of them.
+Full contract: `common-docs/systems/platform/proxy-identity/FEATURE.md`.
 
 **No `next/*` import lives in the package.** `cookies()` and `NextResponse` arrive through
 structural seams (`createResponse: () => NextResponse.next({ request })`), so `/next`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-matrx/data",
-  "version": "0.17.0",
+  "version": "0.17.1",
   "description": "The opinionated AI Matrx data layer: the /db tier's hard-won Supabase primitives — optimistic concurrency, complete-list reads, JSONB merge, session-retry, the domain-wide auth cookie, realtime channel hygiene — the /net resilience trio, and the /files lane: the Matrx file-communication client (durable-ref resolution, the mx_files_session bootstrap, authenticated blob fetch, uploads, the public-link door).",
   "type": "module",
   "main": "./dist/index.cjs",