@object-ui/auth 17.3.0 → 17.6.0

package/CHANGELOG.md

@@ -1,5 +1,217 @@
 # @object-ui/auth
 
+## 17.6.0
+
+### Minor Changes
+
+- 1b21b1a: `AuthInvitation.status` is the closed four-member union it always documented, enforced at the auth client's wire boundary.
+  
+  The field was declared `status: string` while its own doc comment enumerated
+  `'pending' | 'accepted' | 'rejected' | 'canceled'`, and `createAuthClient` cast
+  better-auth's `any` responses straight to `AuthInvitation[]` with no check. The
+  enumeration was therefore advisory: any value a backend stored reached the
+  console untouched, where the invitations screen coloured it through a
+  `default: 'secondary'` badge arm and printed it with
+  `defaultValue: inv.status` — the raw wire string rendered as interface copy, in
+  all ten packs (objectui#3879). Nobody could trigger it today, because the four
+  are what better-auth writes; it was the contract that was loose, and a loose
+  consumer is where an unexpected value would have hidden.
+  
+  `AuthInvitationStatus` now carries the union and **binds better-auth's own
+  `InvitationStatus`** rather than restating it, the way `org-roles.ts` binds the
+  spec's `BUILTIN_MEMBERSHIP_ROLES` — a member-for-member copy is the state one
+  upstream release away from drifting silently. The runtime list
+  (`AUTH_INVITATION_STATUSES`) is derived from a total map keyed by that union, so
+  a fifth status upstream is a build failure here rather than a gap in the guard.
+  `isAuthInvitationStatus` is exported alongside, and all four invitation-returning
+  client methods (`listInvitations`, `listUserInvitations`, `getInvitation`,
+  `inviteMember`) narrow their wire rows through it.
+  
+  Behaviour change, stated because it is one: an invitation whose `status` is
+  outside the set now **fails loudly** — the call rejects with a message naming the
+  value it refused and the four it expected — instead of resolving into a badge.
+  Both call paths already render a rejection with a retry, so the throw lands on a
+  designed surface. Degrading quietly was the alternative and was deliberately not
+  taken: a neutral label is how the raw value shipped in the first place, and
+  dropping the row would delete an invitation from an administrative ledger without
+  saying so. The console's badge switch is exhaustive over the union now and has no
+  `default:` arm, so if better-auth ever adds a member the type-check gate stops the
+  build at the one place a human has to choose a colour.
+  
+  Consumers assigning an arbitrary string to `AuthInvitation.status` (a hand-built
+  fixture, a mock) will need one of the four members.
+
+### Patch Changes
+
+- 5458414: Publish relative import specifiers with explicit `.js` extensions so these six packages load under plain Node ESM.
+  
+  Node's ESM resolver does not extension-search relative specifiers and `tsc` never rewrites them, so an extensionless `./Foo` in the source shipped as an extensionless `./Foo` in `dist` and importing the package entry outside a bundler failed with `ERR_MODULE_NOT_FOUND`. Bundled consumers were unaffected. Unbundled consumers — plain Node ESM, an SSR host importing the package directly, anyone running the published tarball without a build step — can now import these entries, and so can the downstream `@object-ui/plugin-*` packages that evaluate through `mobile`, `permissions` and `providers`.
+- 61b097c: Sign-out now drops the client-side caches that belonged to the session it ends,
+  and the metadata seed cache is keyed by session identity.
+  
+  `sessionStorage` is per-tab, not per-session, and no sign-out call site reloads
+  the page — so the `objectui:metadata:*` entries (the app list the server
+  permission-filters per session) and the active-organization id survived into
+  whatever happened next in that tab. A second person signing in on a shared,
+  kiosk or handover browser was seeded with the previous user's filtered app list.
+  Organization scoping did not close this: two users in the same organization
+  computed the same cache key.
+  
+  `AuthProvider.signOut()` now purges the `objectui:metadata:` entries and clears
+  `ActiveOrganizationStorage` (and the in-memory organization block) on both the
+  success and failure paths, and `MetadataProvider` keys each entry by a
+  fingerprint of the session token, so an entry that escapes the purge is
+  unreadable by the next principal rather than merely undeleted. Entries left by
+  another principal are deleted the first time a console mounts.
+- a9e17b4: `auth.forgotPassword.successDescription`'s address hole is now spelled with
+  single braces (`{email}`) instead of i18next's double braces (`{{email}}`),
+  in all ten locale packs.
+  
+  This is a spelling-only change — rendered output is byte-identical in every
+  language, because the hole was never filled by i18next in the first place:
+  `ForgotPasswordForm` substitutes the address itself once the user submits
+  the form (the label renders before the address exists, so `t()` cannot do
+  it). `{{email}}` and a genuinely unfilled i18next hole were indistinguishable
+  at the call site, and passing `email` as an interpolation argument — the
+  natural "fix" for what looks like a missing argument — would let i18next
+  consume the hole and cause the address to be appended a second time
+  (objectui#4135).
+  
+  Converging on `{x}` for every hole a component fills downstream of `t()`
+  (the convention `resendOtpCountdownText`'s `{seconds}` already used) puts
+  this hole outside i18next's `{{…}}` syntax entirely, so the ambiguity is
+  gone by construction rather than fenced by an exemption. Accordingly,
+  `scripts/check-i18n-call-site-keys.mjs`'s `EXTERNALLY_INTERPOLATED_HOLES`
+  registry entry for this key is retired — the gate needs no exemption for a
+  hole i18next was never going to touch.
+  
+  `ForgotPasswordForm.tsx`'s replacement marker and its own built-in default
+  label move to the same spelling in the same change, as does the inline
+  `defaultValue` at `apps/console/src/pages/auth/ForgotPasswordPage.tsx`'s
+  call site.
+- Updated dependencies [88085e3]
+- Updated dependencies [279fb13]
+- Updated dependencies [1184192]
+- Updated dependencies [a2a9747]
+- Updated dependencies [af5e292]
+- Updated dependencies [7f96b10]
+- Updated dependencies [f1d4748]
+- Updated dependencies [578e025]
+- Updated dependencies [598c89a]
+- Updated dependencies [b8b9af4]
+- Updated dependencies [97abb24]
+- Updated dependencies [deb157a]
+- Updated dependencies [d2ce342]
+- Updated dependencies [9695da7]
+- Updated dependencies [58b8346]
+- Updated dependencies [3cf4de0]
+- Updated dependencies [c9dc811]
+- Updated dependencies [a0b9e91]
+- Updated dependencies [99bd015]
+  - @object-ui/types@17.6.0
+
+## 17.5.0
+
+### Minor Changes
+
+- 5cc847c: The data lane now honors `set-auth-token`, so impersonation takes effect at all (#4467).
+
+  The console injects the same localStorage bearer from two lanes: the AUTH lane
+  (`createBearerFetch` inside `createAuthClient`) and the DATA lane
+  (`createAuthenticatedFetch` — the adapter, `provider: 'api'` data sources, and every
+  metadata `type: 'api'` action). better-auth's server-side bearer plugin hands a ROTATED
+  session token back in the `set-auth-token` response header on whichever lane the call
+  arrived over, and only the auth lane read it. A rotation issued to a data-lane call was
+  discarded and the browser kept sending the old token.
+
+  `POST /auth/admin/impersonate-user` is exactly such a call — an ordinary metadata action.
+  The impersonated session token was dropped on the floor while the server's bearer plugin
+  kept overwriting the impersonation cookie with the admin bearer the console kept sending,
+  so impersonation was a complete no-op in the console rather than merely an invisible one.
+  Support staff believed they were seeing a user's view while acting entirely as themselves.
+
+  Published behaviour that moves: a data-lane response carrying `set-auth-token` now
+  replaces the stored session token, on any API call this lane authenticated (untrusted
+  targets remain the `sameOriginOnly` option's job — it short-circuits before any header
+  work). The accepted cost, recorded on the card: while impersonating, the administrator's
+  own token is replaced in localStorage for the duration, and a client that misses the stop
+  rotation is stranded until re-login.
+
+  Also in this release, all additive:
+
+  - `AuthContextValue.refreshSession()` re-resolves `user`/`session` from the server in
+    place, without raising `isLoading` — the transitions that change WHO the session is
+    without going through `signIn`/`signOut`.
+  - `TokenStorage.subscribeRotation()` notifies when a token already in hand is replaced by
+    a different one. First store, `clear()`, and re-storing the same value stay silent:
+    those transitions have an owner that updates identity itself.
+  - `AuthClientSession.impersonatedBy?: string` — optional, set by better-auth's admin
+    plugin for the life of an impersonated session.
+
+### Patch Changes
+
+- 58bebf6: Organization & invitation console: translate the English holdouts a zh session was left reading (#4474)
+
+  Three families of string, one sweep over `console/organizations/`:
+
+  - **Role names** now come from the single shared `ORG_ROLE_LABELS` map at every
+    site. The role badges on the members and invitations pages were rendering the
+    raw server identifier (`owner`) under a CSS `capitalize` that made it look like
+    a label in English and left it untranslated everywhere else; the accept page
+    did the same in its role row and inside its otherwise-translated sentence. The
+    map's four `organization.roles.*` keys existed in no locale pack, so even the
+    dropdown that did consult it fell through to English — all ten packs now carry
+    them. An unrecognized role renders verbatim rather than blank.
+  - **Server-echoed errors** are mapped by better-auth's stable `code`, never by
+    matching its English text. `createAuthClient` was dropping that code for every
+    `organization.*` call while preserving it for sign-in/sign-up, so the console
+    had nothing to key on; all sixteen organization methods now go through the same
+    `toAuthError` helper. Messages are unchanged — the code simply stops being
+    thrown away. An unmapped code still shows the server's own sentence.
+  - **Icon-only `aria-label`s** (member actions, copy invitation link, cancel
+    invitation, and a fourth on the share-link copy button) are translated — for an
+    icon-only control this is the only name a screen reader gets.
+
+- 564252c: `features.passkeys` and `features.magicLink` are documented as reserved, so enabling them no longer implies a login-page entry point that does not exist
+
+  `GET /api/v1/auth/config` advertises eight login-surface capability flags. Six of them gate something real — `sso` gates the "Sign in with SSO" button, `phoneNumberOtp` the verification-code mode, `deviceAuthorization` the device-approval page — and each carries a doc comment saying what it gates. Two did not gate anything: `passkeys` and `magicLink` existed only as two undocumented lines in `AuthPublicConfig.features`, consumed by no component, no route and no metadata. A deployer who turned one on got a flag that changed nothing, with nothing anywhere to say so. That is the mirror of the defect the audit was looking for (framework#2874 P2②): not UI advertising a capability the backend lacks, but a backend advertising a capability the UI lacks.
+
+  Both flags are now marked reserved at the two places a deployer meets them. The declarations in `packages/auth/src/types.ts` carry doc comments — which ship in the published `.d.ts`, so the warning appears on hover — stating that enabling the flag adds no entry point and naming the follow-up card. `packages/auth/README.md` gains a "Server Feature Flags" section documenting what the `features` map is for and a "Reserved flags" table saying the same thing in prose. Per the maintainer's ruling on objectui#2514, the UI is deliberately not built here; it is filed as objectui#4179 and left unscheduled.
+
+  No runtime behaviour changes: nothing read these flags before and nothing reads them now. What changes is that the published types and docs stop being silent about it.
+
+  The three artifacts are pinned together by `packages/auth/src/__tests__/reserved-auth-features.test.ts`, which asserts the declarations still exist, that each carries a reserved marking naming the card, that the README section says the same, and — the inverse direction — that no source file under `packages/*/src`, `apps/*/src` or `examples/*/src` references either identifier. The sweep covers `.json` as well as `.ts`/`.tsx` because `AppContent` hands the whole `features` object to `ExpressionProvider`, so authored metadata can reach these flags without any source file naming them. Two calibration cases keep the pin from rotting into a vacuous pass: one asserts the sweep reads a non-trivial number of files, the other that it can still find a flag that _is_ consumed. When the UI is eventually built, the pin fails and its docblock spells out the retirement checklist — the doc comments, the README section and the pin itself come out in the same PR.
+
+  `features.twoFactor` is untouched and explicitly excluded: two-factor is implemented in this package (`enableTwoFactor` / `verifyTwoFactor`) and its challenge is driven by server-side remediation rather than by the flag, so `LoginForm` not reading it is the design rather than a gap. The README says so, and the pin asserts `twoFactor` never appears in the reserved table.
+
+- Updated dependencies [f650253]
+- Updated dependencies [3d9769a]
+- Updated dependencies [92876f0]
+- Updated dependencies [d9d3463]
+- Updated dependencies [2a40f69]
+- Updated dependencies [bec3e14]
+- Updated dependencies [1f9b905]
+- Updated dependencies [abb0f81]
+- Updated dependencies [38ab505]
+- Updated dependencies [7e4f0e5]
+- Updated dependencies [c1d939f]
+- Updated dependencies [bb68488]
+- Updated dependencies [ab04728]
+  - @object-ui/types@17.5.0
+
+## 17.4.0
+
+### Patch Changes
+
+- Updated dependencies [d229dfa]
+- Updated dependencies [c2fd122]
+- Updated dependencies [48132f7]
+- Updated dependencies [7e5bb5d]
+- Updated dependencies [e6fdbdc]
+- Updated dependencies [7e2b7e9]
+- Updated dependencies [c1e1e6b]
+  - @object-ui/types@17.4.0
+
 ## 17.3.0
 
 ### Patch Changes
@@ -868,6 +1080,7 @@
   no visible effect — the user/session were nulled but the UI stayed authenticated.
 
   Changes:
+
   - **`@object-ui/auth`** — added `isAuthEnabled: boolean` to `AuthContextValue`
     (`true` only when real auth is in use, `false` for guest/preview modes).
   - **`@object-ui/app-shell`** — `AppHeader` and `AppSidebar` now hide the "Log out"

package/README.md

@@ -21,7 +21,6 @@ npm install @object-ui/auth
 
 **Peer Dependencies:**
 - `react` ^18.0.0 || ^19.0.0
-- `react-dom` ^18.0.0 || ^19.0.0
 
 ## Quick Start
 
@@ -138,6 +137,190 @@ const authedFetch = createAuthenticatedFetch();
 const apiProviderFetch = createAuthenticatedFetch({ sameOriginOnly: true });
 ```
 
+## The `X-Tenant-ID` edge contract
+
+`createAuthenticatedFetch` stamps `X-Tenant-ID` on the requests it wraps. This section is
+that header's contract: what it means, who stamps it, who reads it, what a reader may
+assume, and the one window in which it is not sent at all.
+
+It is written down because **a grep cannot answer any of those questions from this
+repository.** The header's only non-CORS consumer lives in the **cloud** repository, so a
+search confined to this repo and the framework (`objectstack`) finds zero readers and
+reads as *"nothing consumes this stamp"*. That reading is what
+[objectui#5279](https://github.com/objectstack-ai/objectui/issues/5279) was filed on, and
+it is false. Do not act on it.
+
+### What it means
+
+A **routing hint** for the hosting edge — *this request belongs to tenant `<id>`*:
+
+```http
+X-Tenant-ID: <better-auth activeOrganizationId>
+```
+
+The value is the active **organization** id, the same id the session carries as
+`session.activeOrganizationId`. The header is **not** an identity claim, **not** an
+authorization input, and **not** what scopes rows.
+
+### Who stamps it
+
+| | |
+| --- | --- |
+| Stamped by | `createAuthenticatedFetch` ([`src/createAuthenticatedFetch.ts`](src/createAuthenticatedFetch.ts)) |
+| Value read from | `ActiveOrganizationStorage` ([`src/ActiveOrganizationStorage.ts`](src/ActiveOrganizationStorage.ts)) — `localStorage`, key `auth-active-organization-id:u:$userId` (per-user since objectui#5664; the bare key is the retired pre-#5664 spelling) |
+| Condition | that storage holds a non-empty value |
+| *Not* conditioned on | the URL being an `/api/` call. `Authorization` and `Accept-Language` are; this is not |
+| Suppressed by | `createAuthenticatedFetch({ sameOriginOnly: true })` for cross-origin URLs — it returns before any header work |
+| Precedence | overwrites an `X-Tenant-ID` the caller passed in `init.headers` |
+
+`ActiveOrganizationStorage` has exactly one writer, [`AuthProvider`](src/AuthProvider.tsx):
+
+| Event | Effect |
+| --- | --- |
+| `refreshOrganizations` — after `getSession` &rarr; `listOrganizations` &rarr; `getActiveOrganization` resolves (including the ADR-0081 single-membership repair) | set |
+| `switchOrganization` — the org switcher | set, or clear when the server returns no org |
+| `deleteOrganization` / `leaveOrganization`, when the active org is the one going away | clear |
+| sign-out | clear |
+
+### Who reads it
+
+**The cloud edge — yes.** The non-test readers are recorded on objectui#5279:
+`packages/service-tenant/src/tenant-context.ts` (header resolution) and
+`packages/tenant-router/src/spec/turso-multi-tenant.zod.ts`, both in the `cloud`
+repository. That repository is not readable from this one, so those paths are cited as the
+recorded reading rather than re-derived here.
+
+**Its configuration contract, though, IS readable from here**, because this package
+depends on `@objectstack/spec`. `TenantRoutingConfigSchema` (`@objectstack/spec/cloud`) is
+what configures a tenant resolver; parsing an empty config on the version this package
+resolves today (17.1.0) yields:
+
+```text
+enabled:               false
+identificationSources: ["subdomain", "header", "jwt_claim"]
+tenantHeaderName:      "X-Tenant-ID"
+jwtOrganizationClaim:  "organizationId"
+```
+
+Two consequences matter to a client author:
+
+- **The header name is configurable.** `X-Tenant-ID` is its default, not a constant.
+- **The header is one of six identification sources** (`subdomain`, `custom_domain`,
+  `header`, `jwt_claim`, `session`, `default`), and in the default precedence it ranks
+  **second, behind `subdomain`**. On a subdomain-routed deployment it is not the thing
+  that picks the tenant, and a deployment may leave it out of `identificationSources`
+  entirely.
+
+**The framework (`objectstack`) — no.** `resolveAuthzContext`
+(`packages/core/src/security/resolve-authz-context.ts`) derives `tenantId` from the
+API-key principal or from `session.activeOrganizationId`, and from no header;
+`packages/verify/src/harness.org-context.test.ts` pins it — *"`session.activeOrganizationId`
+is the ONE field `resolveAuthzContext` reads into `tenantId`"*. Environment and kernel
+routing read the hostname and `X-Environment-Id`. The framework's only other mentions are
+the CORS preflight allow-list (`DEFAULT_CORS_ALLOW_HEADERS`, whose comment describes
+`X-Tenant-ID` / `X-Environment-Id` as what routes "a request to its environment") and
+`plugin-sharing`, which records that trusting `x-tenant-id` as identity **was a
+vulnerability**: its secure default stopped reading identity from headers because doing so
+let a client forge attribution and enumerate or revoke other users' links.
+
+### What a reader may assume
+
+A reader **may**:
+
+- use it to select the tenant database or environment to route to, subject to its own
+  `identificationSources` precedence;
+- treat it as a hint that may be absent, stale, or contradicted by the session.
+
+A reader **may not**:
+
+- treat it as authenticated identity, or as an authorization decision. It is
+  client-controlled — any caller can send any value, and `plugin-sharing` is the recorded
+  precedent for what happens to a server that trusts it;
+- assume the row scoping it sees downstream came from this header. It did not: the
+  framework scopes from the session;
+- assume the header is present. See below.
+
+### The unstamped-first-request gap
+
+The stamp reads storage that `AuthProvider` fills only **after** `getSession` &rarr;
+`listOrganizations` &rarr; `getActiveOrganization` resolves. Every request that leaves
+before that chain completes carries **no** `X-Tenant-ID` at all.
+
+The window opens in five situations:
+
+1. a browser that has never signed in, or whose site data was cleared, including a private
+   window;
+2. the page load in which the user signs in — from the sign-in response until the
+   organization chain resolves;
+3. after sign-out, which clears the storage, until a new organization resolves;
+4. outside a browser (SSR, tests, a worker), where `localStorage` is unavailable and the
+   storage falls back to a per-process in-memory value that starts empty on every cold
+   start;
+5. a browser where `localStorage` exists but **rejects writes** (Safari private browsing,
+   quota exhaustion). There the window never closes — the in-memory fallback is written
+   but never read back, because `get()` only falls back when reading itself *throws*, and
+   a rejected write leaves reads working and returning `null`. Reported on objectui#5279
+   as a separate defect; it is not fixed here.
+
+Case 1 is not theoretical in this codebase: `app-shell`'s `MetadataProvider` issues its
+eager `app` metadata fetch inside exactly this window, which is why its first-boot cache
+scope needed its own reasoning
+([`packages/app-shell/src/providers/MetadataProvider.tsx`](../app-shell/src/providers/MetadataProvider.tsx),
+pinned by `MetadataProvider.firstBootOrgScope.test.tsx`).
+
+**What a reader observes in the window:** the header is **absent**, never
+present-and-empty. A resolver must fall through to its next configured identification
+source — `subdomain` already outranks it by default, with `jwt_claim`, `session` and
+`defaultTenantId` behind it — rather than fail closed on the absence. It must also not
+cache a routing decision taken inside the window as *the* tenant for the session: the very
+next request will normally carry the header.
+
+**Why the gap does not corrupt data scoping.** A response computed inside the window is
+still computed for the right tenant, because the framework takes `tenantId` from the
+session rather than from the header. The gap is a *routing-input* gap, not a scoping gap.
+This is the same reasoning objectui#5243 relied on when it relabelled a metadata cache
+entry that had been written in the window.
+
+**Closing the gap is a separate decision, not an omission.** The cloud readers observe the
+current behaviour, so changing when the header first appears changes what they see. If it
+should be closed, it needs its own card.
+
+## Server Feature Flags (`GET /auth/config`)
+
+`createAuthClient().getConfig()` fetches the server's public auth configuration. The
+`features` map on it tells the login surface which capabilities the deployment actually
+has, so the UI never renders an entry point whose endpoint is not mounted — `features.sso`
+gates the "Sign in with SSO" button, `features.phoneNumberOtp` gates the
+verification-code mode, `features.deviceAuthorization` gates the device-approval page,
+and so on.
+
+### Reserved flags — advertised by the server, consumed by nothing
+
+Two members of that map are **declared but deliberately not consumed** by this package:
+
+| Flag | Status | What enabling it does in the UI today |
+| --- | --- | --- |
+| `features.passkeys` | **Reserved** | Nothing. There is no passkey sign-in or registration UI for it to gate. |
+| `features.magicLink` | **Reserved** | Nothing. There is neither a magic-link request step nor a route that consumes the emailed token. |
+
+They are typed so the `/auth/config` payload round-trips without loss, not because
+anything reads them. **Turning either flag on server-side adds no entry point to the login
+page.** If you are enabling one because you expect a button to appear, it will not — and
+that is the whole reason this section exists.
+
+Building the two flows is tracked as a separate, unscheduled feature card,
+[objectui#4179](https://github.com/objectstack-ai/objectui/issues/4179). Documenting them
+as reserved rather than building them now follows the maintainer's ruling on
+[objectui#2514](https://github.com/objectstack-ai/objectui/issues/2514): mark them
+reserved today, build the UI when the login surface gets roadmap time, at which point it
+renders driven by these same flags. When that lands, this section retires with it.
+
+`features.twoFactor` is **not** in this category, despite also not being read by
+`LoginForm`. Two-factor authentication is implemented here (`enableTwoFactor` /
+`verifyTwoFactor` on the auth client) and its challenge is driven by server-side
+remediation rather than by the flag, so the login form ignoring the flag is the design,
+not a gap.
+
 ## Preview Mode
 
 Preview mode allows visitors (e.g. marketplace customers) to explore the platform without registering or logging in. The `AuthProvider` auto-authenticates with a simulated user identity and bypasses login/registration screens.
@@ -207,20 +390,8 @@ function MyComponent() {
 
 > **⚠️ Security:** Preview mode should **never** be used in production environments.
 
-<!-- release-metadata:v3.3.0 -->
-
-## Compatibility
-
-- **React:** 18.x or 19.x
-- **Node.js:** ≥ 18
-- **TypeScript:** ≥ 5.0 (strict mode)
-- **`@objectstack/spec`:** ^3.3.0
-- **`@objectstack/client`:** ^3.3.0
-- **Tailwind CSS:** ≥ 3.4 (for packages with UI)
-
 ## Links
 
-- 📚 [Documentation](https://www.objectui.org/docs/packages/auth)
 - 📦 [npm package](https://www.npmjs.com/package/@object-ui/auth)
 - 📝 [Changelog](./CHANGELOG.md)
 - 🐛 [Report an issue](https://github.com/objectstack-ai/objectui/issues)

package/dist/ActiveOrganizationStorage.d.ts

@@ -0,0 +1,168 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * Drop the outgoing user's client state wholesale — part 3 of the fix.
+ *
+ * Order is load-bearing and mirrors `clear()`'s: the in-memory active org goes
+ * FIRST, because `ActiveOrganizationStorage.get()` falls through to
+ * `_memoryValue` whenever the persisted read is null, which is exactly the
+ * state this function leaves behind (objectui#5703). Sweeping storage first
+ * would leave the outgoing user's org id live in memory for the rest of the
+ * page-load — the SPA sign-out-then-sign-in path never reloads.
+ *
+ * Both stores are swept. `sessionStorage` is per-TAB, not per-session, so the
+ * previous user's `objectui:metadata:*` seed (their PERMISSION-FILTERED app
+ * list) and their `objectui-ctx-*` scope picks survive into whoever signs in
+ * next in that tab unless something removes them.
+ */
+export declare function purgePreviousUserClientState(): void;
+/**
+ * Which user's client state this browser holds, and the transition that drops
+ * the previous user's state.
+ */
+export declare const SessionUserScope: {
+    /**
+     * Memory copy of the pointer. Read FIRST by {@link current}: once this
+     * page-load has adopted a user, that answer is authoritative for this tab
+     * even if another tab has since written a different id, and it is the only
+     * copy in a browser whose `localStorage` rejects writes.
+     */
+    _userId: string | null;
+    /** The user whose state this browser holds, or `null` if it has never held one. */
+    current(): string | null;
+    /**
+     * Record `userId` as the owner of this browser's client state, dropping the
+     * previous owner's state wholesale when it changes.
+     *
+     * Idempotent: re-adopting the same user purges nothing. Called from
+     * `AuthProvider` for real sessions only — the synthetic `preview-user` /
+     * `guest` identities never reach it, so a preview mount cannot purge a real
+     * user's state.
+     *
+     * Because the decision reads the PERSISTED pointer, anything that deletes
+     * that pointer without deleting the state it describes would silently retire
+     * this invariant. `apps/console/src/lib/auth-preflight.ts` is the one place
+     * that sweeps auth keys before render, and it says so in its own comment:
+     * it removes every active-org spelling and leaves `auth-session-user-id`
+     * alone on purpose.
+     */
+    adopt(userId: string): void;
+    /**
+     * Forget the in-memory pointer. Test seam only — production has no reason to
+     * un-know who is signed in, and sign-out deliberately KEEPS the persisted
+     * pointer so that the next sign-in by a DIFFERENT user still sees a previous
+     * owner to purge.
+     */
+    _resetForTests(): void;
+};
+/**
+ * Get/set the active organization id that {@link createAuthenticatedFetch}
+ * stamps as `X-Tenant-ID`.
+ *
+ * `AuthProvider` is the only writer, at four moments: `refreshOrganizations`
+ * sets it once the `getSession` -> `listOrganizations` ->
+ * `getActiveOrganization` chain resolves (including the ADR-0081
+ * single-membership repair), `switchOrganization` sets or clears it,
+ * `deleteOrganization` / `leaveOrganization` clear it when the active org is
+ * the one going away, and sign-out clears it.
+ *
+ * Because the first of those is asynchronous, this reads EMPTY for the first
+ * stretch of a boot, and every request that leaves in that window carries no
+ * tenant header at all. That window is a documented part of the header's
+ * contract, not an accident to paper over — see the "unstamped-first-request
+ * gap" section of this package's README (objectui#5279).
+ */
+export declare const ActiveOrganizationStorage: {
+    _memoryValue: string | null;
+    /**
+     * Keys whose removal by {@link clear} did not stick — the value was still
+     * readable afterwards (objectui#5731).
+     *
+     * {@link get} refuses to answer from the persisted layer for a key in here,
+     * which is the mechanism that keeps a cleared organization cleared. Held in
+     * memory, so it lasts exactly one page-load: a browser that starts fresh
+     * re-measures rather than inheriting a verdict.
+     */
+    _unremovedKeys: Set<string>;
+    /**
+     * The active org id for the CURRENT user, or `null`.
+     *
+     * READ ORDER — a non-null `localStorage` read wins; anything else falls
+     * through to `_memoryValue`. Returning the `localStorage` read
+     * UNCONDITIONALLY (what this did before objectui#5703) left the fallback
+     * reachable only when the read THREW, and there is a real browser state
+     * where the read does not throw and the fallback is still the only copy:
+     * `localStorage` present and readable but REJECTING WRITES — Safari private
+     * browsing, and any quota-exhausted origin, where `setItem` throws
+     * `QuotaExceededError`. `set()` swallows that failure into `_memoryValue`
+     * (correctly — the fallback is right there), and `get()` then never
+     * consulted it: the value was stored and could not be read back, so
+     * `X-Tenant-ID` went unstamped for the whole session, not just the early
+     * requests.
+     *
+     * WHY FALLING BACK ON `null` DOES NOT RESURRECT A CLEARED ORG. After
+     * `clear()` the `localStorage` read is null by construction, so this
+     * fallback fires — and it must answer `null`, because sign-out is one of
+     * `clear()`'s callers. It does, because `clear()` nulls `_memoryValue` too.
+     * That property is what makes this read order safe rather than an
+     * incidental detail of `clear()`'s body, so it is pinned by test
+     * (`__tests__/activeOrgStorageFallback-5703.test.tsx`) instead of being
+     * re-derived by whoever edits `clear()` next.
+     *
+     * The same reasoning is why a change of session user purges through
+     * {@link purgePreviousUserClientState} rather than by removing keys: the
+     * outgoing user's id in `_memoryValue` would otherwise outlive their
+     * persisted key on the SPA sign-out-then-sign-in path (objectui#5664).
+     */
+    get(): string | null;
+    /**
+     * With no session user known this writes to memory ONLY. That is not a
+     * degraded path to apologise for — it is the fix: a persisted write with no
+     * owner is the un-namespaced key this card retired.
+     */
+    set(orgId: string): void;
+    /**
+     * Drop the active organization, from memory and from the persisted key.
+     *
+     * POSTCONDITION: {@link get} answers `null` afterwards. Sign-out is one of
+     * the callers, so that is a security-relevant guarantee rather than a
+     * convenience — and before objectui#5731 it was not one, because a
+     * `removeItem` that failed was swallowed and the surviving key won `get()`'s
+     * read order.
+     *
+     * ## Why a failed removal is neither thrown nor returned (objectui#5731)
+     *
+     * Every caller arrives here AFTER the transition it is following up on has
+     * already happened, and not one of them can act on a storage failure:
+     *
+     *  - `AuthProvider`'s `purgeSignedOutClientCaches` — the session is already
+     *    ended. Sign-out cannot be refused because a key would not delete.
+     *  - `switchOrganization` — the server already switched or cleared the
+     *    active org; a throw would report a successful switch as a failure and
+     *    route the caller into its error branch.
+     *  - `deleteOrganization` / `leaveOrganization` — the org is already deleted
+     *    or already left.
+     *  - {@link purgePreviousUserClientState}, via {@link SessionUserScope.adopt}
+     *    — runs on the SIGN-IN path inside an `AuthProvider` effect, where a
+     *    throw breaks the boot of the ARRIVING user.
+     *
+     * A `boolean` return only moves the problem one step: all five call sites
+     * would have nothing to write in the failure branch, and a return value that
+     * every caller ignores reads as handled when it is not. So the invariant is
+     * restored HERE, where it can be, and the failure is reported to the console,
+     * where a human can find it.
+     *
+     * The third shape considered and rejected was re-writing the key with an
+     * empty value. That relocates the fix into every consumer's truthiness test
+     * (`createAuthenticatedFetch` does `if (activeOrgId)`), which is the lenient
+     * consumer AGENTS.md #0.1 forbids, and it leaves a signed-out browser holding
+     * a live key.
+     */
+    clear(): void;
+};
+//# sourceMappingURL=ActiveOrganizationStorage.d.ts.map

package/dist/ActiveOrganizationStorage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ActiveOrganizationStorage.d.ts","sourceRoot":"","sources":["../src/ActiveOrganizationStorage.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAyOH;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,4BAA4B,IAAI,IAAI,CAInD;AAED;;;GAGG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;aACc,MAAM,GAAG,IAAI;IAE9B,mFAAmF;eACxE,MAAM,GAAG,IAAI;IAKxB;;;;;;;;;;;;;;;OAeG;kBACW,MAAM,GAAG,IAAI;IA0B3B;;;;;OAKG;sBACe,IAAI;CAGvB,CAAC;AAqBF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,yBAAyB;kBACd,MAAM,GAAG,IAAI;IAEnC;;;;;;;;OAQG;;IAGH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;WACI,MAAM,GAAG,IAAI;IAsBpB;;;;OAIG;eACQ,MAAM,GAAG,IAAI;IAOxB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;aACM,IAAI;CAyCd,CAAC"}