@flow-industries/id 0.10.0 → 0.11.0

package/dist/sdk/client/refresh-store.d.ts

@@ -1,22 +1,23 @@
 import type { RefreshCookieConfig } from "../types";
 /**
- * First-party persistence for the rotating refresh token. It lives in the
- * consumer app's OWN localStorage (origin-scoped), so it survives reloads and
- * navigations and — unlike the old id.flow.industries cookie — is never a
- * third-party cookie, so iOS ITP can't block it. Keyed by `host` so pointing
- * the SDK at a different Flow ID origin (dev vs prod) doesn't collide.
+ * First-party persistence for the rotating refresh token, keyed by `host` so
+ * pointing the SDK at a different Flow ID origin (dev vs prod) doesn't
+ * collide. Two modes:
+ *
+ * - With a cookie config (`createFlow({ cookies: true })`) the first-party
+ *   cookie is the sole store. The app's own server reads and rotates it
+ *   during SSR, so any second copy only drifts behind on each rotation —
+ *   and presenting a superseded token looks like theft to the server's
+ *   reuse detection, which revokes the whole lineage (self-logout).
+ *
+ * - Without one (a consumer with no server to share the token with), it
+ *   lives in the app's own localStorage: origin-scoped, survives reloads,
+ *   and — unlike the old id.flow.industries cookie — never third-party, so
+ *   iOS ITP can't block it.
  */
 export interface RefreshStore {
     get(): string | null;
     set(token: string): void;
     clear(): void;
 }
-/**
- * With a cookie config (`createFlow({ cookies: true })`) the token is
- * additionally mirrored into a first-party cookie so the app's own server can
- * refresh the session during SSR. Reads prefer the cookie: the only writer
- * that updates one side without the other is that server (Set-Cookie only),
- * and its value is always a successor of whatever localStorage still holds;
- * every client-side write hits both in the same call.
- */
 export declare function makeRefreshStore(host: string, cookie?: RefreshCookieConfig): RefreshStore;

package/dist/sdk/client/refresh-store.js

@@ -1,66 +1,76 @@
 import { clearBrowserCookie, REFRESH_COOKIE_MAX_AGE_S, readBrowserCookie, writeBrowserCookie, } from "../cookies";
-/**
- * With a cookie config (`createFlow({ cookies: true })`) the token is
- * additionally mirrored into a first-party cookie so the app's own server can
- * refresh the session during SSR. Reads prefer the cookie: the only writer
- * that updates one side without the other is that server (Set-Cookie only),
- * and its value is always a successor of whatever localStorage still holds;
- * every client-side write hits both in the same call.
- */
-export function makeRefreshStore(host, cookie) {
-    const key = `flow.id.refresh:${host}`;
-    const readLocal = () => {
-        try {
-            return localStorage.getItem(key);
-        }
-        catch {
-            return null;
-        }
-    };
-    const readCookie = () => {
-        if (!cookie || typeof document === "undefined")
-            return null;
-        return readBrowserCookie(document.cookie, cookie.name);
-    };
-    const store = {
+function localStorageStore(key) {
+    return {
         get() {
-            return readCookie() ?? readLocal();
+            try {
+                return localStorage.getItem(key);
+            }
+            catch {
+                return null;
+            }
         },
         set(token) {
-            // Never persist a missing token: localStorage.setItem coerces undefined
-            // to the literal "undefined", which later reads back as a bogus bearer
-            // and 401s as refresh_token_invalid. Fail safe by ignoring it instead.
-            if (!token)
-                return;
             try {
                 localStorage.setItem(key, token);
             }
             catch { }
-            if (cookie) {
-                writeBrowserCookie(cookie.name, token, {
-                    maxAge: REFRESH_COOKIE_MAX_AGE_S,
-                    secure: cookie.secure,
-                });
-            }
         },
         clear() {
             try {
                 localStorage.removeItem(key);
             }
             catch { }
-            if (cookie)
-                clearBrowserCookie(cookie.name, { secure: cookie.secure });
         },
     };
-    // One-time reconcile so exactly one canonical value exists before the first
-    // refresh: an SSR rotation updates only the cookie, leaving localStorage one
-    // generation behind — presenting that stale token would look like reuse.
-    const fromCookie = readCookie();
-    if (fromCookie && fromCookie !== readLocal()) {
-        try {
-            localStorage.setItem(key, fromCookie);
-        }
-        catch { }
+}
+function cookieStore(cookie) {
+    return {
+        get() {
+            return readBrowserCookie(document.cookie, cookie.name);
+        },
+        set(token) {
+            writeBrowserCookie(cookie.name, token, {
+                maxAge: REFRESH_COOKIE_MAX_AGE_S,
+                secure: cookie.secure,
+            });
+        },
+        clear() {
+            clearBrowserCookie(cookie.name, { secure: cookie.secure });
+        },
+    };
+}
+/**
+ * Never persist a missing token: both backends coerce undefined to the
+ * literal "undefined", which later reads back as a bogus bearer and 401s as
+ * refresh_token_invalid. Fail safe by ignoring it instead.
+ */
+function withMissingTokenGuard(store) {
+    return {
+        ...store,
+        set(token) {
+            if (!token)
+                return;
+            store.set(token);
+        },
+    };
+}
+export function makeRefreshStore(host, cookie) {
+    const legacy = localStorageStore(`flow.id.refresh:${host}`);
+    if (!cookie)
+        return withMissingTokenGuard(legacy);
+    const store = cookieStore(cookie);
+    // One-time takeover from the dual-write SDK (<= 0.10.0), which kept a
+    // localStorage copy: promote it when no cookie exists yet (a session
+    // predating the app's cookie mode), then drop the key — a leftover copy
+    // goes stale on the next SSR rotation and replaying it trips lineage
+    // revocation. Remove this block once every legacy token has rotated or
+    // expired (REFRESH_COOKIE_MAX_AGE_S after 0.11.0 reaches all cookie-mode
+    // apps).
+    const legacyToken = legacy.get();
+    if (legacyToken) {
+        if (!store.get())
+            store.set(legacyToken);
+        legacy.clear();
     }
-    return store;
+    return withMissingTokenGuard(store);
 }

package/dist/sdk/client/refresh-store.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/sdk/client/refresh-store.test.js

@@ -0,0 +1,90 @@
+import { beforeEach, describe, expect, test } from "bun:test";
+import { makeRefreshStore } from "./refresh-store";
+const HOST = "https://id.flow.industries";
+const KEY = `flow.id.refresh:${HOST}`;
+const COOKIE = { name: "flow_id.refresh_p5173", secure: false };
+let local;
+let jar;
+function installBrowserStubs() {
+    local = new Map();
+    jar = new Map();
+    globalThis.localStorage = {
+        getItem: (k) => local.get(k) ?? null,
+        setItem: (k, v) => void local.set(k, String(v)),
+        removeItem: (k) => void local.delete(k),
+    };
+    globalThis.document = {
+        get cookie() {
+            return [...jar.entries()].map(([n, v]) => `${n}=${v}`).join("; ");
+        },
+        set cookie(str) {
+            const [pair = "", ...attrs] = str.split(";");
+            const eq = pair.indexOf("=");
+            const name = pair.slice(0, eq).trim();
+            const value = pair.slice(eq + 1).trim();
+            if (attrs.some((a) => a.trim() === "Max-Age=0"))
+                jar.delete(name);
+            else
+                jar.set(name, value);
+        },
+    };
+}
+beforeEach(installBrowserStubs);
+describe("localStorage mode (no cookie config)", () => {
+    test("round-trips through localStorage", () => {
+        const store = makeRefreshStore(HOST);
+        expect(store.get()).toBeNull();
+        store.set("tok_a");
+        expect(local.get(KEY)).toBe("tok_a");
+        expect(store.get()).toBe("tok_a");
+        store.clear();
+        expect(store.get()).toBeNull();
+    });
+    test("ignores a missing token instead of persisting a bogus value", () => {
+        const store = makeRefreshStore(HOST);
+        store.set(undefined);
+        expect(store.get()).toBeNull();
+    });
+    test("never touches cookies", () => {
+        const store = makeRefreshStore(HOST);
+        store.set("tok_a");
+        expect(jar.size).toBe(0);
+    });
+});
+describe("cookie mode", () => {
+    test("promotes a legacy localStorage token into the cookie and drops the key", () => {
+        local.set(KEY, "tok_legacy");
+        const store = makeRefreshStore(HOST, COOKIE);
+        expect(store.get()).toBe("tok_legacy");
+        expect(jar.get(COOKIE.name)).toBe("tok_legacy");
+        expect(local.has(KEY)).toBe(false);
+    });
+    test("an existing cookie wins over a stale localStorage copy", () => {
+        local.set(KEY, "tok_stale");
+        jar.set(COOKIE.name, "tok_rotated");
+        const store = makeRefreshStore(HOST, COOKIE);
+        expect(store.get()).toBe("tok_rotated");
+        expect(local.has(KEY)).toBe(false);
+    });
+    test("reads and writes only the cookie", () => {
+        const store = makeRefreshStore(HOST, COOKIE);
+        store.set("tok_b");
+        expect(jar.get(COOKIE.name)).toBe("tok_b");
+        expect(local.size).toBe(0);
+        local.set(KEY, "tok_planted_later");
+        jar.delete(COOKIE.name);
+        expect(store.get()).toBeNull();
+    });
+    test("clear deletes the cookie", () => {
+        const store = makeRefreshStore(HOST, COOKIE);
+        store.set("tok_c");
+        store.clear();
+        expect(store.get()).toBeNull();
+        expect(jar.has(COOKIE.name)).toBe(false);
+    });
+    test("ignores a missing token instead of persisting a bogus value", () => {
+        const store = makeRefreshStore(HOST, COOKIE);
+        store.set(undefined);
+        expect(store.get()).toBeNull();
+    });
+});

package/dist/sdk/cookies.d.ts

@@ -1,6 +1,6 @@
 /**
  * First-party cookie names and (de)serialization shared by the browser SDK
- * (which mirrors the session into cookies) and the server helper (which reads
+ * (which persists the session into cookies) and the server helper (which reads
  * them per-request to render auth-aware UI without a client round-trip).
  * Isomorphic: no browser globals at import time.
  */

package/dist/sdk/cookies.js

@@ -1,6 +1,6 @@
 /**
  * First-party cookie names and (de)serialization shared by the browser SDK
- * (which mirrors the session into cookies) and the server helper (which reads
+ * (which persists the session into cookies) and the server helper (which reads
  * them per-request to render auth-aware UI without a client round-trip).
  * Isomorphic: no browser globals at import time.
  */

package/dist/sdk/types/sdk.d.ts

@@ -72,11 +72,12 @@ export type CreateFlowOptions = {
      */
     autoGuest?: boolean;
     /**
-     * If true, the JWT and the rotating refresh token are mirrored into
-     * first-party cookies on the app's own origin so the app's server can
-     * resolve the session per-request (see `@flow-industries/id/server`).
-     * Off by default — a backend that never reads them shouldn't start
-     * receiving refresh tokens on every request.
+     * If true, the session lives in first-party cookies on the app's own
+     * origin: the JWT is mirrored there from memory and the rotating refresh
+     * token is stored there alone (not in localStorage), so the app's server
+     * can resolve and rotate the session per-request (see
+     * `@flow-industries/id/server`). Off by default — a backend that never
+     * reads them shouldn't start receiving refresh tokens on every request.
      */
     cookies?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flow-industries/id",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "main": "./dist/sdk/client/index.js",
   "module": "./dist/sdk/client/index.js",
   "types": "./dist/sdk/client/index.d.ts",