@object-ui/auth 17.5.0 → 17.6.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @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

package/README.md

@@ -137,6 +137,154 @@ 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

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"}