cursedbelt-core 2.6.0 → 2.8.0

package/dist/core/passwordPolicy.d.ts

@@ -1,15 +1,17 @@
 /**
  * The one place a satellite's owner-password floor is decided.
  *
- * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * ── Why this is shared, and why the default is 6 ────────────────────────────
  * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
  * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
  * a paragraph in each explaining itself against the others. A floor is a
  * POLICY, and a policy copied three times is three policies.
  *
- * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
- * owner wants for an ordinary satellite: long enough that it is not a PIN, short
- * enough that it does not push the owner toward writing it down or reusing one.
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 6 — the owner, 2026-09-24:
+ * *"make the minimum password length 6 characters"* (it was 9). It is a SIGN-IN
+ * floor: every door that uses it rate-limits guesses, so a short password costs
+ * an attacker attempts, not seconds. A secret that can be guessed OFFLINE (vault's
+ * passphrase, which derives its encryption key) raises it at its own call site.
  * Argon2id — what every caller hashes with — is what actually carries the cost
  * of a guess here; these apps have exactly ONE principal and no enumerable user
  * list, so the marginal value of characters 10–14 is small and the friction is
@@ -25,7 +27,7 @@
  * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
  * go below the default**. An app that genuinely runs at higher stakes says so
  * at its own call site, in one visible argument, with a comment saying why.
- * No app overrides it today — the retired orch companion app did (14, as the single
+ * `vault` does (9, since 2026-09-24 — its passphrase is an encryption key). The retired orch companion app did (14, as the single
  * internet-facing door into the host that runs `claude` in every repo) until
  * the owner dropped it to the shared floor on 2026-07-26.
  *
@@ -38,12 +40,12 @@
  * they read, so a multi-byte character counts as more than one, which is the
  * conservative direction).
  */
-export declare const DEFAULT_MIN_PASSWORD_BYTES = 9;
+export declare const DEFAULT_MIN_PASSWORD_BYTES = 6;
 /**
  * The floor this app enforces: the default, or a higher one it asks for.
  *
  * Throws on an override below the default rather than silently clamping. A
- * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * caller passing 4 believes it is enforcing 4; being handed 6 without a word is
  * how a security floor becomes folklore.
  */
 export declare function resolveMinPasswordBytes(override?: number): number;

package/dist/core/passwordPolicy.js

@@ -1,15 +1,17 @@
 /**
  * The one place a satellite's owner-password floor is decided.
  *
- * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * ── Why this is shared, and why the default is 6 ────────────────────────────
  * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
  * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
  * a paragraph in each explaining itself against the others. A floor is a
  * POLICY, and a policy copied three times is three policies.
  *
- * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
- * owner wants for an ordinary satellite: long enough that it is not a PIN, short
- * enough that it does not push the owner toward writing it down or reusing one.
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 6 — the owner, 2026-09-24:
+ * *"make the minimum password length 6 characters"* (it was 9). It is a SIGN-IN
+ * floor: every door that uses it rate-limits guesses, so a short password costs
+ * an attacker attempts, not seconds. A secret that can be guessed OFFLINE (vault's
+ * passphrase, which derives its encryption key) raises it at its own call site.
  * Argon2id — what every caller hashes with — is what actually carries the cost
  * of a guess here; these apps have exactly ONE principal and no enumerable user
  * list, so the marginal value of characters 10–14 is small and the friction is
@@ -25,7 +27,7 @@
  * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
  * go below the default**. An app that genuinely runs at higher stakes says so
  * at its own call site, in one visible argument, with a comment saying why.
- * No app overrides it today — the retired orch companion app did (14, as the single
+ * `vault` does (9, since 2026-09-24 — its passphrase is an encryption key). The retired orch companion app did (14, as the single
  * internet-facing door into the host that runs `claude` in every repo) until
  * the owner dropped it to the shared floor on 2026-07-26.
  *
@@ -38,12 +40,12 @@
  * they read, so a multi-byte character counts as more than one, which is the
  * conservative direction).
  */
-export const DEFAULT_MIN_PASSWORD_BYTES = 9;
+export const DEFAULT_MIN_PASSWORD_BYTES = 6;
 /**
  * The floor this app enforces: the default, or a higher one it asks for.
  *
  * Throws on an override below the default rather than silently clamping. A
- * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * caller passing 4 believes it is enforcing 4; being handed 6 without a word is
  * how a security floor becomes folklore.
  */
 export function resolveMinPasswordBytes(override) {

package/dist/ctgrClient/convertRequest.d.ts

@@ -0,0 +1,18 @@
+/** One converted request ready for `fetch`: the GET-twin path + the GET init. */
+export interface CtgrFetchRequest {
+    /** `/ctgr<xx><path>?<params>` — a path; the caller prepends any API prefix. */
+    url: string;
+    init: RequestInit;
+}
+/**
+ * Convert one request for the tunnel. Returns the chunked GET requests to send in
+ * order (usually one); when the mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ *
+ * `formData` may be passed explicitly, or left off and put on `init.body` (the shape
+ * a typed client already uses) — an `init.body` that is a `FormData` is detected and
+ * serialized the same way.
+ */
+export declare function convertIfOnlyGETRequests(url: string, init?: RequestInit, formData?: FormData): Promise<{
+    requests: CtgrFetchRequest[];
+}>;

package/dist/ctgrClient/convertRequest.js

@@ -0,0 +1,98 @@
+/*
+ * The browser half of the GET-only tunnel. When the mode is on, a mutating request
+ * is rewritten into one or more `/ctgr<xx>` GET twins via the isomorphic codec (gzip
+ * + single base64url + integrity); a plain GET passes through untouched. FormData
+ * uploads are serialized into the JSON body's `__files` shape (the server
+ * reconstructs the uploads from it). When the mode is off, every request passes
+ * through unchanged.
+ */
+import { encodeRequest, METHOD_TO_ABBREV, toBase64, } from '../ctgr/index.js';
+import { isCtgrModeOn } from './ctgrConfig.js';
+// 10 MB per-file cap for GET-only mode. base64 + URL transport inflates each file and
+// needs many sequential GETs per MB; beyond this the upload hangs/OOMs on mobile.
+const CTGR_MAX_FILE_BYTES = 10 * 1024 * 1024;
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+/**
+ * Convert one request for the tunnel. Returns the chunked GET requests to send in
+ * order (usually one); when the mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ *
+ * `formData` may be passed explicitly, or left off and put on `init.body` (the shape
+ * a typed client already uses) — an `init.body` that is a `FormData` is detected and
+ * serialized the same way.
+ */
+export async function convertIfOnlyGETRequests(url, init = { method: 'GET' }, formData) {
+    const form = formData ??
+        (typeof FormData !== 'undefined' && init.body instanceof FormData ? init.body : undefined);
+    const method = (init.method ?? (form ? 'POST' : 'GET')).toUpperCase();
+    if (!isCtgrModeOn() || (SAFE_METHODS.has(method) && !form)) {
+        return { requests: [{ url, init }] };
+    }
+    const upper = method;
+    if (!METHOD_TO_ABBREV[upper]) {
+        throw new Error(`ctgr: "${method}" is not a tunnelable method`);
+    }
+    const body = form ? await formDataToBody(form) : bodyFromInit(init.body);
+    const getInit = toGetInit(init);
+    const { chunks } = await encodeRequest(upper, url, body);
+    return { requests: chunks.map((chunk) => ({ url: chunk.url, init: getInit })) };
+}
+/** Turn a FormData upload into the `__files` JSON body shape the GET path carries. */
+async function formDataToBody(formData) {
+    const files = [];
+    const fields = {};
+    for (const [key, value] of formData.entries()) {
+        if (typeof value === 'object' && value !== null && 'arrayBuffer' in value) {
+            const file = value;
+            if (file.size > CTGR_MAX_FILE_BYTES) {
+                throw new Error(`"${file.name}" (${Math.round(file.size / 1024 / 1024)} MB) is too large to upload in ` +
+                    `GET-only mode`);
+            }
+            files.push({
+                field: key,
+                name: file.name,
+                type: file.type,
+                dataBase64: toBase64(new Uint8Array(await file.arrayBuffer())),
+            });
+        }
+        else {
+            fields[key] = String(value);
+        }
+    }
+    return { __files: files, ...fields };
+}
+/** The request body as a JS value: a JSON string is parsed; anything else passes through. */
+function bodyFromInit(body) {
+    if (typeof body !== 'string')
+        return body ?? undefined;
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return body;
+    }
+}
+/** A GET copy of the init: no body, and the now-meaningless content-type dropped. */
+function toGetInit(init) {
+    const next = { ...init, method: 'GET', headers: stripContentType(init.headers) };
+    delete next.body;
+    return next;
+}
+function stripContentType(headers) {
+    if (!headers)
+        return headers;
+    if (headers instanceof Headers) {
+        const next = new Headers(headers);
+        next.delete('content-type');
+        return next;
+    }
+    if (Array.isArray(headers)) {
+        return headers.filter(([key]) => key.toLowerCase() !== 'content-type');
+    }
+    const next = {};
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() !== 'content-type')
+            next[key] = value;
+    }
+    return next;
+}

package/dist/ctgrClient/ctgrConfig.d.ts

@@ -0,0 +1,23 @@
+export declare const isCtgrModeOn: () => boolean;
+export declare const setCtgrMode: (on: boolean) => void;
+/**
+ * The state a `ctgr` query value asks for: on, off, or (unknown/absent) leave the
+ * device as it is. Pure — no storage, no DOM — so it is trivially testable and the
+ * one place the accepted spellings live.
+ */
+export declare const readCtgrIntent: (value: string | null | undefined) => "on" | "off" | "keep";
+/**
+ * Apply a `ctgr` query value to this device's persisted mode and report whether the
+ * mode is on afterwards. Called by `applyCtgrFromLocation` with the value read off
+ * the URL; exposed on its own so a host that already parsed its query can reuse it.
+ */
+export declare const applyCtgrIntent: (value: string | null | undefined) => boolean;
+/**
+ * Boot hook: read `?ctgr=…` off the current location (or a supplied search string /
+ * URL), persist the change for this device, and return whether the mode is on. Safe
+ * to call with no argument in the browser; returns `false` with no `window`.
+ *
+ * Call this ONCE, before the app issues its first request — pairing it with
+ * `installCtgrGuard()` so a request made during that first tick is still caught.
+ */
+export declare const applyCtgrFromLocation: (search?: string) => boolean;

package/dist/ctgrClient/ctgrConfig.js

@@ -0,0 +1,94 @@
+/*
+ * Single source of truth for GET-only request mode. When on, the request layer
+ * rewrites every mutating call to a GET (see `convertIfOnlyGETRequests`) and the
+ * network-boundary guard hard-blocks any raw non-GET. Both read this one flag, so
+ * they can never disagree.
+ *
+ * The mode is per-DEVICE, persisted in localStorage so it survives reloads and is
+ * never tied to an account — a device that has it on keeps it on, a device that does
+ * not never gains it. Default is OFF.
+ *
+ * A site sets it up front, before its first request, by reading the URL:
+ *   • `?ctgr=t` (or `on`/`1`/`yes`)  → turn on, persist for this device.
+ *   • `?ctgr=f` (or `off`/`0`/`no`)  → turn off, clear it for this device.
+ *   • no `ctgr` param               → whatever this device already had.
+ * `applyCtgrFromLocation()` is the one call that does this on boot.
+ */
+const CTGR_KEY = 'ctgr';
+const ON_VALUES = new Set(['t', 'on', '1', 'yes', 'true']);
+const OFF_VALUES = new Set(['f', 'off', '0', 'no', 'false']);
+export const isCtgrModeOn = () => {
+    try {
+        return localStorage.getItem(CTGR_KEY) === 'on';
+    }
+    catch {
+        return false;
+    }
+};
+export const setCtgrMode = (on) => {
+    try {
+        if (on)
+            localStorage.setItem(CTGR_KEY, 'on');
+        else
+            localStorage.removeItem(CTGR_KEY);
+    }
+    catch {
+        // localStorage unavailable (private mode / SSR) — nothing to persist.
+    }
+};
+/**
+ * The state a `ctgr` query value asks for: on, off, or (unknown/absent) leave the
+ * device as it is. Pure — no storage, no DOM — so it is trivially testable and the
+ * one place the accepted spellings live.
+ */
+export const readCtgrIntent = (value) => {
+    if (value == null)
+        return 'keep';
+    const v = value.trim().toLowerCase();
+    if (ON_VALUES.has(v))
+        return 'on';
+    if (OFF_VALUES.has(v))
+        return 'off';
+    return 'keep';
+};
+/**
+ * Apply a `ctgr` query value to this device's persisted mode and report whether the
+ * mode is on afterwards. Called by `applyCtgrFromLocation` with the value read off
+ * the URL; exposed on its own so a host that already parsed its query can reuse it.
+ */
+export const applyCtgrIntent = (value) => {
+    const intent = readCtgrIntent(value);
+    if (intent === 'on')
+        setCtgrMode(true);
+    else if (intent === 'off')
+        setCtgrMode(false);
+    return isCtgrModeOn();
+};
+/**
+ * Boot hook: read `?ctgr=…` off the current location (or a supplied search string /
+ * URL), persist the change for this device, and return whether the mode is on. Safe
+ * to call with no argument in the browser; returns `false` with no `window`.
+ *
+ * Call this ONCE, before the app issues its first request — pairing it with
+ * `installCtgrGuard()` so a request made during that first tick is still caught.
+ */
+export const applyCtgrFromLocation = (search) => {
+    let query = search;
+    if (query === undefined) {
+        if (typeof window === 'undefined' || !window.location)
+            return isCtgrModeOn();
+        query = window.location.search;
+    }
+    let value = null;
+    try {
+        // Accept a bare search (`?ctgr=t`), a full href, or already-extracted params.
+        const params = query.includes('://')
+            ? new URL(query).searchParams
+            : new URLSearchParams(query.startsWith('?') ? query.slice(1) : query);
+        value = params.get(CTGR_KEY);
+    }
+    catch {
+        value = null;
+    }
+    return applyCtgrIntent(value);
+};

package/dist/ctgrClient/ctgrGuard.d.ts

@@ -0,0 +1 @@
+export declare const installCtgrGuard: () => void;

package/dist/ctgrClient/ctgrGuard.js

@@ -0,0 +1,83 @@
+/*
+ * Safety net for GET-only mode. Even though the request layer is supposed to rewrite
+ * every mutating call to a GET (`convertIfOnlyGETRequests`), this guard sits at the
+ * actual network boundary and hard-blocks any non-GET request to our own API surface
+ * when the mode is on — so a code path that forgot to run through the converter can
+ * never put a raw POST/PUT/PATCH/DELETE on the wire. Catches both `fetch` and
+ * `XMLHttpRequest`. It only ever tightens; it must never weaken.
+ */
+import { isCtgrModeOn } from './ctgrConfig.js';
+// Methods that never mutate and are always safe to allow.
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+const urlOf = (input) => {
+    if (typeof input === 'string')
+        return input;
+    if (input instanceof URL)
+        return input.href;
+    if (input instanceof Request)
+        return input.url;
+    return String(input);
+};
+// Only guard our OWN API surface — same-origin AND under a path the request layer
+// owns (`/api/…` or a `/ctgr<xx>` twin). Restricting to these prefixes (rather than
+// "any same-origin path") matters: same-origin also covers paths we do not own, like
+// Cloudflare's `/cdn-cgi/rum` beacon, which fires a raw POST on every page view —
+// guarding it would break RUM and fire for every ordinary visitor, not just a
+// misbehaving call site.
+const isGuardedPath = (rawUrl) => {
+    let path;
+    if (rawUrl.startsWith('/')) {
+        path = rawUrl;
+    }
+    else {
+        try {
+            const u = new URL(rawUrl, window.location.href);
+            if (u.origin !== window.location.origin)
+                return false;
+            path = u.pathname;
+        }
+        catch {
+            return false;
+        }
+    }
+    return path.startsWith('/api/') || path.startsWith('/ctgr');
+};
+// Deliberately generic: this message can reach the console of ANY visitor, so it says
+// nothing about the request layer, the call site, or what a blocked request was.
+const block = () => {
+    const message = 'Service unavailable.';
+    console.error(message, new Error('blocked request'));
+    return new Error(message);
+};
+let installed = false;
+export const installCtgrGuard = () => {
+    if (installed || typeof window === 'undefined')
+        return;
+    installed = true;
+    // ── fetch ──────────────────────────────────────────────────────────────────
+    if (typeof window.fetch === 'function') {
+        const originalFetch = window.fetch.bind(window);
+        const guardedFetch = (input, init) => {
+            const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+            const url = urlOf(input);
+            if (isCtgrModeOn() && !SAFE_METHODS.has(method) && isGuardedPath(url)) {
+                return Promise.reject(block());
+            }
+            return originalFetch(input, init);
+        };
+        window.fetch = guardedFetch;
+    }
+    // ── XMLHttpRequest ───────────────────────────────────────────────────────────
+    if (typeof XMLHttpRequest !== 'undefined') {
+        const originalOpen = XMLHttpRequest.prototype.open;
+        // biome-ignore lint/suspicious/noExplicitAny: matching XHR.open's variadic overloads
+        XMLHttpRequest.prototype.open = function open(method, url, ...rest) {
+            const upper = String(method).toUpperCase();
+            if (isCtgrModeOn() && !SAFE_METHODS.has(upper) && isGuardedPath(String(url))) {
+                throw block();
+            }
+            // biome-ignore lint/suspicious/noExplicitAny: forwarding the original variadic call
+            return originalOpen.call(this, method, url, ...rest);
+        };
+    }
+};

package/dist/ctgrClient/index.d.ts

@@ -0,0 +1,3 @@
+export { applyCtgrFromLocation, applyCtgrIntent, isCtgrModeOn, readCtgrIntent, setCtgrMode, } from './ctgrConfig.js';
+export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrGuard } from './ctgrGuard.js';

package/dist/ctgrClient/index.js

@@ -0,0 +1,15 @@
+/*
+ * cursedbelt-core/ctgr-client — the browser adapters that turn any site into a
+ * GET-only client:
+ *   • the per-device mode flag + the `?ctgr=t|f` boot toggle (`ctgrConfig`),
+ *   • the request converter that rewrites a mutation into `/ctgr<xx>` GET twins,
+ *   • the network-boundary guard that blocks a stray raw verb.
+ *
+ * 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`.
+ */
+export { applyCtgrFromLocation, applyCtgrIntent, isCtgrModeOn, readCtgrIntent, setCtgrMode, } from './ctgrConfig.js';
+export { convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrGuard } from './ctgrGuard.js';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-core",
-	"version": "2.6.0",
+	"version": "2.8.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.",
@@ -371,6 +371,12 @@
 			"bun": "./src/client/wsWire.ts",
 			"source": "./src/client/wsWire.ts",
 			"import": "./dist/client/wsWire.js"
+		},
+		"./ctgr-client": {
+			"types": "./dist/ctgrClient/index.d.ts",
+			"bun": "./src/ctgrClient/index.ts",
+			"source": "./src/ctgrClient/index.ts",
+			"import": "./dist/ctgrClient/index.js"
 		}
 	},
 	"dependencies": {

package/src/core/passwordPolicy.spec.ts

@@ -7,13 +7,13 @@ import { DEFAULT_MIN_PASSWORD_BYTES, resolveMinPasswordBytes } from './passwordP
 describe('resolveMinPasswordBytes', () => {
   it('is the shared default when an app asks for nothing', () => {
     expect(resolveMinPasswordBytes()).toBe(DEFAULT_MIN_PASSWORD_BYTES);
-    expect(DEFAULT_MIN_PASSWORD_BYTES).toBe(9);
+    expect(DEFAULT_MIN_PASSWORD_BYTES).toBe(6);
   });
   it('lets an app raise it, visibly, at its own call site', () => {
     expect(resolveMinPasswordBytes(14)).toBe(14);
   });
   it('🔴 refuses to go BELOW the default, and refuses a non-integer', () => {
-    expect(() => resolveMinPasswordBytes(8)).toThrow(/may only be RAISED/);
-    expect(() => resolveMinPasswordBytes(9.5)).toThrow(/must be an integer/);
+    expect(() => resolveMinPasswordBytes(5)).toThrow(/may only be RAISED/);
+    expect(() => resolveMinPasswordBytes(6.5)).toThrow(/must be an integer/);
   });
 });

package/src/core/passwordPolicy.ts

@@ -1,15 +1,17 @@
 /**
  * The one place a satellite's owner-password floor is decided.
  *
- * ── Why this is shared, and why the default is 9 ────────────────────────────
+ * ── Why this is shared, and why the default is 6 ────────────────────────────
  * Three apps had independently written a `MIN_PASSWORD_BYTES` constant into
  * their own `scripts/owner.ts`, and they had already drifted (9, 14, 14) with
  * a paragraph in each explaining itself against the others. A floor is a
  * POLICY, and a policy copied three times is three policies.
  *
- * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 9, which is the floor the
- * owner wants for an ordinary satellite: long enough that it is not a PIN, short
- * enough that it does not push the owner toward writing it down or reusing one.
+ * The default is {@link DEFAULT_MIN_PASSWORD_BYTES} = 6 — the owner, 2026-09-24:
+ * *"make the minimum password length 6 characters"* (it was 9). It is a SIGN-IN
+ * floor: every door that uses it rate-limits guesses, so a short password costs
+ * an attacker attempts, not seconds. A secret that can be guessed OFFLINE (vault's
+ * passphrase, which derives its encryption key) raises it at its own call site.
  * Argon2id — what every caller hashes with — is what actually carries the cost
  * of a guess here; these apps have exactly ONE principal and no enumerable user
  * list, so the marginal value of characters 10–14 is small and the friction is
@@ -25,7 +27,7 @@
  * {@link resolveMinPasswordBytes} takes an optional override and **refuses to
  * go below the default**. An app that genuinely runs at higher stakes says so
  * at its own call site, in one visible argument, with a comment saying why.
- * No app overrides it today — the retired orch companion app did (14, as the single
+ * `vault` does (9, since 2026-09-24 — its passphrase is an encryption key). The retired orch companion app did (14, as the single
  * internet-facing door into the host that runs `claude` in every repo) until
  * the owner dropped it to the shared floor on 2026-07-26.
  *
@@ -39,13 +41,13 @@
  * they read, so a multi-byte character counts as more than one, which is the
  * conservative direction).
  */
-export const DEFAULT_MIN_PASSWORD_BYTES = 9;
+export const DEFAULT_MIN_PASSWORD_BYTES = 6;
 
 /**
  * The floor this app enforces: the default, or a higher one it asks for.
  *
  * Throws on an override below the default rather than silently clamping. A
- * caller passing 6 believes it is enforcing 6; being handed 9 without a word is
+ * caller passing 4 believes it is enforcing 4; being handed 6 without a word is
  * how a security floor becomes folklore.
  */
 export function resolveMinPasswordBytes(override?: number): number {

package/src/ctgrClient/convertRequest.ts

@@ -0,0 +1,123 @@
+/*
+ * The browser half of the GET-only tunnel. When the mode is on, a mutating request
+ * is rewritten into one or more `/ctgr<xx>` GET twins via the isomorphic codec (gzip
+ * + single base64url + integrity); a plain GET passes through untouched. FormData
+ * uploads are serialized into the JSON body's `__files` shape (the server
+ * reconstructs the uploads from it). When the mode is off, every request passes
+ * through unchanged.
+ */
+import {
+  type CtgrMethod,
+  encodeRequest,
+  METHOD_TO_ABBREV,
+  type SerializedFile,
+  toBase64,
+} from '../ctgr/index.js';
+import { isCtgrModeOn } from './ctgrConfig.js';
+
+/** One converted request ready for `fetch`: the GET-twin path + the GET init. */
+export interface CtgrFetchRequest {
+  /** `/ctgr<xx><path>?<params>` — a path; the caller prepends any API prefix. */
+  url: string;
+  init: RequestInit;
+}
+
+// 10 MB per-file cap for GET-only mode. base64 + URL transport inflates each file and
+// needs many sequential GETs per MB; beyond this the upload hangs/OOMs on mobile.
+const CTGR_MAX_FILE_BYTES = 10 * 1024 * 1024;
+
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+
+/**
+ * Convert one request for the tunnel. Returns the chunked GET requests to send in
+ * order (usually one); when the mode is off, or it is already a body-less GET, the
+ * original request passes through unchanged as a single entry.
+ *
+ * `formData` may be passed explicitly, or left off and put on `init.body` (the shape
+ * a typed client already uses) — an `init.body` that is a `FormData` is detected and
+ * serialized the same way.
+ */
+export async function convertIfOnlyGETRequests(
+  url: string,
+  init: RequestInit = { method: 'GET' },
+  formData?: FormData,
+): Promise<{ requests: CtgrFetchRequest[] }> {
+  const form =
+    formData ??
+    (typeof FormData !== 'undefined' && init.body instanceof FormData ? init.body : undefined);
+  const method = (init.method ?? (form ? 'POST' : 'GET')).toUpperCase();
+
+  if (!isCtgrModeOn() || (SAFE_METHODS.has(method) && !form)) {
+    return { requests: [{ url, init }] };
+  }
+
+  const upper = method as CtgrMethod;
+  if (!METHOD_TO_ABBREV[upper]) {
+    throw new Error(`ctgr: "${method}" is not a tunnelable method`);
+  }
+
+  const body: unknown = form ? await formDataToBody(form) : bodyFromInit(init.body);
+  const getInit = toGetInit(init);
+  const { chunks } = await encodeRequest(upper, url, body);
+  return { requests: chunks.map((chunk) => ({ url: chunk.url, init: getInit })) };
+}
+
+/** Turn a FormData upload into the `__files` JSON body shape the GET path carries. */
+async function formDataToBody(formData: FormData): Promise<Record<string, unknown>> {
+  const files: SerializedFile[] = [];
+  const fields: Record<string, string> = {};
+  for (const [key, value] of formData.entries()) {
+    if (typeof value === 'object' && value !== null && 'arrayBuffer' in value) {
+      const file = value as File;
+      if (file.size > CTGR_MAX_FILE_BYTES) {
+        throw new Error(
+          `"${file.name}" (${Math.round(file.size / 1024 / 1024)} MB) is too large to upload in ` +
+            `GET-only mode`,
+        );
+      }
+      files.push({
+        field: key,
+        name: file.name,
+        type: file.type,
+        dataBase64: toBase64(new Uint8Array(await file.arrayBuffer())),
+      });
+    } else {
+      fields[key] = String(value);
+    }
+  }
+  return { __files: files, ...fields };
+}
+
+/** The request body as a JS value: a JSON string is parsed; anything else passes through. */
+function bodyFromInit(body: BodyInit | null | undefined): unknown {
+  if (typeof body !== 'string') return body ?? undefined;
+  try {
+    return JSON.parse(body);
+  } catch {
+    return body;
+  }
+}
+
+/** A GET copy of the init: no body, and the now-meaningless content-type dropped. */
+function toGetInit(init: RequestInit): RequestInit {
+  const next: RequestInit = { ...init, method: 'GET', headers: stripContentType(init.headers) };
+  delete next.body;
+  return next;
+}
+
+function stripContentType(headers: HeadersInit | undefined): HeadersInit | undefined {
+  if (!headers) return headers;
+  if (headers instanceof Headers) {
+    const next = new Headers(headers);
+    next.delete('content-type');
+    return next;
+  }
+  if (Array.isArray(headers)) {
+    return headers.filter(([key]) => key.toLowerCase() !== 'content-type');
+  }
+  const next: Record<string, string> = {};
+  for (const [key, value] of Object.entries(headers)) {
+    if (key.toLowerCase() !== 'content-type') next[key] = value;
+  }
+  return next;
+}

package/src/ctgrClient/ctgrClient.spec.ts

@@ -0,0 +1,135 @@
+import { beforeEach, describe, expect, test } from 'bun:test';
+import { decodeRequest } from '../ctgr/index.js';
+import {
+  applyCtgrFromLocation,
+  applyCtgrIntent,
+  convertIfOnlyGETRequests,
+  isCtgrModeOn,
+  readCtgrIntent,
+  setCtgrMode,
+} from './index.js';
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+describe('the per-device mode flag', () => {
+  test('is off by default and round-trips through setCtgrMode', () => {
+    expect(isCtgrModeOn()).toBe(false);
+    setCtgrMode(true);
+    expect(isCtgrModeOn()).toBe(true);
+    setCtgrMode(false);
+    expect(isCtgrModeOn()).toBe(false);
+  });
+});
+
+describe('readCtgrIntent — the accepted spellings', () => {
+  test('on-values → on', () => {
+    for (const v of ['t', 'on', '1', 'yes', 'true', 'T', ' On ']) {
+      expect(readCtgrIntent(v)).toBe('on');
+    }
+  });
+  test('off-values → off', () => {
+    for (const v of ['f', 'off', '0', 'no', 'false']) {
+      expect(readCtgrIntent(v)).toBe('off');
+    }
+  });
+  test('absent or unknown → keep', () => {
+    expect(readCtgrIntent(null)).toBe('keep');
+    expect(readCtgrIntent(undefined)).toBe('keep');
+    expect(readCtgrIntent('maybe')).toBe('keep');
+  });
+});
+
+describe('applyCtgrIntent persists per device', () => {
+  test('on then off', () => {
+    expect(applyCtgrIntent('t')).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+    expect(applyCtgrIntent('f')).toBe(false);
+    expect(isCtgrModeOn()).toBe(false);
+  });
+  test('an absent value leaves an already-on device on', () => {
+    setCtgrMode(true);
+    expect(applyCtgrIntent(null)).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+  });
+});
+
+describe('applyCtgrFromLocation — the boot toggle', () => {
+  test('?ctgr=t turns it on, ?ctgr=f turns it off, from a bare search string', () => {
+    expect(applyCtgrFromLocation('?ctgr=t')).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+    expect(applyCtgrFromLocation('?ctgr=f')).toBe(false);
+    expect(isCtgrModeOn()).toBe(false);
+  });
+  test('accepts a full href and other params alongside', () => {
+    expect(applyCtgrFromLocation('https://desk.example.com/x?foo=1&ctgr=on')).toBe(true);
+    expect(isCtgrModeOn()).toBe(true);
+  });
+  test('no ctgr param leaves the device as it was', () => {
+    setCtgrMode(true);
+    expect(applyCtgrFromLocation('?foo=1')).toBe(true);
+    setCtgrMode(false);
+    expect(applyCtgrFromLocation('?foo=1')).toBe(false);
+  });
+});
+
+describe('convertIfOnlyGETRequests', () => {
+  test('mode OFF: every request passes through unchanged', async () => {
+    const init = { method: 'POST', body: JSON.stringify({ a: 1 }) };
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files', init);
+    expect(requests).toHaveLength(1);
+    expect(requests[0].url).toBe('/api/v1/files');
+    expect(requests[0].init).toBe(init);
+  });
+
+  test('mode ON: a POST becomes a decodable GET twin', async () => {
+    setCtgrMode(true);
+    const body = { title: 'hello', n: 42 };
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(body),
+    });
+    expect(requests).toHaveLength(1);
+    const twin = requests[0];
+    expect(twin.url.startsWith('/ctgrpo/api/v1/files?')).toBe(true);
+    expect((twin.init.method ?? 'GET').toUpperCase()).toBe('GET');
+    expect(twin.init.body).toBeUndefined();
+    // The server codec reverses it exactly.
+    const params = new URL(twin.url, 'http://x').searchParams;
+    const decoded = await decodeRequest(params);
+    expect(decoded).not.toBe('partial');
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.method).toBe('POST');
+    expect(decoded.body).toEqual(body);
+  });
+
+  test('mode ON: a plain GET still passes through untouched', async () => {
+    setCtgrMode(true);
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files', { method: 'GET' });
+    expect(requests).toHaveLength(1);
+    expect(requests[0].url).toBe('/api/v1/files');
+  });
+
+  test('mode ON: a DELETE with no body tunnels too', async () => {
+    setCtgrMode(true);
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/files/x', { method: 'DELETE' });
+    expect(requests[0].url.startsWith('/ctgrde/api/v1/files/x')).toBe(true);
+    const decoded = await decodeRequest(new URL(requests[0].url, 'http://x').searchParams);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.method).toBe('DELETE');
+  });
+
+  test('mode ON: a FormData upload rides as __files and reconstructs', async () => {
+    setCtgrMode(true);
+    const form = new FormData();
+    form.append('name', 'pic');
+    form.append('file', new File([new Uint8Array([1, 2, 3])], 'p.bin', { type: 'image/png' }));
+    const { requests } = await convertIfOnlyGETRequests('/api/v1/media', { method: 'POST' }, form);
+    const decoded = await decodeRequest(new URL(requests[0].url, 'http://x').searchParams);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.files?.[0]).toMatchObject({ originalname: 'p.bin', mimetype: 'image/png' });
+    expect(decoded.body).toEqual({ name: 'pic' });
+  });
+});

package/src/ctgrClient/ctgrConfig.ts

@@ -0,0 +1,89 @@
+/*
+ * Single source of truth for GET-only request mode. When on, the request layer
+ * rewrites every mutating call to a GET (see `convertIfOnlyGETRequests`) and the
+ * network-boundary guard hard-blocks any raw non-GET. Both read this one flag, so
+ * they can never disagree.
+ *
+ * The mode is per-DEVICE, persisted in localStorage so it survives reloads and is
+ * never tied to an account — a device that has it on keeps it on, a device that does
+ * not never gains it. Default is OFF.
+ *
+ * A site sets it up front, before its first request, by reading the URL:
+ *   • `?ctgr=t` (or `on`/`1`/`yes`)  → turn on, persist for this device.
+ *   • `?ctgr=f` (or `off`/`0`/`no`)  → turn off, clear it for this device.
+ *   • no `ctgr` param               → whatever this device already had.
+ * `applyCtgrFromLocation()` is the one call that does this on boot.
+ */
+const CTGR_KEY = 'ctgr';
+
+const ON_VALUES = new Set(['t', 'on', '1', 'yes', 'true']);
+const OFF_VALUES = new Set(['f', 'off', '0', 'no', 'false']);
+
+export const isCtgrModeOn = (): boolean => {
+  try {
+    return localStorage.getItem(CTGR_KEY) === 'on';
+  } catch {
+    return false;
+  }
+};
+
+export const setCtgrMode = (on: boolean): void => {
+  try {
+    if (on) localStorage.setItem(CTGR_KEY, 'on');
+    else localStorage.removeItem(CTGR_KEY);
+  } catch {
+    // localStorage unavailable (private mode / SSR) — nothing to persist.
+  }
+};
+
+/**
+ * The state a `ctgr` query value asks for: on, off, or (unknown/absent) leave the
+ * device as it is. Pure — no storage, no DOM — so it is trivially testable and the
+ * one place the accepted spellings live.
+ */
+export const readCtgrIntent = (value: string | null | undefined): 'on' | 'off' | 'keep' => {
+  if (value == null) return 'keep';
+  const v = value.trim().toLowerCase();
+  if (ON_VALUES.has(v)) return 'on';
+  if (OFF_VALUES.has(v)) return 'off';
+  return 'keep';
+};
+
+/**
+ * Apply a `ctgr` query value to this device's persisted mode and report whether the
+ * mode is on afterwards. Called by `applyCtgrFromLocation` with the value read off
+ * the URL; exposed on its own so a host that already parsed its query can reuse it.
+ */
+export const applyCtgrIntent = (value: string | null | undefined): boolean => {
+  const intent = readCtgrIntent(value);
+  if (intent === 'on') setCtgrMode(true);
+  else if (intent === 'off') setCtgrMode(false);
+  return isCtgrModeOn();
+};
+
+/**
+ * Boot hook: read `?ctgr=…` off the current location (or a supplied search string /
+ * URL), persist the change for this device, and return whether the mode is on. Safe
+ * to call with no argument in the browser; returns `false` with no `window`.
+ *
+ * Call this ONCE, before the app issues its first request — pairing it with
+ * `installCtgrGuard()` so a request made during that first tick is still caught.
+ */
+export const applyCtgrFromLocation = (search?: string): boolean => {
+  let query = search;
+  if (query === undefined) {
+    if (typeof window === 'undefined' || !window.location) return isCtgrModeOn();
+    query = window.location.search;
+  }
+  let value: string | null = null;
+  try {
+    // Accept a bare search (`?ctgr=t`), a full href, or already-extracted params.
+    const params = query.includes('://')
+      ? new URL(query).searchParams
+      : new URLSearchParams(query.startsWith('?') ? query.slice(1) : query);
+    value = params.get(CTGR_KEY);
+  } catch {
+    value = null;
+  }
+  return applyCtgrIntent(value);
+};

package/src/ctgrClient/ctgrGuard.ts

@@ -0,0 +1,86 @@
+/*
+ * Safety net for GET-only mode. Even though the request layer is supposed to rewrite
+ * every mutating call to a GET (`convertIfOnlyGETRequests`), this guard sits at the
+ * actual network boundary and hard-blocks any non-GET request to our own API surface
+ * when the mode is on — so a code path that forgot to run through the converter can
+ * never put a raw POST/PUT/PATCH/DELETE on the wire. Catches both `fetch` and
+ * `XMLHttpRequest`. It only ever tightens; it must never weaken.
+ */
+import { isCtgrModeOn } from './ctgrConfig.js';
+
+// Methods that never mutate and are always safe to allow.
+const SAFE_METHODS = new Set(['GET', 'HEAD']);
+
+const urlOf = (input: RequestInfo | URL): string => {
+  if (typeof input === 'string') return input;
+  if (input instanceof URL) return input.href;
+  if (input instanceof Request) return input.url;
+  return String(input);
+};
+
+// Only guard our OWN API surface — same-origin AND under a path the request layer
+// owns (`/api/…` or a `/ctgr<xx>` twin). Restricting to these prefixes (rather than
+// "any same-origin path") matters: same-origin also covers paths we do not own, like
+// Cloudflare's `/cdn-cgi/rum` beacon, which fires a raw POST on every page view —
+// guarding it would break RUM and fire for every ordinary visitor, not just a
+// misbehaving call site.
+const isGuardedPath = (rawUrl: string): boolean => {
+  let path: string;
+  if (rawUrl.startsWith('/')) {
+    path = rawUrl;
+  } else {
+    try {
+      const u = new URL(rawUrl, window.location.href);
+      if (u.origin !== window.location.origin) return false;
+      path = u.pathname;
+    } catch {
+      return false;
+    }
+  }
+  return path.startsWith('/api/') || path.startsWith('/ctgr');
+};
+
+// Deliberately generic: this message can reach the console of ANY visitor, so it says
+// nothing about the request layer, the call site, or what a blocked request was.
+const block = (): Error => {
+  const message = 'Service unavailable.';
+  console.error(message, new Error('blocked request'));
+  return new Error(message);
+};
+
+let installed = false;
+
+export const installCtgrGuard = (): void => {
+  if (installed || typeof window === 'undefined') return;
+  installed = true;
+
+  // ── fetch ──────────────────────────────────────────────────────────────────
+  if (typeof window.fetch === 'function') {
+    const originalFetch = window.fetch.bind(window);
+    const guardedFetch = (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+      const method = (
+        init?.method ?? (input instanceof Request ? input.method : 'GET')
+      ).toUpperCase();
+      const url = urlOf(input);
+      if (isCtgrModeOn() && !SAFE_METHODS.has(method) && isGuardedPath(url)) {
+        return Promise.reject(block());
+      }
+      return originalFetch(input, init);
+    };
+    window.fetch = guardedFetch as typeof window.fetch;
+  }
+
+  // ── XMLHttpRequest ───────────────────────────────────────────────────────────
+  if (typeof XMLHttpRequest !== 'undefined') {
+    const originalOpen = XMLHttpRequest.prototype.open;
+    // biome-ignore lint/suspicious/noExplicitAny: matching XHR.open's variadic overloads
+    XMLHttpRequest.prototype.open = function open(method: string, url: string, ...rest: any[]) {
+      const upper = String(method).toUpperCase();
+      if (isCtgrModeOn() && !SAFE_METHODS.has(upper) && isGuardedPath(String(url))) {
+        throw block();
+      }
+      // biome-ignore lint/suspicious/noExplicitAny: forwarding the original variadic call
+      return (originalOpen as any).call(this, method, url, ...rest);
+    };
+  }
+};

package/src/ctgrClient/index.ts

@@ -0,0 +1,21 @@
+/*
+ * cursedbelt-core/ctgr-client — the browser adapters that turn any site into a
+ * GET-only client:
+ *   • the per-device mode flag + the `?ctgr=t|f` boot toggle (`ctgrConfig`),
+ *   • the request converter that rewrites a mutation into `/ctgr<xx>` GET twins,
+ *   • the network-boundary guard that blocks a stray raw verb.
+ *
+ * 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`.
+ */
+export {
+  applyCtgrFromLocation,
+  applyCtgrIntent,
+  isCtgrModeOn,
+  readCtgrIntent,
+  setCtgrMode,
+} from './ctgrConfig.js';
+export { type CtgrFetchRequest, convertIfOnlyGETRequests } from './convertRequest.js';
+export { installCtgrGuard } from './ctgrGuard.js';