@mosano-product-framework/sdk 0.2.0

package/README.react.md

@@ -0,0 +1,348 @@
+# @mosano-product-framework/sdk/react
+
+React bindings for the MPF SDK: a provider, six hooks, and nothing else.
+
+**Dependency-free apart from React.** No TanStack Query, no zustand, no router.
+State lives in a small external store read through `useSyncExternalStore`, so
+there are no constraints on how you manage the rest of your data — SWR, Apollo,
+TanStack Query and plain `fetch` consumers are equally supported.
+
+For the SDK core — tenant selection, claims, session management — see
+[README.md](./README.md).
+
+## Installation
+
+React is an **optional peer dependency**. Installing the SDK does not install
+React, and importing the root barrel never pulls React in.
+
+```bash
+pnpm add @mosano-product-framework/sdk react
+```
+
+Requires **React 18+** (`useSyncExternalStore` is 18+).
+
+## Setup
+
+```tsx
+import { MPFAuthProvider } from '@mosano-product-framework/sdk/react';
+import { createAuthClient } from '@mosano-product-framework/sdk/identity';
+import { createDefaultStorage } from '@mosano-product-framework/sdk/auth';
+
+const auth = createAuthClient({ baseUrl: 'https://api.example.com/auth' });
+
+export function App() {
+  return (
+    <MPFAuthProvider
+      renew={(refreshToken) => auth.renewSession({ refresh_token: refreshToken })}
+      storage={createDefaultStorage()}
+      onDeadSession={() => navigate('/login')}
+    >
+      <Routes />
+    </MPFAuthProvider>
+  );
+}
+```
+
+### `<MPFAuthProvider>` props
+
+| Prop | Required | Description |
+|---|---|---|
+| `renew` | ✅ | `(refreshToken) => Promise<{ access_token, refresh_token }>`. Wire to `auth.renewSession`. |
+| `storage` | | Where the refresh token and tenant selection are persisted. Defaults to `localStorage`, falling back to memory. |
+| `onDeadSession` | | Called when the session cannot be renewed. Defaults to a one-time `console.warn`. |
+| `tenantProvider` | | A pre-built `createTenantSelection()` store, so non-React code can share the same selection. |
+| `loadTenantDirectory` | | Fetches tenant display names. See [`useTenantDirectory()`](#usetenantdirectory). |
+| `autoLoadTenantDirectory` | | Fetch names automatically once signed in. Default `true` when a loader is supplied. |
+| `sessionOptions` | | Forwarded to the session manager (`bufferSeconds`, `jitterMs`, `crossTab`, ...). |
+| `session` | | A pre-built `SessionManager`. Mainly a test seam. |
+
+### Hydration
+
+The provider hydrates **synchronously**, during its first render. Anything
+already in storage — the refresh token, the selected tenant — is present on the
+very first paint, so a reload does not flash a login form and does not reset the
+user's tenant to "none". There is no `loading` state to handle for hydration;
+`useAuth().hydrated` is always `true` by the time your component runs.
+
+## Hooks
+
+### `useAuth()`
+
+Core state and actions.
+
+```tsx
+function Header() {
+  const { authenticated, claims, signOut } = useAuth();
+
+  if (!authenticated) return <SignInLink />;
+  return <button onClick={signOut}>Sign out {claims?.uid}</button>;
+}
+```
+
+| Field | Description |
+|---|---|
+| `hydrated` | Always `true` after the first render. |
+| `authenticated` | Whether an access token is present. |
+| `claims` | Decoded (**unverified**) claims, or `null`. |
+| `getAccessToken()` | `Promise<string \| null>`, renewing first if the token is stale. |
+| `setTokens(pair)` | Adopt a fresh token pair after sign-in. |
+| `signOut()` | Drop the session locally. **Does not navigate.** |
+
+Sign-in looks like this — the SDK does not own your form or your routing:
+
+```tsx
+const { setTokens } = useAuth();
+
+async function onSubmit(email: string, password: string) {
+  const result = await auth.signInEmailPassword({ email, password });
+  setTokens(result);          // provider state updates synchronously
+  navigate('/dashboard');     // your router, your call
+}
+```
+
+### `useTenants()`
+
+The tenants the current token grants access to. **Synchronous, and cannot fail** —
+the answer is already in the access token, which is fresher than anything a round
+trip could tell you.
+
+```tsx
+function TenantSwitcher() {
+  const { status, tenants } = useTenants();
+  const current = useCurrentTenant();
+  const select = useSelectTenant();
+
+  if (status === 'unloaded') return null;   // not signed in
+
+  return (
+    <select value={current.tenant ?? ''} onChange={(e) => select(e.target.value || null)}>
+      <option value="">All (no tenant)</option>
+      {tenants.map((t) => (
+        <option key={t.id} value={t.id}>{t.name ?? t.id}</option>
+      ))}
+    </select>
+  );
+}
+```
+
+`status` is only `'unloaded' | 'loaded'`, because there is no fetch here and
+therefore nothing to fail. Each entry has `id`, `roles`, `defaultRole` (the
+token's explicit `dfr` for that tenant when it carries one, else `roles[0]`),
+and — once the directory has loaded — `name` and `slug`.
+
+### `useTenantDirectory()`
+
+Tenant **display names**, which do require a network call and can genuinely fail.
+
+`tnts` in the token carries ids and roles only, so without this a switcher shows
+UUIDs. Opt in by giving the provider a loader:
+
+```tsx
+// Simplest: REST. `listMyTenants()` returns id, name and slug.
+<MPFAuthProvider
+  renew={renew}
+  loadTenantDirectory={() => auth.listMyTenants()}
+>
+```
+
+```tsx
+// Or GraphQL, if your app already has a client. Query with `{ tenant: null }` —
+// the tenantless role has exactly the permission a switcher needs.
+import { TENANT_DIRECTORY_QUERY } from '@mosano-product-framework/sdk/auth';
+
+<MPFAuthProvider
+  renew={renew}
+  loadTenantDirectory={async () => {
+    const data = await gql.query(TENANT_DIRECTORY_QUERY, undefined, { tenant: null });
+    return data.identity_tenants;
+  }}
+>
+```
+
+The loader is injected rather than built in, so the React layer never depends on
+the GraphQL client and either transport works unchanged.
+
+```tsx
+const { status, directory, error, available, load } = useTenantDirectory();
+```
+
+| `status` | Meaning |
+|---|---|
+| `'unloaded'` | No loader supplied, or not fetched yet. |
+| `'loading'` | In flight. |
+| `'loaded'` | Names fetched. **May legitimately be empty** — that means "this user has no tenants". |
+| `'failed'` | The fetch failed. `error` says why. |
+
+`'loaded'`-but-empty and `'failed'` are deliberately distinct. Collapsing them is
+how an empty switcher comes to silently mean "the server was unreachable".
+
+**A failed name lookup never empties the switcher.** The ids come from the token,
+so they remain listed and selectable; only the names are missing. Render
+`name ?? id`:
+
+```tsx
+function TenantSwitcher() {
+  const { tenants } = useTenants();
+  const { status, error } = useTenantDirectory();
+
+  return (
+    <>
+      {status === 'failed' && <Warning>Couldn't load names: {error?.message}</Warning>}
+      {tenants.map((t) => <Option key={t.id} label={t.name ?? t.id} />)}
+    </>
+  );
+}
+```
+
+Names are dropped on `signOut()`. Entries for tenants the token does not grant
+are ignored, so a name lookup can never make an unauthorised tenant selectable.
+
+### `useCurrentTenant()`
+
+The current selection: `{ tenant: string | null, role?: string }`. `tenant` is
+`null` on the no-tenant path.
+
+### `useSelectTenant()`
+
+```tsx
+const select = useSelectTenant();
+
+select('tenant-uuid');            // select a tenant, default role
+select('tenant-uuid', 'admin');   // select a specific role
+select(null);                     // no tenant
+```
+
+**Synchronous. No `await`, no network, no renewal.** Tenant is a request header,
+so switching is a local state change and the next request simply carries a
+different header — the access token is byte-identical before and after. A test
+asserts it fires zero fetches and zero renewals.
+
+The selection is persisted, so it survives a reload.
+
+### `useClaims()`
+
+Decoded claims of the current access token, or `null`.
+
+> ### ⚠️ Decode, not verify
+>
+> These claims are **decoded, never verified**. There is no signature check and
+> no key material in this package. A hostile client can forge any value here: any
+> user id, any tenant, any role, any expiry.
+>
+> Use them for UI only — rendering a switcher, greying out an option, deciding
+> when to renew. **Never gate a security-relevant branch on them.** The server
+> verifies the signature and re-derives tenant and role on every request, and a
+> forged claim buys an attacker nothing there.
+
+```tsx
+const claims = useClaims();
+const isOwnerSomewhere = (claims?.tnts ?? []).some((t) => t.rls.includes('owner'));
+// ^ fine for showing a menu item. NOT fine as an authorization decision.
+```
+
+### `useMPFAuthOptional()`
+
+Returns the context or `null` instead of throwing, for components rendered both
+inside and outside an authenticated shell.
+
+```tsx
+function Header() {
+  const ctx = useMPFAuthOptional();
+  if (!ctx) return <MarketingHeader />;
+  return <AppHeader />;
+}
+```
+
+Every other hook throws a descriptive error when no provider is mounted.
+
+## Storage adapters
+
+```tsx
+import { createDefaultStorage, createMemoryStorage } from '@mosano-product-framework/sdk/auth';
+```
+
+- `createDefaultStorage()` — `localStorage`, probed for writability and falling
+  back to memory (Safari private mode and blocked third-party contexts expose
+  `localStorage` but throw on write).
+- `createMemoryStorage()` — in-memory; the automatic choice when `window` is
+  absent, and useful in tests.
+- Anything with `getItem` / `setItem` / `removeItem` works, so `sessionStorage`
+  or an encrypted wrapper drops straight in.
+
+Only the **refresh token** and the **tenant selection** are persisted. The access
+token stays in memory.
+
+## `onDeadSession` is a callback, never a navigation
+
+The SDK never navigates. Routing is your application's concern, and hard-coding
+`window.location` or a `useNavigate()` call would couple the library to one
+router and one URL scheme.
+
+```tsx
+<MPFAuthProvider
+  renew={renew}
+  onDeadSession={(error) => {
+    queryClient.clear();
+    navigate('/login', { state: { reason: error.message } });
+  }}
+>
+```
+
+The default is a one-time `console.warn` telling you to supply one.
+
+## Using with TanStack Query
+
+The bindings hold auth state; your query library holds server state. Wire them
+with `getAccessToken`, and key queries on the tenant so a switch refetches.
+
+```tsx
+import { useQuery, useQueryClient } from '@tanstack/react-query';
+import { useAuth, useCurrentTenant, useSelectTenant } from '@mosano-product-framework/sdk/react';
+
+function useMembers() {
+  const { getAccessToken } = useAuth();
+  const { tenant } = useCurrentTenant();
+
+  return useQuery({
+    // Tenant in the key: switching tenants refetches instead of showing stale rows.
+    queryKey: ['members', tenant],
+    queryFn: async () => {
+      await getAccessToken();       // renews if stale, before the request goes out
+      return auth.listTenantMembers(tenant!);
+    },
+    enabled: Boolean(tenant),
+  });
+}
+
+// Switching stays synchronous; the query layer reacts to the key change.
+function Switcher() {
+  const select = useSelectTenant();
+  return <button onClick={() => select('other-tenant')}>Switch</button>;
+}
+```
+
+On sign-out, clear the cache so one user's data cannot be shown to the next:
+
+```tsx
+const queryClient = useQueryClient();
+const { signOut } = useAuth();
+
+const logout = () => {
+  signOut();
+  queryClient.clear();
+};
+```
+
+The same shape works with SWR (`useSWR(['members', tenant], ...)`) or Apollo
+(refetch on the tenant change).
+
+## Out of scope
+
+GraphQL subscriptions and websockets are not supported — see the
+[Out of scope](./README.md#out-of-scope) section of the main README for why the
+tenant model makes long-lived sockets a separate design problem rather than a
+missing feature.
+
+## License
+
+MIT

package/dist/auth/claims-types.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Types for MPF access-token claims.
+ *
+ * These describe what the server puts in a token. They are NOT a security
+ * boundary — see the block comment at the top of `claims.ts`.
+ */
+/**
+ * A role name.
+ *
+ * Deliberately `string` and NOT a closed union. Roles are database rows
+ * (`identity.tenant_membership_valid_roles`, seeded `owner | admin | member |
+ * guest`), so a newly seeded role must not require an SDK release — and closing
+ * this union is exactly how the stale `'viewer'` role leaked into the types.
+ *
+ * Closed unions are appropriate on *request* types (where autocomplete earns
+ * its keep), never on decoded server output.
+ */
+export type MPFRole = string;
+/**
+ * One entry of the `tnts` array: a tenant the user belongs to.
+ */
+export interface MPFTenantClaim {
+    /** Tenant id (uuid). */
+    id: string;
+    /** Every role held in this tenant. Non-empty. */
+    rls: MPFRole[];
+    /**
+     * This tenant's explicit default role — the role the server applies when a
+     * request selects this tenant without naming one.
+     *
+     * OPTIONAL: omitted entirely when the tenant has no explicit default, in
+     * which case selection falls back to `rls[0]`. The server refuses to mint a
+     * `dfr` that is not a member of that same tenant's `rls`, so a default that
+     * is invalid in its own tenant is unrepresentable.
+     */
+    dfr?: MPFRole;
+}
+/**
+ * Version 1 of the MPF access-token claim set.
+ */
+export interface MPFClaimsV1 {
+    /** Claim-set version. Dispatches parsing. */
+    v: 1;
+    /** User id (uuid). */
+    uid: string;
+    /** Session id (uuid). */
+    sid: string;
+    /** Expiry, seconds since the epoch. */
+    exp: number;
+    /**
+     * Issued-at, seconds since the epoch.
+     *
+     * Optional in this type on purpose: it is only needed to compute token
+     * lifetime for the renewal-buffer clamp. A server that stops emitting it
+     * should degrade that clamp, not lock every client out of decoding.
+     */
+    iat?: number;
+    /**
+     * Every tenant the user belongs to, with the roles held in each.
+     *
+     * An ARRAY, always present — `[]` for a user with no tenants (which is every
+     * brand-new signup). Each entry may carry an explicit `dfr`; when it does not,
+     * that tenant's default role is `rls[0]`.
+     */
+    tnts: MPFTenantClaim[];
+    /**
+     * The role applied when no tenant is selected.
+     *
+     * Optional: a deployment may have no tenantless role configured, in which case
+     * the server emits an empty string. Nothing the client does with this value is
+     * load-bearing — the server decides the effective role on every request — so
+     * an empty one degrades to `undefined` rather than failing the whole decode.
+     */
+    drl?: MPFRole;
+}
+/**
+ * Any supported MPF claim set.
+ *
+ * A discriminated union on `v`. Adding v2 means adding a member here and one
+ * entry to the parser registry in `claims.ts`.
+ */
+export type MPFClaims = MPFClaimsV1;
+/**
+ * A parser turning an unverified JWT payload into typed claims.
+ *
+ * Must throw `MPFClaimsError` when the payload does not match its version's
+ * shape, and must tolerate unknown extra keys.
+ */
+export type ClaimsParser = (payload: Record<string, unknown>) => MPFClaims;

package/dist/auth/claims.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ============================================================================
+ * SECURITY BOUNDARY — READ BEFORE USING ANYTHING IN THIS FILE
+ * ============================================================================
+ *
+ * This module DECODES access tokens. It does NOT VERIFY them.
+ *
+ * There is no signature check here. There is no key material here. We call
+ * `jose.decodeJwt`, which base64-decodes the payload and nothing else — 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 this module returns: any user
+ * id, any session id, any tenant, any role, any expiry.
+ *
+ * Every consumer of this module must be UX-only:
+ *   - rendering a tenant switcher,
+ *   - failing an obviously-invalid selection locally instead of round-tripping
+ *     for a 403,
+ *   - deciding when to proactively renew.
+ *
+ * NEVER gate a security-relevant branch on these values. The server is the only
+ * authority: `hasura-authd` and `internal/go-chi-middleware-auth` verify the
+ * signature and re-derive tenant and role from the token on every single
+ * request, and a forged claim buys the attacker exactly nothing there.
+ *
+ * `jwtVerify` must never appear in this package. Verification needs the signing
+ * secret, and the signing secret must never reach a browser.
+ * ============================================================================
+ */
+import type { ClaimsParser, MPFClaims, MPFRole } from './claims-types.js';
+/**
+ * Drop every cached decode.
+ *
+ * Call on logout so a decoded token cannot outlive the session in memory.
+ */
+export declare function clearClaimsCache(): void;
+/**
+ * Register a parser for a claim-set version.
+ *
+ * Exported so a consumer pinned to an older SDK can teach it a newer shape
+ * without waiting for a release.
+ *
+ * @throws {MPFClaimsError} If the version already has a parser — a silent
+ * overwrite would make decoding depend on module import order.
+ */
+export declare function registerClaimsParser(version: number, parser: ClaimsParser): void;
+/**
+ * The claim-set versions this build understands.
+ */
+export declare function supportedClaimsVersions(): number[];
+/**
+ * Decode an access token's claims.
+ *
+ * **Decodes, does not verify** — see the security block at the top of this file.
+ *
+ * Succeeds on an EXPIRED token by design: the session manager needs `exp` in
+ * order to decide that a renewal is due, so expiry is the caller's question,
+ * not this function's. Use {@link isExpired} to ask it.
+ *
+ * @param token - Raw JWT string.
+ * @returns The typed claims.
+ * @throws {MPFUnsupportedClaimsVersionError} If `v` is absent or unknown.
+ * @throws {MPFClaimsError} If the token is malformed or a claim has the wrong type.
+ */
+export declare function decodeAccessToken(token: string): MPFClaims;
+/**
+ * Decode an access token, returning `null` instead of throwing.
+ *
+ * For UI paths that must render something regardless of token health.
+ *
+ * **Decodes, does not verify** — see the security block at the top of this file.
+ */
+export declare function tryDecodeAccessToken(token: string | null | undefined): MPFClaims | null;
+/**
+ * Tenant ids present in the token, in `tnts` order.
+ */
+export declare function listTenants(claims: MPFClaims): string[];
+/**
+ * Roles held in a tenant.
+ *
+ * Returns a fresh array; mutating it cannot corrupt the cached claims.
+ */
+export declare function rolesForTenant(claims: MPFClaims, tenantId: string): MPFRole[];
+/**
+ * The default role for a tenant: its explicit `dfr` when the entry carries one,
+ * otherwise `rls[0]`.
+ *
+ * `undefined` when the tenant is not in the token, or holds no roles.
+ */
+export declare function defaultRoleForTenant(claims: MPFClaims, tenantId: string): MPFRole | undefined;
+/**
+ * Whether a tenant (and optionally a role) *appears* selectable in this token.
+ *
+ * ⚠️ **NOT A PERMISSION CHECK.** This reads unverified, client-forgeable claims.
+ * It exists so a switcher can grey out an entry and so an obviously-invalid
+ * selection fails locally instead of costing a round trip for a 403. A `true`
+ * here grants nothing: the server re-derives tenant and role from the verified
+ * token on every request and will reject a selection this function approved.
+ * Never branch on it for anything that must hold.
+ *
+ * @param claims - Decoded (unverified) claims.
+ * @param tenantId - Tenant to select, or `null` for the no-tenant path.
+ * @param role - Optional specific role; omitted means "the tenant's default".
+ */
+export declare function canSelect(claims: MPFClaims, tenantId: string | null, role?: MPFRole): boolean;
+/**
+ * The token's expiry as a `Date`.
+ */
+export declare function expiresAt(claims: MPFClaims): Date;
+/**
+ * Whether the token is expired, optionally treating it as expired
+ * `skewSeconds` early.
+ *
+ * @param claims - Decoded claims.
+ * @param skewSeconds - Seconds of headroom. `120` answers "will this token die
+ * within the next two minutes?", which is the question a renewal buffer asks.
+ * @param nowMs - Injectable clock for tests. Defaults to `Date.now()`.
+ */
+export declare function isExpired(claims: MPFClaims, skewSeconds?: number, nowMs?: number): boolean;
+/**
+ * Token lifetime in seconds (`exp - iat`), or `undefined` when the token
+ * carries no `iat`.
+ */
+export declare function tokenLifetimeSeconds(claims: MPFClaims): number | undefined;

package/dist/auth/cross-tab.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Cross-tab refresh coordination.
+ *
+ * ## The problem, precisely
+ *
+ * Multiple tabs of ONE browser share one login and read the same refresh token
+ * from origin-scoped `localStorage`. The refresh token is single-use and
+ * rotates, so if two tabs renew concurrently one of them loses and its token is
+ * dead. Separate browsers, machines or devices get separate session rows and
+ * separate refresh tokens, so they are not a concern here.
+ *
+ * With proactive refresh every tab's timer fires at roughly the same moment, so
+ * this is contended by N tabs at once, not two.
+ *
+ * ## Mechanism
+ *
+ * `navigator.locks` (Web Locks) is a standardized cross-tab mutex and needs no
+ * dependency on the primary path. Locks auto-release when a tab is destroyed,
+ * so a closed tab cannot deadlock the others. A polyfill is loaded only where
+ * the API is missing (pre-15.4 Safari, non-secure contexts).
+ *
+ * A lock ALONE is insufficient: N tabs would queue and then each renew in turn,
+ * which is the exact problem the lock was supposed to solve. The session manager
+ * therefore does double-checked locking — re-reading shared state INSIDE the
+ * lock and adopting instead of renewing when another tab got there first.
+ *
+ * ## Fanout: BroadcastChannel, not localStorage
+ *
+ * The winner's fresh ACCESS token is broadcast in memory over a
+ * `BroadcastChannel` rather than persisted, so losing tabs can adopt it without
+ * a network call while the access token still never touches `localStorage`.
+ * Where `BroadcastChannel` is unavailable, losers fall back to renewing with the
+ * rotated refresh token — correct, just less efficient.
+ *
+ * Everything here no-ops when `window` is absent, so Node and the e2e suite are
+ * unaffected.
+ */
+/** A token pair shared between tabs. */
+export interface TokenBroadcast {
+    accessToken: string;
+    refreshToken: string;
+}
+/** The subset of `LockManager` this module uses. */
+export interface LockManagerLike {
+    request(name: string, options: {
+        signal?: AbortSignal;
+    }, callback: () => Promise<unknown>): Promise<unknown>;
+}
+/** The subset of `BroadcastChannel` this module uses. */
+export interface BroadcastChannelLike {
+    postMessage(message: unknown): void;
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    close(): void;
+}
+/** How the coordinator is providing mutual exclusion. */
+export type CrossTabMode = 'native' | 'polyfill' | 'none';
+export interface CrossTabCoordinator {
+    /** How mutual exclusion is being provided. */
+    readonly mode: CrossTabMode;
+    /** Run `fn` holding the cross-tab refresh lock. */
+    withLock<T>(fn: () => Promise<T>): Promise<T>;
+    /** Tell other tabs about a fresh token pair. */
+    publish(message: TokenBroadcast): void;
+    /** Observe other tabs' fresh token pairs. Returns an unsubscribe function. */
+    subscribe(listener: (message: TokenBroadcast) => void): () => void;
+    /** Release resources. */
+    close(): void;
+}
+export interface CrossTabOptions {
+    /** Lock name. @default 'mpf.refresh' */
+    lockName?: string;
+    /** BroadcastChannel name. @default 'mpf.auth' */
+    channelName?: string;
+    /**
+     * How long to wait for the lock before giving up and proceeding without it.
+     * @default 5000
+     */
+    lockTimeoutMs?: number;
+    /** Injectable lock manager. Defaults to `navigator.locks`. For tests. */
+    locks?: LockManagerLike | null;
+    /**
+     * Loads a Web Locks polyfill when the native API is absent. Resolve `null` to
+     * decline. The default declines — no polyfill is bundled, keeping the primary
+     * path dependency-free; a consumer targeting old Safari supplies one here.
+     */
+    loadPolyfill?: () => Promise<LockManagerLike | null>;
+    /** Injectable channel factory. Defaults to `BroadcastChannel`. For tests. */
+    channelFactory?: (name: string) => BroadcastChannelLike | null;
+}
+/**
+ * Apply symmetric jitter to a delay.
+ *
+ * Without this, N tabs computed the same proactive-renew deadline from the same
+ * token and all wake on the same millisecond, then serialize through the lock
+ * for no reason. Result is clamped at 0.
+ *
+ * @param baseMs - The unjittered delay.
+ * @param jitterMs - Maximum deviation in either direction.
+ * @param random - Injectable `Math.random` for tests.
+ */
+export declare function applyJitter(baseMs: number, jitterMs: number, random?: () => number): number;
+/**
+ * Create a cross-tab coordinator.
+ *
+ * Resolution order for the lock: injected `locks` → `navigator.locks` →
+ * `loadPolyfill()` → none (run without coordination, correct in a
+ * single-context environment like Node).
+ */
+export declare function createCrossTabCoordinator(options?: CrossTabOptions): CrossTabCoordinator;