@loomup/astro 0.1.8 → 0.1.10

package/README.md

@@ -52,6 +52,25 @@ Package exports:
 - `@loomup/astro/middleware` — authentication middleware.
 - `@loomup/astro/auth` — lower-level cookie authentication helpers.
 
+## Coordinated browser sessions
+
+`createAuthenticatedProject()` coordinates cookie refresh within a tab and
+across same-origin tabs. Custom browser integrations can use the same primitive:
+
+```ts
+import { createBrowserSessionCoordinator } from "@loomup/astro/client";
+
+const session = createBrowserSessionCoordinator({
+  lockName: "/api/loomup",
+  loadSession: () => fetch("/api/loomup/session").then((response) => response.json()),
+});
+```
+
+For apps where every browser request uses that coordinator, configure the auth
+handler with `dataProxyRefresh: "client-coordinated"`. This keeps single-use
+refresh rotation on the session endpoint instead of racing parallel data proxy
+requests. The compatibility default remains `"server"`.
+
 See the [Astro SDK guide](https://tryloomup.com/docs) for middleware,
 authenticated islands, object storage, and deployment guidance.
 

package/dist/auth.d.ts

@@ -10,6 +10,12 @@ export type LoomupAuthHandlerOptions = CreateServerClientOptions & {
     param?: string;
     /** Exact application callback URL allowlisted in `$auth.redirect_urls`. */
     oauthCallbackUrl?: string;
+    /**
+     * Who rotates an absent access cookie for data requests. The compatibility
+     * default is `server`; browser-coordinated applications should use
+     * `client-coordinated` so only the session endpoint rotates refresh tokens.
+     */
+    dataProxyRefresh?: "server" | "client-coordinated";
 };
 /**
  * Create one Astro catch-all endpoint for login, logout, session hydration,

package/dist/auth.js

@@ -169,7 +169,7 @@ async function proxyToLoomup(context, options, baseUrl, action) {
     if (method !== "GET" && method !== "HEAD")
         assertSameOrigin(context.request);
     let tokens = readTokens(context.cookies, options.cookies?.names);
-    if (!tokens.access) {
+    if (!tokens.access && options.dataProxyRefresh !== "client-coordinated") {
         if (!tokens.refresh) {
             throw new LoomupError("authentication required", "unauthorized", 401);
         }

package/dist/client.d.ts

@@ -14,6 +14,30 @@ export type CreateBrowserClientOptions = {
     refreshToken?: string;
     WebSocketImpl?: CreateClientOptions["WebSocketImpl"];
 };
+export type BrowserSessionCoordinatorOptions<TSession> = {
+    /** Load the current same-origin session. This may rotate an expired session. */
+    loadSession: () => Promise<TSession>;
+    /** Explicitly rotate a still-valid session that is close to expiry. */
+    refreshSession?: () => Promise<TSession>;
+    /** Return the access JWT when the session exposes it. */
+    accessToken?: (session: TSession) => string | undefined;
+    /** Refresh this long before the JWT expiry. Default: 60 seconds. */
+    expirySkewMs?: number;
+    /** Same-origin lock shared by every tab using this session. */
+    lockName?: string;
+};
+export type BrowserSessionCoordinator<TSession> = {
+    getSession(): Promise<TSession>;
+    ensureFresh(): Promise<TSession>;
+    invalidate(): void;
+};
+/**
+ * Coordinate cookie-session refreshes within one tab and across same-origin
+ * tabs. The operation always reloads the session after acquiring the lock, so
+ * a waiter adopts cookies rotated by the winner instead of replaying a
+ * single-use refresh token.
+ */
+export declare function createBrowserSessionCoordinator<TSession>(options: BrowserSessionCoordinatorOptions<TSession>): BrowserSessionCoordinator<TSession>;
 /**
  * Create a browser Loomup client for islands.
  *

package/dist/client.js

@@ -26,6 +26,178 @@ function resolveBrowserUrl(explicit) {
         return fromEnv;
     throw new Error("@loomup/astro: createBrowserClient requires `url` or PUBLIC_LOOMUP_URL (set via the loomup() integration)");
 }
+let coordinatorSequence = 0;
+function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function jwtExpiry(token) {
+    if (!token)
+        return undefined;
+    try {
+        const encoded = token.split(".")[1];
+        if (!encoded)
+            return undefined;
+        const normalized = encoded.replace(/-/g, "+").replace(/_/g, "/");
+        const padded = normalized.padEnd(Math.ceil(normalized.length / 4) * 4, "=");
+        const decode = globalThis.atob;
+        if (!decode)
+            return undefined;
+        const payload = JSON.parse(decode(padded));
+        return typeof payload.exp === "number" ? payload.exp * 1_000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function browserLockManager() {
+    try {
+        return globalThis.navigator?.locks;
+    }
+    catch {
+        return undefined;
+    }
+}
+function browserStorage() {
+    try {
+        return globalThis.localStorage;
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaseOwner() {
+    const cryptoApi = globalThis.crypto;
+    if (typeof cryptoApi?.randomUUID === "function")
+        return cryptoApi.randomUUID();
+    coordinatorSequence += 1;
+    return `${Date.now()}-${coordinatorSequence}`;
+}
+function readLease(storage, key) {
+    try {
+        const raw = storage.getItem(key);
+        if (!raw)
+            return null;
+        const value = JSON.parse(raw);
+        if (typeof value.owner !== "string" || typeof value.expiresAt !== "number")
+            return null;
+        return { owner: value.owner, expiresAt: value.expiresAt };
+    }
+    catch {
+        return null;
+    }
+}
+async function withLease(name, operation) {
+    const storage = browserStorage();
+    if (!storage)
+        return operation();
+    const key = `@loomup/astro:auth-lock:${name}`;
+    const owner = leaseOwner();
+    const deadline = Date.now() + 30_000;
+    const channel = typeof BroadcastChannel === "function"
+        ? new BroadcastChannel(`@loomup/astro:auth:${name}`)
+        : undefined;
+    try {
+        while (Date.now() < deadline) {
+            const current = readLease(storage, key);
+            if (!current || current.expiresAt <= Date.now()) {
+                try {
+                    storage.setItem(key, JSON.stringify({ owner, expiresAt: Date.now() + 15_000 }));
+                }
+                catch {
+                    return operation();
+                }
+                // localStorage has no compare-and-swap. A short settle and owner check
+                // ensures only the last contender enters the critical section.
+                await delay(20);
+                if (readLease(storage, key)?.owner === owner) {
+                    const heartbeat = setInterval(() => {
+                        if (readLease(storage, key)?.owner === owner) {
+                            storage.setItem(key, JSON.stringify({ owner, expiresAt: Date.now() + 15_000 }));
+                        }
+                    }, 5_000);
+                    try {
+                        return await operation();
+                    }
+                    finally {
+                        clearInterval(heartbeat);
+                        if (readLease(storage, key)?.owner === owner)
+                            storage.removeItem(key);
+                        channel?.postMessage("released");
+                    }
+                }
+            }
+            await delay(50);
+        }
+        throw new LoomupError("timed out waiting for session refresh", "auth_lock_timeout", 503);
+    }
+    finally {
+        channel?.close();
+    }
+}
+async function withBrowserSessionLock(name, operation) {
+    const locks = browserLockManager();
+    if (locks) {
+        return locks.request(`@loomup/astro:auth:${name}`, { mode: "exclusive" }, operation);
+    }
+    return withLease(name, operation);
+}
+function isTerminalSessionError(error) {
+    return error instanceof LoomupError && error.status === 401;
+}
+/**
+ * Coordinate cookie-session refreshes within one tab and across same-origin
+ * tabs. The operation always reloads the session after acquiring the lock, so
+ * a waiter adopts cookies rotated by the winner instead of replaying a
+ * single-use refresh token.
+ */
+export function createBrowserSessionCoordinator(options) {
+    const lockName = options.lockName ?? "default";
+    const expirySkewMs = Math.max(0, options.expirySkewMs ?? 60_000);
+    let cached;
+    let inFlight = null;
+    const execute = (checkExpiry) => {
+        if (inFlight)
+            return inFlight;
+        const attempt = async () => withBrowserSessionLock(lockName, async () => {
+            const loaded = await options.loadSession();
+            if (!checkExpiry || !options.refreshSession || !options.accessToken)
+                return loaded;
+            const expiresAt = jwtExpiry(options.accessToken(loaded));
+            return expiresAt !== undefined && expiresAt - Date.now() <= expirySkewMs
+                ? options.refreshSession()
+                : loaded;
+        });
+        inFlight = (async () => {
+            try {
+                cached = await attempt();
+            }
+            catch (error) {
+                if (!isTerminalSessionError(error))
+                    throw error;
+                // A tab that could not participate in the primary lock may have lost a
+                // rotation race. Reacquire and observe the cookie jar once before the
+                // caller treats the session as terminal.
+                await delay(100);
+                cached = await attempt();
+            }
+            return cached;
+        })().finally(() => {
+            inFlight = null;
+        });
+        return inFlight;
+    };
+    return {
+        getSession() {
+            return cached === undefined ? execute(false) : Promise.resolve(cached);
+        },
+        ensureFresh() {
+            return execute(true);
+        },
+        invalidate() {
+            cached = undefined;
+        },
+    };
+}
 /**
  * Create a browser Loomup client for islands.
  *
@@ -71,14 +243,18 @@ async function authRequest(fetchImpl, endpoint, action, init) {
 export async function createAuthenticatedProject(options = {}) {
     const fetchImpl = options.fetch ?? globalThis.fetch;
     const endpoint = options.authEndpoint ?? "/api/loomup";
-    const session = await authRequest(fetchImpl, endpoint, "session", { method: "GET" });
+    const coordinator = createBrowserSessionCoordinator({
+        lockName: endpoint,
+        loadSession: () => authRequest(fetchImpl, endpoint, "session", { method: "GET" }),
+    });
+    const session = await coordinator.getSession();
     if (!session.user) {
         throw new LoomupError("authenticated session required", "unauthorized", 401);
     }
     const db = createProject({
         url: options.dataEndpoint ?? `${endpoint.replace(/\/$/, "")}/data`,
         accessTokenProvider: async () => {
-            await authRequest(fetchImpl, endpoint, "refresh", { method: "POST" });
+            await coordinator.ensureFresh();
             // The core client requires a truthy retry signal. This marker is sent
             // only to the same-origin gateway, which replaces Authorization with
             // the server-held access token.
@@ -90,6 +266,7 @@ export async function createAuthenticatedProject(options = {}) {
         user: session.user,
         async signOut() {
             await authRequest(fetchImpl, endpoint, "logout", { method: "POST" });
+            coordinator.invalidate();
             db.setToken(undefined);
         },
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loomup/astro",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "description": "Astro integration and SSR helpers for Loomup Realtime",
   "type": "module",
   "main": "dist/index.js",