cursedbelt-core 1.0.0

package/src/ctgr/codec.spec.ts

@@ -0,0 +1,208 @@
+import { describe, expect, test } from 'bun:test';
+import { toBase64 } from './base64url';
+import { ChunkStore } from './chunkStore';
+import { decodePayload, decodeRequest, encodeRequest, extractFiles, parseChunk } from './codec';
+import { ABBREV_TO_METHOD } from './types';
+
+const paramsOf = (url: string) => Object.fromEntries(new URL(url, 'http://x').searchParams);
+
+// Deterministic, gzip-resistant payload (an LCG over printable ASCII) — used to force
+// genuine multi-chunk splits even with compression on.
+const incompressible = (n: number): string => {
+  let s = '';
+  let x = 0x12345;
+  for (let i = 0; i < n; i++) {
+    x = (x * 1103515245 + 12345) & 0x7fffffff;
+    s += String.fromCharCode(33 + (x % 90));
+  }
+  return s;
+};
+
+describe('encodeRequest / decodeRequest', () => {
+  test('single chunk, no gzip — round-trips body + method', async () => {
+    const req = await encodeRequest('POST', '/api/v1/notes', { body: 'hello' });
+    expect(req.chunks).toHaveLength(1);
+    expect(req.chunks[0].url.startsWith('/ctgrpo/api/v1/notes?')).toBe(true);
+    expect(req.chunks[0].params._cv).toBe('1');
+    expect(req.chunks[0].params._cg).toBe('0');
+    expect(req.chunks[0].params._sha).toBeDefined();
+
+    const decoded = await decodeRequest(new URL(req.chunks[0].url, 'http://x').searchParams);
+    expect(decoded).not.toBe('partial');
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.body).toEqual({ body: 'hello' });
+    expect(decoded.method).toBe('POST');
+  });
+
+  test('the chunk URL is well-formed and URL-safe (no encoding blowup)', async () => {
+    const req = await encodeRequest('DELETE', '/things/1', { a: 1 });
+    const [chunk] = req.chunks;
+    // _d is base64url: only [A-Za-z0-9_-]; URLSearchParams must not have re-encoded it.
+    expect(chunk.params._d).toMatch(/^[A-Za-z0-9_-]*$/);
+    expect(new URL(chunk.url, 'http://x').searchParams.get('_d')).toBe(chunk.params._d);
+    expect(chunk.params._cm).toBe('de');
+  });
+
+  test('every method maps to its twin abbreviation', async () => {
+    for (const [abbrev, method] of Object.entries(ABBREV_TO_METHOD)) {
+      const req = await encodeRequest(method, '/x', { ok: true });
+      expect(req.chunks[0].url.startsWith(`/ctgr${abbrev}/x?`)).toBe(true);
+      expect(req.chunks[0].params._cm).toBe(abbrev);
+    }
+  });
+
+  test('round-trips unicode + emoji', async () => {
+    const body = { msg: 'héllo — 世界 🎲', tags: ['café', 'naïve'] };
+    const req = await encodeRequest('PUT', '/x', body);
+    const decoded = await decodeRequest(req.chunks[0].params);
+    expect(decoded).not.toBe('partial');
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.body).toEqual(body);
+  });
+
+  test('a body-less mutation encodes as a null body', async () => {
+    const req = await encodeRequest('DELETE', '/things/9', undefined);
+    const decoded = await decodeRequest(req.chunks[0].params);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.method).toBe('DELETE');
+    expect(decoded.body).toBeNull();
+  });
+
+  test('gzip flips on past the threshold and shrinks the payload', async () => {
+    const med = { data: 'x'.repeat(2000) };
+    const req = await encodeRequest('POST', '/x', med, { gzipThresholdBytes: 1000 });
+    expect(req.chunks[0].params._cg).toBe('1');
+    const decoded = await decodeRequest(req.chunks[0].params);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.body).toEqual(med);
+  });
+
+  test('large payload splits into multiple chunks; decodeRequest returns partial', async () => {
+    // gzip disabled → deterministic chunk count from the raw JSON size.
+    const big = { data: 'x'.repeat(10000) };
+    const req = await encodeRequest('PATCH', '/api/v1/lists/123', big, {
+      chunkSizeBytes: 500,
+      gzipThresholdBytes: 10_000_000,
+    });
+    expect(req.chunks.length).toBeGreaterThan(1);
+    // A lone non-final chunk cannot be decoded standalone.
+    expect(await decodeRequest(req.chunks[0].params)).toBe('partial');
+
+    const store = new ChunkStore();
+    for (const chunk of req.chunks.slice(0, -1)) {
+      expect(await store.add(chunk.params)).toBe(false);
+    }
+    const result = await store.add(req.chunks.at(-1)!.params);
+    expect(result).not.toBe(false);
+    expect(result).not.toBeInstanceOf(Error);
+    expect((result as { body: unknown }).body).toEqual(big);
+  });
+
+  test('gzip + multi-chunk together: incompressible data still round-trips', async () => {
+    const big = { blob: incompressible(6000) };
+    const req = await encodeRequest('POST', '/x', big, {
+      chunkSizeBytes: 800,
+      gzipThresholdBytes: 1024,
+    });
+    expect(req.chunks.length).toBeGreaterThan(1); // gzip couldn't shrink it under one chunk
+    expect(req.chunks[0].params._cg).toBe('1');
+
+    const store = new ChunkStore();
+    let result: unknown = false;
+    for (const chunk of req.chunks) result = await store.add(chunk.params);
+    expect((result as { body: unknown }).body).toEqual(big);
+  });
+
+  test('reconstructs files from the __files body shape', async () => {
+    const bytes = new Uint8Array([1, 2, 3, 4, 250, 0, 99]);
+    const body = {
+      title: 'memo',
+      __files: [
+        {
+          field: 'doc',
+          name: 'a.bin',
+          type: 'application/octet-stream',
+          dataBase64: toBase64(bytes),
+        },
+      ],
+    };
+    const req = await encodeRequest('POST', '/files', body);
+    const decoded = await decodeRequest(req.chunks[0].params);
+    if (decoded === 'partial') throw new Error('unreachable');
+    expect(decoded.body).toEqual({ title: 'memo' });
+    expect(decoded.files).toHaveLength(1);
+    expect(decoded.files?.[0]).toMatchObject({
+      fieldname: 'doc',
+      originalname: 'a.bin',
+      mimetype: 'application/octet-stream',
+      size: bytes.length,
+    });
+    expect(Array.from(decoded.files![0].buffer)).toEqual(Array.from(bytes));
+  });
+
+  test('extractFiles leaves a plain body untouched', () => {
+    expect(extractFiles({ a: 1 })).toEqual({ body: { a: 1 } });
+    expect(extractFiles(null)).toEqual({ body: null });
+  });
+});
+
+describe('integrity + validation', () => {
+  test('a chunk whose declared crc does not match its bytes is rejected', async () => {
+    const req = await encodeRequest('POST', '/x', { hello: 'world' });
+    const tampered = { ...req.chunks[0].params, _crc: '123' }; // valid base64, wrong crc
+    expect(() => parseChunk(tampered)).toThrow(/crc/);
+  });
+
+  test('a structurally invalid _d is rejected', async () => {
+    const req = await encodeRequest('POST', '/x', { hello: 'world' });
+    const tampered = { ...req.chunks[0].params, _d: '!!!not base64!!!' };
+    expect(() => parseChunk(tampered)).toThrow();
+  });
+
+  test('a tampered sha256 throws on single-chunk decode', async () => {
+    const req = await encodeRequest('POST', '/x', { hello: 'world' });
+    const tampered = { ...req.chunks[0].params, _sha: 'deadbeef' };
+    await expect(decodeRequest(tampered)).rejects.toThrow(/sha256/);
+  });
+
+  test('an unknown wire version is rejected', () => {
+    expect(() =>
+      parseChunk({
+        _cv: '9',
+        _cm: 'po',
+        _ci: '0',
+        _ct: '1',
+        _cl: '0',
+        _cid: 'x',
+        _crc: '0',
+        _d: '',
+      }),
+    ).toThrow(/version/);
+  });
+
+  test('an unknown method abbreviation is rejected', () => {
+    expect(() =>
+      parseChunk({
+        _cv: '1',
+        _cm: 'zz',
+        _ci: '0',
+        _ct: '1',
+        _cl: '0',
+        _cid: 'x',
+        _crc: '0',
+        _d: '',
+      }),
+    ).toThrow(/method/);
+  });
+
+  test('decodePayload is the inverse of the encode pipeline (plain + gzip)', async () => {
+    const enc = new TextEncoder();
+    const plain = enc.encode(JSON.stringify({ a: 1 }));
+    expect((await decodePayload(plain, false, 'POST')).body).toEqual({ a: 1 });
+  });
+
+  test('paramsOf parses a real chunk url', async () => {
+    const req = await encodeRequest('POST', '/x', { z: 9 });
+    expect(paramsOf(req.chunks[0].url)._cv).toBe('1');
+  });
+});

package/src/ctgr/codec.ts

@@ -0,0 +1,202 @@
+/*
+ * ctgr v1 codec — pack ANY mutating request body into URL-safe GET-twin chunks, and
+ * the pure inverse. Isomorphic (browser + Bun), no runtime deps.
+ *
+ * Pipeline: JSON → UTF-8 bytes → gzip when > threshold → split into chunks → each
+ * chunk base64url-encoded with a crc32, the envelope carrying a self-describing
+ * header (version, gzip flag, method, index/total, payload length, payload id) and a
+ * full-payload sha256 on the last chunk. The decoder needs nothing but the params.
+ *
+ * This replaces the legacy `encode→reverse→swap→base64→swap` chain, which
+ * double-base64'd and whose swap/reverse was trivially-reversible obfuscation, not
+ * protection — the real protection (getOnly JWT claim + CSRF guard) is unchanged.
+ */
+import { fromBase64, fromBase64url, toBase64url } from './base64url';
+import { gunzip, gzip } from './compress';
+import { crc32 } from './crc32';
+import { sha256Hex } from './digest';
+import {
+  ABBREV_TO_METHOD,
+  CTGR_WIRE_VERSION,
+  type CtgrAbbrev,
+  type CtgrDecoded,
+  type CtgrMethod,
+  type EncodedChunk,
+  type EncodedRequest,
+  type EncodeOpts,
+  METHOD_TO_ABBREV,
+  type SerializedFile,
+  type UploadedFile,
+} from './types';
+
+const DEFAULT_CHUNK_SIZE = 1800;
+const DEFAULT_GZIP_THRESHOLD = 1024;
+
+const textEncoder = new TextEncoder();
+const textDecoder = 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
+ * into `chunkSizeBytes` pieces. Each chunk carries a crc32; the last carries the
+ * full-payload sha256.
+ */
+export async function encodeRequest(
+  method: CtgrMethod,
+  url: string,
+  body: unknown,
+  opts: EncodeOpts = {},
+): Promise<EncodedRequest> {
+  const chunkSize = opts.chunkSizeBytes ?? DEFAULT_CHUNK_SIZE;
+  const gzipThreshold = opts.gzipThresholdBytes ?? DEFAULT_GZIP_THRESHOLD;
+
+  // `JSON.stringify(undefined)` is `undefined`; coerce a missing body to `null` so a
+  // body-less mutation (e.g. DELETE) still rides the normal, single-versioned path.
+  const raw = textEncoder.encode(JSON.stringify(body ?? null));
+  const useGzip = raw.length > gzipThreshold;
+  const payload = useGzip ? await gzip(raw) : raw;
+  const sha = await sha256Hex(payload);
+  const cid = crypto.randomUUID();
+  const abbrev = METHOD_TO_ABBREV[method];
+  const totalChunks = Math.max(1, Math.ceil(payload.length / chunkSize));
+
+  const chunks: EncodedChunk[] = [];
+  for (let i = 0; i < totalChunks; i++) {
+    const slice = payload.subarray(i * chunkSize, (i + 1) * chunkSize);
+    const params: Record<string, string> = {
+      _cv: CTGR_WIRE_VERSION,
+      _cm: abbrev,
+      _cg: useGzip ? '1' : '0',
+      _ci: String(i),
+      _ct: String(totalChunks),
+      _cl: String(payload.length),
+      _cid: cid,
+      _crc: String(crc32(slice)),
+      _d: toBase64url(slice),
+    };
+    if (i === totalChunks - 1) params._sha = sha;
+    const path = `/ctgr${abbrev}${url}`;
+    const separator = path.includes('?') ? '&' : '?';
+    const query = new URLSearchParams(params).toString();
+    chunks.push({ url: `${path}${separator}${query}`, params });
+  }
+  return { chunks };
+}
+
+/** A validated, crc-verified single chunk — ready to buffer or decode. */
+export interface ParsedChunk {
+  method: CtgrMethod;
+  gzip: boolean;
+  index: number;
+  total: number;
+  /** Declared full-payload length in bytes (post-gzip, pre-base64). */
+  payloadLength: number;
+  cid: string;
+  /** Full-payload sha256 (hex) — present on the last chunk only. */
+  sha?: string;
+  bytes: Uint8Array;
+}
+
+function asRecord(params: Record<string, string> | URLSearchParams): Record<string, string> {
+  return params instanceof URLSearchParams ? Object.fromEntries(params) : params;
+}
+
+/**
+ * Parse + crc-verify ONE chunk's params. Throws on an unknown version, a bad method
+ * abbrev, malformed index/total/length, or a crc mismatch — callers that must not
+ * throw (the chunk store, the middleware) catch and map to an Error/400.
+ */
+export function parseChunk(params: Record<string, string> | URLSearchParams): ParsedChunk {
+  const p = asRecord(params);
+
+  if (p._cv !== CTGR_WIRE_VERSION) {
+    throw new Error(`ctgr: unsupported wire version "${p._cv ?? ''}"`);
+  }
+  const method = ABBREV_TO_METHOD[p._cm as CtgrAbbrev];
+  if (!method) throw new Error(`ctgr: unknown method abbreviation "${p._cm ?? ''}"`);
+
+  const index = Number(p._ci);
+  const total = Number(p._ct);
+  const payloadLength = Number(p._cl);
+  if (!Number.isInteger(total) || total <= 0) throw new Error('ctgr: invalid chunk total');
+  if (!Number.isInteger(index) || index < 0 || index >= total) {
+    throw new Error('ctgr: chunk index out of range');
+  }
+  if (!Number.isInteger(payloadLength) || payloadLength < 0) {
+    throw new Error('ctgr: invalid payload length');
+  }
+
+  const bytes = fromBase64url(p._d ?? '');
+  const expectedCrc = Number(p._crc);
+  if (!Number.isInteger(expectedCrc) || crc32(bytes) !== expectedCrc) {
+    throw new Error('ctgr: chunk crc mismatch');
+  }
+
+  return {
+    method,
+    gzip: p._cg === '1',
+    index,
+    total,
+    payloadLength,
+    cid: p._cid ?? '',
+    sha: p._sha,
+    bytes,
+  };
+}
+
+/**
+ * Split an `__files` array out of a decoded body into multer-shaped uploads. The
+ * `__files` data is standard base64 (what the client's FormData serializer emits);
+ * everything else stays on the returned `body`.
+ */
+export function extractFiles(parsed: unknown): { body: unknown; files?: UploadedFile[] } {
+  if (
+    parsed &&
+    typeof parsed === 'object' &&
+    Array.isArray((parsed as { __files?: unknown }).__files)
+  ) {
+    const source = parsed as { __files: SerializedFile[] } & Record<string, unknown>;
+    const files: UploadedFile[] = source.__files.map((f) => {
+      const buffer = fromBase64(f.dataBase64 ?? '');
+      return {
+        fieldname: f.field ?? 'file',
+        originalname: f.name ?? 'file',
+        mimetype: f.type || 'application/octet-stream',
+        buffer,
+        size: buffer.length,
+      };
+    });
+    const { __files, ...body } = source;
+    return { body, files };
+  }
+  return { body: parsed };
+}
+
+/** Decode an assembled payload (gunzip when flagged) → method + body (+ files). */
+export async function decodePayload(
+  payload: Uint8Array,
+  gzipped: boolean,
+  method: CtgrMethod,
+): Promise<CtgrDecoded> {
+  const raw = gzipped ? await gunzip(payload) : payload;
+  const json = textDecoder.decode(raw);
+  const parsed: unknown = json.length ? JSON.parse(json) : undefined;
+  const { body, files } = extractFiles(parsed);
+  return files ? { method, body, files } : { method, body };
+}
+
+/**
+ * Decode a single set of chunk params. For the common single-chunk request this
+ * fully decodes (verifying the payload sha256); for one chunk of a multi-chunk
+ * payload it returns `'partial'` — those reassemble through {@link ChunkStore}.
+ */
+export async function decodeRequest(
+  params: Record<string, string> | URLSearchParams,
+): Promise<CtgrDecoded | 'partial'> {
+  const chunk = parseChunk(params);
+  if (chunk.total !== 1) return 'partial';
+  if (chunk.sha && (await sha256Hex(chunk.bytes)) !== chunk.sha) {
+    throw new Error('ctgr: payload sha256 mismatch');
+  }
+  return decodePayload(chunk.bytes, chunk.gzip, chunk.method);
+}

package/src/ctgr/compress.ts

@@ -0,0 +1,21 @@
+/*
+ * Isomorphic gzip via the web-standard CompressionStream / DecompressionStream —
+ * native on Bun and in the browser, so one implementation serves both the browser
+ * encoder and the Bun server decoder (no `node:zlib`, no `Bun.gzipSync` branch).
+ * Async on both ends, which is why the whole ctgr codec is async.
+ */
+// `new Uint8Array(bytes)` re-backs the view on a plain ArrayBuffer — Blob/SubtleCrypto
+// reject the `ArrayBufferLike` default (which admits SharedArrayBuffer) under TS 6.
+export async function gzip(bytes: Uint8Array): Promise<Uint8Array> {
+  const stream = new Blob([new Uint8Array(bytes)])
+    .stream()
+    .pipeThrough(new CompressionStream('gzip'));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}
+
+export async function gunzip(bytes: Uint8Array): Promise<Uint8Array> {
+  const stream = new Blob([new Uint8Array(bytes)])
+    .stream()
+    .pipeThrough(new DecompressionStream('gzip'));
+  return new Uint8Array(await new Response(stream).arrayBuffer());
+}

package/src/ctgr/crc32.ts

@@ -0,0 +1,23 @@
+/*
+ * Pure-JS CRC-32 (IEEE 802.3 / zlib polynomial) over a 256-entry lookup table — no
+ * 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 = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+
+/** CRC-32 of `bytes` as an unsigned 32-bit integer. */
+export function crc32(bytes: Uint8Array): number {
+  let crc = 0xffffffff;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = (crc >>> 8) ^ TABLE[(crc ^ bytes[i]) & 0xff];
+  }
+  return (crc ^ 0xffffffff) >>> 0;
+}

package/src/ctgr/digest.ts

@@ -0,0 +1,14 @@
+/*
+ * Hex SHA-256 via web-standard SubtleCrypto — isomorphic (Bun + browser both expose
+ * `crypto.subtle`). Used for the full-payload integrity check the wire format carries
+ * on the last chunk (`_sha`); per-chunk integrity is the cheaper {@link crc32}.
+ */
+export async function sha256Hex(bytes: Uint8Array): Promise<string> {
+  // `new Uint8Array(bytes)` re-backs the view on a plain ArrayBuffer — SubtleCrypto's
+  // BufferSource rejects the `ArrayBufferLike` default under TS 6.
+  const digest = await crypto.subtle.digest('SHA-256', new Uint8Array(bytes));
+  const view = new Uint8Array(digest);
+  let hex = '';
+  for (let i = 0; i < view.length; i++) hex += view[i].toString(16).padStart(2, '0');
+  return hex;
+}

package/src/ctgr/index.ts

@@ -0,0 +1,39 @@
+/*
+ * src/ctgr — the isomorphic ctgr codec, re-exported from `cursedbelt-server`; (browser + Bun, no runtime deps). The
+ * Hono transport binding (`unGETify` + `buildRoutes`) lives in `cursedbelt-server`;
+ * the browser guard + request converter live in `cursedbelt-cc/client`.
+ *
+ * The ChunkAccumulator is the primary abstraction for multi-chunk payload assembly;
+ * ChunkStore is kept for backward compatibility (they are identical implementations).
+ */
+export { fromBase64, fromBase64url, toBase64, toBase64url } from './base64url';
+export {
+  ChunkAccumulator,
+  type ChunkAccumulatorConfig,
+} from './chunkAccumulator';
+export { ChunkStore, type ChunkStoreOpts } from './chunkStore';
+export {
+  decodePayload,
+  decodeRequest,
+  encodeRequest,
+  extractFiles,
+  type ParsedChunk,
+  parseChunk,
+} from './codec';
+export { gunzip, gzip } from './compress';
+export { crc32 } from './crc32';
+export { sha256Hex } from './digest';
+export {
+  ABBREV_TO_METHOD,
+  CTGR_WIRE_VERSION,
+  type CtgrAbbrev,
+  type CtgrDecoded,
+  type CtgrMethod,
+  type EncodedChunk,
+  type EncodedRequest,
+  type EncodeOpts,
+  METHOD_TO_ABBREV,
+  type SerializedFile,
+  type UploadedFile,
+} from './types';
+export { decodeV0Payload, V0ChunkStore, type V0ChunkStoreOpts } from './v0compat';

package/src/ctgr/types.ts

@@ -0,0 +1,80 @@
+/*
+ * ctgr wire-format types + the method⇄abbreviation maps shared by the codec, the
+ * chunk store, the Hono transport, and the browser client. Pure types + literal
+ * const maps only (no runtime APIs) so this module is trivially isomorphic.
+ */
+
+/** The mutating HTTP methods ctgr tunnels through a `/ctgr<XX>` GET twin. */
+export type CtgrMethod = 'POST' | 'PATCH' | 'PUT' | 'DELETE';
+
+/** Method → its 2-char abbreviation (the `/ctgr<XX>` path segment + the `_cm` param). */
+export const METHOD_TO_ABBREV = {
+  POST: 'po',
+  PATCH: 'pa',
+  PUT: 'pu',
+  DELETE: 'de',
+} as const satisfies Record<CtgrMethod, string>;
+
+/** The inverse of {@link METHOD_TO_ABBREV}. */
+export const ABBREV_TO_METHOD = {
+  po: 'POST',
+  pa: 'PATCH',
+  pu: 'PUT',
+  de: 'DELETE',
+} as const satisfies Record<string, CtgrMethod>;
+
+export type CtgrAbbrev = keyof typeof ABBREV_TO_METHOD;
+
+/** Current wire-format version. v0 (the legacy `_cv`-absent codec) lives in `v0compat.ts`. */
+export const CTGR_WIRE_VERSION = '1';
+
+/**
+ * A reconstructed multipart upload, multer-shaped so the file came over the ctgr
+ * GET-tunnel the same way it would over multipart. `buffer` is raw isomorphic bytes
+ * (a `Uint8Array`, not a Node `Buffer`) — wrap it where a `Buffer` is required.
+ */
+export interface UploadedFile {
+  fieldname: string;
+  originalname: string;
+  mimetype: string;
+  buffer: Uint8Array;
+  size: number;
+}
+
+/** The fully-decoded request a downstream handler / validator consumes. */
+export interface CtgrDecoded {
+  /** The original HTTP method the GET twin stands in for. */
+  method: CtgrMethod;
+  /** The parsed JSON body, with any `__files` array extracted into {@link files}. */
+  body: unknown;
+  /** Reconstructed uploads — present only when the body carried an `__files` array. */
+  files?: UploadedFile[];
+}
+
+/** One encoded chunk: the GET-twin URL plus the query params it carries (same data). */
+export interface EncodedChunk {
+  /** `/ctgr<XX><path>?<params>` — a path (no origin); the caller adds any prefix. */
+  url: string;
+  /** The `_c*` params, also serialized into {@link url}. Handy for tests + reassembly. */
+  params: Record<string, string>;
+}
+
+/** The output of `encodeRequest`: one chunk for small bodies, N for large ones. */
+export interface EncodedRequest {
+  chunks: EncodedChunk[];
+}
+
+export interface EncodeOpts {
+  /** Max payload bytes per chunk (pre-base64url). Default 1800 → ~2400 URL chars. */
+  chunkSizeBytes?: number;
+  /** Gzip the payload when it exceeds this many bytes. Default 1024. */
+  gzipThresholdBytes?: number;
+}
+
+/** The `__files` entry shape the client serializes an upload into (base64 data). */
+export interface SerializedFile {
+  field?: string;
+  name?: string;
+  type?: string;
+  dataBase64?: string;
+}

package/src/ctgr/v0compat.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from 'bun:test';
+import { toBase64 } from './base64url';
+import { decodeV0Payload, V0ChunkStore } from './v0compat';
+
+// Mirror the legacy client encode pipeline exactly: encode→reverse→swap→encode→swap,
+// where `encode` is standard base64 of the UTF-8 bytes. Used to prove the v1 server's
+// v0 fallback decodes what an un-updated client still sends.
+const encodeV0 = (jsonString: string): string => {
+  const encode = (s: string) => toBase64(new TextEncoder().encode(s));
+  const reverse = (s: string) => s.split('').reverse().join('');
+  const swap = (s: string) => {
+    if (s.length < 2) return s;
+    const arr = s.split('');
+    arr[0] = s[s.length - 1];
+    arr[s.length - 1] = s[0];
+    return arr.join('');
+  };
+  return swap(encode(swap(reverse(encode(jsonString)))));
+};
+
+describe('v0 compat', () => {
+  test('decodeV0Payload reverses the legacy pipeline', () => {
+    const body = { hello: 'world', n: 42, nested: { a: [1, 2, 3] }, emoji: '🎲 — café' };
+    expect(decodeV0Payload(encodeV0(JSON.stringify(body)))).toEqual(body);
+  });
+
+  test('V0ChunkStore decodes a single payload with the path-derived method', () => {
+    const store = new V0ChunkStore();
+    const body = { title: 'legacy note' };
+    const result = store.add({ p: encodeV0(JSON.stringify(body)) }, 'POST');
+    expect(result).not.toBe(false);
+    expect(result).toEqual({ method: 'POST', body });
+  });
+
+  test('V0ChunkStore treats a missing payload as a body-less request', () => {
+    const store = new V0ChunkStore();
+    expect(store.add({}, 'DELETE')).toEqual({ method: 'DELETE', body: undefined });
+  });
+
+  test('V0ChunkStore reassembles a chunked legacy payload', () => {
+    const store = new V0ChunkStore();
+    const body = { data: 'z'.repeat(2000) };
+    const encoded = encodeV0(JSON.stringify(body));
+    const size = Math.ceil(encoded.length / 3);
+    const parts = [encoded.slice(0, size), encoded.slice(size, size * 2), encoded.slice(size * 2)];
+    expect(store.add({ cid: 'u1', ci: '0', ct: '3', p: parts[0] }, 'PATCH')).toBe(false);
+    expect(store.add({ cid: 'u1', ci: '1', ct: '3', p: parts[1] }, 'PATCH')).toBe(false);
+    const result = store.add({ cid: 'u1', ci: '2', ct: '3', p: parts[2] }, 'PATCH');
+    expect(result).toEqual({ method: 'PATCH', body });
+  });
+
+  test('V0ChunkStore reconstructs files from a legacy __files body', () => {
+    const store = new V0ChunkStore();
+    const bytes = new Uint8Array([9, 8, 7]);
+    const body = {
+      __files: [{ field: 'f', name: 'x.bin', type: 'image/png', dataBase64: toBase64(bytes) }],
+    };
+    const result = store.add({ p: encodeV0(JSON.stringify(body)) }, 'POST');
+    expect(result).not.toBe(false);
+    if (result === false || result instanceof Error) throw new Error('unreachable');
+    expect(result.body).toEqual({});
+    expect(result.files?.[0]).toMatchObject({
+      fieldname: 'f',
+      originalname: 'x.bin',
+      mimetype: 'image/png',
+    });
+  });
+
+  test('V0ChunkStore rejects invalid chunk metadata', () => {
+    const store = new V0ChunkStore();
+    expect(store.add({ cid: 'u', ci: '5', ct: '3', p: 'x' }, 'POST')).toBeInstanceOf(Error);
+  });
+});