@loomup/astro 0.1.9 → 0.1.11

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,237 @@ 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;
+const SESSION_LOCK_DATABASE = "@loomup/astro:auth-locks";
+const SESSION_LOCK_STORE = "leases";
+const SESSION_LOCK_TTL_MS = 120_000;
+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 browserIndexedDB() {
+    try {
+        return globalThis.indexedDB;
+    }
+    catch {
+        return undefined;
+    }
+}
+function leaseOwner() {
+    const cryptoApi = globalThis.crypto;
+    if (typeof cryptoApi?.randomUUID === "function")
+        return cryptoApi.randomUUID();
+    coordinatorSequence += 1;
+    return `${Date.now()}-${coordinatorSequence}`;
+}
+function storedLease(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const lease = value;
+    if (typeof lease.owner !== "string" || typeof lease.expiresAt !== "number")
+        return null;
+    return { owner: lease.owner, expiresAt: lease.expiresAt };
+}
+function openLeaseDatabase(factory) {
+    return new Promise((resolve, reject) => {
+        const request = factory.open(SESSION_LOCK_DATABASE, 1);
+        request.onupgradeneeded = () => {
+            if (!request.result.objectStoreNames.contains(SESSION_LOCK_STORE)) {
+                request.result.createObjectStore(SESSION_LOCK_STORE);
+            }
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error("could not open session lock database"));
+        request.onblocked = () => reject(new Error("session lock database is blocked"));
+    });
+}
+function mutateLease(database, key, decide) {
+    return new Promise((resolve, reject) => {
+        const transaction = database.transaction(SESSION_LOCK_STORE, "readwrite");
+        const store = transaction.objectStore(SESSION_LOCK_STORE);
+        const request = store.get(key);
+        let result = false;
+        request.onsuccess = () => {
+            const mutation = decide(storedLease(request.result));
+            result = mutation.result;
+            if (mutation.write === "put" && mutation.lease)
+                store.put(mutation.lease, key);
+            else if (mutation.write === "delete")
+                store.delete(key);
+        };
+        transaction.oncomplete = () => resolve(result);
+        transaction.onerror = () => reject(transaction.error ?? new Error("session lock transaction failed"));
+        transaction.onabort = () => reject(transaction.error ?? new Error("session lock transaction aborted"));
+    });
+}
+function acquireLease(database, key, owner) {
+    return mutateLease(database, key, (current) => {
+        if (current && current.expiresAt > Date.now()) {
+            return { result: false, write: "none" };
+        }
+        return {
+            result: true,
+            write: "put",
+            lease: { owner, expiresAt: Date.now() + SESSION_LOCK_TTL_MS },
+        };
+    });
+}
+function renewLease(database, key, owner) {
+    return mutateLease(database, key, (current) => current?.owner === owner
+        ? {
+            result: true,
+            write: "put",
+            lease: { owner, expiresAt: Date.now() + SESSION_LOCK_TTL_MS },
+        }
+        : { result: false, write: "none" });
+}
+function releaseLease(database, key, owner) {
+    return mutateLease(database, key, (current) => current?.owner === owner
+        ? { result: true, write: "delete" }
+        : { result: false, write: "none" });
+}
+async function withLease(name, operation) {
+    const factory = browserIndexedDB();
+    if (!factory) {
+        if (typeof window === "undefined")
+            return operation();
+        throw new LoomupError("browser storage cannot coordinate session refresh", "auth_lock_unavailable", 503);
+    }
+    let database;
+    try {
+        database = await openLeaseDatabase(factory);
+    }
+    catch {
+        throw new LoomupError("browser storage cannot coordinate session refresh", "auth_lock_unavailable", 503);
+    }
+    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) {
+            if (await acquireLease(database, key, owner)) {
+                let heartbeatInFlight = null;
+                const heartbeat = setInterval(() => {
+                    if (heartbeatInFlight)
+                        return;
+                    heartbeatInFlight = renewLease(database, key, owner)
+                        .catch(() => false)
+                        .finally(() => { heartbeatInFlight = null; });
+                }, 5_000);
+                try {
+                    return await operation();
+                }
+                finally {
+                    clearInterval(heartbeat);
+                    const pendingHeartbeat = heartbeatInFlight;
+                    if (pendingHeartbeat)
+                        await pendingHeartbeat;
+                    await releaseLease(database, key, owner).catch(() => false);
+                    channel?.postMessage("released");
+                }
+            }
+            await delay(50);
+        }
+        throw new LoomupError("timed out waiting for session refresh", "auth_lock_timeout", 503);
+    }
+    finally {
+        channel?.close();
+        database.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 +302,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 +325,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.9",
+  "version": "0.1.11",
   "description": "Astro integration and SSR helpers for Loomup Realtime",
   "type": "module",
   "main": "dist/index.js",
@@ -46,8 +46,9 @@
     }
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "fake-indexeddb": "^6.2.5",
+    "typescript": "^5.7.0"
   },
   "engines": {
     "node": ">=18"