@mosano-product-framework/sdk 0.2.0

package/README.md

@@ -0,0 +1,827 @@
+# @mosano-product-framework/sdk
+
+TypeScript SDK for MPF services. Typed clients for **identity** (authentication,
+tenants) and **storage** (files), plus a GraphQL client, a middleware pipeline,
+and an auth layer covering token claims, tenant selection and session renewal.
+
+React bindings live in a separate subpath — see [README.react.md](./README.react.md).
+
+## Installation
+
+```bash
+npm install @mosano-product-framework/sdk
+# or
+pnpm add @mosano-product-framework/sdk
+```
+
+## Quick start
+
+```typescript
+import { createAuthClient } from '@mosano-product-framework/sdk/identity';
+import { createTenantSelection } from '@mosano-product-framework/sdk/auth';
+
+// A tenant selection is a mutable leaf: build it first, share it across clients.
+const tenants = createTenantSelection();
+
+const auth = createAuthClient({
+  baseUrl: 'https://api.example.com/auth',
+  tokenProvider: { getAccessToken: () => localStorage.getItem('access_token') },
+  tenantProvider: tenants,
+});
+
+const { access_token, refresh_token } = await auth.signInEmailPassword({
+  email: 'user@example.com',
+  password: 'secret123',
+});
+
+localStorage.setItem('access_token', access_token);
+
+// Every subsequent request carries the selected tenant. No re-login, no renewal.
+tenants.set('tenant-uuid');
+const profile = await auth.getMe();
+```
+
+## Multi-tenancy
+
+An access token carries **every** tenant the user belongs to, with their roles in
+each. Which tenant a given request acts on is chosen **per request, by header**:
+
+| Header | Meaning | When absent |
+|---|---|---|
+| `X-MPF-Tenant` | selected tenant uuid | no tenant: the request runs under the token's default role (`drl`) |
+| `X-MPF-Tenant-Role` | selected role within that tenant | the server applies that tenant's default role: its `dfr`, else `rls[0]` |
+
+Consequences worth internalising:
+
+- **Switching tenants requires no new token.** It is a header change. No renewal,
+  no network round trip, no re-login. The access token is byte-identical before
+  and after.
+- **The header is a *selection*, not a grant.** It says "act on this tenant",
+  never "give me access to this tenant". The server verifies the token's
+  signature and checks the requested tenant and role against the token's claims
+  on every single request. Asking for a tenant the token does not hold is a 401,
+  not a privilege escalation.
+- **All validation is server-side.** Nothing the client sends, and nothing this
+  SDK decodes, is trusted.
+
+### Selecting a tenant
+
+```typescript
+import { createTenantSelection, createDefaultStorage } from '@mosano-product-framework/sdk/auth';
+
+// Persisted, so a page reload keeps the user in the tenant they chose.
+const tenants = createTenantSelection({ storage: createDefaultStorage() });
+
+tenants.set('tenant-uuid');                 // select a tenant (default role)
+tenants.set('tenant-uuid', 'admin');        // select a specific role
+tenants.clear();                            // back to the no-tenant path
+
+tenants.get();                               // { tenant: 'tenant-uuid', role: 'admin' }
+
+const unsubscribe = tenants.subscribe((selection) => {
+  console.log('now acting on', selection.tenant);
+});
+```
+
+Pass the **same instance** to every client so identity, storage and GraphQL stay
+in step:
+
+```typescript
+const auth = createAuthClient({ baseUrl, tokenProvider, tenantProvider: tenants });
+const storage = createStorageClient({ baseUrl, tokenProvider, tenantProvider: tenants });
+```
+
+`createTenantSelection` deliberately imports nothing, so it can be constructed
+before any client without an import cycle.
+
+### Per-request override
+
+`RequestOptions` gains `tenant`, `tenantRole` and `skipTenant`. `tenant` has
+**three** meaningful states and the distinction matters:
+
+```typescript
+await auth.getMe();                             // inherit the client-wide selection
+await auth.getMe({ tenant: 'other-tenant' });   // this request only
+await auth.getMe({ tenant: null });             // deliberately unscoped (no tenant header)
+await auth.getMe({ skipTenant: true });         // send no tenant headers at all
+```
+
+- `undefined` — "I did not say", so inherit the ambient selection.
+- `null` — "I mean no tenant", so ignore the ambient selection for this call.
+
+Without both states, a deliberately unscoped call would silently pick up whatever
+tenant happened to be selected.
+
+A per-request tenant does **not** inherit the client-wide role. Selecting tenant
+B while tenant A's role is selected sends B with no role header, letting the
+server apply B's default — sending A's role to B would be wrong.
+
+The tenant header is **omitted entirely** when there is no tenant. An
+empty-string header is rejected server-side by design, so a bug cannot
+masquerade as the no-tenant path.
+
+### The no-tenant (`drl`) path
+
+With no tenant selected, a request runs under the token's default role. That is
+the correct state for tenant-agnostic calls — `getMe()`, `listMyTenants()`, a
+tenant switcher — and the wrong state for anything tenant-scoped, which will
+return empty results or a 403 rather than another tenant's data.
+
+Because that failure is quiet, the tenant middleware emits a **one-time
+`console.warn`** the first time a request goes out with no tenant selected while
+the token *does* hold tenants. It fires only for the unscoped-by-omission case
+(`undefined`), never for an explicit `{ tenant: null }` — stating intent is not a
+mistake, and warning on it would train you to ignore the warning.
+
+### GraphQL
+
+`GraphQLRequestOptions` carries the same fields, so tenant selection works
+identically:
+
+```typescript
+await gql.query(MyDocument, variables, { tenant: 'tenant-uuid' });
+await gql.query(TenantListDocument, undefined, { tenant: null });
+```
+
+## Access token claims
+
+The SDK can decode an access token to drive UI — render a tenant switcher, grey
+out an unavailable option, decide when to renew.
+
+> ### ⚠️ Decode, not verify
+>
+> This SDK **decodes** access tokens. It does **not verify** them.
+>
+> There is no signature check and no key material in this package. An unsigned
+> token, a token signed with the wrong key, and a token whose payload was
+> hand-edited in devtools all decode identically and successfully.
+>
+> A hostile client can therefore forge **any** value these functions return: any
+> user id, any session id, any tenant, any role, any expiry.
+>
+> Every use must be UX-only. **Never gate a security-relevant branch on these
+> values.** The server is the only authority: it verifies the signature and
+> re-derives tenant and role from the token on every request, and a forged claim
+> buys an attacker exactly nothing there.
+>
+> Verification would require the signing secret, and the signing secret must
+> never reach a browser.
+
+```typescript
+import {
+  decodeAccessToken,
+  tryDecodeAccessToken,
+  listTenants,
+  rolesForTenant,
+  defaultRoleForTenant,
+  canSelect,
+  isExpired,
+  expiresAt,
+  clearClaimsCache,
+} from '@mosano-product-framework/sdk/auth';
+
+const claims = decodeAccessToken(access_token);
+// { v: 1, uid, sid, iat, exp,
+//   tnts: [{ id: '<tenant>', rls: ['owner', 'member'], dfr: 'owner' }],
+//   drl: 'tenantless' }
+// tnts is an ARRAY, always present ([] for a user with no tenants). `dfr` is
+// OPTIONAL per entry and, when present, is always one of that entry's `rls`.
+
+listTenants(claims);                      // ['tenant-a', 'tenant-b']
+rolesForTenant(claims, 'tenant-a');       // ['owner', 'member']
+defaultRoleForTenant(claims, 'tenant-a'); // that entry's `dfr`, else `rls[0]`
+canSelect(claims, 'tenant-a', 'admin');   // false — UX hint only, NOT a permission check
+isExpired(claims, 120);                    // will it die within 2 minutes?
+expiresAt(claims);                         // Date
+```
+
+Notes:
+
+- `decodeAccessToken` **throws**; `tryDecodeAccessToken` returns `null`.
+- Both **succeed on an expired token** by design — the renewal logic needs `exp`,
+  so expiry is the caller's question. Ask it with `isExpired`.
+- `v` dispatches through a parser registry, so a future claim shape coexists with
+  this one. An unknown `v` throws `MPFUnsupportedClaimsVersionError` carrying the
+  version, which distinguishes "this app is older than the server" from "this
+  token is garbage". Unknown *keys* are tolerated so a server-side field addition
+  cannot brick older clients.
+- Successful decodes are cached in a 5-entry LRU keyed on the token string.
+  `clearClaimsCache()` on logout.
+- Roles are typed `MPFRole = string`, not a closed union: they are database rows,
+  so a newly seeded role must not require an SDK release.
+- **Absent claims degrade where the empty state is meaningful.** `tnts` missing
+  or `null` decodes as `[]` (a brand-new user belongs to no tenants), and an
+  empty or absent `drl` becomes
+  `undefined` (a deployment may have no tenantless role). `v`, `exp`, `uid` and
+  `sid` stay hard-required — without those the token cannot be interpreted at
+  all. A claim of the wrong *type* always throws: absence is a legitimate state,
+  corruption is not.
+
+## Sessions and renewal
+
+Access tokens live **15 minutes**. The `SessionManager` keeps one alive across a
+tab's lifetime.
+
+```typescript
+import { createSessionManager, createDefaultStorage } from '@mosano-product-framework/sdk/auth';
+
+const session = createSessionManager({
+  renew: (refreshToken) => auth.renewSession({ refresh_token: refreshToken }),
+  storage: createDefaultStorage(),
+  onDeadSession: (error) => {
+    // A callback, never a navigation. Route however your app routes.
+    console.warn('session over:', error.message);
+  },
+});
+
+session.setTokens({ access_token, refresh_token });
+
+// Wire the client to the manager. getAccessToken renews first if needed.
+const auth = createAuthClient({
+  baseUrl,
+  tokenProvider: {
+    getAccessToken: () => session.getAccessToken(),
+    onUnauthorized: async () => {
+      await session.renew();
+      return true;              // retry the request once with the fresh token
+    },
+    onTokenExpired: () => redirectToLogin(),
+  },
+});
+```
+
+Only the **refresh token** is persisted. The access token stays in memory: at a
+15-minute TTL, persisting it buys almost nothing and it is the more dangerous of
+the two to leave in `localStorage`.
+
+### The 120-second buffer
+
+A token counts as stale 120 seconds before it expires, not at expiry.
+
+60 seconds was tuned against a 6-hour token, where it was 0.3% of the lifetime.
+At 900 seconds it is 6.7%, and the failure mode changes: a request *starting* at
+`exp − 61s` passes a 60-second freshness check and then carries a token that dies
+mid-flight — which large storage uploads routinely will. The buffer has to cover
+renewal latency plus the longest in-flight request, and browser clock skew is
+unbounded. 120s means renewing roughly every 13 minutes.
+
+The buffer is **clamped per token** to just under half the token's lifetime. If
+the buffer were ≥ half the lifetime, a freshly minted token would be "stale" the
+instant it arrived and the manager would renew-loop. A 60-second token therefore
+gets a 29-second buffer, not 120. A `minRenewIntervalMs` floor (default 5s) is a
+second guard against a misconfigured server TTL turning this into a DoS on
+`/sessions/renew`.
+
+### Three layers of renewal
+
+1. **Proactive** — a `setTimeout` fires shortly before the token goes stale, so
+   requests never pay for a renewal. Jittered ±30s so multiple tabs do not all
+   wake on the same millisecond.
+2. **Wake** — `setTimeout` does **not** fire in frozen or discarded tabs (Chrome
+   tab freezing, iOS Safari), so a tab backgrounded for 20 minutes wakes holding
+   a guaranteed-dead token with its timer never having run. On
+   `visibilitychange` → visible and on `online`, the manager renews immediately
+   and publishes a gate that `getAccessToken()` awaits, so requests fired by the
+   same focus event queue behind the renewal instead of each eating a 401. **This
+   is the real safety net, not the timer.**
+3. **Reactive** — a 401 on a request that carried a token triggers one renewal
+   and one retry. See [Auth middleware](#auth-middleware).
+
+Renewals are **coalesced**: concurrent callers share one network call. The
+refresh token is single-use, so two parallel renewals would kill each other.
+
+### Multiple tabs
+
+Every tab of one browser shares a single refresh token via origin-scoped
+`localStorage`, and with proactive renewal all of them wake at roughly the same
+moment. Coordination therefore has to be real:
+
+- **`navigator.locks`** (Web Locks) provides a cross-tab mutex, with no
+  dependency on the primary path. Locks auto-release when a tab is destroyed, so
+  a closed tab cannot deadlock the others.
+- **Double-checked locking** — a lock alone is insufficient: N tabs would queue
+  and then each renew in turn, which is the problem the lock was meant to solve.
+  Each tab re-reads the persisted refresh token *inside* the lock and adopts
+  instead of renewing when another tab got there first.
+- **`BroadcastChannel`** fans the winner's fresh access token out to the other
+  tabs, in memory, so losers adopt with **no network call** while the access
+  token still never touches `localStorage`.
+- **`AbortSignal` timeout** (5s) on the lock request, so a waiter cannot hang
+  behind a frozen tab holding the lock mid-renewal.
+
+Everything no-ops when `window` is absent, so Node and server-side rendering are
+unaffected.
+
+```typescript
+import { createCrossTabCoordinator } from '@mosano-product-framework/sdk/auth';
+
+const session = createSessionManager({
+  renew,
+  crossTab: createCrossTabCoordinator({ lockTimeoutMs: 5000 }),
+});
+// or `crossTab: null` to disable coordination entirely
+```
+
+**Residual limitations, stated honestly:**
+
+- `navigator.locks` and `BroadcastChannel` both need Safari 15.4+ and a secure
+  context. Where locks are missing you may supply a Web Locks polyfill via
+  `loadPolyfill`; without one, tabs run **uncoordinated** and may each renew.
+  That is survivable rather than correct — see the next point.
+- If the lock times out, the manager **proceeds without it**. A duplicate
+  renewal is recoverable (the server returns `REFRESH_TOKEN_SUPERSEDED`, and the
+  losing tab adopts the winner's token instead of logging out), whereas hanging
+  would leave the app with no token at all.
+- Where `BroadcastChannel` is unavailable, losing tabs fall back to renewing with
+  the rotated refresh token — correct, just an extra round trip.
+- Separate **browsers, machines or devices** get separate sessions and separate
+  refresh tokens by design; none of this applies across them.
+
+## Middlewares
+
+### Auth middleware
+
+Injects the `Authorization` header, and handles 401s with two independent guards.
+
+```typescript
+import { createAuthMiddleware } from '@mosano-product-framework/sdk/client';
+
+const authMiddleware = createAuthMiddleware({
+  getAccessToken: () => session.getAccessToken(),
+  onUnauthorized: async () => {
+    await session.renew();
+    return true;                       // renewed -> retry once
+  },
+  onTokenExpired: () => redirectToLogin(),   // the 401 was final
+});
+```
+
+Behaviour: **401 → renew → retry once → success.** Only a *second* 401 reaches
+`onTokenExpired`.
+
+Two guards make that safe:
+
+- A 401 on a request that carried **no** token does nothing at all — no renewal,
+  no logout. This is the wrong-password guard: a failed sign-in must never log
+  you out of a session you do have. It belongs in the SDK rather than in every
+  consumer's app code.
+- Renewal is capped at **one attempt per logical request**, set before awaiting,
+  so a retry loop cannot trigger a second renewal of a single-use refresh token.
+
+`createAuthClient`/`createStorageClient` wire this automatically from
+`tokenProvider`.
+
+### Tenant middleware
+
+Puts the selected tenant on the wire. Auto-wired by `createAuthClient` and
+`createStorageClient` when you pass `tenantProvider`; wire it manually for a bare
+client:
+
+```typescript
+import { createTenantMiddleware, TENANT_HEADER, TENANT_ROLE_HEADER } from '@mosano-product-framework/sdk/client';
+
+const tenantMiddleware = createTenantMiddleware({
+  tenantProvider: tenants,
+  // Optional, enables the one-time under-scoping warning described above.
+  getAccessToken: () => session.peekAccessToken(),
+  warnOnUnscoped: true,
+});
+```
+
+### Retry middleware
+
+Retries failed requests with exponential backoff and jitter.
+
+```typescript
+import { createRetryMiddleware } from '@mosano-product-framework/sdk/client';
+
+const retryMiddleware = createRetryMiddleware({
+  maxRetries: 3,
+  retryDelay: 1000,
+  retryOn: [408, 429, 500, 502, 503, 504],
+  backoffFactor: 2,
+  jitter: true,
+  onRetry: (attempt, error, delay) => console.warn(`retry ${attempt} in ${delay}ms`),
+});
+```
+
+Notes:
+
+- `MPFClient.request()` caps every request at **4 attempts** total
+  (`MAX_REQUEST_ATTEMPTS`), independent of any middleware's `maxRetries`.
+- A `ReadableStream` body cannot be re-sent and disables retrying. `FormData`
+  (storage uploads) is re-readable and does retry.
+- Retry is **opt-in**: neither client factory registers it for you.
+
+### Logging middleware
+
+```typescript
+import { createLoggingMiddleware } from '@mosano-product-framework/sdk/client';
+
+const loggingMiddleware = createLoggingMiddleware({
+  logBody: false,      // default false: bodies may contain secrets
+  logHeaders: false,   // Authorization/Cookie are always redacted when enabled
+  minDuration: 100,    // only log requests slower than this
+});
+```
+
+### Combining middlewares
+
+```typescript
+const auth = createAuthClient({
+  baseUrl: 'https://api.example.com/auth',
+  middlewares: [
+    createLoggingMiddleware(),
+    createRetryMiddleware({ maxRetries: 3 }),
+  ],
+});
+```
+
+Request middlewares run in registration order; response middlewares in reverse.
+**Every** `onError` handler runs, in registration order, even though each signals
+by throwing — so a handler registered after another cannot be silently skipped.
+
+## Service clients
+
+### Identity client
+
+```typescript
+import { createAuthClient } from '@mosano-product-framework/sdk/identity';
+
+const auth = createAuthClient({ baseUrl: 'https://api.example.com/auth' });
+
+// Sign up / sign in
+const tokens = await auth.signUpEmailPassword({
+  display_name: 'John Doe',
+  email: 'john@example.com',
+  password: 'securePassword123',
+});
+const session = await auth.signInEmailPassword({
+  email: 'john@example.com',
+  password: 'securePassword123',
+});
+
+// Profile
+const me = await auth.getMe();                        // UserProfileResponse
+await auth.updateMe({ display_name: 'John Updated' });
+
+// Sessions
+const sessions = await auth.listSessions();
+await auth.deleteSession('session-id');
+const renewed = await auth.renewSession({ refresh_token });
+await auth.revokeSession({ refresh_token });          // sign out
+
+// Tenants
+const tenant = await auth.createTenant({ name: 'My Organization', slug: 'my-org' });
+const myTenants = await auth.listMyTenants();          // id, name, slug
+const members = await auth.listTenantMembers(tenant.id);
+await auth.inviteTenantMember(tenant.id, { email: 'member@example.com', role: 'member' });
+await auth.acceptInvitation('invitation-token');
+```
+
+`signInEmailPassword` may return an MFA challenge rather than tokens — narrow it:
+
+```typescript
+// These narrowing helpers live on the /identity subpath (the root barrel
+// namespaces them as `AuthTypes.isMFARequired`).
+import { isMFARequired } from '@mosano-product-framework/sdk/identity';
+
+const result = await auth.signInEmailPassword({ email, password });
+if (isMFARequired(result)) {
+  const tokens = await auth.verifyMFA({ mfa_ticket: result.mfa_ticket, totp_code: '123456' });
+}
+```
+
+### Google OAuth — and why the `state` must round-trip
+
+```typescript
+import { createAuthClient } from '@mosano-product-framework/sdk/identity';
+import { createOAuthStateStore } from '@mosano-product-framework/sdk/auth';
+
+const oauthState = createOAuthStateStore();          // sessionStorage by default
+const auth = createAuthClient({ baseUrl, oauthStateStore: oauthState });
+
+// 1. Starting the flow. The client persists `state` for you when a store is wired.
+const { url } = await auth.getGoogleOAuthURL({ redirect_uri: 'https://app.test/oauth/callback' });
+window.location.href = url;
+
+// 2. On your callback route, after the redirect back:
+const params = new URLSearchParams(window.location.search);
+const state = oauthState.take();                     // single-use: read and clear
+
+if (!state) {
+  // No pending flow in this tab. Do NOT proceed — send the user back to sign-in.
+  throw new Error('No pending OAuth flow');
+}
+
+const tokens = await auth.handleGoogleOAuthCallback({
+  code: params.get('code')!,
+  redirect_uri: 'https://app.test/oauth/callback',
+  state,
+});
+```
+
+#### Why this matters
+
+**`state` is the CSRF defence for this flow, and dropping it is exploitable —
+not theoretically, but confirmed end to end.**
+
+Without it, a callback route accepts *any* `code` presented to it. An attacker
+obtains an authorization code for **their own** account, then sends the victim to
+`https://yourapp/oauth/callback?code=<attacker's code>`. The victim's browser
+posts it, the server exchanges it, and the victim is now signed in **as the
+attacker** — into an account the attacker still controls. Everything the victim
+does next (entering card details, uploading documents, accepting an invitation)
+happens inside the attacker's account, visible to them.
+
+It is especially easy to get wrong because the exploit needs **no user
+interaction**: a callback route that auto-submits `code` on page load does the
+whole thing on navigation alone.
+
+The state closes it. The server mints an unguessable value, records it, and
+accepts the callback only if the same value comes back — which an attacker
+cannot produce, because it lives in the victim's browser storage.
+
+So:
+
+- `state` is **required** on `GoogleOAuthCallbackRequest`. TypeScript rejects a
+  callback without it, and the SDK throws `MPFValidationError` **before** issuing
+  the request rather than sending one the server must reject.
+- It must survive a **full-page redirect**, so it cannot live in memory, React
+  state, or a closure. `createOAuthStateStore()` puts it in `sessionStorage`.
+- It is **single use**. `take()` reads and clears; the server also rejects reuse.
+- Server-side rejection (mismatch, absent, expired, replayed) surfaces as a
+  normal typed SDK error carrying the server's code — see
+  [Error handling](#error-handling). Treat it as "start the flow again", never as
+  "retry the callback".
+
+**Do not "simplify" the state away.** If a callback seems to work without it,
+that is the vulnerability, not a shortcut.
+
+Storage choice: `sessionStorage` is per-tab, which is right for a redirect flow —
+a state minted in one tab cannot be consumed by another. The tradeoff is that a
+callback landing in a *different* tab won't find it and will fail closed. If your
+flow can land elsewhere, pass `createDefaultStorage()` (localStorage), accepting
+that the state is then readable by every tab on the origin. A cookie is not
+offered: one set from JavaScript cannot be `httpOnly`, so it is no less readable
+than web storage while adding `SameSite` pitfalls on the cross-site return leg.
+
+### Storage client
+
+The storage API is signed-URL based, plus direct multipart upload.
+
+```typescript
+import { createStorageClient } from '@mosano-product-framework/sdk/storage';
+
+const storage = createStorageClient({
+  baseUrl: 'https://api.example.com/storage',
+  tokenProvider: { getAccessToken: () => session.getAccessToken() },
+  tenantProvider: tenants,
+});
+
+// Direct multipart upload
+const metadata = await storage.uploadFile(file);
+
+// Or the signed-URL flow: get a URL, PUT to it yourself, then confirm
+const { url, file_id } = await storage.getUploadSignedUrl({ /* ... */ });
+await storage.confirmUpload(file_id);
+
+// Download
+const download = await storage.getDownloadSignedUrl(metadata.id);
+
+// Batch variants exist for each operation
+await storage.getBatchUploadSignedUrls({ /* ... */ });
+await storage.batchUploadFiles(files);
+await storage.batchDeleteFiles({ /* ... */ });
+
+// Replace and delete
+await storage.replaceFile(metadata.id, newFile);
+await storage.deleteFile(metadata.id);
+```
+
+## Error handling
+
+```typescript
+import {
+  MPFAPIError,
+  MPFNetworkError,
+  MPFAuthError,
+  MPFValidationError,
+} from '@mosano-product-framework/sdk/client';
+
+try {
+  await auth.signInEmailPassword({ email, password: 'wrong' });
+} catch (error) {
+  if (error instanceof MPFAuthError) {
+    // 401/403
+    console.error(error.message, error.authErrorType, error.serverCode);
+  } else if (error instanceof MPFValidationError) {
+    console.error('Validation failed:', error.fieldErrors);
+  } else if (error instanceof MPFNetworkError) {
+    console.error('No response:', error.message);
+  } else if (error instanceof MPFAPIError) {
+    console.error(`API error ${error.status}:`, error.message);
+  }
+}
+```
+
+`MPFAuthError.code` is derived from the error classification and collapses every
+401 to `UNAUTHORIZED`. Use **`serverCode`** for the code the server actually sent
+— `REFRESH_TOKEN_SUPERSEDED` being the one that matters, since it means "another
+tab renewed first" and is recoverable rather than fatal.
+
+## Modules
+
+The package is cut into five subpaths. Import from the one that owns the name:
+
+| Subpath | Contents |
+|---|---|
+| `@mosano-product-framework/sdk/client` | The generic transport layer: `MPFClient`, the middleware pipeline and the built-in middlewares (auth, admin-auth, tenant, retry, logging, turnstile), the error types, shared request/response types, the URL helpers, and the GraphQL clients (HTTP, WebSocket and hybrid). |
+| `@mosano-product-framework/sdk/auth` | The auth layer: JWT claim types and decoding, session manager, cross-tab coordination, storage adapters, tenant selection, OAuth state. Framework-agnostic. |
+| `@mosano-product-framework/sdk/identity` | The identity service client: signup, signin, forgot password, OAuth, token renewal — plus its request/response types. |
+| `@mosano-product-framework/sdk/storage` | The storage service client and its types. |
+| `@mosano-product-framework/sdk/react` | React bindings — provider, hooks, store. See [README.react.md](./README.react.md). |
+
+```typescript
+import { createAuthClient } from '@mosano-product-framework/sdk/identity';
+import { createStorageClient } from '@mosano-product-framework/sdk/storage';
+import { decodeAccessToken } from '@mosano-product-framework/sdk/auth';
+import { MPFAPIError } from '@mosano-product-framework/sdk/client';
+import { MPFAuthProvider } from '@mosano-product-framework/sdk/react';
+```
+
+### The root export is a namespace object
+
+The root re-exports the four non-React modules as **namespaces**, not as flat
+names:
+
+```typescript
+import { client, auth, identity, storage } from '@mosano-product-framework/sdk';
+
+const api = identity.createAuthClient({ baseUrl });
+const selection = auth.createTenantSelection();
+if (error instanceof client.MPFAPIError) { /* ... */ }
+```
+
+A default export with the same shape is available too:
+
+```typescript
+import sdk from '@mosano-product-framework/sdk';
+
+const api = sdk.identity.createAuthClient({ baseUrl });
+```
+
+Two things are deliberately **not** reachable from the root in any form — not
+even as a namespace:
+
+- **`react`.** It is an optional peer dependency. A static re-export from the
+  root would put `react` in every consumer's module graph, so merely importing
+  the package would require React to be installed — breaking plain-Node
+  consumers. Use the `/react` subpath.
+- **`createGraphQLClient` / `createGraphQLWsTransport`.** Same reasoning for the
+  optional `graphql-ws` peer, which those two reach (through a dynamic
+  `import()`). The root's `client` namespace is the peer-free half of `/client`;
+  use the `/client` subpath for subscriptions.
+
+`tests/module-boundaries.test.ts` and `tests/package-exports.test.ts` enforce
+both rules.
+
+## TypeScript
+
+Request/response types come from the service subpath that owns them:
+
+```typescript
+import type { UserProfileResponse, LoginRequest, TenantResponse } from '@mosano-product-framework/sdk/identity';
+import type { FileMetadataResponse } from '@mosano-product-framework/sdk/storage';
+
+const profile: UserProfileResponse = { /* ... */ };
+const login: LoginRequest = { email, password };
+const tenant: TenantResponse = { /* ... */ };
+```
+
+From the root they are reached through the namespace — `identity.LoginRequest`,
+`storage.FileMetadataResponse`.
+
+## ESM only
+
+This package ships **ES modules only**. There is no CommonJS build.
+
+`require()` from a CommonJS file fails with a message that reads more alarmingly
+than the situation warrants:
+
+```
+Error [ERR_PACKAGE_PATH_NOT_EXPORTED]: No "exports" main defined in
+  .../node_modules/@mosano-product-framework/sdk/package.json
+```
+
+That does **not** mean the package has no entry point — it means there is no
+`require` condition in the exports map, because the package is ESM-only. From
+CommonJS, use a dynamic import:
+
+```javascript
+const { identity } = await import('@mosano-product-framework/sdk');
+const auth = identity.createAuthClient({ baseUrl });
+```
+
+Any bundler (Vite, webpack, esbuild, Rollup, Next.js) and any `"type": "module"`
+package consume it directly with a static `import`.
+
+## GraphQL subscriptions
+
+Subscriptions go over `graphql-ws` and live on the `/client` subpath, behind
+`createGraphQLClient({ mode: 'websocket' | 'hybrid' })`. `graphql-ws` is an
+optional peer, loaded through a dynamic `import()` only when one of those modes
+is used.
+
+Two constraints come from Hasura and shape the API:
+
+- Hasura authenticates a socket **once**, at `connection_init`. Headers come from
+  that payload and anything sent later is ignored, so a connection is pinned to
+  **one tenant for its entire lifetime**. Switching tenants in a subscribing UI
+  means tearing the socket down and reconnecting — hence the explicit
+  `reconnectWebSocket()` on the hybrid client.
+- With auth caching disabled (`no-store`, the safe default), the socket's
+  authorization is never re-evaluated, so a connection **outlives the access
+  token** that opened it. Wire `reconnectWebSocket` to
+  `SessionManager.onTokensChanged`.
+
+## Migrating to 0.2.0
+
+Nothing is released yet, so this is a clean break rather than a deprecation.
+
+### Package and module layout
+
+1. **The package was renamed** `@mosano-product-framework/public-sdk` →
+   `@mosano-product-framework/sdk`. Its directory in the monorepo moved
+   `pkg/mpf-public-sdk/` → `pkg/js-sdk/`.
+2. **The root export is a namespace object.** `import { MPFAPIError } from '...'`
+   no longer works; it is `import { client } from '...'` +
+   `client.MPFAPIError`, or the subpath `import { MPFAPIError } from
+   '.../client'`. See [Modules](#modules).
+3. **The `./graphql` subpath is gone.** Everything it exported — the GraphQL
+   clients, `createGraphQLClient`, `createGraphQLWsTransport` — is on `./client`,
+   which is now the home of the whole generic transport layer (core client,
+   middlewares, errors, shared types).
+4. **`AuthTypes` / `StorageTypes` are gone** as root namespaces. The identity and
+   storage types are exported directly from `./identity` and `./storage`, and
+   reachable from the root as `identity.*` / `storage.*`.
+
+### API breaking changes
+
+1. **`tenantId` removed** from `LoginRequest`, `ResetPasswordRequest`,
+   `RenewSessionRequest`, `FinishPasskeyLoginRequest`,
+   `GoogleOAuthCallbackRequest`, `MFAVerifyRequest` and
+   `MFASetupVerifyRequest`. Select a tenant with headers instead. This is
+   runtime-neutral: the SDK sent camelCase `tenantId` while the API only ever
+   read snake_case `tenant_id`, so the field never reached the server.
+2. **`tenant_id` removed** from `getGoogleOAuthURL` params — the one path where
+   it did reach the server.
+3. **Response `role` fields widened** to `MPFRole` (`string`) on
+   `MembershipResponse`, `PendingInvitationResponse` and
+   `IssuedInvitationResponse`. An exhaustive `switch` over the old union now
+   needs a `default`.
+4. **Request `role` fields**: `'viewer'` → `'guest'`. `'viewer'` was never a
+   seeded database role.
+5. **5xx responses now actually retry** when a retry middleware is registered.
+   Previously the retry middleware was dead code — it slept, set a flag, and
+   nothing ever read it. Non-idempotent requests may now reach the server more
+   than once.
+6. New `/auth` and `/react` subpaths; `sideEffects: false`; React as an optional
+   peer dependency.
+
+#### 7. Google OAuth `state` — a security fix, not a refactor
+
+**This one is different from the rest of this list.** The others are type-level
+tidying with no runtime consequence. This closes a **confirmed exploitable CSRF
+vulnerability** in the OAuth callback flow, and code that does not adopt it stays
+vulnerable. Migrate it deliberately, not mechanically.
+
+- `getGoogleOAuthURL()` now resolves to **`{ url, state }`** instead of `{ url }`.
+- `GoogleOAuthCallbackRequest` gains a **required** `state`.
+- The server validates `state` before exchanging the code and rejects a mismatch,
+  absence, expiry or reuse.
+
+```diff
+- const { url } = await auth.getGoogleOAuthURL({ redirect_uri });
+- window.location.href = url;
++ const oauthState = createOAuthStateStore();
++ const auth = createAuthClient({ baseUrl, oauthStateStore: oauthState });
++ const { url } = await auth.getGoogleOAuthURL({ redirect_uri });
++ window.location.href = url;
+
+  // callback route
+- await auth.handleGoogleOAuthCallback({ code, redirect_uri });
++ const state = oauthState.take();
++ if (!state) throw new Error('No pending OAuth flow');
++ await auth.handleGoogleOAuthCallback({ code, redirect_uri, state });
+```
+
+TypeScript will point at every call site, since `state` is required. The failure
+mode if you skip this is not a compile error in plain JavaScript, though — it is
+a working-looking login that lets an attacker sign a user into the attacker's
+account. See [Google OAuth](#google-oauth--and-why-the-state-must-round-trip) for
+the full mechanism.
+
+## License
+
+MIT