cursedbelt-core 2.15.0 → 2.16.0

package/dist/ctgr/codec.js

@@ -18,8 +18,9 @@ import { sha256Hex } from './digest.js';
 import { ABBREV_TO_METHOD, CTGR_WIRE_VERSION, METHOD_TO_ABBREV, } from './types.js';
 const DEFAULT_CHUNK_SIZE = 1800;
 const DEFAULT_GZIP_THRESHOLD = 1024;
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
+// Pure, so a bundler can leave the codec out of a chunk that only lazy-loads it (forge task 4805).
+const textEncoder = /* @__PURE__ */ new TextEncoder();
+const textDecoder = /* @__PURE__ */ new TextDecoder();
 /**
  * Encode a mutating request into one or more `/ctgr<XX>` GET-twin chunks. Small
  * bodies become a single chunk; large bodies gzip (when over the threshold) and split

package/dist/ctgr/crc32.js

@@ -3,7 +3,9 @@
  * native addon. Client and server share this exact implementation so a chunk's
  * `_crc` integrity check computes the same value on both ends of the tunnel.
  */
-const TABLE = (() => {
+// Marked pure so a bundler drops the table with the codec: a client that lazy-loads the codec
+// (`installCtgrFetch`) must not carry it in its entry chunk (forge task 4805).
+const TABLE = /* @__PURE__ */ (() => {
     const table = new Uint32Array(256);
     for (let n = 0; n < 256; n++) {
         let c = n;

package/dist/ctgrClient/ctgrFetch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The same-origin `/api/…` path (with its query) a URL names, or null when it is another
+ * origin or a path the request layer does not own (Cloudflare's `/cdn-cgi/rum` beacon, an
+ * asset, a twin that is already converted).
+ */
+export declare const ownApiPath: (rawUrl: string, base: string) => string | null;
+/**
+ * Arm the guard, then route every same-origin `/api/` mutation through the GET tunnel while
+ * the mode is on. Call once at boot, after `applyCtgrFromLocation()` and before anything
+ * fetches. Idempotent; a no-op with no `window.fetch`.
+ */
+export declare const installCtgrFetch: () => void;

package/dist/ctgrClient/ctgrFetch.js

@@ -0,0 +1,88 @@
+/*
+ * GET-only mode for a whole site in ONE boot call: `installCtgrFetch()`.
+ *
+ * auth and desk route each request through `convertIfOnlyGETRequests` + `sendCtgrRequests`
+ * by hand, inside their own API client. An app whose mutations are spread over dozens of
+ * `fetch` call sites (music, 2026-11-09: the owner opened it with `?ctgr=1` on a machine whose
+ * network refuses every non-GET, and nothing in it went through the tunnel) would need each
+ * one rewritten. This wraps `window.fetch` instead: while the device's mode is on, a mutating
+ * request to this origin's own `/api/…` leaves as its `/ctgr<xx>` GET twin(s) and answers with
+ * the one real response; everything else — a GET, another origin, a path the app does not own
+ * — passes through untouched. With the mode off it is a pass-through.
+ *
+ * 🔴 It arms the guard FIRST and wraps it, never the other way round: wrapped by the guard,
+ * a POST would be refused before it could be converted. The server half is `mountCtgrTunnel`
+ * (`cursedbelt-server/ctgr-tunnel`), which re-dispatches each twin into the real route.
+ */
+import { isCtgrModeOn } from './ctgrConfig.js';
+import { installCtgrGuard } from './ctgrGuard.js';
+/**
+ * The codec (gzip, sha-256, crc, base64url) loads only on a device that is in the mode: in an
+ * app's entry chunk it cost every visitor ~4.5 kB gzip (music, measured 2026-11-09) for a path
+ * almost none of them take. A bundler splits it out at this `import()`.
+ */
+const loadTunnel = () => Promise.all([import('./convertRequest.js'), import('./sendRequests.js')]).then(([c, s]) => ({
+    convertIfOnlyGETRequests: c.convertIfOnlyGETRequests,
+    sendCtgrRequests: s.sendCtgrRequests,
+}));
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * The same-origin `/api/…` path (with its query) a URL names, or null when it is another
+ * origin or a path the request layer does not own (Cloudflare's `/cdn-cgi/rum` beacon, an
+ * asset, a twin that is already converted).
+ */
+export const ownApiPath = (rawUrl, base) => {
+    try {
+        const u = new URL(rawUrl, base);
+        if (u.origin !== new URL(base).origin)
+            return null;
+        return u.pathname.startsWith('/api/') ? `${u.pathname}${u.search}` : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** A `Request`'s body as something the converter carries: its form, or its text. */
+const bodyOfRequest = async (request) => {
+    if (!request.body)
+        return undefined;
+    const type = request.headers.get('content-type') ?? '';
+    return type.includes('multipart/form-data') ? request.clone().formData() : request.clone().text();
+};
+let installed = false;
+/**
+ * Arm the guard, then route every same-origin `/api/` mutation through the GET tunnel while
+ * the mode is on. Call once at boot, after `applyCtgrFromLocation()` and before anything
+ * fetches. Idempotent; a no-op with no `window.fetch`.
+ */
+export const installCtgrFetch = () => {
+    if (installed || typeof window === 'undefined' || typeof window.fetch !== 'function')
+        return;
+    installed = true;
+    installCtgrGuard();
+    const inner = window.fetch.bind(window);
+    const tunnelled = async (input, init) => {
+        if (!isCtgrModeOn())
+            return inner(input, init);
+        const request = input instanceof Request ? input : null;
+        const method = (init?.method ?? request?.method ?? 'GET').toUpperCase();
+        if (SAFE_METHODS.has(method))
+            return inner(input, init);
+        const href = request ? request.url : input instanceof URL ? input.href : String(input);
+        const path = ownApiPath(href, window.location.href);
+        if (path === null)
+            return inner(input, init);
+        const effective = { ...init, method };
+        if (request) {
+            effective.headers ??= request.headers;
+            effective.credentials ??= request.credentials;
+            effective.signal ??= request.signal;
+            if (init?.body === undefined)
+                effective.body = await bodyOfRequest(request);
+        }
+        const { convertIfOnlyGETRequests, sendCtgrRequests } = await loadTunnel();
+        const { requests } = await convertIfOnlyGETRequests(path, effective);
+        return sendCtgrRequests(requests, (twin) => inner(twin.url, twin.init));
+    };
+    window.fetch = tunnelled;
+};

package/dist/ctgrClient/index.d.ts

@@ -1,4 +1,5 @@
 export { applyCtgrFromLocation, applyCtgrIntent, isCtgrModeOn, readCtgrIntent, setCtgrMode, } from './ctgrConfig.js';
 export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrFetch, ownApiPath } from './ctgrFetch.js';
 export { installCtgrGuard } from './ctgrGuard.js';
 export { CTGR_INCOMPLETE_STATUS, type CtgrSend, type SendCtgrOptions, sendCtgrRequests, } from './sendRequests.js';

package/dist/ctgrClient/index.js

@@ -9,9 +9,12 @@
  * The wire codec is `cursedbelt-core/ctgr`; the server that decodes the twins is
  * `cursedbelt-server` (`mountCtgrTunnel`). A site opts in with two boot calls —
  * `applyCtgrFromLocation()` then `installCtgrGuard()` — and routes its requests
- * through `convertIfOnlyGETRequests`, then `sendCtgrRequests`.
+ * through `convertIfOnlyGETRequests`, then `sendCtgrRequests`. A site whose mutations
+ * are spread over many `fetch` calls calls `installCtgrFetch()` instead of the guard,
+ * and every same-origin `/api/` mutation takes the tunnel with no call site changed.
  */
 export { applyCtgrFromLocation, applyCtgrIntent, isCtgrModeOn, readCtgrIntent, setCtgrMode, } from './ctgrConfig.js';
 export { convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrFetch, ownApiPath } from './ctgrFetch.js';
 export { installCtgrGuard } from './ctgrGuard.js';
 export { CTGR_INCOMPLETE_STATUS, sendCtgrRequests, } from './sendRequests.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.15.0",
+	"version": "2.16.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "Framework-agnostic core of the cursedbelt split — isomorphic domain logic. cwip below it, cursedbelt-server and cursedbelt (react) above it.",

package/src/ctgr/codec.ts

@@ -32,8 +32,9 @@ import {
 const DEFAULT_CHUNK_SIZE = 1800;
 const DEFAULT_GZIP_THRESHOLD = 1024;
 
-const textEncoder = new TextEncoder();
-const textDecoder = new TextDecoder();
+// Pure, so a bundler can leave the codec out of a chunk that only lazy-loads it (forge task 4805).
+const textEncoder = /* @__PURE__ */ new TextEncoder();
+const textDecoder = /* @__PURE__ */ new TextDecoder();
 
 /**
  * Encode a mutating request into one or more `/ctgr<XX>` GET-twin chunks. Small

package/src/ctgr/crc32.ts

@@ -3,7 +3,9 @@
  * native addon. Client and server share this exact implementation so a chunk's
  * `_crc` integrity check computes the same value on both ends of the tunnel.
  */
-const TABLE = (() => {
+// Marked pure so a bundler drops the table with the codec: a client that lazy-loads the codec
+// (`installCtgrFetch`) must not carry it in its entry chunk (forge task 4805).
+const TABLE = /* @__PURE__ */ (() => {
   const table = new Uint32Array(256);
   for (let n = 0; n < 256; n++) {
     let c = n;

package/src/ctgrClient/ctgrFetch.spec.ts

@@ -0,0 +1,111 @@
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from 'bun:test';
+import { decodeRequest } from '../ctgr/index.js';
+import { installCtgrFetch, ownApiPath, setCtgrMode } from './index.js';
+
+/** What reached the network under the shim: the URL and the method, in order. */
+let wire: { url: string; method: string }[] = [];
+const original = window.fetch;
+
+beforeAll(() => {
+  // The "network": records what it was handed and answers 200 with the URL it saw.
+  window.fetch = (async (input: RequestInfo | URL, init?: RequestInit) => {
+    const url = input instanceof Request ? input.url : String(input);
+    const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+    wire.push({ url, method });
+    return new Response(JSON.stringify({ url }), { status: 200 });
+  }) as typeof window.fetch;
+  installCtgrFetch();
+});
+
+afterAll(() => {
+  window.fetch = original;
+});
+
+beforeEach(() => {
+  wire = [];
+  localStorage.clear();
+});
+
+const decodedTwin = async (url: string) => {
+  const decoded = await decodeRequest(new URL(url, 'http://x').searchParams);
+  if (decoded === 'partial') throw new Error('expected a single-chunk twin');
+  return decoded;
+};
+
+describe('installCtgrFetch — every own-API mutation takes the GET tunnel', () => {
+  test('mode OFF: a POST goes out as the POST it is', async () => {
+    await fetch('/api/plays', { method: 'POST', body: JSON.stringify({ id: 1 }) });
+    expect(wire).toEqual([{ url: '/api/plays', method: 'POST' }]);
+  });
+
+  test('mode ON: a POST leaves as its GET twin, carrying the body and the query', async () => {
+    setCtgrMode(true);
+    const res = await fetch('/api/plays?x=1', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ id: 1 }),
+    });
+    expect(res.status).toBe(200);
+    expect(wire).toHaveLength(1);
+    expect(wire[0]?.method).toBe('GET');
+    expect(wire[0]?.url.startsWith('/ctgrpo/api/plays?x=1&')).toBe(true);
+    const decoded = await decodedTwin(wire[0]?.url ?? '');
+    expect(decoded.method).toBe('POST');
+    expect(decoded.body).toEqual({ id: 1 });
+  });
+
+  test('mode ON: a Request object is read for its method and body', async () => {
+    setCtgrMode(true);
+    const url = new URL('/api/playlists/7', window.location.href).href;
+    await fetch(new Request(url, { method: 'PATCH', body: JSON.stringify({ name: 'b' }) }));
+    expect(wire[0]?.method).toBe('GET');
+    const decoded = await decodedTwin(wire[0]?.url ?? '');
+    expect(decoded.method).toBe('PATCH');
+    expect(decoded.body).toEqual({ name: 'b' });
+  });
+
+  test('mode ON: GETs, other origins and paths outside /api/ pass through untouched', async () => {
+    setCtgrMode(true);
+    await fetch('/api/library');
+    await fetch('https://media.example.com/api/upload', { method: 'POST', body: 'x' });
+    await fetch('/cdn-cgi/rum', { method: 'POST', body: 'x' });
+    expect(wire).toEqual([
+      { url: '/api/library', method: 'GET' },
+      { url: 'https://media.example.com/api/upload', method: 'POST' },
+      { url: '/cdn-cgi/rum', method: 'POST' },
+    ]);
+  });
+});
+
+describe('ownApiPath', () => {
+  const base = 'https://music.example.com/library';
+  test('a same-origin /api/ path, absolute or relative, keeps its query', () => {
+    expect(ownApiPath('/api/a?b=1', base)).toBe('/api/a?b=1');
+    expect(ownApiPath('https://music.example.com/api/a', base)).toBe('/api/a');
+  });
+  test('another origin, or a path the app does not own, is null', () => {
+    expect(ownApiPath('https://auth.example.com/api/a', base)).toBeNull();
+    expect(ownApiPath('/ctgrpo/api/a', base)).toBeNull();
+    expect(ownApiPath('/assets/x.js', base)).toBeNull();
+  });
+});
+
+describe('the codec stays out of an entry chunk that only boots the mode (forge task 4805)', () => {
+  const read = (rel: string) => Bun.file(new URL(rel, import.meta.url)).text();
+
+  test('ctgrFetch reaches the converter and the sender only through import()', async () => {
+    const src = await read('./ctgrFetch.ts');
+    expect(src).not.toMatch(/^import [^;]*from '\.\/(convertRequest|sendRequests)\.js'/m);
+    expect(src).toContain("import('./convertRequest.js')");
+    expect(src).toContain("import('./sendRequests.js')");
+  });
+
+  test('every top-level `new` or IIFE in the codec is marked pure, so a bundler can drop it', async () => {
+    for (const rel of ['../ctgr/codec.ts', '../ctgr/crc32.ts']) {
+      const offenders = (await read(rel))
+        .split('\n')
+        .filter((line) => /^(const|let) \w+ = (new |\()/.test(line));
+      expect({ rel, offenders }).toEqual({ rel, offenders: [] });
+    }
+  });
+});

package/src/ctgrClient/ctgrFetch.ts

@@ -0,0 +1,88 @@
+/*
+ * GET-only mode for a whole site in ONE boot call: `installCtgrFetch()`.
+ *
+ * auth and desk route each request through `convertIfOnlyGETRequests` + `sendCtgrRequests`
+ * by hand, inside their own API client. An app whose mutations are spread over dozens of
+ * `fetch` call sites (music, 2026-11-09: the owner opened it with `?ctgr=1` on a machine whose
+ * network refuses every non-GET, and nothing in it went through the tunnel) would need each
+ * one rewritten. This wraps `window.fetch` instead: while the device's mode is on, a mutating
+ * request to this origin's own `/api/…` leaves as its `/ctgr<xx>` GET twin(s) and answers with
+ * the one real response; everything else — a GET, another origin, a path the app does not own
+ * — passes through untouched. With the mode off it is a pass-through.
+ *
+ * 🔴 It arms the guard FIRST and wraps it, never the other way round: wrapped by the guard,
+ * a POST would be refused before it could be converted. The server half is `mountCtgrTunnel`
+ * (`cursedbelt-server/ctgr-tunnel`), which re-dispatches each twin into the real route.
+ */
+import { isCtgrModeOn } from './ctgrConfig.js';
+import { installCtgrGuard } from './ctgrGuard.js';
+
+/**
+ * The codec (gzip, sha-256, crc, base64url) loads only on a device that is in the mode: in an
+ * app's entry chunk it cost every visitor ~4.5 kB gzip (music, measured 2026-11-09) for a path
+ * almost none of them take. A bundler splits it out at this `import()`.
+ */
+const loadTunnel = () =>
+  Promise.all([import('./convertRequest.js'), import('./sendRequests.js')]).then(([c, s]) => ({
+    convertIfOnlyGETRequests: c.convertIfOnlyGETRequests,
+    sendCtgrRequests: s.sendCtgrRequests,
+  }));
+
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+
+/**
+ * The same-origin `/api/…` path (with its query) a URL names, or null when it is another
+ * origin or a path the request layer does not own (Cloudflare's `/cdn-cgi/rum` beacon, an
+ * asset, a twin that is already converted).
+ */
+export const ownApiPath = (rawUrl: string, base: string): string | null => {
+  try {
+    const u = new URL(rawUrl, base);
+    if (u.origin !== new URL(base).origin) return null;
+    return u.pathname.startsWith('/api/') ? `${u.pathname}${u.search}` : null;
+  } catch {
+    return null;
+  }
+};
+
+/** A `Request`'s body as something the converter carries: its form, or its text. */
+const bodyOfRequest = async (request: Request): Promise<BodyInit | undefined> => {
+  if (!request.body) return undefined;
+  const type = request.headers.get('content-type') ?? '';
+  return type.includes('multipart/form-data') ? request.clone().formData() : request.clone().text();
+};
+
+let installed = false;
+
+/**
+ * Arm the guard, then route every same-origin `/api/` mutation through the GET tunnel while
+ * the mode is on. Call once at boot, after `applyCtgrFromLocation()` and before anything
+ * fetches. Idempotent; a no-op with no `window.fetch`.
+ */
+export const installCtgrFetch = (): void => {
+  if (installed || typeof window === 'undefined' || typeof window.fetch !== 'function') return;
+  installed = true;
+  installCtgrGuard();
+  const inner = window.fetch.bind(window);
+  const tunnelled = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    if (!isCtgrModeOn()) return inner(input, init);
+    const request = input instanceof Request ? input : null;
+    const method = (init?.method ?? request?.method ?? 'GET').toUpperCase();
+    if (SAFE_METHODS.has(method)) return inner(input, init);
+    const href = request ? request.url : input instanceof URL ? input.href : String(input);
+    const path = ownApiPath(href, window.location.href);
+    if (path === null) return inner(input, init);
+
+    const effective: RequestInit = { ...init, method };
+    if (request) {
+      effective.headers ??= request.headers;
+      effective.credentials ??= request.credentials;
+      effective.signal ??= request.signal;
+      if (init?.body === undefined) effective.body = await bodyOfRequest(request);
+    }
+    const { convertIfOnlyGETRequests, sendCtgrRequests } = await loadTunnel();
+    const { requests } = await convertIfOnlyGETRequests(path, effective);
+    return sendCtgrRequests(requests, (twin) => inner(twin.url, twin.init));
+  };
+  window.fetch = tunnelled as typeof window.fetch;
+};

package/src/ctgrClient/index.ts

@@ -9,7 +9,9 @@
  * The wire codec is `cursedbelt-core/ctgr`; the server that decodes the twins is
  * `cursedbelt-server` (`mountCtgrTunnel`). A site opts in with two boot calls —
  * `applyCtgrFromLocation()` then `installCtgrGuard()` — and routes its requests
- * through `convertIfOnlyGETRequests`, then `sendCtgrRequests`.
+ * through `convertIfOnlyGETRequests`, then `sendCtgrRequests`. A site whose mutations
+ * are spread over many `fetch` calls calls `installCtgrFetch()` instead of the guard,
+ * and every same-origin `/api/` mutation takes the tunnel with no call site changed.
  */
 export {
   applyCtgrFromLocation,
@@ -19,6 +21,7 @@ export {
   setCtgrMode,
 } from './ctgrConfig.js';
 export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrFetch, ownApiPath } from './ctgrFetch.js';
 export { installCtgrGuard } from './ctgrGuard.js';
 export {
   CTGR_INCOMPLETE_STATUS,