cursedbelt 2.7.0 → 3.0.0

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

@@ -1,112 +0,0 @@
-/**
- * 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 "../../core/master-lock/policy";
-import {
-	type MasterLockKdfParams,
-	deriveMasterLockVerifier,
-	newMasterLockKdfParams,
-} from "../../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

@@ -1,35 +0,0 @@
-/**
- * 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

@@ -1,115 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import type { ImagePipelineSpec } from '../../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

@@ -1,134 +0,0 @@
-// 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 '../../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

@@ -1,52 +0,0 @@
-// 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 '../../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

@@ -1,134 +0,0 @@
-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=');
-  });
-});