@mosano-product-framework/sdk 0.2.0

package/dist/auth/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Errors for the auth layer.
+ */
+import { MPFError } from '../client/core/errors.js';
+/**
+ * Base error for access-token claim decoding failures.
+ */
+export declare class MPFClaimsError extends MPFError {
+    constructor(message: string, code?: string, details?: unknown);
+}
+/**
+ * Thrown when a token's claim-set version has no registered parser.
+ *
+ * Carries the offending version so a client can distinguish "this app is older
+ * than the server" (a deploy-ordering problem, usually fixed by reloading) from
+ * "this token is garbage" (a real auth failure).
+ */
+export declare class MPFUnsupportedClaimsVersionError extends MPFClaimsError {
+    /** The `v` value found in the token, or null when it was absent/non-numeric. */
+    readonly version: number | null;
+    constructor(version: number | null);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Thrown when the session can no longer be renewed and the user must
+ * re-authenticate.
+ *
+ * This is a terminal state: the refresh token was rejected, absent, or the
+ * renew endpoint failed in a non-recoverable way.
+ */
+export declare class DeadSessionError extends MPFError {
+    /** The underlying error that killed the session, when there was one. */
+    readonly cause?: Error;
+    constructor(message?: string, cause?: Error);
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Type guard for {@link DeadSessionError}.
+ */
+export declare function isDeadSession(error: unknown): error is DeadSessionError;

package/dist/auth/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Auth layer: token claims, tenant selection, session lifecycle.
+ *
+ * ⚠️ Claim decoding in this module DECODES BUT DOES NOT VERIFY. Its output is
+ * UX-only and is forgeable by a hostile client. See the security block at the
+ * top of `claims.ts`.
+ *
+ * @packageDocumentation
+ */
+export type { MPFRole, MPFClaims, MPFClaimsV1, MPFTenantClaim, ClaimsParser, } from './claims-types.js';
+export { decodeAccessToken, tryDecodeAccessToken, listTenants, rolesForTenant, defaultRoleForTenant, canSelect, expiresAt, isExpired, tokenLifetimeSeconds, clearClaimsCache, registerClaimsParser, supportedClaimsVersions, } from './claims.js';
+export { MPFClaimsError, MPFUnsupportedClaimsVersionError, DeadSessionError, isDeadSession, } from './errors.js';
+export { createTenantSelection, type TenantSelection, type TenantSelectionStore, type TenantSelectionPersistence, type CreateTenantSelectionOptions, } from './tenant-selection.js';
+export { createDefaultStorage, createSessionStorage, createMemoryStorage, type MPFAuthStorage, } from './storage.js';
+export { createOAuthStateStore, type OAuthStateStore, type OAuthStateStoreOptions, } from './oauth-state.js';
+export { createCrossTabCoordinator, applyJitter, type CrossTabCoordinator, type CrossTabMode, type CrossTabOptions, type TokenBroadcast, type LockManagerLike, type BroadcastChannelLike, } from './cross-tab.js';
+export { TENANT_DIRECTORY_QUERY, type TenantDirectoryEntry, type TenantDirectoryLoader, } from './tenant-directory.js';
+export { SessionManager, createSessionManager, isSupersededError, REFRESH_TOKEN_SUPERSEDED, type SessionManagerOptions, type SignOutResult, type TokenPair, } from './session-manager.js';

package/dist/auth/index.js

@@ -0,0 +1,5 @@
+export { TENANT_DIRECTORY_QUERY, createOAuthStateStore } from '../chunk-GPWGOYCA.js';
+export { REFRESH_TOKEN_SUPERSEDED, SessionManager, applyJitter, createCrossTabCoordinator, createDefaultStorage, createMemoryStorage, createSessionManager, createSessionStorage, createTenantSelection, isSupersededError } from '../chunk-7WAV52EO.js';
+export { DeadSessionError, MPFClaimsError, MPFUnsupportedClaimsVersionError, canSelect, clearClaimsCache, decodeAccessToken, defaultRoleForTenant, expiresAt, isDeadSession, isExpired, listTenants, registerClaimsParser, rolesForTenant, supportedClaimsVersions, tokenLifetimeSeconds, tryDecodeAccessToken } from '../chunk-AJWM5MDZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/auth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/auth/oauth-state.d.ts

@@ -0,0 +1,93 @@
+/**
+ * OAuth `state` persistence — CSRF protection for the Google OAuth flow.
+ *
+ * ## What the state is for
+ *
+ * Without it, an OAuth callback route accepts *any* `code` presented to it. An
+ * attacker who obtains an authorization code for their own account can send the
+ * victim to `.../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** —
+ * whose account the attacker still controls. Anything the victim then does
+ * (entering payment details, uploading documents, accepting an invitation)
+ * happens inside the attacker's account.
+ *
+ * That is not theoretical: it was confirmed exploitable end to end in the
+ * reference boilerplate, whose callback route discarded `state` and auto-posted
+ * `code` on page load with no user interaction.
+ *
+ * The state closes it: the server mints an unguessable value, the client stores
+ * it before redirecting, and the server accepts the callback only if the value
+ * comes back. An attacker cannot produce a state that matches the victim's
+ * browser storage.
+ *
+ * ## Why this store exists
+ *
+ * The state must survive a **full-page redirect to Google and back**, so it
+ * cannot live in memory or in React state. That leaves web storage, and
+ * "remember to persist a value across a redirect" is precisely the step the
+ * boilerplate omitted. This makes it one call each way.
+ *
+ * Sending the state stays explicit: `GoogleOAuthCallbackRequest.state` is
+ * required, so TypeScript rejects a callback that forgets it. This store solves
+ * *where to keep it*, not *whether to send it* — a security parameter should not
+ * be invisibly injected.
+ */
+import { type MPFAuthStorage } from './storage.js';
+export interface OAuthStateStore {
+    /** Persist the state returned by `getGoogleOAuthURL`, before redirecting. */
+    save(state: string): void;
+    /**
+     * Read and **clear** the stored state, for sending on the callback.
+     *
+     * Single-use by design: a state that could be replayed is not much better than
+     * no state at all, and the server also rejects reuse.
+     */
+    take(): string | null;
+    /** Read without clearing. For diagnostics; prefer `take()` in the flow. */
+    peek(): string | null;
+    /** Discard any pending state (e.g. the user abandoned the flow). */
+    clear(): void;
+}
+export interface OAuthStateStoreOptions {
+    /**
+     * Where to keep the pending state.
+     *
+     * Defaults to `sessionStorage`, which is the right default for a redirect
+     * flow: it is scoped to the tab that started it, so a state minted in one tab
+     * cannot be consumed by another, and it is cleared when the tab closes.
+     *
+     * **Limitation worth knowing:** `sessionStorage` is per-tab, so a callback
+     * that lands in a *different* tab (a provider opening a new tab, or the user
+     * moving the URL) will not find the state and the callback will be rejected —
+     * failing closed, which is the correct direction, but it will look like a
+     * spurious error. Pass `createDefaultStorage()` (localStorage) if your flow
+     * can land in another tab, accepting that the state is then visible to 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?: MPFAuthStorage;
+    /** Storage key. @default 'mpf.oauth_state' */
+    storageKey?: string;
+}
+/**
+ * Create a store for the pending OAuth state.
+ *
+ * @example
+ * ```ts
+ * const oauthState = createOAuthStateStore();
+ * const auth = createAuthClient({ baseUrl, oauthStateStore: oauthState });
+ *
+ * // Starting the flow — the client saves the state for you.
+ * const { url } = await auth.getGoogleOAuthURL({ redirect_uri });
+ * window.location.href = url;
+ *
+ * // On the callback route, send it back explicitly.
+ * const state = oauthState.take();
+ * if (!state) throw new Error('No pending OAuth flow in this tab');
+ * const tokens = await auth.handleGoogleOAuthCallback({ code, redirect_uri, state });
+ * ```
+ */
+export declare function createOAuthStateStore(options?: OAuthStateStoreOptions): OAuthStateStore;

package/dist/auth/session-manager.d.ts

@@ -0,0 +1,253 @@
+/**
+ * Session manager — single access token, single refresh token.
+ *
+ * There is deliberately no per-tenant token map, no `renewScoped`, and no
+ * scoped/general token split: tenant is a request header now, so all of that
+ * machinery is gone by construction rather than by choice.
+ *
+ * What remains, and why:
+ * - **Coalescing** — the refresh token is single-use, so concurrent renewals
+ *   must serialize into one network call or they kill each other.
+ * - **Proactive timer** — renew before expiry so requests never pay for it.
+ * - **Wake handling** — `setTimeout` does not fire in frozen or discarded tabs,
+ *   so the timer alone is not a safety net. See `handleWake`.
+ * - **Cross-tab lock** — N tabs of one browser share one refresh token.
+ */
+import type { MPFClaims } from './claims-types.js';
+import { DeadSessionError } from './errors.js';
+import { type MPFAuthStorage } from './storage.js';
+import { type CrossTabCoordinator } from './cross-tab.js';
+/** Outcome of {@link SessionManager.signOut}. */
+export interface SignOutResult {
+    /** Whether the server-side revoke succeeded. */
+    revoked: boolean;
+    /**
+     * Why the revoke failed, when it did. Local state is cleared regardless, so
+     * this is informational — surface it if you want to tell the user the session
+     * may still be live elsewhere.
+     */
+    error?: Error;
+}
+/** A token pair as returned by `POST /v0/sessions/renew`. */
+export interface TokenPair {
+    access_token: string;
+    refresh_token: string;
+}
+/**
+ * The server's code when a renew loses the rotation race — another tab renewed
+ * with the same refresh token first.
+ *
+ * This is recoverable: the winner's token is valid, so adopt it instead of
+ * declaring the session dead.
+ */
+export declare const REFRESH_TOKEN_SUPERSEDED = "REFRESH_TOKEN_SUPERSEDED";
+export interface SessionManagerOptions {
+    /**
+     * Performs the network renewal. Injected rather than taking an `AuthClientV0`
+     * so this module stays a leaf and cannot form an import cycle with the
+     * identity client that consumes it.
+     */
+    renew: (refreshToken: string) => Promise<TokenPair>;
+    /**
+     * Revokes the session server-side. Wire to
+     * `(refreshToken) => authClient.revokeSession({ refresh_token: refreshToken })`.
+     *
+     * Injected for the same reason as {@link renew}: it keeps `src/auth/` a leaf.
+     *
+     * Supplying it is what makes {@link SessionManager.signOut} revoke rather than
+     * only clearing locally. Without it, `signOut()` still clears — a sign-out
+     * button must always sign the user out — but the refresh token stays valid
+     * server-side until it expires.
+     */
+    revoke?: (refreshToken: string) => Promise<unknown>;
+    /** Where the refresh token is persisted. @default localStorage, else memory */
+    storage?: MPFAuthStorage;
+    /** Storage key for the refresh token. @default 'mpf.refresh_token' */
+    storageKey?: string;
+    /**
+     * Seconds before expiry at which a token is considered stale.
+     *
+     * @default 120
+     *
+     * 120 rather than 60: at a 900s TTL, a request *starting* at `exp − 61s`
+     * passes a 60s freshness check and then carries a token that dies mid-flight,
+     * which storage uploads routinely will. The buffer must cover renew latency
+     * plus the longest in-flight request, and browser clock skew is unbounded.
+     *
+     * Clamped per token — see {@link SessionManager.effectiveBufferSeconds}.
+     */
+    bufferSeconds?: number;
+    /**
+     * Minimum gap between two network renewals. Second line of defence against a
+     * renew loop caused by a misconfigured server TTL.
+     * @default 5000
+     */
+    minRenewIntervalMs?: number;
+    /** Symmetric jitter on the proactive timer. @default 30000 */
+    jitterMs?: number;
+    /** Called when the session cannot be renewed and the user must log in again. */
+    onDeadSession?: (error: DeadSessionError) => void;
+    /** Called whenever the in-memory token pair changes. */
+    onTokensChanged?: (tokens: TokenPair | null) => void;
+    /**
+     * Cross-tab coordinator. Pass `null` to disable coordination entirely.
+     * @default createCrossTabCoordinator()
+     */
+    crossTab?: CrossTabCoordinator | null;
+    /** Injectable clock, in ms. @default Date.now */
+    now?: () => number;
+    /** Injectable randomness for jitter. @default Math.random */
+    random?: () => number;
+    /**
+     * Whether to attach `visibilitychange` / `online` listeners.
+     * @default true when `window` exists
+     */
+    listenToWake?: boolean;
+}
+/**
+ * Manages one session's tokens.
+ */
+export declare class SessionManager {
+    private readonly options;
+    private accessToken;
+    private refreshToken;
+    /** In-flight renewal, for coalescing. */
+    private inflight;
+    /**
+     * Gate that `getAccessToken()` awaits. Set by the wake path so that requests
+     * queued during a wake renewal block behind it instead of shipping a token
+     * that is already dead.
+     */
+    private wakeGate;
+    private timer;
+    private lastRenewAt;
+    private destroyed;
+    /**
+     * Incremented on every `clear()`. A renewal captures it before its network
+     * call and refuses to adopt a result from a superseded generation, so signing
+     * out (or clearing) mid-renew cannot be undone by the renewal completing.
+     */
+    private generation;
+    private readonly storage;
+    private readonly storageKey;
+    private readonly bufferSeconds;
+    private readonly minRenewIntervalMs;
+    private readonly jitterMs;
+    private readonly now;
+    private readonly random;
+    private readonly crossTab;
+    private readonly unsubscribeBroadcast;
+    private readonly wakeListening;
+    constructor(options: SessionManagerOptions);
+    /**
+     * Adopt a freshly minted token pair (after sign-in, or after any flow that
+     * changes memberships).
+     */
+    setTokens(tokens: TokenPair): void;
+    /**
+     * A usable access token, renewing first if necessary.
+     *
+     * Returns `null` only when there is no session at all.
+     */
+    getAccessToken(): Promise<string | null>;
+    /** The current access token without renewing. */
+    peekAccessToken(): string | null;
+    /** Decoded (UNVERIFIED — UX only) claims of the current access token. */
+    getClaims(): MPFClaims | null;
+    /**
+     * Renew the session. Coalesced: concurrent callers share one network call,
+     * which is mandatory because the refresh token is single-use.
+     */
+    renew(): Promise<string>;
+    /**
+     * Sign out: revoke the session server-side, then clear it locally.
+     *
+     * **Never throws, and always clears.** A user who clicked sign-out must end up
+     * signed out locally whatever the network did — a UI that refuses to log out
+     * is worse than a token that outlives its client, and the failed revoke leaves
+     * that token behind either way. The outcome is reported in the return value so
+     * an app can say "signed out, but we couldn't reach the server" rather than
+     * having to guess.
+     *
+     * Order is load-bearing: `revokeSession` is an *authenticated* endpoint, so
+     * the revoke must go out **before** the access token is cleared. Reversing it
+     * silently sends an unauthenticated request that cannot succeed.
+     *
+     * Idempotent: with no session, it is a no-op reporting `revoked: false`.
+     *
+     * This exists so consumers never need the raw refresh token. Reaching into
+     * storage for it — `localStorage.getItem('mpf.refresh_token')` — hardcodes the
+     * default key and breaks for anyone using a custom storage or key.
+     */
+    signOut(): Promise<SignOutResult>;
+    /**
+     * Forget the session locally. Stops timers and invalidates any in-flight
+     * renewal so it cannot resurrect the session after it resolves.
+     *
+     * Prefer {@link signOut} for a user-initiated sign-out: this leaves the
+     * refresh token valid server-side.
+     */
+    clear(): void;
+    /** Detach listeners and release the coordinator. */
+    destroy(): void;
+    /**
+     * The buffer actually in force for the current token.
+     *
+     * The configured buffer is clamped 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, hammering
+     * `/sessions/renew` forever. A 60s-TTL token therefore gets a 29s buffer, not
+     * the configured 120s.
+     *
+     * Falls back to the configured value when the token carries no `iat` and the
+     * lifetime is unknowable.
+     */
+    effectiveBufferSeconds(): number;
+    private isStale;
+    private adopt;
+    private renewGuarded;
+    private networkRenew;
+    /**
+     * After a REFRESH_TOKEN_SUPERSEDED, take the winner's tokens.
+     *
+     * The winner's access token arrives over the broadcast channel; its refresh
+     * token is in storage. If neither is usable there is nothing to adopt and the
+     * caller declares the session dead.
+     */
+    private adoptAfterSuperseded;
+    private die;
+    private cancelTimer;
+    /**
+     * Schedule a renewal shortly before the token goes stale.
+     *
+     * Jittered so that N tabs computing the same deadline from the same token do
+     * not all wake on the same millisecond.
+     */
+    private scheduleProactiveRenew;
+    private readonly onWakeEvent;
+    /**
+     * Wake path — the real safety net.
+     *
+     * `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.
+     *
+     * Merely rescheduling here is wrong: the delay computes negative, becomes
+     * `setTimeout(0)`, and then races whatever the app fires on focus. Instead
+     * renew immediately and publish a gate that `getAccessToken()` awaits, so
+     * requests triggered by the same focus event queue behind the renewal rather
+     * than each eating a 401.
+     */
+    private handleWake;
+}
+/**
+ * Whether an error is the server's "another tab renewed first" signal.
+ *
+ * Checks `serverCode` because `MPFAuthError.code` is derived from the error
+ * classification and collapses every 401 to `UNAUTHORIZED`.
+ */
+export declare function isSupersededError(error: unknown): boolean;
+/**
+ * Create a session manager.
+ */
+export declare function createSessionManager(options: SessionManagerOptions): SessionManager;

package/dist/auth/storage.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pluggable persistence for the session manager.
+ *
+ * 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 sitting in `localStorage`.
+ */
+/**
+ * Minimal synchronous key/value store.
+ *
+ * Matches the `localStorage` shape so the browser default is a pass-through.
+ */
+export interface MPFAuthStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * An in-memory store. Used automatically when `window` is absent (Node, SSR,
+ * the e2e suite) and available explicitly for tests.
+ */
+export declare function createMemoryStorage(): MPFAuthStorage;
+/**
+ * `sessionStorage` when it is usable, an in-memory store otherwise.
+ *
+ * Per-tab and cleared when the tab closes, which is what a redirect flow wants:
+ * see `createOAuthStateStore`.
+ */
+export declare function createSessionStorage(): MPFAuthStorage;
+/**
+ * `localStorage` when it is usable, an in-memory store otherwise.
+ *
+ * Access is probed rather than assumed: Safari in private mode and blocked
+ * third-party contexts expose `localStorage` but throw on write.
+ */
+export declare function createDefaultStorage(): MPFAuthStorage;

package/dist/auth/tenant-directory.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Tenant display metadata — names and slugs.
+ *
+ * ## Why this is separate from the claim set
+ *
+ * The access token's `tnts` array carries tenant **ids and roles only**. That is
+ * the authoritative, freshest answer to "which tenants may this user select",
+ * and it needs no network call — but it renders a switcher full of UUIDs.
+ *
+ * Names live in the database (`identity.tenants`), so fetching them is a real
+ * network operation that can really fail. Keeping it in its own module, behind
+ * its own state, means the two questions stay distinguishable:
+ *
+ * - "which tenants can I select?" — claims, synchronous, cannot fail
+ * - "what are they called?" — network, asynchronous, can fail
+ *
+ * Merging them would make a failed name lookup indistinguishable from having no
+ * tenants, which is the exact bug class the tri-state exists to prevent.
+ *
+ * ## Reachability
+ *
+ * The `tenantless` Hasura role has select permissions on `identity_tenants`
+ * scoped to `X-Hasura-User-Id`, so a signed-in user with NO tenant selected can
+ * read the names of the tenants they belong to. That is precisely the switcher's
+ * situation.
+ */
+/** Display metadata for one tenant. */
+export interface TenantDirectoryEntry {
+    id: string;
+    name?: string;
+    slug?: string;
+}
+/**
+ * Loads display metadata for the given tenant ids.
+ *
+ * Injected rather than implemented here so that neither this module nor the
+ * React layer has to depend on the GraphQL client — which keeps `src/auth/` a
+ * leaf and the React layer free of `src/client/graphql/`. Use
+ * {@link TENANT_DIRECTORY_QUERY} with whichever GraphQL client the app already
+ * has.
+ */
+export type TenantDirectoryLoader = (tenantIds: string[]) => Promise<TenantDirectoryEntry[]>;
+/**
+ * A ready-made query for the loader.
+ *
+ * Runs under the `tenantless` role — i.e. with no `X-MPF-Tenant` header — which
+ * is why a switcher can populate itself before any tenant is selected.
+ *
+ * @example
+ * ```ts
+ * import { TENANT_DIRECTORY_QUERY } from '@mosano-product-framework/sdk/auth';
+ *
+ * const loadTenantDirectory = async () => {
+ *   const data = await gql.query(TENANT_DIRECTORY_QUERY, undefined, { tenant: null });
+ *   return data.identity_tenants;
+ * };
+ * ```
+ */
+export declare const TENANT_DIRECTORY_QUERY = "query MPFTenantDirectory {\n  identity_tenants {\n    id\n    name\n    slug\n  }\n}";

package/dist/auth/tenant-selection.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Tenant selection — a dependency-free mutable leaf.
+ *
+ * Deliberately imports nothing but its own types, so it can be constructed
+ * BEFORE any client and then shared by the identity, storage and GraphQL
+ * clients without an import cycle:
+ *
+ * ```ts
+ * const tenants = createTenantSelection();
+ * const auth = createAuthClient({ baseUrl, tokenProvider, tenantProvider: tenants });
+ * const storage = createStorageClient({ baseUrl, tokenProvider, tenantProvider: tenants });
+ * tenants.set(tenantId);   // both clients now scope to it, no reconstruction
+ * ```
+ */
+import type { MPFRole } from './claims-types.js';
+import type { MPFAuthStorage } from './storage.js';
+/**
+ * The currently selected tenant.
+ */
+export interface TenantSelection {
+    /** Selected tenant id, or `null` for the no-tenant (`drl`) path. */
+    tenant: string | null;
+    /**
+     * Selected role. `undefined` lets the server apply that tenant's default
+     * role (`tnts[].dfr`, else `tnts[].rls[0]`).
+     */
+    role?: MPFRole;
+}
+/**
+ * A mutable, observable tenant selection.
+ */
+export interface TenantSelectionStore {
+    /** Current selection. */
+    get(): TenantSelection;
+    /**
+     * Select a tenant.
+     *
+     * Synchronous by design — selecting a tenant is a header change, so there is
+     * no renew, no await and no network call.
+     *
+     * @param tenant - Tenant id, or `null` for the no-tenant path.
+     * @param role - Optional role; omit to let the server apply the default.
+     */
+    set(tenant: string | null, role?: MPFRole): void;
+    /** Reset to the no-tenant path. */
+    clear(): void;
+    /**
+     * Observe changes. Returns an unsubscribe function.
+     *
+     * The listener is called only when the selection actually changes.
+     */
+    subscribe(listener: (selection: TenantSelection) => void): () => void;
+}
+/**
+ * Persistence options for the tenant selection.
+ *
+ * The selected tenant IS persisted (unlike the access token). A tenant uuid the
+ * user demonstrably has access to is not credential material, and losing the
+ * selection on reload is a real UX regression: pick a tenant, refresh, land back
+ * in the no-tenant state. Reading it synchronously at construction is also what
+ * makes the provider's anti-flash hydration possible.
+ *
+ * Note this is a UX convenience only. A tampered value grants nothing — the
+ * server re-derives tenant and role from the verified token on every request and
+ * rejects a tenant the token does not hold.
+ */
+export interface TenantSelectionPersistence {
+    /** Where to store it. Omit to disable persistence. */
+    storage?: MPFAuthStorage;
+    /** Storage key. @default 'mpf.tenant_selection' */
+    storageKey?: string;
+}
+export interface CreateTenantSelectionOptions extends TenantSelectionPersistence {
+    /**
+     * Initial selection. Takes precedence over a persisted value, so an app can
+     * force a tenant (e.g. from a URL) without the stored one overriding it.
+     */
+    initial?: TenantSelection;
+}
+/**
+ * Create a tenant selection store.
+ *
+ * Accepts either a bare initial selection (back-compatible) or an options
+ * object enabling persistence.
+ *
+ * @example
+ * ```ts
+ * const tenants = createTenantSelection({ storage: createDefaultStorage() });
+ * // survives a page reload
+ * ```
+ */
+export declare function createTenantSelection(initialOrOptions?: TenantSelection | CreateTenantSelectionOptions): TenantSelectionStore;