cursedbelt-server 4.34.0 → 4.36.0

package/dist/server/ctgrTunnel.d.ts

@@ -0,0 +1,16 @@
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import type { Hono } from 'hono';
+import type { CursedbeltEnv } from './context.js';
+export interface CtgrTunnelOptions {
+    /**
+     * The accumulator for multi-chunk payloads. Share ONE across an app (the default is
+     * a fresh singleton); pass your own to tune the DoS caps ({@link ChunkStore}).
+     */
+    store?: ChunkStore;
+}
+/**
+ * Mount the GET-only tunnel on `app`. Call once, on the Hono app whose real routes sit
+ * at the paths the twins mirror (a twin path is `/ctgr<xx>` + the real path). Returns
+ * the {@link ChunkStore} in use, for tests and metrics.
+ */
+export declare function mountCtgrTunnel<E extends CursedbeltEnv = CursedbeltEnv>(app: Hono<E>, options?: CtgrTunnelOptions): ChunkStore;

package/dist/server/ctgrTunnel.js

@@ -0,0 +1,91 @@
+/*
+ * The one-line server adapter for the GET-only tunnel: `mountCtgrTunnel(app)`.
+ *
+ * Where {@link unGETify} + {@link buildRoutes} ask each route to register a twin and
+ * read its body from `c.get('ctgrDecoded')`, this mounts a single middleware that
+ * DECODES a `/ctgr<xx>` GET twin and RE-DISPATCHES it into the same app at the real
+ * method + path — so every existing `app.post(...)` / `app.delete(...)` handler is
+ * reached unchanged, reading `await c.req.json()` / `c.req.formData()` as it always
+ * did. That is what makes the tunnel droppable onto any Hono app in one call.
+ *
+ * A single-chunk twin decodes inline; a multi-chunk payload accumulates in the shared
+ * {@link ChunkStore} (an intermediate chunk answers 202). Legacy `_cv`-absent twins
+ * fall through the v0 decoder. The middleware decodes and re-dispatches only; whatever
+ * gate stands in front of the app (Access, a session cookie, a getOnly claim) is
+ * unchanged and still runs on the real handler.
+ */
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import { ABBREV_TO_METHOD, } from 'cursedbelt-core/ctgr/types';
+import { V0ChunkStore } from 'cursedbelt-core/ctgr/v0compat';
+import { CTGR_ROUTE_PATTERN } from './ctgr.js';
+/** Query keys the codec adds to a twin URL — dropped when rebuilding the real request. */
+const isCtgrParam = (key) => key === '_d' || key === '_sha' || key.startsWith('_c');
+/**
+ * Mount the GET-only tunnel on `app`. Call once, on the Hono app whose real routes sit
+ * at the paths the twins mirror (a twin path is `/ctgr<xx>` + the real path). Returns
+ * the {@link ChunkStore} in use, for tests and metrics.
+ */
+export function mountCtgrTunnel(app, options = {}) {
+    const store = options.store ?? new ChunkStore();
+    const legacy = new V0ChunkStore();
+    app.use(CTGR_ROUTE_PATTERN, async (c) => {
+        const url = new URL(c.req.url);
+        const params = Object.fromEntries(url.searchParams);
+        // The twin path is `/ctgr<xx>...`; the abbreviation is the two chars after `ctgr`.
+        const pathMethod = ABBREV_TO_METHOD[c.req.path.slice(5, 7)];
+        if (!pathMethod) {
+            return c.json({ error: 'not found', code: 'NOT_FOUND' }, 404);
+        }
+        const result = params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+        if (result === false)
+            return c.json({ acknowledged: true }, 202);
+        if (result instanceof Error) {
+            return c.json({ error: result.message, code: 'BAD_REQUEST' }, 400);
+        }
+        const realReq = rebuildRequest(c.req.raw, c.req.path, url, result);
+        // Re-enter the app at the real route. The real path never starts with `/ctgr`, so
+        // this middleware does not re-match — no recursion.
+        let executionCtx;
+        try {
+            executionCtx = c.executionCtx;
+        }
+        catch {
+            executionCtx = undefined;
+        }
+        return app.fetch(realReq, c.env, executionCtx);
+    });
+    return store;
+}
+/** Build the real Request the decoded twin stands in for. */
+function rebuildRequest(raw, twinPath, url, decoded) {
+    // Strip the `/ctgr<xx>` prefix and the codec's own query params; keep the rest.
+    const realPath = twinPath.replace(/^\/ctgr../, '') || '/';
+    const kept = new URLSearchParams();
+    for (const [key, value] of url.searchParams) {
+        if (!isCtgrParam(key))
+            kept.set(key, value);
+    }
+    const search = kept.toString();
+    const realUrl = `${url.origin}${realPath}${search ? `?${search}` : ''}`;
+    const headers = new Headers(raw.headers);
+    headers.delete('content-length');
+    let body;
+    if (decoded.files && decoded.files.length > 0) {
+        const form = new FormData();
+        const fields = (decoded.body ?? {});
+        for (const [key, value] of Object.entries(fields)) {
+            form.append(key, typeof value === 'string' ? value : JSON.stringify(value));
+        }
+        for (const file of decoded.files) {
+            form.append(file.fieldname, new File([new Uint8Array(file.buffer)], file.originalname, { type: file.mimetype }));
+        }
+        body = form;
+        // Let the runtime set the multipart content-type + boundary.
+        headers.delete('content-type');
+    }
+    else if (decoded.body !== undefined) {
+        body = JSON.stringify(decoded.body);
+        headers.set('content-type', 'application/json');
+    }
+    return new Request(realUrl, { method: decoded.method, headers, body });
+}

package/dist/server/index.d.ts

@@ -3,6 +3,7 @@ export { type CreateAppOpts, createApp, type ServeBunOpts, serveBun } from './ap
 export { type AppJwtPayload, AUTH_COOKIE_NAME, type AuthEnv, type AuthUser, type AuthVariables, type CreateSessionInput, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, type CsrfOptions, clearAuthCookie, createAuthMiddleware, createCsrfMiddleware, clientKeyOf, clientKeyOfContext, createLoginThrottle, createSessionStore, createRs256FileTokenSigner, DEFAULT_TOTP_ISSUER, decryptVaultItem, deriveVaultKey, encryptVaultItem, generateRecoveryCodes, generateTotpSecret, getOnlyEnforcement, getTotpUri, hashPassword, isGetOnlyViolation, type LoginThrottle, type LoginThrottleOptions, type ThrottleVerdict, needsRehash, type Rs256FileTokenSignerOptions, type Session, type SessionStore, type SessionStoreOptions, signToken, type TokenPurpose, verifyPassword, verifyPurposeToken, verifyRecoveryCode, verifyToken, verifyTotpCode, } from './auth/index.js';
 export type { CursedbeltEnv, CursedbeltVariables } from './context.js';
 export { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr.js';
+export { type CtgrTunnelOptions, mountCtgrTunnel } from './ctgrTunnel.js';
 export { createKysely, type PlumbingDb } from './db/kysely.js';
 export type { AppConfigRow, AuthSessionRow, EmailFailureRow, EventLogRow, JobRunRow, JobStateRow, MigrationRow, PlumbingSchema, RequestMetricRow, SystemSampleRow, } from './db/plumbingTypes.js';
 export { ApiError, type ApiErrorOptions, type ErrorEnvelope, isApiError, toErrorEnvelope, toValidationIssues, VALIDATION_ERROR_CODE, type ValidationIssue, validationEnvelope, } from './errors.js';

package/dist/server/index.js

@@ -12,6 +12,7 @@ export { createApp, serveBun } from './app.js';
 //    login throttle, argon2id passwords, TOTP, vault crypto, the composed middleware.
 export { AUTH_COOKIE_NAME, CSRF_COOKIE_NAME, CSRF_HEADER_NAME, clearAuthCookie, createAuthMiddleware, createCsrfMiddleware, clientKeyOf, clientKeyOfContext, createLoginThrottle, createSessionStore, createRs256FileTokenSigner, DEFAULT_TOTP_ISSUER, decryptVaultItem, deriveVaultKey, encryptVaultItem, generateRecoveryCodes, generateTotpSecret, getOnlyEnforcement, getTotpUri, hashPassword, isGetOnlyViolation, needsRehash, signToken, verifyPassword, verifyPurposeToken, verifyRecoveryCode, verifyToken, verifyTotpCode, } from './auth/index.js';
 export { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr.js';
+export { mountCtgrTunnel } from './ctgrTunnel.js';
 // ── Kysely-typed plumbing tables ────────────────────────────────────────────
 export { createKysely } from './db/kysely.js';
 // ── Errors ──────────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.34.0",
+	"version": "4.36.0",
 	"license": "ISC",
 	"type": "module",
 	"description": "The app-facing Bun/Hono server tier of the cursedbelt split — storage, sharing, activity, guard, sync. React-free; cursedbelt-core below it.",
@@ -59,6 +59,12 @@
 			"source": "./src/server/context.ts",
 			"import": "./dist/server/context.js"
 		},
+		"./ctgr-tunnel": {
+			"types": "./dist/server/ctgrTunnel.d.ts",
+			"bun": "./src/server/ctgrTunnel.ts",
+			"source": "./src/server/ctgrTunnel.ts",
+			"import": "./dist/server/ctgrTunnel.js"
+		},
 		"./analytics": {
 			"types": "./dist/server/analytics/index.d.ts",
 			"bun": "./src/server/analytics/index.ts",

package/src/server/ctgrTunnel.spec.ts

@@ -0,0 +1,110 @@
+import { describe, expect, test } from 'bun:test';
+import { encodeRequest } from 'cursedbelt-core/ctgr';
+import { Hono } from 'hono';
+import type { CursedbeltEnv } from './context.js';
+import { mountCtgrTunnel } from './ctgrTunnel.js';
+
+const ORIGIN = 'http://localhost';
+
+/**
+ * An ordinary Hono app with ordinary handlers — NONE of them ctgr-aware. The tunnel
+ * is dropped on with one call; the handlers read `c.req.json()` / `c.req.formData()`
+ * exactly as they would for a real POST.
+ */
+function makeApp() {
+  const app = new Hono<CursedbeltEnv>();
+  const store = mountCtgrTunnel(app, { store: undefined });
+
+  app.post('/api/v1/notes', async (c) => {
+    const body = await c.req.json();
+    return c.json({ ok: true, method: c.req.method, body });
+  });
+  app.patch('/api/v1/notes/:id', async (c) => {
+    const body = await c.req.json();
+    return c.json({ ok: true, id: c.req.param('id'), method: c.req.method, body });
+  });
+  app.delete('/api/v1/notes/:id', (c) =>
+    c.json({ ok: true, id: c.req.param('id'), method: c.req.method, permanent: c.req.query('permanent') ?? null }),
+  );
+  app.post('/api/v1/media', async (c) => {
+    const form = await c.req.formData();
+    const file = form.get('file') as File;
+    return c.json({
+      ok: true,
+      name: form.get('name'),
+      file: { name: file.name, type: file.type, size: file.size },
+    });
+  });
+  app.get('/api/v1/notes', (c) => c.json({ list: true }));
+
+  return { app, store };
+}
+
+const fetchTwin = (app: Hono<CursedbeltEnv>, url: string) =>
+  app.fetch(new Request(ORIGIN + url));
+
+describe('mountCtgrTunnel — re-dispatch, zero handler changes', () => {
+  test('a single-chunk POST twin reaches the real handler with the decoded body', async () => {
+    const { app } = makeApp();
+    const { chunks } = await encodeRequest('POST', '/api/v1/notes', { title: 'hi', n: 1 });
+    const res = await fetchTwin(app, chunks[0].url);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({ ok: true, method: 'POST', body: { title: 'hi', n: 1 } });
+  });
+
+  test('a PATCH twin routes with its path param intact', async () => {
+    const { app } = makeApp();
+    const { chunks } = await encodeRequest('PATCH', '/api/v1/notes/abc', { done: true });
+    const res = await fetchTwin(app, chunks[0].url);
+    expect(await res.json()).toEqual({ ok: true, id: 'abc', method: 'PATCH', body: { done: true } });
+  });
+
+  test('a DELETE twin preserves the app query string and drops the codec params', async () => {
+    const { app } = makeApp();
+    const { chunks } = await encodeRequest('DELETE', '/api/v1/notes/z?permanent=1', undefined);
+    const res = await fetchTwin(app, chunks[0].url);
+    expect(await res.json()).toEqual({ ok: true, id: 'z', method: 'DELETE', permanent: '1' });
+  });
+
+  test('a FormData upload rebuilds as multipart the handler reads unchanged', async () => {
+    const { app } = makeApp();
+    // Encode the __files body shape the client converter produces.
+    const body = {
+      __files: [{ field: 'file', name: 'p.png', type: 'image/png', dataBase64: btoa('abc') }],
+      name: 'pic',
+    };
+    const { chunks } = await encodeRequest('POST', '/api/v1/media', body);
+    const res = await fetchTwin(app, chunks[0].url);
+    expect(await res.json()).toEqual({
+      ok: true,
+      name: 'pic',
+      file: { name: 'p.png', type: 'image/png', size: 3 },
+    });
+  });
+
+  test('a multi-chunk payload answers 202 until the last chunk, then runs once', async () => {
+    const { app } = makeApp();
+    // Incompressible-ish and gzip disabled, so it really splits into many chunks.
+    const big = { blob: Array.from({ length: 4000 }, (_, i) => String.fromCharCode(33 + (i % 90))).join('') };
+    const { chunks } = await encodeRequest('POST', '/api/v1/notes', big, {
+      chunkSizeBytes: 800,
+      gzipThresholdBytes: 10 * 1024 * 1024,
+    });
+    expect(chunks.length).toBeGreaterThan(1);
+    for (const chunk of chunks.slice(0, -1)) {
+      const res = await fetchTwin(app, chunk.url);
+      expect(res.status).toBe(202);
+    }
+    const final = await fetchTwin(app, chunks[chunks.length - 1].url);
+    expect(final.status).toBe(200);
+    expect(await final.json()).toEqual({ ok: true, method: 'POST', body: big });
+  });
+
+  test('an unknown method twin is a 404, and a real GET route is untouched', async () => {
+    const { app } = makeApp();
+    const bad = await fetchTwin(app, '/ctgrzz/api/v1/notes?_cv=1');
+    expect(bad.status).toBe(404);
+    const get = await fetchTwin(app, '/api/v1/notes');
+    expect(await get.json()).toEqual({ list: true });
+  });
+});

package/src/server/ctgrTunnel.ts

@@ -0,0 +1,120 @@
+/*
+ * The one-line server adapter for the GET-only tunnel: `mountCtgrTunnel(app)`.
+ *
+ * Where {@link unGETify} + {@link buildRoutes} ask each route to register a twin and
+ * read its body from `c.get('ctgrDecoded')`, this mounts a single middleware that
+ * DECODES a `/ctgr<xx>` GET twin and RE-DISPATCHES it into the same app at the real
+ * method + path — so every existing `app.post(...)` / `app.delete(...)` handler is
+ * reached unchanged, reading `await c.req.json()` / `c.req.formData()` as it always
+ * did. That is what makes the tunnel droppable onto any Hono app in one call.
+ *
+ * A single-chunk twin decodes inline; a multi-chunk payload accumulates in the shared
+ * {@link ChunkStore} (an intermediate chunk answers 202). Legacy `_cv`-absent twins
+ * fall through the v0 decoder. The middleware decodes and re-dispatches only; whatever
+ * gate stands in front of the app (Access, a session cookie, a getOnly claim) is
+ * unchanged and still runs on the real handler.
+ */
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import {
+  ABBREV_TO_METHOD,
+  type CtgrAbbrev,
+  type CtgrDecoded,
+} from 'cursedbelt-core/ctgr/types';
+import { V0ChunkStore } from 'cursedbelt-core/ctgr/v0compat';
+import type { ExecutionContext, Hono } from 'hono';
+import type { CursedbeltEnv } from './context.js';
+import { CTGR_ROUTE_PATTERN } from './ctgr.js';
+
+/** Query keys the codec adds to a twin URL — dropped when rebuilding the real request. */
+const isCtgrParam = (key: string): boolean =>
+  key === '_d' || key === '_sha' || key.startsWith('_c');
+
+export interface CtgrTunnelOptions {
+  /**
+   * The accumulator for multi-chunk payloads. Share ONE across an app (the default is
+   * a fresh singleton); pass your own to tune the DoS caps ({@link ChunkStore}).
+   */
+  store?: ChunkStore;
+}
+
+/**
+ * Mount the GET-only tunnel on `app`. Call once, on the Hono app whose real routes sit
+ * at the paths the twins mirror (a twin path is `/ctgr<xx>` + the real path). Returns
+ * the {@link ChunkStore} in use, for tests and metrics.
+ */
+export function mountCtgrTunnel<E extends CursedbeltEnv = CursedbeltEnv>(
+  app: Hono<E>,
+  options: CtgrTunnelOptions = {},
+): ChunkStore {
+  const store = options.store ?? new ChunkStore();
+  const legacy = new V0ChunkStore();
+
+  app.use(CTGR_ROUTE_PATTERN, async (c) => {
+    const url = new URL(c.req.url);
+    const params = Object.fromEntries(url.searchParams);
+    // The twin path is `/ctgr<xx>...`; the abbreviation is the two chars after `ctgr`.
+    const pathMethod = ABBREV_TO_METHOD[c.req.path.slice(5, 7) as CtgrAbbrev];
+    if (!pathMethod) {
+      return c.json({ error: 'not found', code: 'NOT_FOUND' }, 404);
+    }
+
+    const result =
+      params._cv === undefined ? legacy.add(params, pathMethod) : await store.add(params);
+
+    if (result === false) return c.json({ acknowledged: true }, 202);
+    if (result instanceof Error) {
+      return c.json({ error: result.message, code: 'BAD_REQUEST' }, 400);
+    }
+
+    const realReq = rebuildRequest(c.req.raw, c.req.path, url, result);
+    // Re-enter the app at the real route. The real path never starts with `/ctgr`, so
+    // this middleware does not re-match — no recursion.
+    let executionCtx: ExecutionContext | undefined;
+    try {
+      executionCtx = c.executionCtx as ExecutionContext;
+    } catch {
+      executionCtx = undefined;
+    }
+    return app.fetch(realReq, c.env as E, executionCtx);
+  });
+
+  return store;
+}
+
+/** Build the real Request the decoded twin stands in for. */
+function rebuildRequest(raw: Request, twinPath: string, url: URL, decoded: CtgrDecoded): Request {
+  // Strip the `/ctgr<xx>` prefix and the codec's own query params; keep the rest.
+  const realPath = twinPath.replace(/^\/ctgr../, '') || '/';
+  const kept = new URLSearchParams();
+  for (const [key, value] of url.searchParams) {
+    if (!isCtgrParam(key)) kept.set(key, value);
+  }
+  const search = kept.toString();
+  const realUrl = `${url.origin}${realPath}${search ? `?${search}` : ''}`;
+
+  const headers = new Headers(raw.headers);
+  headers.delete('content-length');
+
+  let body: BodyInit | undefined;
+  if (decoded.files && decoded.files.length > 0) {
+    const form = new FormData();
+    const fields = (decoded.body ?? {}) as Record<string, unknown>;
+    for (const [key, value] of Object.entries(fields)) {
+      form.append(key, typeof value === 'string' ? value : JSON.stringify(value));
+    }
+    for (const file of decoded.files) {
+      form.append(
+        file.fieldname,
+        new File([new Uint8Array(file.buffer)], file.originalname, { type: file.mimetype }),
+      );
+    }
+    body = form;
+    // Let the runtime set the multipart content-type + boundary.
+    headers.delete('content-type');
+  } else if (decoded.body !== undefined) {
+    body = JSON.stringify(decoded.body);
+    headers.set('content-type', 'application/json');
+  }
+
+  return new Request(realUrl, { method: decoded.method, headers, body });
+}

package/src/server/index.ts

@@ -68,6 +68,7 @@ export {
 } from './auth/index.js';
 export type { CursedbeltEnv, CursedbeltVariables } from './context.js';
 export { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr.js';
+export { type CtgrTunnelOptions, mountCtgrTunnel } from './ctgrTunnel.js';
 // ── Kysely-typed plumbing tables ────────────────────────────────────────────
 export { createKysely, type PlumbingDb } from './db/kysely.js';
 export type {