cursedbelt-server 4.33.1 → 4.35.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/dist/server/storage/binaryStore.d.ts

@@ -405,6 +405,29 @@ export declare function binaryStoreTenant(appId: string, env?: Record<string, st
  * apps and that is precisely why the difference goes unnoticed when it is not.
  */
 export declare function resolvedMediaTenant(appId: string, env?: Record<string, string | undefined>): string | null;
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export declare function storeUnreachableStatus(status: number): boolean;
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export declare class BinaryStoreUnreachableError extends Error {
+    readonly status = 503;
+    readonly code = "BYTE_STORE_UNREACHABLE";
+    constructor(op: string, key: string, detail: string);
+    getResponse(): Response;
+}
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):

package/dist/server/storage/binaryStore.js

@@ -430,7 +430,11 @@ export function createBinaryStore(cfg) {
                 method: 'PUT',
                 headers: mime ? { 'content-type': mime } : undefined,
                 body: bytes,
+            }).catch((cause) => {
+                throw new BinaryStoreUnreachableError('put', key, cause instanceof Error ? cause.message : String(cause));
             });
+            if (storeUnreachableStatus(res.status))
+                throw new BinaryStoreUnreachableError('put', key, String(res.status));
             if (!res.ok) {
                 // A 413 that reaches here despite the threshold above means the edge's
                 // real cap is lower than we think, or the caller disabled the
@@ -499,7 +503,12 @@ export function createBinaryStore(cfg) {
                     method: 'PUT',
                     headers: mime ? { 'content-type': mime } : undefined,
                     body: slice,
+                }).catch((cause) => {
+                    throw new BinaryStoreUnreachableError('putLarge', key, cause instanceof Error ? cause.message : String(cause));
                 });
+                if (storeUnreachableStatus(res.status)) {
+                    throw new BinaryStoreUnreachableError('putLarge', key, `chunk ${ci + 1}/${total}: ${res.status}`);
+                }
                 if (!res.ok) {
                     throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
                 }
@@ -752,6 +761,40 @@ export function binaryStoreTenant(appId, env = process.env) {
 export function resolvedMediaTenant(appId, env = process.env) {
     return readBinaryStoreEnv(appId, env)?.appId ?? null;
 }
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export function storeUnreachableStatus(status) {
+    return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530);
+}
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export class BinaryStoreUnreachableError extends Error {
+    status = 503;
+    code = 'BYTE_STORE_UNREACHABLE';
+    constructor(op, key, detail) {
+        super(`[binary-store] ${op} ${key}: the file store did not answer (${detail}) — nothing was saved; ` +
+            'everything already stored still opens. Try again when the home server is on.');
+        this.name = 'BinaryStoreUnreachableError';
+    }
+    getResponse() {
+        return new Response(JSON.stringify({
+            error: this.code,
+            message: 'The file store did not answer, so nothing was saved. Everything already stored still opens — try again in a moment.',
+        }), { status: 503, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': '30' } });
+    }
+}
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "cursedbelt-server",
-	"version": "4.33.1",
+	"version": "4.35.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.",

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 {

package/src/server/storage/binaryStore.spec.ts

@@ -34,6 +34,7 @@ import {
   BINARY_REPEAT_THRESHOLD,
   BINARY_REPEAT_WINDOW_MS,
   type BinaryStoreConfig,
+  BinaryStoreUnreachableError,
   binaryStoreTenant,
   createBinaryStore,
   normalizePrivateKeyPem,
@@ -41,6 +42,7 @@ import {
   repeatedBinaryKeys,
   resetRepeatedBinaryKeys,
   resolvedMediaTenant,
+  storeUnreachableStatus,
   wantsFresh,
 } from './binaryStore.js';
 import { binaryStoreFakeDefaults } from './binaryStoreFake.js';
@@ -962,3 +964,58 @@ describe('binaryStoreFakeDefaults', () => {
     expect(await fake.signToken({ k: 'c/a' }, 60)).toBe('fake-token');
   });
 });
+
+describe('🔴 a write the store could not ANSWER is a 503 that names it (2026-09-26)', () => {
+  it('502-504 and 52x/530 are the origin unreachable; everything else is its own answer', () => {
+    for (const status of [502, 503, 504, 520, 522, 524, 530]) expect(storeUnreachableStatus(status)).toBe(true);
+    for (const status of [400, 403, 404, 413, 422, 500, 507]) expect(storeUnreachableStatus(status)).toBe(false);
+  });
+
+  it('put on a 530 throws the typed error, keeping the [binary-store] head batch callers print', async () => {
+    reply = () => new Response('tunnel gone', { status: 530 });
+    const error = await makeStore().put('art/a.png', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toStartWith('[binary-store] put art/a.png: the file store did not answer (530)');
+    expect((error as BinaryStoreUnreachableError).status).toBe(503);
+  });
+
+  it('a fetch that THROWS is the same fact', async () => {
+    const store = makeStore({ fetch: () => Promise.reject(new Error('connection refused')) });
+    const error = await store.put('k', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toContain('connection refused');
+  });
+
+  it('putLarge says which chunk found the store gone', async () => {
+    reply = () => new Response('', { status: 502 });
+    const error = await makeStore()
+      .putLarge('v.mp4', new Uint8Array(10), 'video/mp4', { chunkBytes: 4 })
+      .catch((e: unknown) => e);
+    expect(error).toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toContain('chunk 1/3: 502');
+  });
+
+  it('🔴 getResponse() is the 503 a Hono app answers with when the error escapes a route', async () => {
+    const res = new BinaryStoreUnreachableError('put', 'k', '530').getResponse();
+    expect(res.status).toBe(503);
+    expect(res.headers.get('retry-after')).toBe('30');
+    expect(((await res.json()) as { error: string }).error).toBe('BYTE_STORE_UNREACHABLE');
+  });
+
+  it('…and a real Hono app DOES answer it, with no onError of its own', async () => {
+    const { Hono } = await import('hono');
+    const app = new Hono().post('/upload', () => {
+      throw new BinaryStoreUnreachableError('put', 'k', '530');
+    });
+    const res = await app.request('/upload', { method: 'POST' });
+    expect(res.status).toBe(503);
+    expect(((await res.json()) as { error: string }).error).toBe('BYTE_STORE_UNREACHABLE');
+  });
+
+  it("the origin's own refusals are unchanged — a 403 is still the plain status error", async () => {
+    reply = () => new Response('', { status: 403 });
+    const error = await makeStore().put('k', new Uint8Array([1])).catch((e: unknown) => e);
+    expect(error).not.toBeInstanceOf(BinaryStoreUnreachableError);
+    expect(String((error as Error).message)).toBe('[binary-store] put k: 403');
+  });
+});

package/src/server/storage/binaryStore.ts

@@ -725,7 +725,10 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
           headers: mime ? { 'content-type': mime } : undefined,
           body: bytes as unknown as BodyInit,
         },
-      );
+      ).catch((cause: unknown) => {
+        throw new BinaryStoreUnreachableError('put', key, cause instanceof Error ? cause.message : String(cause));
+      });
+      if (storeUnreachableStatus(res.status)) throw new BinaryStoreUnreachableError('put', key, String(res.status));
       if (!res.ok) {
         // A 413 that reaches here despite the threshold above means the edge's
         // real cap is lower than we think, or the caller disabled the
@@ -805,7 +808,12 @@ export function createBinaryStore(cfg: BinaryStoreConfig): BinaryStore {
             headers: mime ? { 'content-type': mime } : undefined,
             body: slice,
           },
-        );
+        ).catch((cause: unknown) => {
+          throw new BinaryStoreUnreachableError('putLarge', key, cause instanceof Error ? cause.message : String(cause));
+        });
+        if (storeUnreachableStatus(res.status)) {
+          throw new BinaryStoreUnreachableError('putLarge', key, `chunk ${ci + 1}/${total}: ${res.status}`);
+        }
         if (!res.ok) {
           throw new Error(`[binary-store] putLarge ${key} chunk ${ci + 1}/${total}: ${res.status}`);
         }
@@ -1071,6 +1079,48 @@ export function resolvedMediaTenant(
   return readBinaryStoreEnv(appId, env)?.appId ?? null;
 }
 
+/**
+ * binary-server's origin did not ANSWER a write — as opposed to answering "no".
+ *
+ * binary-server itself never answers 502, 503 or 504; those, and Cloudflare's 52x family (530 is a
+ * tunnel with no connector), are the edge speaking for an origin it could not reach — the owner's
+ * Mac off, asleep, or restarting. A thrown `fetch` is the same fact. Since 2026-09-26 the edge
+ * Worker takes an R2-backed tenant's whole upload itself in that case
+ * (`apps/binary-server/edge-worker/src/upload.ts`), so for desk and family this is what is left
+ * when BOTH halves failed; for a tenant whose bytes rest on the Mac it is simply "the Mac is off".
+ */
+export function storeUnreachableStatus(status: number): boolean {
+  return status === 502 || status === 503 || status === 504 || (status >= 520 && status <= 530);
+}
+
+/**
+ * The write could not reach the store. Carries `getResponse()`, so a Hono app that lets it escape
+ * a route answers a 503 that names the file store — Hono's default error handler returns
+ * `err.getResponse()` for any error that has one — instead of a bare `500 Internal Server Error`.
+ * The message keeps the `[binary-store] <op> <key>:` head every batch caller already prints.
+ */
+export class BinaryStoreUnreachableError extends Error {
+  readonly status = 503;
+  readonly code = 'BYTE_STORE_UNREACHABLE';
+  constructor(op: string, key: string, detail: string) {
+    super(
+      `[binary-store] ${op} ${key}: the file store did not answer (${detail}) — nothing was saved; ` +
+        'everything already stored still opens. Try again when the home server is on.',
+    );
+    this.name = 'BinaryStoreUnreachableError';
+  }
+  getResponse(): Response {
+    return new Response(
+      JSON.stringify({
+        error: this.code,
+        message:
+          'The file store did not answer, so nothing was saved. Everything already stored still opens — try again in a moment.',
+      }),
+      { status: 503, headers: { 'content-type': 'application/json; charset=utf-8', 'retry-after': '30' } },
+    );
+  }
+}
+
 /**
  * The standard env surface every tenant's secrets file carries
  * (`$FORGE_STATE/secrets/<app>.env`, written at bs registration):