cursedbelt-server 1.0.0

package/dist/server/notifications/index.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `cursedbelt-server/notifications` — the SERVER half of the fleet's one
+ * notification primitive.
+ *
+ * ── What was already here, and what was missing ─────────────────────────────
+ * The dispatch engine has lived in `cwip/notifications` for months (a
+ * persistent per-user row, `groupKey` coalescing, unread counts, deep links, a
+ * live-delivery sink) and the whole client has lived in
+ * `cursedbelt/react/notifications` (store, bell, feed, inbox, poll transport).
+ * What did NOT exist was a way to MOUNT any of it: the only mounted surface in
+ * the fleet was `orch-ui/services/notifications`, written against
+ * `@satellites/satellite-rpc` inside a package only the orchestrator consumes.
+ * So a satellite wanting a bell had two options, and both were wrong — adopt
+ * orch's rpc layer, or write the routes again.
+ *
+ * This module is the third: ordinary Hono routes, an SSE hub behind the sink
+ * the center already had, and a migration for apps using cursedbelt's runner.
+ *
+ *   const notifications = createNotificationService({ db });
+ *   notifications.mount(app, { authorize: (c) => userOf(c)?.id ?? null });
+ *
+ * and on the client:
+ *
+ *   const { store } = createNotificationsBinding();   // cursedbelt/react/notifications
+ *   <NotificationBell store={store} />
+ *
+ * ── The three properties worth knowing ──────────────────────────────────────
+ * 1. **A notification is a row before it is an event.** Delivery is a cache of
+ *    who is listening; the poll transport is the backstop and is not optional.
+ *    Nothing is lost by a closed laptop.
+ * 2. **Coalescing is a database constraint, not a debounce.** The partial
+ *    unique index on `(user_id, group_key) WHERE group_key IS NOT NULL AND
+ *    done = 0` is what makes "twenty of the same thing" one row with a count,
+ *    even under concurrent producers.
+ * 3. **The routes address the session's user and nothing else.** There is no
+ *    route that notifies somebody else; producing is server-side code calling
+ *    `center.notify*`.
+ */
+export { createNotificationHub } from "./hub";
+export type { NotificationHub, NotificationHubEvent, NotificationHubListener, NotificationHubOptions, } from "./hub";
+export { NOTIFICATION_MIGRATIONS, NOTIFICATIONS_TABLE } from "./migrations";
+export { mountNotificationRoutes } from "./routes";
+export type { NotificationRouteCenter, NotificationRoutesOptions } from "./routes";
+export { createNotificationService } from "./service";
+export type { CreateNotificationServiceOptions, NotificationService, NotificationServiceMountOptions, } from "./service";
+export { createNotificationCenter, createMemoryNotificationStore, createSqliteNotificationStore, migrateNotificationsSchema, } from "cwip/notifications";
+export type { AppNotification, ListNotificationsQuery, NotificationAudience, NotificationCenter, NotificationCenterOptions, NotificationDraft, NotificationFilter, NotificationPage, NotificationSeverity, NotificationSink, NotificationStore, Notifier, } from "cwip/notifications";

package/dist/server/notifications/index.js

@@ -0,0 +1,46 @@
+/**
+ * `cursedbelt-server/notifications` — the SERVER half of the fleet's one
+ * notification primitive.
+ *
+ * ── What was already here, and what was missing ─────────────────────────────
+ * The dispatch engine has lived in `cwip/notifications` for months (a
+ * persistent per-user row, `groupKey` coalescing, unread counts, deep links, a
+ * live-delivery sink) and the whole client has lived in
+ * `cursedbelt/react/notifications` (store, bell, feed, inbox, poll transport).
+ * What did NOT exist was a way to MOUNT any of it: the only mounted surface in
+ * the fleet was `orch-ui/services/notifications`, written against
+ * `@satellites/satellite-rpc` inside a package only the orchestrator consumes.
+ * So a satellite wanting a bell had two options, and both were wrong — adopt
+ * orch's rpc layer, or write the routes again.
+ *
+ * This module is the third: ordinary Hono routes, an SSE hub behind the sink
+ * the center already had, and a migration for apps using cursedbelt's runner.
+ *
+ *   const notifications = createNotificationService({ db });
+ *   notifications.mount(app, { authorize: (c) => userOf(c)?.id ?? null });
+ *
+ * and on the client:
+ *
+ *   const { store } = createNotificationsBinding();   // cursedbelt/react/notifications
+ *   <NotificationBell store={store} />
+ *
+ * ── The three properties worth knowing ──────────────────────────────────────
+ * 1. **A notification is a row before it is an event.** Delivery is a cache of
+ *    who is listening; the poll transport is the backstop and is not optional.
+ *    Nothing is lost by a closed laptop.
+ * 2. **Coalescing is a database constraint, not a debounce.** The partial
+ *    unique index on `(user_id, group_key) WHERE group_key IS NOT NULL AND
+ *    done = 0` is what makes "twenty of the same thing" one row with a count,
+ *    even under concurrent producers.
+ * 3. **The routes address the session's user and nothing else.** There is no
+ *    route that notifies somebody else; producing is server-side code calling
+ *    `center.notify*`.
+ */
+export { createNotificationHub } from "./hub";
+export { NOTIFICATION_MIGRATIONS, NOTIFICATIONS_TABLE } from "./migrations";
+export { mountNotificationRoutes } from "./routes";
+export { createNotificationService } from "./service";
+// Re-exported so a server consumer needs ONE import for the whole contract —
+// the same courtesy `server/sharing` extends over `cursedbelt-core/sharing`. The
+// engine remains cwip's; this is a door, not a copy.
+export { createNotificationCenter, createMemoryNotificationStore, createSqliteNotificationStore, migrateNotificationsSchema, } from "cwip/notifications";

package/dist/server/notifications/migrations.d.ts

@@ -0,0 +1,13 @@
+import type { Migration } from "../migration/types";
+export declare const NOTIFICATIONS_TABLE = "notifications";
+/**
+ * Ordered migrations for the notification table.
+ *
+ *   applyRecommendedPragmas(db);
+ *   runMigrations(db, [...APP_MIGRATIONS, ...NOTIFICATION_MIGRATIONS]);
+ *
+ * An app that instead constructs `createSqliteNotificationStore(db)` gets the
+ * same table without this — the store migrates on construction. Running both is
+ * harmless and is the normal state of an app that adopted the store first.
+ */
+export declare const NOTIFICATION_MIGRATIONS: readonly Migration[];

package/dist/server/notifications/migrations.js

@@ -0,0 +1,20 @@
+import { migrateNotificationsSchema } from "cwip/notifications";
+export const NOTIFICATIONS_TABLE = "notifications";
+/**
+ * Ordered migrations for the notification table.
+ *
+ *   applyRecommendedPragmas(db);
+ *   runMigrations(db, [...APP_MIGRATIONS, ...NOTIFICATION_MIGRATIONS]);
+ *
+ * An app that instead constructs `createSqliteNotificationStore(db)` gets the
+ * same table without this — the store migrates on construction. Running both is
+ * harmless and is the normal state of an app that adopted the store first.
+ */
+export const NOTIFICATION_MIGRATIONS = [
+    {
+        name: "0001_notifications",
+        up(db) {
+            migrateNotificationsSchema(db, NOTIFICATIONS_TABLE);
+        },
+    },
+];

package/dist/server/notifications/routes.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The plain-HTTP surface for the notification center.
+ *
+ * ── Why this exists (2026-08-11) ────────────────────────────────────────────
+ * The engine (`cwip/notifications`), the store and the whole client
+ * (`cursedbelt/react/notifications`) were already fleet-wide. The only mounted
+ * SERVER surface was `orch-ui/services/notifications`, written against
+ * `@satellites/satellite-rpc` and living inside a package only the orchestrator
+ * consumes — so every other satellite's route to a notification was "adopt
+ * orch's rpc layer" or "write it again". This is that surface as ordinary
+ * routes on an ordinary Hono app, one mount call, no rpc.
+ *
+ * The route table mirrors the rpc one 1:1 on purpose: the two are the same
+ * contract in two dialects, and a client written against either sees the same
+ * fields. `mutations` are POST/DELETE and `queries` are GET, so the GET-only
+ * enforcement middleware some satellites run stays meaningful.
+ *
+ *   GET    {base}                → { items, hasMore }   ?filter=&limit=&offset=
+ *   GET    {base}/unread-count   → { count }
+ *   GET    {base}/stream         → SSE (live delivery; needs a hub)
+ *   GET    {base}/:id            → { notification }
+ *   POST   {base}/read-all       → { changed }
+ *   POST   {base}/done-all       → { changed }
+ *   POST   {base}/:id/read       → { changed }   body { read?: boolean }
+ *   POST   {base}/:id/done       → { changed }   body { done?: boolean }
+ *   DELETE {base}/:id            → { changed }
+ *
+ * 🔴 **Every handler addresses `authorize(c)`'s user and never a body field.**
+ * The center is user-scoped at the store level, but a route that took a
+ * `userId` parameter would make that scoping decorative — so there is no such
+ * parameter anywhere below, and there is deliberately no route that notifies
+ * somebody else. Producing notifications is server-side business logic calling
+ * `center.notify*` directly; a browser can only ever read and acknowledge its
+ * OWN inbox.
+ */
+import type { Context, Hono } from "hono";
+import type { NotificationCenter } from "cwip/notifications";
+import type { NotificationHub } from "./hub";
+/** The slice of the center these routes use — `createNotificationCenter(...)`
+ *  satisfies it, and so does any app-specific facade over one. */
+export type NotificationRouteCenter = Pick<NotificationCenter, "list" | "get" | "unreadCount" | "markRead" | "markAllRead" | "setDone" | "doneAll" | "remove">;
+export interface NotificationRoutesOptions {
+    center: NotificationRouteCenter;
+    /**
+     * Resolve the caller to a user id, or null to refuse with 401. This is the
+     * app's session model and the ONLY thing that decides whose inbox is served.
+     */
+    authorize: (c: Context) => string | null | Promise<string | null>;
+    /** Live delivery. Omit it and `{base}/stream` is not mounted at all — a
+     *  route that answers 200 with a stream that never emits is worse than a
+     *  404 the client can fall back from. */
+    hub?: NotificationHub;
+    /** Path prefix. Default `/api/notifications`. */
+    basePath?: string;
+    /** Largest page a caller may ask for. Default 200. */
+    maxLimit?: number;
+}
+export declare function mountNotificationRoutes(app: Hono, options: NotificationRoutesOptions): void;

package/dist/server/notifications/routes.js

@@ -0,0 +1,113 @@
+const NO_STORE = { "cache-control": "no-store" };
+const FILTERS = ["unread", "all", "done"];
+const parseFilter = (raw) => FILTERS.find((f) => f === raw);
+/** Query integers are untrusted text: a NaN or a negative offset must become
+ *  the default, never reach SQL, and never be an error the caller has to handle. */
+const parseInt_ = (raw, min, max) => {
+    if (raw === undefined || raw === "")
+        return undefined;
+    const value = Number.parseInt(raw, 10);
+    if (!Number.isFinite(value))
+        return undefined;
+    return Math.min(max, Math.max(min, value));
+};
+/** A body that is absent, malformed, or oversized is `{}` — every field these
+ *  routes read is optional with a documented default, so there is nothing a
+ *  caller could usefully be told about a bad one. */
+const readFlag = async (c, key) => {
+    try {
+        const raw = await c.req.text();
+        if (!raw || raw.length > 1024)
+            return true;
+        const body = JSON.parse(raw);
+        const value = body?.[key];
+        return typeof value === "boolean" ? value : true;
+    }
+    catch {
+        return true;
+    }
+};
+export function mountNotificationRoutes(app, options) {
+    const base = options.basePath ?? "/api/notifications";
+    const maxLimit = options.maxLimit ?? 200;
+    const { center, hub } = options;
+    /** Every handler starts here. Returns the user id, or the 401 to return. */
+    const whoOr401 = async (c) => {
+        const userId = await options.authorize(c);
+        if (!userId)
+            return c.json({ error: "unauthorized" }, 401, NO_STORE);
+        return userId;
+    };
+    app.get(base, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        const page = await center.list({
+            userId: who,
+            filter: parseFilter(c.req.query("filter")),
+            limit: parseInt_(c.req.query("limit"), 1, maxLimit),
+            offset: parseInt_(c.req.query("offset"), 0, Number.MAX_SAFE_INTEGER),
+        });
+        return c.json(page, 200, NO_STORE);
+    });
+    app.get(`${base}/unread-count`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        return c.json({ count: await center.unreadCount(who) }, 200, NO_STORE);
+    });
+    // Mounted only when there is something to stream — see the option's doc.
+    if (hub) {
+        app.get(`${base}/stream`, async (c) => {
+            const who = await whoOr401(c);
+            if (typeof who !== "string")
+                return who;
+            // The request's own abort signal is what ends the stream when the tab
+            // closes; without it the subscription outlives the socket.
+            return hub.stream(who, { signal: c.req.raw.signal });
+        });
+    }
+    app.post(`${base}/read-all`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        return c.json({ changed: await center.markAllRead(who) }, 200, NO_STORE);
+    });
+    app.post(`${base}/done-all`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        return c.json({ changed: await center.doneAll(who) }, 200, NO_STORE);
+    });
+    app.post(`${base}/:id/read`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        const read = await readFlag(c, "read");
+        return c.json({ changed: await center.markRead(who, c.req.param("id"), read) }, 200, NO_STORE);
+    });
+    app.post(`${base}/:id/done`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        const done = await readFlag(c, "done");
+        return c.json({ changed: await center.setDone(who, c.req.param("id"), done) }, 200, NO_STORE);
+    });
+    app.delete(`${base}/:id`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        return c.json({ changed: await center.remove(who, c.req.param("id")) }, 200, NO_STORE);
+    });
+    // LAST: `/:id` would otherwise swallow `/unread-count` and `/stream`, and
+    // the failure is a 404-shaped `{ notification: null }` rather than an error.
+    app.get(`${base}/:id`, async (c) => {
+        const who = await whoOr401(c);
+        if (typeof who !== "string")
+            return who;
+        const notification = await center.get(who, c.req.param("id"));
+        if (!notification)
+            return c.json({ error: "not found" }, 404, NO_STORE);
+        return c.json({ notification }, 200, NO_STORE);
+    });
+}

package/dist/server/notifications/service.d.ts

@@ -0,0 +1,58 @@
+/**
+ * One call that gives an app the whole server half: a migrated table, the
+ * dispatch center, live delivery, and the routes.
+ *
+ *   const notifications = createNotificationService({ db });
+ *   notifications.mount(app, { authorize: (c) => userOf(c)?.id ?? null });
+ *   // …anywhere in the app's business logic:
+ *   await notifications.center.notify(userId, { type: "auth.login", title: "New sign-in" });
+ *
+ * Everything it composes is separately usable — an app that already has a
+ * center, or that wants the routes on a store of its own, calls
+ * `mountNotificationRoutes` directly. This exists so the common case is one
+ * import and no wiring to get wrong.
+ */
+import type { Database } from "bun:sqlite";
+import { type NotificationCenter, type NotificationStore } from "cwip/notifications";
+import type { Context, Hono } from "hono";
+import { type NotificationHub } from "./hub";
+export interface CreateNotificationServiceOptions {
+    /** The app's own database — the table lands beside its rows. */
+    db: Database;
+    /** Table name override (identifier-validated by the store). */
+    table?: string;
+    /** Resolve a role audience (`notifyAudience({ role })`) to user ids. */
+    resolveRole?: (role: string) => Promise<string[]>;
+    /**
+     * Live delivery. `false` builds no hub — the client's poll transport is the
+     * whole delivery story then, which is a perfectly good one for an app whose
+     * notifications are not time-critical.
+     */
+    live?: boolean | {
+        heartbeatMs?: number;
+        maxStreamsPerUser?: number;
+    };
+    /** Producer-path failures and sink failures land here. Defaults to stderr. */
+    onError?: (error: unknown, context: string) => void;
+    /** Test seams, forwarded to the center. */
+    now?: () => number;
+    newId?: () => string;
+}
+export interface NotificationServiceMountOptions {
+    /** Resolve the caller to a user id, or null to refuse. */
+    authorize: (c: Context) => string | null | Promise<string | null>;
+    /** Path prefix. Default `/api/notifications`. */
+    basePath?: string;
+    /** Largest page a caller may ask for. Default 200. */
+    maxLimit?: number;
+}
+export interface NotificationService {
+    readonly center: NotificationCenter;
+    readonly store: NotificationStore;
+    /** Null when `live: false` — there is then nothing to stream. */
+    readonly hub: NotificationHub | null;
+    mount(app: Hono, options: NotificationServiceMountOptions): void;
+    /** Drop live subscribers (shutdown, tests). Safe to call with no hub. */
+    close(): void;
+}
+export declare function createNotificationService(options: CreateNotificationServiceOptions): NotificationService;

package/dist/server/notifications/service.js

@@ -0,0 +1,41 @@
+import { createNotificationCenter, createSqliteNotificationStore, } from "cwip/notifications";
+import { createNotificationHub } from "./hub";
+import { mountNotificationRoutes } from "./routes";
+export function createNotificationService(options) {
+    const onError = options.onError ??
+        ((error, context) => console.error(`[notifications] ${context}:`, error instanceof Error ? error.message : error));
+    const store = createSqliteNotificationStore(options.db, {
+        table: options.table,
+    });
+    const hub = options.live === false
+        ? null
+        : createNotificationHub({
+            ...(typeof options.live === "object" ? options.live : {}),
+            onError,
+        });
+    const center = createNotificationCenter({
+        store,
+        sink: hub?.sink,
+        resolveRole: options.resolveRole,
+        now: options.now,
+        newId: options.newId,
+        onError,
+    });
+    return {
+        center,
+        store,
+        hub,
+        mount(app, mountOptions) {
+            mountNotificationRoutes(app, {
+                center,
+                hub: hub ?? undefined,
+                authorize: mountOptions.authorize,
+                basePath: mountOptions.basePath,
+                maxLimit: mountOptions.maxLimit,
+            });
+        },
+        close() {
+            hub?.close();
+        },
+    };
+}

package/dist/server/paths/appDataHome.d.ts

@@ -0,0 +1,19 @@
+/** The one env var. A machine with a shared data root sets this and nothing else. */
+export declare const APP_DATA_HOME_ENV = "APP_DATA_HOME";
+/** The cross-desktop convention this honors ahead of the platform default. */
+export declare const XDG_DATA_HOME_ENV = "XDG_DATA_HOME";
+export interface ResolveAppDataHomeOptions {
+    /** An explicit answer from the caller. Wins outright — this is the "argument" half. */
+    readonly override?: string;
+    /** Environment to read. Injected by tests; defaults to the process's own. */
+    readonly env?: Record<string, string | undefined>;
+    /**
+     * Platform to resolve for. Injected by tests so both branches are proved on one
+     * machine; defaults to the running platform.
+     */
+    readonly platform?: string;
+}
+/**
+ * The machine's app-data home. See the module note for the ordering rationale.
+ */
+export declare function resolveAppDataHome(options?: ResolveAppDataHomeOptions): string;

package/dist/server/paths/appDataHome.js

@@ -0,0 +1,68 @@
+/**
+ * Where a machine keeps an app's data — as CONFIGURATION, never as a convention
+ * baked into the library.
+ *
+ * ## What this replaces, and why it is a defect rather than untidiness
+ *
+ * Until 2026-09-13 three live modules in this package joined the ambient home
+ * directory to a hardcoded dotfolder belonging to the previous generation: the
+ * retention store, the archive, and `resolveAppDataRoot`. This package is
+ * PUBLISHED. Anybody who installed it got a library that went looking for a
+ * directory in their home that has nothing to do with them, and — worse — wrote
+ * into it if it happened to exist.
+ *
+ * A library may not know the name of a directory in somebody's home. It may know
+ * two things: what the caller told it, and what the operating system says the
+ * convention is. That is the whole ladder below.
+ *
+ * ## The ladder
+ *
+ *   1. an explicit `override` — a `--data-root` flag, a host's own resolution;
+ *   2. `$APP_DATA_HOME` — the ONE env var, for a machine that keeps every app's
+ *      data under one root so a fleet-wide tool can see all of it at once;
+ *   3. `$XDG_DATA_HOME` — the user already told the OS where data goes;
+ *   4. the platform default: `~/Library/Application Support` on macOS,
+ *      `~/.local/share` everywhere else.
+ *
+ * `$XDG_DATA_HOME` is honored on macOS too. It is not the platform's own
+ * convention there, but a user who sets it has stated a preference, and a
+ * preference outranks a default on any platform.
+ *
+ * Nothing here touches the filesystem: it is a pure mapping from environment to
+ * path, so a caller can reason about the answer before creating anything, and a
+ * test can assert both platforms on one machine.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** The one env var. A machine with a shared data root sets this and nothing else. */
+export const APP_DATA_HOME_ENV = "APP_DATA_HOME";
+/** The cross-desktop convention this honors ahead of the platform default. */
+export const XDG_DATA_HOME_ENV = "XDG_DATA_HOME";
+/** Trimmed, or undefined — an env var set to whitespace is not a configuration. */
+function configured(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/**
+ * The machine's app-data home. See the module note for the ordering rationale.
+ */
+export function resolveAppDataHome(options = {}) {
+    const env = options.env ?? process.env;
+    const override = configured(options.override);
+    if (override)
+        return override;
+    const appDataHome = configured(env[APP_DATA_HOME_ENV]);
+    if (appDataHome)
+        return appDataHome;
+    const xdg = configured(env[XDG_DATA_HOME_ENV]);
+    if (xdg)
+        return xdg;
+    // `env.HOME` rather than `homedir()` alone, so a caller passing an env object
+    // gets a resolution it can actually control — every test below depends on it,
+    // and so does any host that boots an app under a different account.
+    const home = configured(env.HOME) ?? homedir();
+    const platform = options.platform ?? process.platform;
+    return platform === "darwin"
+        ? join(home, "Library", "Application Support")
+        : join(home, ".local", "share");
+}

package/dist/server/private-media/crypto.d.ts

@@ -0,0 +1,37 @@
+export type KeyMode = 'standard' | 'deniable';
+/** A random per-user salt (non-secret, stored plaintext, stable once created). Domain-separates
+ * a user's password-derived keys so the same password yields different keys across users. */
+export declare const generateUserSalt: () => string;
+/** Zero-knowledge set key: scrypt(password, per-user salt). The server never stores this (or a
+ * hash of it); it exists only transiently after an unlock. Different passwords → disjoint sets. */
+export declare const derivePasswordSetKey: (password: string, userSalt: string) => Buffer;
+/** Recoverable set key: scrypt(serverSecret, userId). The server can always derive it, so
+ * `standard`-mode media is decryptable once private is unlocked (session-gated) — protects a
+ * stolen disk / Finder / backups, but a compromised running server can decrypt. */
+export declare const deriveServerSetKey: (serverSecret: string, userId: string) => Buffer;
+export declare const sealMeta: (setKey: Buffer, meta: unknown) => string;
+/** Open a sealed envelope, or null if this key doesn't own it (wrong password / mode key).
+ * The null return IS the membership signal — no stored set identifier is needed. */
+export declare function openMeta<T = unknown>(setKey: Buffer, sealed: string): T | null;
+export type ContentKey = {
+    key: Buffer;
+    iv: Buffer;
+};
+export declare const generateContentKey: () => ContentKey;
+export declare const wrapContentKey: (setKey: Buffer, content: ContentKey) => string;
+/** Unwrap a content key, or null if the set key can't open it (wrong password / mode key). */
+export declare function unwrapContentKey(setKey: Buffer, wrapped: string): ContentKey | null;
+/** Pipe a byte stream through the item's AES-128-CTR keystream. Symmetric: pass ciphertext to
+ * decrypt, plaintext to encrypt. */
+/** Big-endian increment of a 16-byte CTR IV by `blocks` — the counter arithmetic that lets a
+ * decryptor start mid-stream (genapp-100: Range/seek on private blobs). */
+export declare function incrementIv(iv: Buffer, blocks: number): Buffer;
+/**
+ * Decrypt a CTR ciphertext stream that starts at the BLOCK-ALIGNED offset covering plaintext
+ * byte `startOffset`, dropping the intra-block lead-in — the seek half of {@link cryptBlobStream}.
+ * CTR is length-preserving and positionally keyed, so byte N of plaintext only needs ciphertext
+ * from block ⌊N/16⌋ onward with the IV counter advanced by that many blocks (genapp-100: this is
+ * what makes big private videos scrub on a remote-store host with no local derivatives).
+ */
+export declare function cryptBlobRangeStream(content: ContentKey, stream: ReadableStream<Uint8Array>, startOffset: number): ReadableStream<Uint8Array>;
+export declare function cryptBlobStream(content: ContentKey, stream: ReadableStream<Uint8Array>): ReadableStream<Uint8Array>;

package/dist/server/private-media/crypto.js

@@ -0,0 +1,111 @@
+import { createCipheriv, randomBytes } from 'node:crypto';
+import { decryptSecret, deriveKey, encryptSecret } from 'cwip/node';
+/** A random per-user salt (non-secret, stored plaintext, stable once created). Domain-separates
+ * a user's password-derived keys so the same password yields different keys across users. */
+export const generateUserSalt = () => randomBytes(16).toString('base64url');
+/** Zero-knowledge set key: scrypt(password, per-user salt). The server never stores this (or a
+ * hash of it); it exists only transiently after an unlock. Different passwords → disjoint sets. */
+export const derivePasswordSetKey = (password, userSalt) => deriveKey(password, `pmedia:${userSalt}`);
+/** Recoverable set key: scrypt(serverSecret, userId). The server can always derive it, so
+ * `standard`-mode media is decryptable once private is unlocked (session-gated) — protects a
+ * stolen disk / Finder / backups, but a compromised running server can decrypt. */
+export const deriveServerSetKey = (serverSecret, userId) => deriveKey(serverSecret, `pmedia-srv:${userId}`);
+// ── Sealed metadata envelope (title / thumbnail key / notes / tags) ──────────────
+// Encrypted under the set key; NEVER stored in the plaintext index. A successful decrypt is
+// also the deniable MEMBERSHIP TEST — trying a password reveals only the items it opens.
+export const sealMeta = (setKey, meta) => encryptSecret(JSON.stringify(meta), setKey);
+/** Open a sealed envelope, or null if this key doesn't own it (wrong password / mode key).
+ * The null return IS the membership signal — no stored set identifier is needed. */
+export function openMeta(setKey, sealed) {
+    try {
+        return JSON.parse(decryptSecret(sealed, setKey));
+    }
+    catch {
+        return null;
+    }
+}
+export const generateContentKey = () => ({
+    key: randomBytes(16), // AES-128
+    iv: randomBytes(16),
+});
+export const wrapContentKey = (setKey, content) => encryptSecret(`${content.key.toString('base64')}.${content.iv.toString('base64')}`, setKey);
+/** Unwrap a content key, or null if the set key can't open it (wrong password / mode key). */
+export function unwrapContentKey(setKey, wrapped) {
+    try {
+        const [k, iv] = decryptSecret(wrapped, setKey).split('.');
+        if (!k || !iv)
+            return null;
+        return { key: Buffer.from(k, 'base64'), iv: Buffer.from(iv, 'base64') };
+    }
+    catch {
+        return null;
+    }
+}
+// ── Whole-file blob cipher (non-video private files: photos, docs) ────────────────
+// AES-128-CTR under the item's content key — the same key/IV material the HLS path wraps, so
+// wrap/unwrap is shared. CTR is length-preserving and streaming (no padding, no buffering), and
+// encrypt/decrypt are the same operation. Tamper-evidence comes from the GCM-sealed descriptor +
+// the gated serve route (parity with the encrypted-HLS segments, which are CBC-without-MAC too).
+/** Pipe a byte stream through the item's AES-128-CTR keystream. Symmetric: pass ciphertext to
+ * decrypt, plaintext to encrypt. */
+/** Big-endian increment of a 16-byte CTR IV by `blocks` — the counter arithmetic that lets a
+ * decryptor start mid-stream (genapp-100: Range/seek on private blobs). */
+export function incrementIv(iv, blocks) {
+    const out = Buffer.from(iv);
+    let carry = BigInt(blocks);
+    for (let i = out.length - 1; i >= 0 && carry > 0n; i--) {
+        const sum = BigInt(out[i]) + (carry & 0xffn);
+        out[i] = Number(sum & 0xffn);
+        carry = (carry >> 8n) + (sum >> 8n);
+    }
+    return out;
+}
+/**
+ * Decrypt a CTR ciphertext stream that starts at the BLOCK-ALIGNED offset covering plaintext
+ * byte `startOffset`, dropping the intra-block lead-in — the seek half of {@link cryptBlobStream}.
+ * CTR is length-preserving and positionally keyed, so byte N of plaintext only needs ciphertext
+ * from block ⌊N/16⌋ onward with the IV counter advanced by that many blocks (genapp-100: this is
+ * what makes big private videos scrub on a remote-store host with no local derivatives).
+ */
+export function cryptBlobRangeStream(content, stream, startOffset) {
+    const BLOCK = 16;
+    const blocks = Math.floor(startOffset / BLOCK);
+    let drop = startOffset % BLOCK;
+    const cipher = createCipheriv('aes-128-ctr', content.key, incrementIv(content.iv, blocks));
+    return stream.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            let out = cipher.update(chunk);
+            if (drop > 0) {
+                const skip = Math.min(drop, out.byteLength);
+                out = out.subarray(skip);
+                drop -= skip;
+            }
+            if (out.byteLength > 0) {
+                controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+            }
+        },
+        flush(controller) {
+            const out = cipher.final(); // empty for CTR — kept for cipher-contract completeness
+            if (out.byteLength > 0) {
+                controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+            }
+        },
+    }));
+}
+export function cryptBlobStream(content, stream) {
+    const cipher = createCipheriv('aes-128-ctr', content.key, content.iv);
+    return stream.pipeThrough(new TransformStream({
+        transform(chunk, controller) {
+            const out = cipher.update(chunk);
+            if (out.byteLength > 0) {
+                controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+            }
+        },
+        flush(controller) {
+            const out = cipher.final(); // empty for CTR — kept for cipher-contract completeness
+            if (out.byteLength > 0) {
+                controller.enqueue(new Uint8Array(out.buffer, out.byteOffset, out.byteLength));
+            }
+        },
+    }));
+}