cursedbelt-server 1.0.0

package/src/server/auth/vault.ts

@@ -0,0 +1,71 @@
+/**
+ * Vault item at-rest crypto — standard Web Crypto (HKDF-SHA256 + AES-256-GCM),
+ * replacing the old hand-rolled `secretBox`/`deriveKey` scheme. Auditable, native on
+ * modern Bun, zero dependencies. These primitives live in cursedbelt (not ca's
+ * business layer) because ru gains a vault too.
+ *
+ * Keying is SERVER-SECRET–derived (per user), NOT master-password–derived: the
+ * master password is a separate argon2id gate (a `Bun.password` hash — see
+ * {@link ./password}), so resetting it never requires re-encrypting vault data. The
+ * envelope carries a version byte so a future re-key can proceed row-by-row without
+ * a flag-day migration.
+ */
+
+const VERSION = 1;
+const IV_BYTES = 12; // 96-bit nonce — the AES-GCM standard
+const enc = new TextEncoder();
+const dec = new TextDecoder();
+
+/**
+ * Derive a per-user AES-256-GCM vault key from the server secret via HKDF. The
+ * per-user `salt` domain-separates users; `info` domain-separates this use of the
+ * secret. The returned key is non-extractable (encrypt/decrypt only).
+ */
+export async function deriveVaultKey(serverSecret: string, userId: string): Promise<CryptoKey> {
+  const baseKey = await crypto.subtle.importKey(
+    'raw',
+    enc.encode(serverSecret),
+    { name: 'HKDF' },
+    false,
+    ['deriveKey'],
+  );
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: enc.encode(`vault:${userId}`),
+      info: enc.encode('vault-item-key'),
+    },
+    baseKey,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+/**
+ * Encrypt vault item plaintext. Returns a base64 envelope:
+ *   `version(1B) || iv(12B) || ciphertext(+GCM tag)`
+ * A fresh random IV per call. Store the string verbatim in `vault_items.data`.
+ */
+export async function encryptVaultItem(key: CryptoKey, plaintext: string): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(IV_BYTES));
+  const ct = await crypto.subtle.encrypt({ name: 'AES-GCM', iv }, key, enc.encode(plaintext));
+  const envelope = new Uint8Array(1 + IV_BYTES + ct.byteLength);
+  envelope[0] = VERSION;
+  envelope.set(iv, 1);
+  envelope.set(new Uint8Array(ct), 1 + IV_BYTES);
+  return Buffer.from(envelope).toString('base64');
+}
+
+/** Decrypt an envelope produced by {@link encryptVaultItem}. Throws on an unknown
+ * version, a truncated envelope, or a failed GCM auth (tamper/wrong key). */
+export async function decryptVaultItem(key: CryptoKey, envelope: string): Promise<string> {
+  const bytes = new Uint8Array(Buffer.from(envelope, 'base64'));
+  if (bytes.length < 1 + IV_BYTES + 16) throw new Error('vault: envelope too short');
+  if (bytes[0] !== VERSION) throw new Error(`vault: unsupported envelope version ${bytes[0]}`);
+  const iv = bytes.subarray(1, 1 + IV_BYTES);
+  const ct = bytes.subarray(1 + IV_BYTES);
+  const plain = await crypto.subtle.decrypt({ name: 'AES-GCM', iv }, key, ct);
+  return dec.decode(plain);
+}

package/src/server/context.ts

@@ -0,0 +1,37 @@
+import type { CtgrDecoded, CtgrMethod } from 'cursedbelt-core/ctgr/types';
+
+/**
+ * The cursedbelt Hono environment. `createApp()` returns a `Hono<CursedbeltEnv>`
+ * so every middleware and handler shares one typed `c.get`/`c.set` surface.
+ *
+ * Only *plumbing* variables live here — request identity that the cross-cutting
+ * middleware owns. Business variables (roles, session, sharing) are added by the
+ * app's own auth/feature middleware via its own env extension (task 26+).
+ */
+export interface CursedbeltVariables {
+  /** Per-request correlation id. Set by {@link correlationId} on every request. */
+  correlationId: string;
+  /**
+   * Authenticated user id. cursedbelt never sets this — the app's auth middleware
+   * (task 26) populates it so the request logger can attribute metrics/events to a
+   * user. Optional because anonymous requests have none.
+   */
+  userId?: string;
+  /**
+   * The decoded original request on a `/ctgr*` GET twin. Set by the ctgr `unGETify`
+   * middleware; the downstream handler / zod validator reads the body from here.
+   */
+  ctgrDecoded?: CtgrDecoded;
+  /** The decoded original HTTP method of a ctgr-tunneled request. */
+  ctgrMethod?: CtgrMethod;
+  /**
+   * The parsed/coerced/stripped body a `zValidator(...)` route accepted. A convenience
+   * mirror of the typed `c.req.valid('json')` slot for handlers that prefer a getter.
+   * Set only on a validated route; `unknown` because the type is the route's schema.
+   */
+  validatedBody?: unknown;
+}
+
+export interface CursedbeltEnv {
+  Variables: CursedbeltVariables;
+}

package/src/server/ctgr.spec.ts

@@ -0,0 +1,138 @@
+import { describe, expect, test } from 'bun:test';
+import { Hono } from 'hono';
+import { toBase64 } from 'cursedbelt-core/ctgr';
+import { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import { encodeRequest } from 'cursedbelt-core/ctgr';
+import type { CursedbeltEnv } from './context';
+import { buildRoutes, CTGR_ROUTE_PATTERN, getCtgrDecoded, unGETify } from './ctgr';
+
+const ORIGIN = 'http://localhost';
+const fetchChunk = (app: Hono<CursedbeltEnv>, url: string, init?: RequestInit) =>
+  app.fetch(new Request(ORIGIN + url, init));
+
+// Mirror the legacy client encoder so we can exercise the v0 fallback path.
+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)))));
+};
+
+function makeApp() {
+  const app = new Hono<CursedbeltEnv>();
+  const store = new ChunkStore();
+  app.use(CTGR_ROUTE_PATTERN, unGETify(store));
+
+  const register = buildRoutes(app);
+  // An echo handler shared by the real verb route AND its GET twin: it reads the
+  // body from the ctgr-decoded context when tunneled, else from the request.
+  register('post', '/notes', async (c) => {
+    const decoded = getCtgrDecoded(c);
+    const body = decoded ? decoded.body : await c.req.json();
+    return c.json({ ok: true, rawMethod: c.req.method, decodedMethod: decoded?.method, body });
+  });
+  register('delete', '/notes/:id', (c) => {
+    const decoded = getCtgrDecoded(c);
+    return c.json({
+      ok: true,
+      id: c.req.param('id'),
+      method: decoded?.method,
+      body: decoded?.body,
+    });
+  });
+
+  // Binary download stays a PLAIN GET — never registered via buildRoutes, so no
+  // `/ctgrde/...` twin exists to mangle its bytes through base64url.
+  app.get('/files/:id/download', (c) => c.text(`binary:${c.req.param('id')}`));
+
+  return app;
+}
+
+describe('unGETify + buildRoutes (Hono integration)', () => {
+  test('a single-chunk POST twin runs the handler with the decoded body', async () => {
+    const app = makeApp();
+    const enc = await encodeRequest('POST', '/notes', { body: 'hi' });
+    const res = await fetchChunk(app, enc.chunks[0].url);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toEqual({
+      ok: true,
+      rawMethod: 'GET', // the transport is a GET — what the getOnly 403 keys off
+      decodedMethod: 'POST', // the decoded intent — what the handler/validator sees
+      body: { body: 'hi' },
+    });
+  });
+
+  test('the real verb route still works (no tunnel)', async () => {
+    const app = makeApp();
+    const res = await app.fetch(
+      new Request(`${ORIGIN}/notes`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ body: 'direct' }),
+      }),
+    );
+    expect(res.status).toBe(200);
+    const json = (await res.json()) as { rawMethod: string; body: unknown };
+    expect(json.rawMethod).toBe('POST');
+    expect(json.body).toEqual({ body: 'direct' });
+  });
+
+  test('a multi-chunk payload: intermediate chunks 202, the last drives the handler', async () => {
+    const app = makeApp();
+    // gzip disabled so the payload genuinely spans multiple chunks/requests.
+    const big = { body: 'q'.repeat(5000) };
+    const enc = await encodeRequest('POST', '/notes', big, {
+      chunkSizeBytes: 400,
+      gzipThresholdBytes: 10_000_000,
+    });
+    expect(enc.chunks.length).toBeGreaterThan(1);
+    for (const chunk of enc.chunks.slice(0, -1)) {
+      const res = await fetchChunk(app, chunk.url);
+      expect(res.status).toBe(202);
+    }
+    const final = await fetchChunk(app, enc.chunks.at(-1)!.url);
+    expect(final.status).toBe(200);
+    expect((await final.json()).body).toEqual(big);
+  });
+
+  test('a body-less DELETE twin decodes to a null body', async () => {
+    const app = makeApp();
+    const enc = await encodeRequest('DELETE', '/notes/7', undefined);
+    const res = await fetchChunk(app, enc.chunks[0].url);
+    expect(res.status).toBe(200);
+    expect(await res.json()).toMatchObject({ ok: true, id: '7', method: 'DELETE', body: null });
+  });
+
+  test('a legacy v0 request (no _cv) decodes via the compat path', async () => {
+    const app = makeApp();
+    const p = encodeV0(JSON.stringify({ body: 'legacy' }));
+    const res = await fetchChunk(app, `/ctgrpo/notes?p=${encodeURIComponent(p)}`);
+    expect(res.status).toBe(200);
+    expect((await res.json()).body).toEqual({ body: 'legacy' });
+  });
+
+  test('a corrupt tunneled payload returns a 400 error envelope', async () => {
+    const app = makeApp();
+    const enc = await encodeRequest('POST', '/notes', { body: 'hi' });
+    const tampered = enc.chunks[0].url.replace(/_sha=[0-9a-f]+/, '_sha=deadbeef');
+    const res = await fetchChunk(app, tampered);
+    expect(res.status).toBe(400);
+    expect((await res.json()).error.message).toMatch(/sha256/);
+  });
+
+  test('binary downloads stay a plain GET with NO ctgr twin', async () => {
+    const app = makeApp();
+    const direct = await fetchChunk(app, '/files/42/download');
+    expect(direct.status).toBe(200);
+    expect(await direct.text()).toBe('binary:42');
+    // No `/ctgrde/files/:id/download` route was registered → 404.
+    const twin = await fetchChunk(app, '/ctgrde/files/42/download');
+    expect(twin.status).toBe(404);
+  });
+});

package/src/server/ctgr.ts

@@ -0,0 +1,108 @@
+/*
+ * ctgr Hono transport — the server half of the GET-tunnel: the `unGETify` middleware
+ * that decodes a `/ctgr<XX>` twin's query params back into the original request, and
+ * the `buildRoutes` registrar that wires the real verb route and its GET twin from one
+ * call. The codec re-exports from `cursedbelt-server`; the browser side is `cursedbelt/client`.
+ *
+ * Protection is unchanged and lives elsewhere by design: the getOnly-claim 403 keys
+ * off the RAW request method (always GET on a twin) in the auth middleware, and the
+ * CSRF double-submit guard fires on every `/ctgr*` path. unGETify ONLY decodes.
+ */
+import type { Context, Hono, MiddlewareHandler } from 'hono';
+import type { H } from 'hono/types';
+import type { ChunkStore } from 'cursedbelt-core/ctgr/chunk-store';
+import {
+  ABBREV_TO_METHOD,
+  type CtgrAbbrev,
+  type CtgrDecoded,
+  type CtgrMethod,
+  METHOD_TO_ABBREV,
+} from 'cursedbelt-core/ctgr/types';
+import { V0ChunkStore } from 'cursedbelt-core/ctgr/v0compat';
+import type { CursedbeltEnv } from './context';
+import { ApiError, toErrorEnvelope } from './errors';
+
+/**
+ * The path pattern that matches EVERY ctgr GET twin (`/ctgr<XX>...`) and nothing
+ * else — mount the decode + CSRF + getOnly middleware on this. NOTE: Hono's router
+ * does not treat `/ctgr*` as a prefix wildcard (a bare-suffix `*` only matches a
+ * single following segment), so a named param with a `ctgr.+` regex is the correct,
+ * portable matcher (`.` spans `/`, so it covers multi-segment paths like
+ * `/ctgrpa/api/v1/lists/123`). Reuse this everywhere a `/ctgr*` mount is meant.
+ */
+export const CTGR_ROUTE_PATTERN = '/:ctgrTwin{ctgr.+}';
+
+/**
+ * Mount on {@link CTGR_ROUTE_PATTERN} (before the twin routes). A single chunk decodes
+ * inline; a multi-chunk payload accumulates in the injected {@link ChunkStore}
+ * (intermediate chunk → 202). The decoded request + method are stashed on the context for the
+ * downstream handler / validator (`c.get('ctgrDecoded')`). Legacy `_cv`-absent
+ * requests fall back to the v0 decoder for the rollout window.
+ */
+export function unGETify(store: ChunkStore): MiddlewareHandler<CursedbeltEnv> {
+  const legacy = new V0ChunkStore();
+  return async (c, next) => {
+    const params = Object.fromEntries(new URL(c.req.url).searchParams);
+    const pathMethod = ABBREV_TO_METHOD[c.req.path.slice(5, 7) as CtgrAbbrev];
+    if (!pathMethod) {
+      return c.json(toErrorEnvelope(new ApiError(400, 'ctgr: unknown method twin', { code: 'unknown_method' })), 400);
+    }
+
+    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(toErrorEnvelope(new ApiError(400, result.message, { code: 'ctgr_decode_failed' })), 400);
+
+    c.set('ctgrDecoded', result);
+    c.set('ctgrMethod', result.method);
+    await next();
+  };
+}
+
+/** Read the ctgr-decoded request a `/ctgr*` twin stashed, if this was a tunneled call. */
+export function getCtgrDecoded(c: Context<CursedbeltEnv>): CtgrDecoded | undefined {
+  return c.get('ctgrDecoded');
+}
+
+/** The internal dispatch shape of `app.on` — Hono's overload soup can't resolve a
+ *  runtime-length handler spread, so we assert the (method, path, ...handlers) shape
+ *  it accepts at runtime while keeping the public {@link buildRoutes} API type-safe. */
+type RouteDispatch = (
+  method: string,
+  path: string,
+  ...handlers: MiddlewareHandler<CursedbeltEnv>[]
+) => unknown;
+
+/**
+ * Twin registrar: one call registers the real verb route AND its `/ctgr<XX>` GET twin
+ * (same handlers; the global `/ctgr*` {@link unGETify} middleware decodes the body
+ * first). Binary/download routes MUST NOT go through this — register those as a plain
+ * `app.get(path, handler)` so their bytes never ride the base64url tunnel and get
+ * mangled.
+ */
+export function buildRoutes(app: Hono<CursedbeltEnv>) {
+  const on = app.on.bind(app) as RouteDispatch;
+  return function register(
+    method: CtgrMethod | Lowercase<CtgrMethod>,
+    path: string,
+    /*
+     * `H`, not `MiddlewareHandler`. These are ROUTE handlers: Hono's
+     * `MiddlewareHandler` must return `Promise<Response | void>`, so declaring it
+     * here forced every caller to be `async` for no reason — a plain
+     * `(c) => c.json(…)` did not typecheck against a registrar whose whole job is
+     * registering exactly that. `H` is Hono's own union of both kinds and is what
+     * `app.on` accepts.
+     */
+    ...handlers: H<CursedbeltEnv>[]
+  ): void {
+    const upper = method.toUpperCase() as CtgrMethod;
+    const abbrev = METHOD_TO_ABBREV[upper];
+    if (!abbrev) throw new Error(`buildRoutes: "${method}" is not a ctgr-tunnelable method`);
+
+    // The real verb route + its GET twin, from one call.
+    on(upper, path, ...handlers);
+    on('GET', `/ctgr${abbrev}${path}`, ...handlers);
+  };
+}

package/src/server/db/kysely.spec.ts

@@ -0,0 +1,62 @@
+import { Database } from 'bun:sqlite';
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { createKysely, type PlumbingDb } from './kysely';
+
+const AUTH_SESSIONS_DDL = `CREATE TABLE auth_sessions (
+  session_id TEXT PRIMARY KEY, user_id TEXT NOT NULL, created_at TEXT NOT NULL,
+  last_seen_at TEXT NOT NULL, refresh_expires_at TEXT NOT NULL, access_expires_at TEXT,
+  get_only INTEGER NOT NULL DEFAULT 0, disabled INTEGER NOT NULL DEFAULT 0,
+  disabled_at TEXT, disabled_by TEXT, user_agent TEXT, ip TEXT
+)`;
+
+describe('createKysely (plumbing tables)', () => {
+  let db: Database;
+  let ky: PlumbingDb;
+
+  beforeEach(() => {
+    db = new Database(':memory:');
+    db.run(AUTH_SESSIONS_DDL);
+    db.run(
+      'CREATE TABLE app_config (key TEXT PRIMARY KEY, value TEXT NOT NULL, updated_at TEXT NOT NULL, updated_by TEXT)',
+    );
+    ky = createKysely(db);
+  });
+
+  afterEach(async () => {
+    await ky.destroy();
+  });
+
+  test('typed selectAll on an empty plumbing table returns []', async () => {
+    const rows = await ky.selectFrom('auth_sessions').selectAll().execute();
+    expect(rows).toEqual([]);
+  });
+
+  test('typed insert + select round-trips a row', async () => {
+    await ky
+      .insertInto('app_config')
+      .values({ key: 'media_backend', value: 'disk', updated_at: 't', updated_by: null })
+      .execute();
+
+    const row = await ky
+      .selectFrom('app_config')
+      .select(['key', 'value'])
+      .where('key', '=', 'media_backend')
+      .executeTakeFirst();
+
+    expect(row).toEqual({ key: 'media_backend', value: 'disk' });
+  });
+
+  test('reads through the SAME connection (raw write is visible to Kysely)', async () => {
+    db.run(
+      `INSERT INTO auth_sessions (session_id, user_id, created_at, last_seen_at, refresh_expires_at)
+       VALUES ('s1', 'u1', 't', 't', 't')`,
+    );
+    const row = await ky
+      .selectFrom('auth_sessions')
+      .selectAll()
+      .where('session_id', '=', 's1')
+      .executeTakeFirst();
+    expect(row?.user_id).toBe('u1');
+    expect(row?.get_only).toBe(0);
+  });
+});

package/src/server/db/kysely.ts

@@ -0,0 +1,21 @@
+import type { Database } from 'bun:sqlite';
+import { Kysely } from 'kysely';
+import { BunSqliteDialect } from 'kysely-bun-sqlite';
+import type { PlumbingSchema } from './plumbingTypes';
+
+/**
+ * A Kysely query builder typed to the {@link PlumbingSchema} plumbing tables, on the
+ * `bun:sqlite` dialect. Use it for type-checked reads/writes of sessions, config,
+ * logs, metrics, and jobs. Business / `data JSON` tables stay on raw `db.query()` —
+ * do NOT add them here (that would couple the Kysely schema to every feature table).
+ *
+ * The dialect wraps the SAME `Database` handle the rest of the app uses, so there is
+ * one connection, one WAL, one transaction space.
+ */
+export function createKysely(db: Database): Kysely<PlumbingSchema> {
+  return new Kysely<PlumbingSchema>({
+    dialect: new BunSqliteDialect({ database: db }),
+  });
+}
+
+export type PlumbingDb = Kysely<PlumbingSchema>;

package/src/server/db/plumbingTypes.ts

@@ -0,0 +1,126 @@
+/**
+ * TypeScript row interfaces for the *plumbing* tables — the structural, non-business
+ * tables cursedbelt owns: sessions, config, logs, metrics, jobs, the migration
+ * sentinel. These get Kysely-typed access (see `./kysely`) so the toolkit's own
+ * queries are type-checked.
+ *
+ * Business / feature tables (notes, lists, shares, …) deliberately stay OUT of this
+ * schema: they keep raw `db.query()` + flexible `data JSON`, so the Kysely schema is
+ * not coupled to every feature table. Shapes mirror the canonical DDL (task 22,
+ * `0001_initial`). INTEGER booleans are kept as `number` (SQLite has no real bool).
+ */
+
+export interface AuthSessionRow {
+  session_id: string;
+  user_id: string;
+  created_at: string;
+  last_seen_at: string;
+  refresh_expires_at: string;
+  access_expires_at: string | null;
+  /** 0 | 1 — the `/f` GET-only restriction, enforced + audited per session. */
+  get_only: number;
+  /** 0 | 1 */
+  disabled: number;
+  disabled_at: string | null;
+  disabled_by: string | null;
+  user_agent: string | null;
+  ip: string | null;
+}
+
+export interface AppConfigRow {
+  key: string;
+  value: string;
+  updated_at: string;
+  updated_by: string | null;
+}
+
+export interface EventLogRow {
+  id: string;
+  correlation_id: string | null;
+  event_name: string;
+  /** info | warn | error (free text, defaults to 'info'). */
+  type: string;
+  message: string | null;
+  /** JSON blob of structured detail. */
+  details: string | null;
+  duration_ms: number | null;
+  user_id: string | null;
+  created_at: string;
+}
+
+export interface RequestMetricRow {
+  id: string;
+  /** Epoch ms. */
+  ts: number;
+  method: string | null;
+  route: string | null;
+  status: number | null;
+  duration_ms: number | null;
+  bytes_out: number | null;
+  user_id: string | null;
+}
+
+export interface SystemSampleRow {
+  id: string;
+  /** Epoch ms. */
+  ts: number;
+  rss: number | null;
+  heap_used: number | null;
+  heap_total: number | null;
+  os_used: number | null;
+  os_total: number | null;
+  uptime_s: number | null;
+  event_loop_lag_ms: number | null;
+  ws_clients: number | null;
+  req_count: number | null;
+  err_count: number | null;
+  avg_duration_ms: number | null;
+}
+
+export interface EmailFailureRow {
+  id: string;
+  created_at: string;
+  recipient: string;
+  subject: string;
+  /** Defaults to 'send_error'. */
+  reason: string;
+  error_name: string | null;
+  error_code: string | null;
+  error_message: string | null;
+  details: string | null;
+}
+
+export interface JobStateRow {
+  name: string;
+  last_run_at: string | null;
+  /** JSON blob. */
+  meta: string | null;
+}
+
+export interface JobRunRow {
+  id: string;
+  job_name: string;
+  started_at: string;
+  ended_at: string | null;
+  /** running | ok | error (defaults to 'running'). */
+  status: string;
+  error: string | null;
+}
+
+export interface MigrationRow {
+  name: string;
+  applied_at: string;
+}
+
+/** The Kysely database schema for cursedbelt plumbing tables. */
+export interface PlumbingSchema {
+  auth_sessions: AuthSessionRow;
+  app_config: AppConfigRow;
+  event_logs: EventLogRow;
+  request_metrics: RequestMetricRow;
+  system_samples: SystemSampleRow;
+  email_failures: EmailFailureRow;
+  job_state: JobStateRow;
+  job_runs: JobRunRow;
+  _migrations: MigrationRow;
+}

package/src/server/dropzone/duplicates.ts

@@ -0,0 +1,121 @@
+/**
+ * Asking binary-server "do you already have this?" — the client half.
+ *
+ * Owner's ask, 2026-08-13: *"make strategy to always check for duplicate binaries in same app
+ * for same user, automatically skip if it's literally a duplicate file"* … *"if it's an
+ * automated upload with ingestions or an agent guiding it and I need to make a decision put it
+ * in binary-server UI for me to see and handle it."*
+ *
+ * ── 🔴 Asked BEFORE the bytes move, and that ordering is the whole point ───────────────
+ * The obvious design is upload-then-detect: store it, notice the collision, delete one. That
+ * moves every duplicate twice, and on a media dropzone it does so for multi-gigabyte video the
+ * store already holds. The scraper has the file, so it has the digest; one small POST answers
+ * the question before a single byte is sent.
+ *
+ * ── 🔴 It lives in cursedbelt, not in satellite-kit ────────────────────────────────────
+ * binary-server itself consumes `cursedbelt` and does NOT consume `satellite-kit`, and every
+ * ingesting app consumes both. This is the one shelf both sides can see. It is also the reason
+ * the request/response shape is stated here as types rather than being re-declared by each
+ * caller — a dropzone that got `hold` backwards would upload exactly the files the owner asked
+ * it to park.
+ */
+
+import { createHash } from "node:crypto";
+import { createReadStream } from "node:fs";
+
+export interface DuplicateQuestion {
+	/** binary-server's loopback origin. Never the public tunnel — see the note below. */
+	baseUrl: string;
+	/** The shared internal secret; this route is internal-only and 403s without it. */
+	internalSecret: string;
+	/** The binary-server tenant, e.g. `music`. */
+	app: string;
+	/** Scope the comparison to one user. Null on the owner-only apps, which is normal. */
+	ownerId?: string | null;
+	/** sha256 of the bytes about to be uploaded, hex. {@link hashFile} produces it. */
+	checksum: string;
+	size: number;
+	/** The name the object would carry — what the "same name" half of the rule compares. */
+	name: string;
+	/** Where the file is right now, so the owner's later decision can act on it. */
+	heldPath?: string | null;
+}
+
+export interface DuplicateVerdict {
+	/** Present when the store already holds these exact bytes. Skip the upload entirely. */
+	exact: { key: string; title: string | null; size: number } | null;
+	/** Name-alikes with different bytes — a question, never an instruction. */
+	likely: { key: string; title: string | null; size: number; reason: string }[];
+	/** True when the caller must NOT upload and must park the file for the owner. */
+	hold: boolean;
+	/** The review-queue row binary-server filed, when it filed one. */
+	candidateId: string | null;
+}
+
+/**
+ * Streaming sha256 of a file on disk.
+ *
+ * Streamed rather than buffered because a music library is thousands of files and some of them
+ * are 60 MB; reading each one whole to hash it is how an ingest becomes a memory problem.
+ */
+export function hashFile(path: string): Promise<string> {
+	return new Promise((resolve, reject) => {
+		const hash = createHash("sha256");
+		const stream = createReadStream(path);
+		stream.on("error", reject);
+		stream.on("data", (chunk) => hash.update(chunk));
+		stream.on("end", () => resolve(hash.digest("hex")));
+	});
+}
+
+/**
+ * Ask binary-server about one incoming file.
+ *
+ * 🔴 **Fails OPEN, deliberately.** If binary-server cannot be reached, or answers something
+ * unexpected, the verdict is "no duplicate, do not hold" and the ingest proceeds. The
+ * alternative is that a dropzone stops taking the owner's files because a de-duplication
+ * nicety is down — trading a real capability for a housekeeping one. A duplicate that slips
+ * through costs disk and is found later by the scan button, which is exactly what that button
+ * is for.
+ *
+ * 🔴 **`baseUrl` must be the LOOPBACK origin.** The route is absent from binary-server's
+ * public path allowlist and 404s when the request arrives bearing the public tunnel Host —
+ * because it reports the titles and sizes of stored objects, and listing is what the tunnel
+ * must never publish. A caller that passes the public URL gets a 404 and, through the
+ * fail-open above, silently loses de-duplication entirely. notes shipped this exact bug once
+ * with `/api/transcode`.
+ */
+export async function askBinaryServerAboutDuplicate(
+	q: DuplicateQuestion,
+): Promise<DuplicateVerdict> {
+	const none: DuplicateVerdict = { exact: null, likely: [], hold: false, candidateId: null };
+	if (!q.internalSecret) return none;
+	try {
+		const res = await fetch(`${q.baseUrl.replace(/\/+$/, "")}/internal/ops/duplicates/check`, {
+			method: "POST",
+			headers: {
+				"content-type": "application/json",
+				"x-internal-secret": q.internalSecret,
+			},
+			body: JSON.stringify({
+				app: q.app,
+				ownerId: q.ownerId ?? null,
+				checksum: q.checksum,
+				size: q.size,
+				name: q.name,
+				origin: "automated",
+				heldPath: q.heldPath ?? null,
+			}),
+		});
+		if (!res.ok) return none;
+		const body = (await res.json()) as Partial<DuplicateVerdict>;
+		return {
+			exact: body.exact ?? null,
+			likely: body.likely ?? [],
+			hold: body.hold === true,
+			candidateId: body.candidateId ?? null,
+		};
+	} catch {
+		return none;
+	}
+}