portal-mojo 0.2.14 → 0.2.15

package/docs/auth.md

@@ -25,8 +25,8 @@ onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issu
 
 ## Session mechanics
 
-- JWT pair (`access_token`/`refresh_token`); single-flight refresh (3
-  concurrent 401s → ONE refresh POST); pre-request gate throws a synthetic
+- JWT pair (`access_token`/`refresh_token`); single-flight refresh (concurrent
+  gated HTTP requests and realtime reconnects → ONE refresh POST); pre-request gate throws a synthetic
   `AuthRequiredError` instead of firing doomed requests.
 - A temporary refresh failure (network, timeout or server unavailable) blocks
   the protected request and rejects with the original transport error. It
@@ -34,7 +34,15 @@ onAuth('rotated', () => queryClient.invalidateQueries());  // same user, re-issu
   open. Only expired/unusable credentials or confirmed refresh 401/403 emit
   `unauthorized` and become `AuthRequiredError`. `refreshTokens()` still
   resolves a boolean, and concurrent gated calls share one refresh POST.
+- Refresh POSTs have a 15-second deadline. A timed-out attempt releases the
+  shared flight so a later request or reconnect can try again. RealtimeProvider
+  uses this same gate before connecting and before sending authentication;
+  applications do not need a second refresh timer for WebSockets.
 - `useAuthSnapshot()` → `{authenticated, uid, email}` — live, cross-tab.
+- An internal session revision distinguishes same-tab renewal from explicit
+  replacement/clearing and cross-tab storage changes. Session-bound realtime
+  retains this fence across unmount/remount, so a late renewal cannot undo a
+  terminal server denial. It is an in-memory lifecycle fence, not authorization.
 - `logout()` is client-side (django-mojo has no logout endpoint) and emits
   `'logout'`.
 - Every flow that answers with a login grant adopts it only when it carries

package/docs/realtime.md

@@ -9,6 +9,23 @@ consumer permissions own topic subscriptions. Disabling the provider or losing
 the auth token closes the socket. A permission loss in one consumer must not
 disable this shared provider.
 
+The provider binds both owned and injected clients to the shared auth session.
+Before opening a socket and again when challenged, it waits for `ensureValidToken()`;
+HTTP and realtime share one refresh POST. A slow or temporarily failed renewal
+keeps the connection in `connecting`/`authenticating`/`backoff`, not `auth-failed`.
+Consumers should preserve their current workspace during these transient states.
+Confirmed refresh denial still fails closed. Token replacement invalidates old
+handshakes synchronously, including during a pending refresh.
+An in-flight renewal completing after an authentication failure or forced
+disconnect cannot clear that suspension. An intentional replacement session
+can authenticate again; ordinary token refresh cannot.
+
+For a non-React session consumer, call `const unbind = client.bindAuthSession()`
+before `client.setEnabled(true)`, and call `unbind()` on teardown. One binding
+owns the client at a time; unbinding closes the connection without aborting a
+renewal shared by HTTP. Standalone `connect(token)` clients keep explicit-token
+behavior and are responsible for their token lifecycle.
+
 ## Wire contract
 
 - URL is derived from the configured API origin as exactly `/ws/realtime/`
@@ -55,7 +72,10 @@ A top-level `{type:'error'}` frame is attributed in order:
 
 1. **During authentication** — auth failure: the client closes and suspends
    until the token value changes. Surfaces through the lifecycle status only;
-   no `error` event is dispatched.
+   no `error` event is dispatched. Exception: the exact direct
+   `message === 'Authentication timeout'` before credentials were sent on a
+   session-bound socket is a transport timeout and enters bounded retry.
+   The same error after credentials were sent remains an authentication failure.
 2. **While a subscribe/unsubscribe is pending** — that operation's denial
    (acknowledgements are uncorrelated, so denial is a generic `error`); the
    topic reports `denied`. Surfaces through the topic status only; no `error`

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "portal-mojo",
-    "version": "0.2.14",
+    "version": "0.2.15",
     "description": "React portal toolkit for django-mojo — typed client + params store, mission-control UI, dependency-free SVG charts, admin section bundles.",
     "type": "module",
     "license": "Apache-2.0",

package/src/client/auth.ts

@@ -61,13 +61,17 @@ export function sessionIsPersistent(): boolean {
 }
 
 export function setTokens(access: string, refresh?: string | null, persistent = true): void {
+    storeTokens(access, refresh, persistent, 'session');
+}
+
+function storeTokens(access: string, refresh: string | null | undefined, persistent: boolean, source: 'session' | 'refresh'): void {
     // Clear both storages first — a leftover token in the other storage must
     // never shadow this session (web-mojo wrote without clearing).
     clearTokens({ silent: true });
     const storage = persistent ? localStorage : sessionStorage;
     storage.setItem(ACCESS_KEY, access);
     if (refresh) storage.setItem(REFRESH_KEY, refresh);
-    notifyAuthChanged();
+    notifyAuthChanged(source);
 }
 
 export function clearTokens(opts: { silent?: boolean } = {}): void {
@@ -89,8 +93,14 @@ export interface AuthSnapshot {
 
 let snapshotCache: AuthSnapshot = { authenticated: false, uid: null, email: null };
 let snapshotKey = '∅';
+let sessionRevision = 0;
 const authListeners = new Set<() => void>();
 
+/** @internal Same-tab replacement fence; ordinary renewal does not advance it. */
+export function getAuthSessionRevision(): number {
+    return sessionRevision;
+}
+
 function computeSnapshot(): void {
     const access = getAccessToken();
     const refresh = getRefreshToken();
@@ -106,7 +116,8 @@ function computeSnapshot(): void {
     };
 }
 
-function notifyAuthChanged(): void {
+function notifyAuthChanged(source: 'session' | 'refresh' = 'session'): void {
+    if (source === 'session') sessionRevision += 1;
     computeSnapshot();
     for (const cb of authListeners) cb();
 }
@@ -212,10 +223,12 @@ async function doRefresh(): Promise<RefreshOutcome> {
     const superseded = (): boolean => getRefreshToken() !== refresh;
     const sessionUsable = (): boolean => checkTokenStatus().action !== 'logout';
     try {
-        const body = await mojoCall(REFRESH_PATH, { method: 'POST', body: { refresh_token: refresh } });
+        const body = await mojoCall(REFRESH_PATH, {
+            method: 'POST', body: { refresh_token: refresh }, signal: AbortSignal.timeout(15_000),
+        });
         if (superseded()) return { ok: sessionUsable() };
         const pkg = body.data as { access_token: string; refresh_token?: string };
-        setTokens(pkg.access_token, pkg.refresh_token, persistent);
+        storeTokens(pkg.access_token, pkg.refresh_token, persistent, 'refresh');
         emitAuth('refreshed');
         return { ok: true };
     } catch (error) {

package/src/client/realtime.ts

@@ -3,7 +3,8 @@ import {
     useSyncExternalStore, type PropsWithChildren,
 } from 'react';
 import { apiOrigin } from './client';
-import { getAccessToken, subscribeAuth } from './auth';
+import { ensureValidToken, getAccessToken, getAuthSessionRevision, getRefreshToken, subscribeAuth } from './auth';
+import { AuthRequiredError } from './errors';
 
 export type RealtimeLifecycleStatus =
     | 'disabled' | 'idle' | 'connecting' | 'authenticating' | 'ready'
@@ -106,6 +107,10 @@ export class RealtimeClient {
     private readonly topicTimeoutMs: number;
     private socket: RealtimeSocket | null = null;
     private token: string | null = null;
+    private authBinding: { unsubscribe: () => void } | null = null;
+    private authSessionRevision: number | null = null;
+    private preparing: object | null = null;
+    private authSent: RealtimeSocket | null = null;
     private enabled = false;
     private generation = 0;
     private reconnectAttempt = 0;
@@ -142,11 +147,44 @@ export class RealtimeClient {
         return () => this.statusListeners.delete(listener);
     };
 
+    /** Bind one session owner; renewal shares HTTP's single-flight auth gate. */
+    bindAuthSession(): () => void {
+        if (this.authBinding) throw new Error('Realtime client already has an auth session owner');
+        const binding = { unsubscribe: () => {} };
+        this.authBinding = binding;
+        this.stop(this.suspended ?? (this.enabled ? 'idle' : 'disabled'));
+        // Synchronous invalidation is essential: a React effect can run after
+        // an old refresh/handshake has completed for the previous account.
+        const syncSession = () => {
+            const revision = getAuthSessionRevision();
+            const replaced = this.authSessionRevision !== revision;
+            this.authSessionRevision = revision;
+            // A renewal already in flight when the server denied/revoked this
+            // connection is not an intentional replacement session. The fence
+            // also survives a renewal completed while no binding was mounted.
+            if (!replaced && this.suspended) {
+                this.token = getAccessToken();
+                return;
+            }
+            this.setToken(getAccessToken());
+        };
+        binding.unsubscribe = subscribeAuth(syncSession);
+        syncSession();
+        if (this.enabled) this.open();
+        return () => {
+            if (this.authBinding !== binding) return;
+            this.disconnect();
+            binding.unsubscribe();
+            this.authBinding = null;
+        };
+    }
+
     setEnabled(enabled: boolean): void {
         if (this.enabled === enabled) return;
         this.enabled = enabled;
         if (!enabled) this.stop('disabled');
-        else if (this.token) this.open();
+        else if (this.suspended) this.setLifecycle(this.suspended);
+        else if (this.hasCredentials()) this.open();
         else this.setLifecycle('idle');
     }
 
@@ -156,7 +194,7 @@ export class RealtimeClient {
         this.token = token;
         this.suspended = null;
         this.stop(this.enabled && token ? 'idle' : this.enabled ? 'idle' : 'disabled');
-        if (this.enabled && token) this.open();
+        if (this.enabled && this.hasCredentials()) this.open();
     }
 
     connect(token: string): void {
@@ -171,6 +209,8 @@ export class RealtimeClient {
 
     destroy(): void {
         this.disconnect();
+        this.authBinding?.unsubscribe();
+        this.authBinding = null;
         this.statusListeners.clear();
         this.topicListeners.clear();
         this.eventListeners.clear();
@@ -232,14 +272,18 @@ export class RealtimeClient {
     }
 
     nudge(): void {
-        if (!this.enabled || !this.token || this.suspended || this.socket || this.retryTimer == null) return;
+        if (!this.enabled || !this.hasCredentials() || this.suspended || this.socket || this.retryTimer == null) return;
         if (this.clock.now() < this.extendedBackoffUntil) return;
         this.clearRetry();
         this.open();
     }
 
+    private hasCredentials(): boolean {
+        return Boolean(this.token || (this.authBinding && getRefreshToken()));
+    }
+
     private open(): void {
-        if (!this.enabled || !this.token || this.suspended || this.socket) return;
+        if (!this.enabled || !this.hasCredentials() || this.suspended || this.socket || this.preparing) return;
         const run = this.generation;
         // Token refresh and provider remount use this same entry point; neither
         // may bypass a server admission deadline.
@@ -248,6 +292,47 @@ export class RealtimeClient {
             return;
         }
         this.setLifecycle('connecting');
+        this.prepareSession(run, null, () => this.openSocket(run));
+    }
+
+    private prepareSession(run: number, socket: RealtimeSocket | null, ready: () => void): void {
+        const binding = this.authBinding;
+        if (!binding) { ready(); return; }
+        if (this.preparing) return;
+        const attempt = {};
+        this.preparing = attempt;
+        const current = () => this.preparing === attempt && this.authBinding === binding
+            && this.enabled && !this.suspended && run === this.generation && this.socket === socket;
+        void Promise.resolve().then(() => {
+            if (current()) return ensureValidToken();
+        }).then(() => {
+            if (!current()) return;
+            this.preparing = null;
+            ready();
+        }).catch((error: unknown) => {
+            if (!current()) return;
+            this.preparing = null;
+            if (error instanceof AuthRequiredError) this.suspend('auth-failed', 4003, 'Authentication failed');
+            else this.retryAuthentication(run, socket);
+        });
+    }
+
+    private retryAuthentication(run: number, socket: RealtimeSocket | null): void {
+        this.preparing = null;
+        this.authSent = null;
+        this.socket = null;
+        this.clearHeartbeat();
+        this.resetTopicConnectionState();
+        this.scheduleReconnect(run, 0);
+        socket?.close(1000, 'Session renewal pending');
+    }
+
+    private openSocket(run: number): void {
+        // A renewal may have completed while an admission cooldown was set.
+        if (this.clock.now() < this.extendedBackoffUntil) {
+            this.scheduleReconnect(run, 0);
+            return;
+        }
         let socket: RealtimeSocket;
         try {
             socket = this.socketFactory(this.url);
@@ -267,6 +352,8 @@ export class RealtimeClient {
         socket.onerror = () => { /* close is the single retry path */ };
         socket.onclose = (event) => {
             if (!this.isCurrent(run, socket)) return;
+            this.preparing = null;
+            this.authSent = null;
             this.socket = null;
             this.clearHeartbeat();
             this.resetTopicConnectionState();
@@ -283,12 +370,16 @@ export class RealtimeClient {
         if (!frame || typeof frame.type !== 'string') return;
 
         if (frame.type === 'auth_required') {
-            if (this.lifecycle !== 'authenticating' || !this.token) return;
-            socket.send(JSON.stringify({ type: 'authenticate', token: this.token, prefix: 'bearer' }));
+            if (this.lifecycle !== 'authenticating' || !this.token || this.authSent === socket) return;
+            this.prepareSession(run, socket, () => {
+                // Latch before send: a transport may answer synchronously.
+                this.authSent = socket;
+                socket.send(JSON.stringify({ type: 'authenticate', token: this.token, prefix: 'bearer' }));
+            });
             return;
         }
         if (frame.type === 'auth_success') {
-            if (this.lifecycle !== 'authenticating') return;
+            if (this.lifecycle !== 'authenticating' || this.authSent !== socket) return;
             this.reconnectAttempt = 0;
             this.extendedBackoffUntil = 0;
             this.automaticUserTopic = (typeof frame.user_type === 'string' && (typeof frame.user_id === 'number' || typeof frame.user_id === 'string'))
@@ -325,6 +416,8 @@ export class RealtimeClient {
             // Fence queued frames before closing: late auth_success must not
             // clear the deadline or make this refused socket ready.
             this.extendedBackoffUntil = this.clock.now() + 60_000;
+            this.preparing = null;
+            this.authSent = null;
             this.socket = null;
             this.clearHeartbeat();
             this.resetTopicConnectionState();
@@ -335,7 +428,11 @@ export class RealtimeClient {
         }
         if (frame.type === 'error') {
             if (this.lifecycle === 'authenticating') {
-                this.suspend('auth-failed', 4003, 'Authentication failed');
+                // The server's admission timer can expire while renewal is
+                // pending. No credential was rejected in this specific case.
+                if (frame.message === 'Authentication timeout' && this.authBinding && this.authSent !== socket) {
+                    this.retryAuthentication(run, socket);
+                } else this.suspend('auth-failed', 4003, 'Authentication failed');
             } else if (this.topicOperation) {
                 this.denyCurrentTopic();
             } else {
@@ -492,6 +589,9 @@ export class RealtimeClient {
 
     private suspend(reason: 'auth-failed' | 'forced-disconnect', code: number, message: string): void {
         this.suspended = reason;
+        this.preparing = null;
+        this.authSent = null;
+        this.clearRetry();
         this.setLifecycle(reason);
         const socket = this.socket;
         this.socket = null;
@@ -502,6 +602,8 @@ export class RealtimeClient {
 
     private stop(status: RealtimeLifecycleStatus): void {
         this.generation += 1;
+        this.preparing = null;
+        this.authSent = null;
         this.clearRetry();
         this.clearHeartbeat();
         this.resetTopicConnectionState();
@@ -561,8 +663,7 @@ export type RealtimeProviderProps = PropsWithChildren<{
 
 export function RealtimeProvider({ children, enabled = true, client, socketFactory, origin }: RealtimeProviderProps) {
     const owned = useMemo(() => client ?? new RealtimeClient({ socketFactory, origin }), [client, socketFactory, origin]);
-    const token = useSyncExternalStore(subscribeAuth, getAccessToken, getAccessToken);
-    useEffect(() => { owned.setToken(token); }, [owned, token]);
+    useEffect(() => owned.bindAuthSession(), [owned]);
     useEffect(() => {
         owned.setEnabled(enabled);
         return () => owned.setEnabled(false);