cursedbelt-server 1.0.0

package/src/server/master-lock/seed.ts

@@ -0,0 +1,112 @@
+/**
+ * Minting a `MASTER_LOCK_SEED` from a password nobody has to guess.
+ *
+ * ── Why this exists (2026-08-20) ────────────────────────────────────────────
+ * The lock's seed is `{kdf, verifierHash, idleMs}` — a KDF descriptor and an
+ * argon2id hash of a PBKDF2 verifier. Every one of those steps is derivable from
+ * the modules beside this one, and until now every one of them was something an
+ * operator had to reproduce by hand in a REPL to arm a new instance. That is the
+ * shape of instruction that gets written into a runbook and then gets a digit
+ * wrong; the fleet's standing answer to that is a function
+ * (`fleet/rules/automation-over-documentation.md`).
+ *
+ * The immediate caller is the ephemeral **stage** environment, whose entire
+ * purpose is to have a master-lock password an AGENT knows, so it can open
+ * `collections` and the binary-server inspector and actually look at them — two
+ * screens no agent has ever seen, because production's password is the vault's
+ * and is the owner's alone.
+ *
+ * 🔴 **A different PASSWORD, never a different SCHEME.** The derivation stays
+ * byte-identical to `apps/vault`'s (see `../../core/master-lock/kdf.ts`), because
+ * a stage that unlocks under different rules from production proves nothing about
+ * production. This function chooses the salt and the password; it changes nothing
+ * else.
+ */
+import { DEFAULT_IDLE_MS } from "cursedbelt-core/master-lock/policy";
+import {
+	type MasterLockKdfParams,
+	deriveMasterLockVerifier,
+	newMasterLockKdfParams,
+} from "cursedbelt-core/master-lock/kdf";
+import type { MasterLockRecord } from "./masterLock";
+
+/**
+ * The idle window a freshly minted lock starts with.
+ *
+ * 🔴 It is `DEFAULT_IDLE_MS` ITSELF, not a copy that claims to match it. Until
+ * 2026-08-25 this read `15 * 60 * 1000` under a comment saying "matches the store's
+ * default", which is 5 minutes — so any app armed through `mintMasterLockSeed` would
+ * have silently got three times the window the owner asked for. Live prod was spared
+ * only by accident: both seeds omit `idleMs` entirely, so the store's own default
+ * applied. A second constant that must equal a first is a drift waiting for a reader
+ * who trusts the comment; there is now only one number.
+ */
+export const DEFAULT_SEED_IDLE_MS = DEFAULT_IDLE_MS;
+
+export interface MintMasterLockSeedOptions {
+	/** Override the idle timeout baked into the seed. */
+	idleMs?: number;
+	/** Reuse existing params instead of generating a salt — for a rotation. */
+	kdf?: MasterLockKdfParams;
+}
+
+/**
+ * `password` → the record an app can be seeded with.
+ *
+ * Returns the parsed record; {@link serializeMasterLockSeed} is what turns it
+ * into the env value, because that step has its own trap (see below).
+ */
+export async function mintMasterLockSeed(
+	password: string,
+	options: MintMasterLockSeedOptions = {},
+): Promise<MasterLockRecord> {
+	if (password.length < 8) {
+		// Not a policy — a floor. A seed minted from a two-character password would
+		// arm a lock that reads as protection and is not.
+		throw new Error("master-lock password must be at least 8 characters");
+	}
+	const kdf = options.kdf ?? newMasterLockKdfParams();
+	const verifier = await deriveMasterLockVerifier(password, kdf);
+	return {
+		kdf,
+		verifierHash: await Bun.password.hash(verifier, { algorithm: "argon2id" }),
+		idleMs: options.idleMs ?? DEFAULT_SEED_IDLE_MS,
+	};
+}
+
+/**
+ * The record as it belongs in a 0600 `.env` file.
+ *
+ * 🔴 **SINGLE-QUOTED, and this is not cosmetic.** An argon2id PHC string contains
+ * `$`, the file is sourced by a shell, and an unquoted value therefore arrives at
+ * the app with `$argon2id` expanded to nothing. `readRecord` strips exactly this
+ * quote pair — `apps/collections` shipped a *doubly*-quoted hash to prod on
+ * 2026-08-12 and spent a day being told its correct passphrase was wrong, which
+ * is why the strip is on the whole blob rather than on the field.
+ */
+export function serializeMasterLockSeed(record: MasterLockRecord): string {
+	return `'${JSON.stringify(record)}'`;
+}
+
+/**
+ * A password worth typing into a stage: unambiguous, and long enough that the
+ * hostname being on the internet behind Cloudflare Access is not the only thing
+ * protecting it.
+ *
+ * No `l`, `1`, `O` or `0` — a stage password gets read out of a terminal and
+ * typed into a browser by hand, and this is the one place where that matters.
+ */
+export function generateStagePassword(words = 4): string {
+	const alphabet = "abcdefghijkmnpqrstuvwxyzACDEFGHJKLMNPQRSTUVWXYZ23456789";
+	const bytes = new Uint8Array(words * 5);
+	crypto.getRandomValues(bytes);
+	const chunks: string[] = [];
+	for (let w = 0; w < words; w += 1) {
+		let chunk = "";
+		for (let i = 0; i < 5; i += 1) {
+			chunk += alphabet[(bytes[w * 5 + i] as number) % alphabet.length];
+		}
+		chunks.push(chunk);
+	}
+	return chunks.join("-");
+}

package/src/server/master-lock/store.ts

@@ -0,0 +1,35 @@
+/**
+ * Two ways to keep the record, so no app has to invent a third.
+ *
+ * The record is one JSON blob on purpose: every app that will ever mount this already has
+ * somewhere to put a string under a key — binary-server's `settings` table, a satellite's
+ * `app_settings`, a `Map` in a test. Asking for a whole table would be asking each adopter
+ * to write a migration for three fields.
+ */
+import type { MasterLockStore } from "./masterLock";
+
+/** The default key, so two apps' rows look the same when somebody goes looking. */
+export const MASTER_LOCK_SETTING_KEY = "master_lock:record";
+
+/** Wrap an app's existing key/value settings surface. */
+export function createKvMasterLockStore(
+	kv: { get(key: string): string | null | undefined; set(key: string, value: string): void },
+	key: string = MASTER_LOCK_SETTING_KEY,
+): MasterLockStore {
+	return {
+		read: () => kv.get(key) ?? null,
+		write: (json) => kv.set(key, json),
+	};
+}
+
+/** For tests, and for a runtime with nowhere to persist — where it means the lock re-seeds
+ *  from the environment on every boot, which is the correct fallback rather than a failure. */
+export function createMemoryMasterLockStore(initial?: string | null): MasterLockStore {
+	let value = initial ?? null;
+	return {
+		read: () => value,
+		write: (json) => {
+			value = json;
+		},
+	};
+}

package/src/server/media-bun/image.spec.ts

@@ -0,0 +1,115 @@
+import { describe, expect, test } from 'bun:test';
+import type { ImagePipelineSpec } from 'cursedbelt-core/media';
+import { renderImage } from './image';
+
+// sharp is an OPTIONAL peer — skip this whole suite cleanly when it isn't installed.
+let sharpFactory: typeof import('sharp').default | null = null;
+try {
+  sharpFactory = (await import('sharp')).default;
+} catch {
+  sharpFactory = null;
+}
+const sharp = sharpFactory;
+
+/** A solid-color JPEG of `w×h` to feed renderImage as a real encoded source. */
+async function jpeg(w: number, h: number, color = { r: 200, g: 50, b: 50 }): Promise<Buffer> {
+  if (!sharp) throw new Error('sharp unavailable');
+  return sharp({ create: { width: w, height: h, channels: 3, background: color } })
+    .jpeg()
+    .toBuffer();
+}
+
+// SKIPPED when the OPTIONAL `sharp` peer is not installed — it is this suite's subject. Runs by default when it is.
+describe.skipIf(!sharp)('renderImage (sharp)', () => {
+  test('resize + format-convert → webp with the right dimensions (acceptance #8)', async () => {
+    const src = await jpeg(400, 300);
+    const spec: ImagePipelineSpec = {
+      input: src,
+      operations: [{ type: 'resize', width: 200 }],
+      output: { format: 'webp', quality: 80 },
+    };
+    const out = await renderImage(spec);
+    expect(out.length).toBeGreaterThan(0);
+    const meta = await sharp!(out).metadata();
+    expect(meta.format).toBe('webp');
+    expect(meta.width).toBe(200);
+    expect(meta.height).toBe(150); // aspect preserved (cover with width-only)
+  });
+
+  test('crop extracts the requested region', async () => {
+    const src = await jpeg(100, 100);
+    const out = await renderImage({
+      input: src,
+      operations: [{ type: 'crop', left: 10, top: 20, width: 40, height: 30 }],
+      output: { format: 'png' },
+    });
+    const meta = await sharp!(out).metadata();
+    expect(meta.width).toBe(40);
+    expect(meta.height).toBe(30);
+  });
+
+  test('rotate by 90° swaps dimensions', async () => {
+    const src = await jpeg(120, 60);
+    const out = await renderImage({
+      input: src,
+      operations: [{ type: 'rotate', angle: 90 }],
+      output: { format: 'png' },
+    });
+    const meta = await sharp!(out).metadata();
+    expect(meta.width).toBe(60);
+    expect(meta.height).toBe(120);
+  });
+
+  test('accepts a file path input + jpeg output', async () => {
+    const src = await jpeg(50, 50);
+    const tmp = `${require('node:os').tmpdir()}/cb-media-${process.pid}-src.jpg`;
+    await Bun.write(tmp, src);
+    const out = await renderImage({
+      input: tmp,
+      operations: [],
+      output: { format: 'jpeg', quality: 70 },
+    });
+    expect((await sharp!(out).metadata()).format).toBe('jpeg');
+    require('node:fs').rmSync(tmp, { force: true });
+  });
+
+  test('remove-bg clears the edge-connected background to transparent', async () => {
+    if (!sharp) return;
+    // 8×8: red border, blue 4×4 center.
+    const W = 8;
+    const H = 8;
+    const raw = Buffer.alloc(W * H * 3);
+    for (let y = 0; y < H; y++) {
+      for (let x = 0; x < W; x++) {
+        const i = (y * W + x) * 3;
+        const center = x >= 2 && x <= 5 && y >= 2 && y <= 5;
+        raw[i] = center ? 0 : 255;
+        raw[i + 1] = 0;
+        raw[i + 2] = center ? 255 : 0;
+      }
+    }
+    const src = await sharp(raw, { raw: { width: W, height: H, channels: 3 } })
+      .png()
+      .toBuffer();
+    const out = await renderImage({
+      input: src,
+      operations: [{ type: 'remove-bg', tolerance: 10 }],
+      output: { format: 'png' },
+    });
+    const { data, info } = await sharp(out)
+      .ensureAlpha()
+      .raw()
+      .toBuffer({ resolveWithObject: true });
+    expect(info.channels).toBe(4);
+    const alphaAt = (x: number, y: number) => data[(y * info.width + x) * 4 + 3];
+    expect(alphaAt(0, 0)).toBe(0); // corner background gone
+    expect(alphaAt(3, 3)).toBe(255); // subject intact
+  });
+
+  test('rejects an invalid spec before touching sharp', async () => {
+    // input '' is a valid string type but an invalid value → validation rejects pre-sharp.
+    await expect(
+      renderImage({ input: '', operations: [], output: { format: 'webp' } }),
+    ).rejects.toThrow(/Invalid ImagePipelineSpec/);
+  });
+});

package/src/server/media-bun/image.ts

@@ -0,0 +1,134 @@
+// Image rendering via sharp. sharp is an OPTIONAL peer dep, imported LAZILY inside
+// renderImage so merely importing `cursedbelt-server` never loads the native binary
+// — only an app that actually renders an image pays for it. The transforms are driven
+// by the media-core `ImagePipelineSpec`; `remove-bg` runs the pure media-core BFS on
+// sharp's raw RGBA buffer, then re-wraps the result.
+
+import {
+  assertValidImagePipelineSpec,
+  clampQuality,
+  floodFillBGS,
+  type ImageOperation,
+  type ImageOutputFormat,
+  type ImagePipelineSpec,
+} from 'cursedbelt-core/media';
+
+// Type-only — erased at runtime, so this does NOT eagerly load sharp.
+type SharpModule = typeof import('sharp');
+type SharpFactory = SharpModule['default'];
+type SharpInstance = ReturnType<SharpFactory>;
+
+let sharpPromise: Promise<SharpFactory> | null = null;
+
+/** Lazily import sharp once; a clear error if the optional peer isn't installed. */
+async function loadSharp(): Promise<SharpFactory> {
+  if (!sharpPromise) {
+    sharpPromise = import('sharp')
+      .then((m) => m.default)
+      .catch((err) => {
+        sharpPromise = null;
+        throw new Error(
+          `cursedbelt media: 'sharp' is required for renderImage but could not be loaded. ` +
+            `Install it in the app (it is an optional peer dependency). Cause: ${
+              err instanceof Error ? err.message : String(err)
+            }`,
+        );
+      });
+  }
+  return sharpPromise;
+}
+
+/** Run a sharp pipeline to a fresh, transparent RGBA buffer, BFS it, re-wrap it. */
+async function applyRemoveBg(
+  sharp: SharpFactory,
+  img: SharpInstance,
+  op: Extract<ImageOperation, { type: 'remove-bg' }>,
+): Promise<SharpInstance> {
+  const { data, info } = await img.ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  const out = floodFillBGS(new Uint8Array(data.buffer, data.byteOffset, data.byteLength), {
+    width: info.width,
+    height: info.height,
+    channels: 4,
+    tolerance: op.tolerance,
+  });
+  return sharp(Buffer.from(out.buffer, out.byteOffset, out.byteLength), {
+    raw: { width: info.width, height: info.height, channels: 4 },
+  });
+}
+
+function applyResize(
+  img: SharpInstance,
+  op: Extract<ImageOperation, { type: 'resize' }>,
+): SharpInstance {
+  return img.resize({
+    width: op.width,
+    height: op.height,
+    fit: op.fit ?? 'cover',
+    withoutEnlargement: false,
+  });
+}
+
+/**
+ * Render an `ImagePipelineSpec` to an encoded image buffer. Operations are applied in
+ * order; `compress` overrides the output quality; `format-convert` is a no-op marker
+ * (the output format does the conversion). Throws on an invalid spec (before sharp).
+ */
+export async function renderImage(spec: ImagePipelineSpec): Promise<Buffer> {
+  assertValidImagePipelineSpec(spec);
+  const sharp = await loadSharp();
+
+  const source =
+    typeof spec.input === 'string'
+      ? spec.input
+      : Buffer.from(spec.input.buffer, spec.input.byteOffset, spec.input.byteLength);
+  // `failOn: 'none'` keeps a slightly-truncated upload from hard-failing the pipeline.
+  let img = sharp(source as string | Buffer, { failOn: 'none' });
+
+  let quality = spec.output.quality;
+  for (const op of spec.operations) {
+    switch (op.type) {
+      case 'resize':
+        img = applyResize(img, op);
+        break;
+      case 'crop':
+        img = img.extract({ left: op.left, top: op.top, width: op.width, height: op.height });
+        break;
+      case 'rotate':
+        // Default background transparent so a non-90° rotate doesn't fill with black.
+        img = img.rotate(op.angle, { background: { r: 0, g: 0, b: 0, alpha: 0 } });
+        break;
+      case 'flip':
+        img = op.direction === 'vertical' ? img.flip() : img.flop();
+        break;
+      case 'remove-bg':
+        img = await applyRemoveBg(sharp, img, op);
+        break;
+      case 'compress':
+        quality = op.quality;
+        break;
+      case 'format-convert':
+        break;
+    }
+  }
+
+  return encode(img, spec.output.format, quality);
+}
+
+function encode(
+  img: SharpInstance,
+  format: ImageOutputFormat,
+  quality: number | undefined,
+): Promise<Buffer> {
+  const q = clampQuality(quality);
+  switch (format) {
+    case 'jpeg':
+      return img.jpeg({ quality: q, mozjpeg: true }).toBuffer();
+    case 'png':
+      // PNG is lossless; map quality → effort/compression for a size/CPU trade-off.
+      return img.png({ compressionLevel: 9 }).toBuffer();
+    case 'webp':
+      return img.webp({ quality: q }).toBuffer();
+    case 'avif':
+      return img.avif({ quality: q }).toBuffer();
+  }
+}

package/src/server/media-bun/index.ts

@@ -0,0 +1,52 @@
+// src/server/media-bun — the Bun server adapter, re-exported from `cursedbelt-server`, for the media-core
+// specs: image rendering via sharp (lazy/optional), video trim + probe + thumbnail
+// via native ffmpeg/ffprobe. App handlers keep auth, FsNode lookup, quota, and
+// storeFile; this owns the actual pixel/codec work.
+
+export {
+  buildProbeArgs,
+  buildThumbnailArgs,
+  buildTrimArgs,
+  ffmpegTimeToSeconds,
+  type ProbeResult,
+  parseFfmpegProgress,
+  parseFfprobe,
+  type VideoCodecPlan,
+  videoCodecPlan,
+} from 'cursedbelt-core/media/ffmpeg';
+export { renderImage } from './image';
+// Streaming pipeline: faststart remux, HLS adaptive-bitrate ladder, scrub sprite + WebVTT,
+// poster, codec-aware probe — pure builders/parsers (testable without ffmpeg).
+export {
+  aacWebAudioArgs,
+  buildFrameJpegArgs,
+  buildSpriteVtt,
+  buildStreamProbeArgs,
+  canStreamCopy,
+  EMPTY_PROBE,
+  FASTSTART,
+  faststartArgs,
+  h264WebVideoArgs,
+  hlsLadderArgs,
+  imageThumbnailArgs,
+  LIBRARY_CRF,
+  LIBRARY_SCALE,
+  parseProgressMicros,
+  parseStreamProbe,
+  planSprite,
+  posterArgs,
+  resolveLadder,
+  type SpritePlan,
+  spriteArgs,
+  type VideoProbe,
+} from './streaming';
+export {
+  extractFrameJpeg,
+  extractThumbnail,
+  isFfmpegAvailable,
+  isFfprobeAvailable,
+  probeMedia,
+  probeVideoStream,
+  runFfmpegProgress,
+  trimVideo,
+} from './video';

package/src/server/media-bun/streaming.spec.ts

@@ -0,0 +1,134 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  buildSpriteVtt,
+  canStreamCopy,
+  faststartArgs,
+  hlsLadderArgs,
+  parseProgressMicros,
+  parseStreamProbe,
+  planSprite,
+  resolveLadder,
+  type VideoProbe,
+} from './streaming';
+
+const probe = (over: Partial<VideoProbe> = {}): VideoProbe => ({
+  duration: 100,
+  width: 1280,
+  height: 720,
+  vcodec: 'h264',
+  acodec: 'aac',
+  pixfmt: 'yuv420p',
+  hasAudio: true,
+  ...over,
+});
+
+describe('parseStreamProbe', () => {
+  test('pulls codecs/dims/duration/audio from ffprobe json', () => {
+    const r = parseStreamProbe({
+      format: { duration: '12.5' },
+      streams: [
+        { codec_type: 'video', codec_name: 'h264', width: 1920, height: 1080, pix_fmt: 'yuv420p' },
+        { codec_type: 'audio', codec_name: 'aac' },
+      ],
+    });
+    expect(r).toEqual({
+      duration: 12.5,
+      width: 1920,
+      height: 1080,
+      vcodec: 'h264',
+      acodec: 'aac',
+      pixfmt: 'yuv420p',
+      hasAudio: true,
+    });
+  });
+  test('handles a video-only file', () => {
+    const r = parseStreamProbe({ streams: [{ codec_type: 'video', codec_name: 'vp9' }] });
+    expect(r.hasAudio).toBe(false);
+    expect(r.acodec).toBe('');
+    expect(r.vcodec).toBe('vp9');
+  });
+});
+
+describe('canStreamCopy', () => {
+  test('true for web-safe h264/yuv420p/aac within width', () => {
+    expect(canStreamCopy(probe())).toBe(true);
+    expect(canStreamCopy(probe({ acodec: '' }))).toBe(true); // no audio is fine
+  });
+  test('false for non-h264, wrong pixfmt, non-aac audio, or too wide', () => {
+    expect(canStreamCopy(probe({ vcodec: 'hevc' }))).toBe(false);
+    expect(canStreamCopy(probe({ pixfmt: 'yuv444p' }))).toBe(false);
+    expect(canStreamCopy(probe({ acodec: 'mp3' }))).toBe(false);
+    expect(canStreamCopy(probe({ width: 3840 }))).toBe(false);
+  });
+});
+
+describe('faststartArgs', () => {
+  test('copy mode just remuxes with +faststart', () => {
+    const a = faststartArgs('in.mp4', 'out.mp4', { copy: true });
+    expect(a).toEqual(['-i', 'in.mp4', '-c', 'copy', '-movflags', '+faststart', 'out.mp4']);
+  });
+  test('re-encode mode scales + uses web-safe h264/aac + faststart', () => {
+    const a = faststartArgs('in.mov', 'out.mp4', { copy: false, crf: 20 });
+    expect(a).toContain('libx264');
+    expect(a).toContain('yuv420p');
+    expect(a.join(' ')).toContain('-crf 20');
+    expect(a.slice(-3)).toEqual(['-movflags', '+faststart', 'out.mp4']);
+  });
+});
+
+describe('parseProgressMicros', () => {
+  test('reads out_time_us and out_time_ms (ms is really µs in ffmpeg, ×1000)', () => {
+    expect(parseProgressMicros('out_time_us=5000000')).toBe(5_000_000);
+    expect(parseProgressMicros('out_time_ms=5000')).toBe(5_000_000);
+    expect(parseProgressMicros('frame=12')).toBeNull();
+  });
+});
+
+describe('resolveLadder', () => {
+  test('drops rungs taller than source, dedupes + sorts ascending', () => {
+    expect(resolveLadder([1080, 720, 360, 720], 720)).toEqual([360, 720]);
+  });
+  test('falls back to source-or-720 when nothing valid', () => {
+    expect(resolveLadder([], 1080)).toEqual([720]);
+    expect(resolveLadder([2160], 480)).toEqual([480]);
+  });
+});
+
+describe('hlsLadderArgs', () => {
+  test('emits a named multi-variant HLS transcode with audio maps', () => {
+    const a = hlsLadderArgs('src.mp4', '/out', { heights: [480, 720], crf: 23, hasAudio: true });
+    const s = a.join(' ');
+    expect(s).toContain('-filter_complex');
+    expect(s).toContain('split=2');
+    expect(s).toContain('-master_pl_name master.m3u8');
+    expect(s).toContain('-var_stream_map v:0,a:0,name:480 v:1,a:1,name:720');
+    expect(s).toContain('/out/%v/playlist.m3u8');
+  });
+  test('omits audio maps when the source has none', () => {
+    const a = hlsLadderArgs('src.mp4', '/out', { heights: [720], crf: 23, hasAudio: false });
+    expect(a.join(' ')).toContain('-var_stream_map v:0,name:720');
+    expect(a).not.toContain('a:0');
+  });
+});
+
+describe('planSprite + buildSpriteVtt', () => {
+  test('bounds the tile count and builds matching geometry', () => {
+    const plan = planSprite(60, 2, 1280, 720); // 30 tiles @ 2s
+    expect(plan.count).toBe(30);
+    expect(plan.cols * plan.rows).toBeGreaterThanOrEqual(plan.count);
+    expect(plan.thumbW).toBe(160);
+    expect(plan.thumbH % 2).toBe(0); // even (yuv420p)
+  });
+  test('widens the interval so a very long video still fits one sheet', () => {
+    const plan = planSprite(10000, 2, 1280, 720);
+    expect(plan.count).toBeLessThanOrEqual(144);
+    expect(plan.effInterval).toBeGreaterThan(2);
+  });
+  test('VTT has a header, one cue per tile, and xywh fragments', () => {
+    const plan = planSprite(20, 2, 1280, 720); // 10 tiles
+    const vtt = buildSpriteVtt(plan);
+    expect(vtt.startsWith('WEBVTT')).toBe(true);
+    expect((vtt.match(/-->/g) ?? []).length).toBe(plan.count);
+    expect(vtt).toContain('sprites.jpg#xywh=');
+  });
+});