@pylonsync/sync 0.22.14 → 0.22.17

package/dist/index.d.ts

@@ -5,7 +5,7 @@ import { SessionResolver } from "./session-resolver";
 export { RoomSubscriptions, type RoomError, type RoomErrorCode, type RoomMember, type RoomMessage, type RoomMessageSubscriber, type RoomSubscriber, } from "./room-subscriptions";
 export { IndexedDBPersistence, persistChange } from "./persistence";
 export type { ReplicaPersistence } from "./persistence";
-export { buildRequest, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
+export { BEARER_REJECTED_HEADER, bearerRejected, buildRequest, clearRejectedToken, pylonFetch, pylonFetchRaw, PylonHttpError, resolveBaseUrl, } from "./transport";
 export type { PylonRequestInit, TransportConfig } from "./transport";
 export { LocalStore } from "./local-store";
 export { MutationQueue, MutationRejectedError, type MutationQueuePersistence, type PendingMutation, } from "./mutation-queue";
@@ -805,6 +805,16 @@ export declare class SyncEngine {
      * A genuinely signed-out user has no stored token, so this stays quiet.
      */
     private warnForeignToken;
+    /**
+     * The server answered with `X-Pylon-Bearer-Rejected`: the token the request
+     * sent resolved to no one (expired, revoked, or not a session of this app).
+     * Clear it from the app's namespace so later requests stop sending it and
+     * the session cookie, when there is one, applies alone. A token passed in
+     * `config.token` belongs to the caller and stays.
+     */
+    private dropRejectedToken;
+    /** `dropRejectedToken` for a response to a request that sent `token`. */
+    private observeBearerVerdict;
     /**
      * Apply a freshly-observed session through the resolver and act on
      * the verdict. Serialized via `sessionChain` so concurrent triggers

package/dist/transport.d.ts

@@ -16,7 +16,31 @@ export interface TransportConfig {
      *  header when the server sets one. Returning a Promise pauses no
      *  one — the transport doesn't await it. */
     onChangeSeq?: (seq: number) => void;
+    /** Invoked with the bearer token a request sent when the server answers
+     *  with `X-Pylon-Bearer-Rejected: 1`: the server resolved the token to no
+     *  one (unknown, expired, or revoked). The code that stored the token
+     *  clears it here, so later requests stop sending it. */
+    onBearerRejected?: (token: string) => void;
 }
+/** Response header the server sets when the request's bearer token resolved
+ *  to no one. Lower case, as `Headers.get` matches without case. */
+export declare const BEARER_REJECTED_HEADER = "x-pylon-bearer-rejected";
+/** True when the server marked the bearer token the request sent as rejected. */
+export declare function bearerRejected(res: Response): boolean;
+/**
+ * Remove a token the server rejected from `storage`, together with its
+ * `:userId` sibling. Only removes it when `key` still holds that exact token,
+ * so a sign-in that wrote a new token while the request was in flight keeps
+ * its token.
+ *
+ * The default unprefixed key `pylon_token` is left alone. Every app on an
+ * origin that has no `appName` shares it, so the token can belong to another
+ * app. Returns true when the token was removed.
+ */
+export declare function clearRejectedToken(storage: {
+    get(key: string): string | null;
+    remove(key: string): void;
+}, key: string, token: string): boolean;
 /**
  * Per-call init shape. Mirrors the standard `RequestInit` but
  * normalizes the two body shapes (JSON-encode-this vs raw-pass-
@@ -56,6 +80,7 @@ export declare function resolveBaseUrl(config: TransportConfig): string;
 export declare function buildRequest(config: TransportConfig, path: string, init?: PylonRequestInit): {
     url: string;
     init: RequestInit;
+    token?: string;
 };
 /** Error thrown by `pylonFetch` for non-2xx responses. Carries the
  *  status + structured error code + the parsed JSON body (if any). */

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.22.14",
+  "version": "0.22.17",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",

package/src/bearer-rejected.test.ts

@@ -0,0 +1,146 @@
+// A stored token the server rejects is cleared. The server answers a request
+// whose bearer token resolved to no one (expired, revoked, or not a session
+// of this app) with `X-Pylon-Bearer-Rejected: 1`, and falls back to the
+// session cookie when it can. Without the client clearing the token, every
+// later request keeps sending it.
+
+import { afterEach, describe, expect, test } from "bun:test";
+
+import {
+  BEARER_REJECTED_HEADER,
+  clearRejectedToken,
+  pylonFetch,
+  pylonFetchRaw,
+  SyncEngine,
+} from "./index";
+import type { Storage } from "./storage";
+
+function memoryStorage(initial: Record<string, string> = {}): Storage & {
+  data: Map<string, string>;
+} {
+  const data = new Map(Object.entries(initial));
+  return {
+    data,
+    get: (k) => data.get(k) ?? null,
+    set: (k, v) => void data.set(k, v),
+    remove: (k) => void data.delete(k),
+  };
+}
+
+const realFetch = globalThis.fetch;
+afterEach(() => {
+  globalThis.fetch = realFetch;
+});
+
+/** Stub fetch: records each request's Authorization header and answers
+ *  with `X-Pylon-Bearer-Rejected: 1` while `rejected(token)` is true. */
+function stubFetch(rejected: (token: string | undefined) => boolean, body: unknown = {}) {
+  const auth: Array<string | undefined> = [];
+  globalThis.fetch = (async (_input: RequestInfo | URL, init: RequestInit = {}) => {
+    const h = (init.headers ?? {}) as Record<string, string>;
+    const header = h.Authorization;
+    auth.push(header);
+    const token = header?.replace(/^Bearer /, "");
+    const headers: Record<string, string> = { "content-type": "application/json" };
+    if (rejected(token)) headers[BEARER_REJECTED_HEADER] = "1";
+    return new Response(JSON.stringify(body), { status: 200, headers });
+  }) as typeof fetch;
+  return auth;
+}
+
+describe("transport: X-Pylon-Bearer-Rejected", () => {
+  test("pylonFetch reports the token it sent when the server rejects it", async () => {
+    stubFetch(() => true);
+    const seen: string[] = [];
+    await pylonFetch(
+      { baseUrl: "http://t.invalid", token: "stale", onBearerRejected: (t) => seen.push(t) },
+      "/api/fn/x",
+      { method: "POST", json: {} },
+    );
+    expect(seen).toEqual(["stale"]);
+  });
+
+  test("pylonFetchRaw reports it too", async () => {
+    stubFetch(() => true);
+    const seen: string[] = [];
+    await pylonFetchRaw(
+      { baseUrl: "http://t.invalid", token: "stale", onBearerRejected: (t) => seen.push(t) },
+      "/api/fn/x",
+      { method: "POST", json: {} },
+    );
+    expect(seen).toEqual(["stale"]);
+  });
+
+  test("nothing is reported without the header, or when no token was sent", async () => {
+    const seen: string[] = [];
+    stubFetch(() => false);
+    await pylonFetch(
+      { baseUrl: "http://t.invalid", token: "good", onBearerRejected: (t) => seen.push(t) },
+      "/api/auth/me",
+    );
+    stubFetch(() => true);
+    await pylonFetch(
+      { baseUrl: "http://t.invalid", onBearerRejected: (t) => seen.push(t) },
+      "/api/auth/me",
+    );
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("clearRejectedToken", () => {
+  test("removes the app's token and user id when the key still holds that token", () => {
+    const s = memoryStorage({ "pylon:miles:token": "stale", "pylon:miles:userId": "u1" });
+    expect(clearRejectedToken(s, "pylon:miles:token", "stale")).toBe(true);
+    expect(s.data.size).toBe(0);
+  });
+
+  test("keeps a token that a sign-in wrote while the request was in flight", () => {
+    const s = memoryStorage({ "pylon:miles:token": "fresh" });
+    expect(clearRejectedToken(s, "pylon:miles:token", "stale")).toBe(false);
+    expect(s.get("pylon:miles:token")).toBe("fresh");
+  });
+
+  test("leaves the shared default key alone", () => {
+    const s = memoryStorage({ pylon_token: "stale" });
+    expect(clearRejectedToken(s, "pylon_token", "stale")).toBe(false);
+    expect(s.get("pylon_token")).toBe("stale");
+  });
+});
+
+describe("SyncEngine clears a stored token the server rejects", () => {
+  function engine(storage: Storage, extra: Record<string, unknown> = {}) {
+    return new SyncEngine({
+      baseUrl: "http://t.invalid",
+      appName: "miles",
+      storage,
+      persist: false,
+      multiTab: false,
+      transport: "poll",
+      ...extra,
+    });
+  }
+
+  test("fn(): the next call sends no Authorization header", async () => {
+    const storage = memoryStorage({ "pylon:miles:token": "stale" });
+    const auth = stubFetch((t) => t === "stale", { ok: true });
+    const e = engine(storage);
+    await e.fn("resetDemoDealership", {});
+    expect(storage.get("pylon:miles:token")).toBeNull();
+    await e.fn("resetDemoDealership", {});
+    expect(auth).toEqual(["Bearer stale", undefined]);
+  });
+
+  test("a token the server accepts stays", async () => {
+    const storage = memoryStorage({ "pylon:miles:token": "good" });
+    stubFetch(() => false, { ok: true });
+    await engine(storage).fn("resetDemoDealership", {});
+    expect(storage.get("pylon:miles:token")).toBe("good");
+  });
+
+  test("an explicitly configured token is the caller's and stays", async () => {
+    const storage = memoryStorage({ "pylon:miles:token": "stale" });
+    stubFetch(() => true, { ok: true });
+    await engine(storage, { token: "stale" }).fn("resetDemoDealership", {});
+    expect(storage.get("pylon:miles:token")).toBe("stale");
+  });
+});

package/src/index.ts

@@ -9,6 +9,8 @@
 // ---------------------------------------------------------------------------
 
 import {
+  bearerRejected,
+  clearRejectedToken,
   pylonFetch,
   PylonHttpError,
   type TransportConfig,
@@ -45,7 +47,10 @@ export {
 export { IndexedDBPersistence, persistChange } from "./persistence";
 export type { ReplicaPersistence } from "./persistence";
 export {
+  BEARER_REJECTED_HEADER,
+  bearerRejected,
   buildRequest,
+  clearRejectedToken,
   pylonFetch,
   pylonFetchRaw,
   PylonHttpError,
@@ -1922,6 +1927,7 @@ export class SyncEngine {
             void this.pull();
           }
         },
+        onBearerRejected: (token) => this.dropRejectedToken(token),
       },
       path,
       {
@@ -2700,6 +2706,29 @@ export class SyncEngine {
     );
   }
 
+  /**
+   * The server answered with `X-Pylon-Bearer-Rejected`: the token the request
+   * sent resolved to no one (expired, revoked, or not a session of this app).
+   * Clear it from the app's namespace so later requests stop sending it and
+   * the session cookie, when there is one, applies alone. A token passed in
+   * `config.token` belongs to the caller and stays.
+   */
+  private dropRejectedToken(token: string): void {
+    if (this.config.token) return;
+    if (clearRejectedToken(this.storage, this.tokenStorageKey(), token)) {
+      console.warn(
+        "[pylon] the server rejected the stored auth token (expired, revoked, " +
+          "or issued by another app) and it has been cleared. Requests now " +
+          "authenticate with the session cookie when there is one.",
+      );
+    }
+  }
+
+  /** `dropRejectedToken` for a response to a request that sent `token`. */
+  private observeBearerVerdict(res: Response, token: string | null | undefined): void {
+    if (token && bearerRejected(res)) this.dropRejectedToken(token);
+  }
+
   /**
    * Apply a freshly-observed session through the resolver and act on
    * the verdict. Serialized via `sessionChain` so concurrent triggers
@@ -2899,10 +2928,12 @@ export class SyncEngine {
     // same → `resetReplica` never fires on /api/auth/select-org
     // → the local store keeps every previous tenant's rows in
     // cache and `db.useQuery` returns stale data after a switch.
-    return fetch(`${this.config.baseUrl}${path}`, {
+    const res = await fetch(`${this.config.baseUrl}${path}`, {
       headers,
       credentials: "include",
     });
+    this.observeBearerVerdict(res, token);
+    return res;
   }
 
   /**
@@ -3040,6 +3071,7 @@ export class SyncEngine {
         headers,
         credentials: "include",
       });
+      this.observeBearerVerdict(res, token);
       if (!res.ok) return null;
       const body = (await res.json()) as { token?: string; url?: string };
       if (!body.token || !body.url) return null;
@@ -3076,6 +3108,7 @@ export class SyncEngine {
       credentials: "include",
       body: body !== undefined ? JSON.stringify(body) : undefined,
     });
+    this.observeBearerVerdict(res, token);
     const text = await res.text();
     let parsed: unknown = null;
     if (text) {
@@ -4220,6 +4253,7 @@ export class SyncEngine {
       credentials: "include",
       body: body ? JSON.stringify(body) : undefined,
     });
+    this.observeBearerVerdict(res, token);
 
     if (!res.ok) {
       // Surface the status so the caller can distinguish transient

package/src/transport.ts

@@ -16,6 +16,9 @@
 //  - X-Pylon-Change-Seq response header surfaced via the optional
 //    `onChangeSeq` callback (so callers can trigger catch-up pulls
 //    when a mutation's seq exceeds their local cursor)
+//  - X-Pylon-Bearer-Rejected response header surfaced via the optional
+//    `onBearerRejected` callback (so the owner of a stored token can
+//    clear a token the server no longer accepts)
 //
 // Streaming + raw-binary callers (file uploads, SSE) bypass the
 // JSON-parse step but reuse the URL/auth/credentials logic via
@@ -40,6 +43,48 @@ export interface TransportConfig {
    *  header when the server sets one. Returning a Promise pauses no
    *  one — the transport doesn't await it. */
   onChangeSeq?: (seq: number) => void;
+  /** Invoked with the bearer token a request sent when the server answers
+   *  with `X-Pylon-Bearer-Rejected: 1`: the server resolved the token to no
+   *  one (unknown, expired, or revoked). The code that stored the token
+   *  clears it here, so later requests stop sending it. */
+  onBearerRejected?: (token: string) => void;
+}
+
+/** Response header the server sets when the request's bearer token resolved
+ *  to no one. Lower case, as `Headers.get` matches without case. */
+export const BEARER_REJECTED_HEADER = "x-pylon-bearer-rejected";
+
+/** True when the server marked the bearer token the request sent as rejected. */
+export function bearerRejected(res: Response): boolean {
+  return res.headers?.get?.(BEARER_REJECTED_HEADER) === "1";
+}
+
+/**
+ * Remove a token the server rejected from `storage`, together with its
+ * `:userId` sibling. Only removes it when `key` still holds that exact token,
+ * so a sign-in that wrote a new token while the request was in flight keeps
+ * its token.
+ *
+ * The default unprefixed key `pylon_token` is left alone. Every app on an
+ * origin that has no `appName` shares it, so the token can belong to another
+ * app. Returns true when the token was removed.
+ */
+export function clearRejectedToken(
+  storage: { get(key: string): string | null; remove(key: string): void },
+  key: string,
+  token: string,
+): boolean {
+  if (key === "pylon_token") return false;
+  try {
+    if (storage.get(key) !== token) return false;
+    storage.remove(key);
+    if (key.endsWith(":token")) storage.remove(key.replace(/:token$/, ":userId"));
+    return true;
+  } catch {
+    // Storage can throw (Safari private mode). The token stays; the server
+    // keeps answering with the session cookie.
+    return false;
+  }
 }
 
 /**
@@ -90,13 +135,13 @@ export function buildRequest(
   config: TransportConfig,
   path: string,
   init: PylonRequestInit = {},
-): { url: string; init: RequestInit } {
+): { url: string; init: RequestInit; token?: string } {
   const base = resolveBaseUrl(config);
   const url = `${base}${path}`;
   const headers: Record<string, string> = { ...(init.headers ?? {}) };
   // Auth: explicit getToken wins over static token. Either may be
   // null/undefined — cookie-auth apps rely solely on credentials.
-  const token = config.getToken?.() ?? config.token;
+  const token = config.getToken?.() ?? config.token ?? undefined;
   if (token) headers["Authorization"] = `Bearer ${token}`;
   if (init.accept) headers["Accept"] = init.accept;
   let body: BodyInit | undefined = init.body;
@@ -106,6 +151,7 @@ export function buildRequest(
   }
   return {
     url,
+    token: token || undefined,
     init: {
       method: init.method ?? (body !== undefined ? "POST" : "GET"),
       headers,
@@ -153,8 +199,9 @@ export async function pylonFetch<T = unknown>(
   path: string,
   init: PylonRequestInit = {},
 ): Promise<T> {
-  const { url, init: req } = buildRequest(config, path, init);
+  const { url, init: req, token } = buildRequest(config, path, init);
   const res = await fetch(url, req);
+  reportBearerVerdict(config, res, token);
   const text = await res.text();
   let parsed: unknown = null;
   if (text) {
@@ -200,6 +247,19 @@ export async function pylonFetchRaw(
   path: string,
   init: PylonRequestInit = {},
 ): Promise<Response> {
-  const { url, init: req } = buildRequest(config, path, init);
-  return fetch(url, req);
+  const { url, init: req, token } = buildRequest(config, path, init);
+  const res = await fetch(url, req);
+  reportBearerVerdict(config, res, token);
+  return res;
+}
+
+/** Call `config.onBearerRejected` when the server rejected the token sent. */
+function reportBearerVerdict(
+  config: TransportConfig,
+  res: Response,
+  token: string | undefined,
+): void {
+  if (token && config.onBearerRejected && bearerRejected(res)) {
+    config.onBearerRejected(token);
+  }
 }