cursedbelt-server 1.0.0

package/dist/server/storage/files/types.d.ts

@@ -0,0 +1,261 @@
+import type { PlayableVideo, ProcessingStatus } from 'cursedbelt-core/media';
+import type { PrivateIndex } from '../../private-media/index-store';
+import type { MediaCtx } from '../types';
+export type FileType = 'image' | 'video' | 'audio' | 'doc' | 'code' | 'other';
+/** User-defined groupings (Apple-Photos-style). `favorites` is a system singleton per owner;
+ * `custom` are free-form. */
+export type CollectionKind = 'custom' | 'favorites';
+/** `normal` — always visible; `unlock` — hidden unless caller passes `includeUnlockable: true`. */
+export type CollectionVisibility = 'normal' | 'unlock';
+export type FileCollection = {
+    id: string;
+    name: string;
+    kind: CollectionKind;
+    visibility: CollectionVisibility;
+    /** Live count of member files. */
+    fileCount: number;
+    createdAt: number;
+    updatedAt: number;
+};
+/** The clean, UI-facing record — explicit capability booleans, no storage keys leaked (ca's
+ * worst inconsistency was `thumbnailKey`-vs-`hasThumbnail` across two shapes). */
+export type FileRecord = {
+    id: string;
+    name: string;
+    mime: string;
+    size: number;
+    fileType: FileType;
+    tags: string[];
+    isPrivate: boolean;
+    hasThumbnail: boolean;
+    hasHls: boolean;
+    hasSprites: boolean;
+    durationSeconds?: number;
+    processingStatus: ProcessingStatus;
+    processingProgress: number;
+    /** True when this file is a member of the caller's Favorites collection. */
+    favorite: boolean;
+    /** All collection ids this file belongs to (within the owner's scope). */
+    collectionIds: string[];
+    createdAt: number;
+    updatedAt: number;
+    /** Set once `trash()` soft-deletes this file (epoch ms) — cleared by `restore()`. Undefined for
+     * a live (non-trashed) file. */
+    trashedAt?: number;
+};
+/** A tag with how many files carry it — the facet the flat browser renders as filter chips. */
+export type TagFacet = {
+    tag: string;
+    count: number;
+};
+/** A page of results with an opaque cursor for the next page (cursor-keyed, not OFFSET). */
+export type FilePage = {
+    items: FileRecord[];
+    nextCursor?: string;
+};
+/** Every listing order the catalogue understands — the single source of truth the route layer
+ * validates against and the `FileSort` union derives from. `recent` = newest first (default);
+ * `oldest` = oldest first; `name` = A→Z; `size` = largest first; `random` = a seeded shuffle
+ * (the seed is minted per session and folded into the cursor, so a visit reshuffles but its own
+ * pagination is stable); `lastViewed` = most-recently-opened first (never-viewed files last). */
+export declare const FILE_SORTS: readonly ["recent", "oldest", "name", "size", "random", "lastViewed"];
+/** Listing order. Every sort is cursor-paginated (the cursor encodes the sort key + id tie-break,
+ * plus the shuffle seed for `random`). A cursor is only valid under the sort that minted it. */
+export type FileSort = (typeof FILE_SORTS)[number];
+export type ListFilesOptions = {
+    /** Smart-view filter (indexed). */
+    type?: FileType;
+    /** Single-tag filter (indexed via the join table). */
+    tag?: string;
+    /** Name substring (public files only — private names are sealed). */
+    query?: string;
+    /** Include the caller's private files (requires an unlocked set — the caller resolves which
+     * ones actually open). Omitted ⇒ public only, matching ca's default listing. */
+    includePrivate?: boolean;
+    /** Filter to members of a specific collection. An unlock-gated collection yields empty unless
+     * `includeUnlockable` is also true. */
+    collectionId?: string;
+    /** Filter to files that are favorited (i.e. members of the owner's Favorites collection). */
+    favorite?: boolean;
+    /** Expose unlock-gated collections/results. Default false — the route layer gates this. */
+    includeUnlockable?: boolean;
+    /** Listing order (default 'recent'). A cursor is only valid for the sort it was minted under. */
+    sort?: FileSort;
+    cursor?: string;
+    limit?: number;
+    /** Browse the trash bin instead of the live library: true ⇒ ONLY trashed rows, omitted/false ⇒
+     * ONLY live rows (the default — trashed files never appear in a normal listing). */
+    trashedOnly?: boolean;
+};
+/** Server-authoritative smart-view classification, computed ONCE at write time and stored.
+ * `isText` (a non-binary inline file) ⇒ code; else by mime. */
+export declare function classifyFileType(mime: string, isText?: boolean): FileType;
+/** The catalogue contract. A SQLite implementation is the production default; the interface lets
+ * an app swap it. All calls are owner-scoped via {@link MediaCtx} (one tenant never sees another). */
+/** Cheap owner-scoped aggregates (COUNT/SUM over the files table) — the admin
+ * surface's "site stats" source. Private items report count + bytes only
+ * (names/kinds stay sealed). */
+export type CatalogueStats = {
+    files: number;
+    bytes: number;
+    byType: Partial<Record<FileType, number>>;
+    privateItems: number;
+    privateBytes: number;
+    processing: number;
+    failed: number;
+};
+export interface FileCatalogue {
+    list(ctx: MediaCtx, opts?: ListFilesOptions): Promise<FilePage>;
+    get(ctx: MediaCtx, id: string): Promise<FileRecord | null>;
+    /** Owner-scoped aggregates for admin/stats surfaces. */
+    stats(ctx: MediaCtx): Promise<CatalogueStats>;
+    tagFacets(ctx: MediaCtx, opts?: {
+        includePrivate?: boolean;
+    }): Promise<TagFacet[]>;
+    /** Ingest a public upload: persist bytes, classify, kick off processing (thumbnail/HLS). */
+    ingest(ctx: MediaCtx, upload: {
+        name: string;
+        mime: string;
+        body: ReadableStream<Uint8Array>;
+        size?: number;
+        tags?: string[];
+    }): Promise<FileRecord>;
+    /** Register bytes uploaded OUT OF BAND (a chunked upload sent direct to the backend) — insert the
+     * row + kick processing WITHOUT re-storing bytes (they already sit at the catalogue's key for this
+     * id: fsSourceKey for video, fileBinaryKey otherwise). */
+    registerUploaded(ctx: MediaCtx, upload: {
+        id: string;
+        name: string;
+        mime: string;
+        size: number;
+        tags?: string[];
+    }): Promise<FileRecord>;
+    /** Rename / retag a file. */
+    update(ctx: MediaCtx, id: string, patch: {
+        name?: string;
+        tags?: string[];
+    }): Promise<FileRecord | null>;
+    /** Overwrite a file's BYTES in place — the identity (id, tags, collections, favorites, view
+     * history) survives while mime/size/fileType re-derive, stale derivatives are wiped, and
+     * processing re-kicks (video transcode / image thumbnail). Public files only — replacing an
+     * encrypted private item throws (delete + re-upload instead). Returns the refreshed record,
+     * or null if the id is unknown/other-owner. */
+    replaceContent(ctx: MediaCtx, id: string, upload: {
+        mime: string;
+        body: ReadableStream<Uint8Array>;
+        size?: number;
+        name?: string;
+    }): Promise<FileRecord | null>;
+    /** PERMANENTLY delete a file + all its derivatives + tags + collection memberships. This is the
+     * hard-delete — a deliberate second action, typically only called on an already-trashed row
+     * (see {@link trash}). No-ops (never throws) for an unknown or other-owner id. */
+    remove(ctx: MediaCtx, id: string): Promise<void>;
+    /** Soft-delete: marks the file trashed (hidden from normal `list()`) without touching its bytes
+     * or metadata — recoverable via {@link restore}. The PRIMARY delete action a user takes.
+     * No-ops for an unknown/other-owner id or one already trashed. */
+    trash(ctx: MediaCtx, id: string): Promise<void>;
+    /** Undo `trash()`: clears trashed_at so the file reappears in normal listings. No-ops for an
+     * unknown/other-owner id. */
+    restore(ctx: MediaCtx, id: string): Promise<void>;
+    /** Ingest file(s) from a LOCAL path already on this host's disk (a directory imports every
+     * regular file inside it, recursively; a file imports just itself). Each imported file is
+     * tagged with its immediate containing folder name (the catalogue is flat — folder structure
+     * survives as a tag, not a tree) plus any `tags` passed. Unreadable/unsupported entries are
+     * skipped, not thrown — the return value reports both. */
+    importFromPath(ctx: MediaCtx, absPath: string, opts?: {
+        tags?: string[];
+    }): Promise<{
+        imported: FileRecord[];
+        skipped: {
+            path: string;
+            reason: string;
+        }[];
+    }>;
+    /** Recover from a restart that lost in-flight transcodes: re-kick public video rows still marked
+     * pending/processing (their source persists), and mark stuck private rows failed. Call once at
+     * app startup. Returns how many were re-queued vs. failed. */
+    recoverProcessing(): {
+        requeued: number;
+        failed: number;
+    };
+    /** Backfill grid thumbnails for finished public video rows that have no poster (landed while
+     * transcoding was off, or failed before the poster step). Re-kicks the poster pipeline for each.
+     * Returns how many were re-queued. */
+    backfillVideoPosters(): {
+        requeued: number;
+    };
+    /** Backfill grid thumbnails for public image rows with no poster (e.g. HEIC photos whose sharp
+     * thumbnail failed before the ffmpeg fallback). Re-kicks the image pipeline. */
+    backfillImageThumbnails(): {
+        requeued: number;
+    };
+    /** List the owner's collections. Unlock-gated ones are excluded unless `includeUnlockable`. */
+    listCollections(ctx: MediaCtx, opts?: {
+        includeUnlockable?: boolean;
+    }): Promise<FileCollection[]>;
+    /** Create a custom collection. Name is trimmed; empty names throw. Duplicate names are allowed. */
+    createCollection(ctx: MediaCtx, input: {
+        name: string;
+        visibility?: CollectionVisibility;
+    }): Promise<FileCollection>;
+    /** Rename or change visibility of an owned collection. Returns null if not found. */
+    updateCollection(ctx: MediaCtx, id: string, patch: {
+        name?: string;
+        visibility?: CollectionVisibility;
+    }): Promise<FileCollection | null>;
+    /** Delete a custom collection (and its memberships). Never deletes files. Favorites cannot be
+     * removed — throws an Error. */
+    removeCollection(ctx: MediaCtx, id: string): Promise<void>;
+    /** Add files to a collection. Idempotent (INSERT OR IGNORE). Unknown or other-owner file ids are
+     * silently skipped. */
+    addToCollection(ctx: MediaCtx, collectionId: string, fileIds: string[]): Promise<void>;
+    /** Remove files from a collection. Silently ignores ids not in the collection. */
+    removeFromCollection(ctx: MediaCtx, collectionId: string, fileIds: string[]): Promise<void>;
+    /** Toggle the favorite state of a file. Lazily creates the owner's Favorites collection on first
+     * use. */
+    setFavorite(ctx: MediaCtx, fileId: string, favorite: boolean): Promise<void>;
+    /** Record a view/watch-open of a file (upserts its last-viewed timestamp + bumps a count) — the
+     * signal the `lastViewed` sort orders by. No-ops for an unknown or other-owner file id. */
+    recordView(ctx: MediaCtx, fileId: string): Promise<void>;
+}
+/** Resolve a video FileRecord to a PlayableVideo (URLs baked server-side). Non-video ⇒ null. */
+export type FileToPlayable = (ctx: MediaCtx, file: FileRecord) => Promise<PlayableVideo | null>;
+/** How a private item's content key is wrapped: `standard` (server-recoverable) vs `deniable`
+ * (password-derived; zero-knowledge). Mirrors private-media `KeyMode`. */
+export type PrivateKeyMode = 'standard' | 'deniable';
+/** The OPAQUE locked-index row — only non-sensitive metadata (so a user can prune media whose
+ * password is lost). NEVER name/tags/thumbnail: those are sealed. No set identifier is exposed. */
+export type PrivateFileItem = {
+    id: string;
+    size: number;
+    createdAt: number;
+    processingStatus: ProcessingStatus;
+    processingProgress: number;
+    hasHls: boolean;
+};
+/** Private-media capability of a catalogue. `createSqliteFileCatalogue` implements this alongside
+ * {@link FileCatalogue}, storing private items as sealed rows in the SAME table (one source of
+ * truth). Membership is by decrypt-success — no stored password/set hash.
+ *
+ * Deliberately small: the catalogue owns only INGEST (the new private-upload path). Everything
+ * else — the locked index, unlock, try-a-password reveal, the gated content-key route, and the
+ * encrypted-HLS byte serving — is the existing `mountPrivateRoutes`, which operates through a
+ * {@link PrivateIndex}. `asPrivateIndex()` is the view that lets those routes read/write the
+ * catalogue's private rows, so there is exactly one store and one set of routes. */
+export interface PrivateFileCatalogue {
+    /** Ingest an encrypted video: stage plaintext (never persisted), transcode to AES-128 HLS, seal
+     * the descriptor + wrap the content key under `setKey`, and insert a private row. */
+    ingestPrivate(ctx: MediaCtx, upload: {
+        name: string;
+        mime: string;
+        body: ReadableStream<Uint8Array>;
+        size?: number;
+        tags?: string[];
+    }, opts: {
+        setKey: Buffer;
+        keyMode: PrivateKeyMode;
+    }): Promise<PrivateFileItem>;
+    /** A {@link PrivateIndex} view over this catalogue's private rows — pass to `mountPrivateRoutes`
+     * so unlock/index/reveal/key/HLS all operate on the catalogue. `remove` also drops the bytes. */
+    asPrivateIndex(): PrivateIndex;
+}

package/dist/server/storage/files/types.js

@@ -0,0 +1,22 @@
+/** Every listing order the catalogue understands — the single source of truth the route layer
+ * validates against and the `FileSort` union derives from. `recent` = newest first (default);
+ * `oldest` = oldest first; `name` = A→Z; `size` = largest first; `random` = a seeded shuffle
+ * (the seed is minted per session and folded into the cursor, so a visit reshuffles but its own
+ * pagination is stable); `lastViewed` = most-recently-opened first (never-viewed files last). */
+export const FILE_SORTS = ['recent', 'oldest', 'name', 'size', 'random', 'lastViewed'];
+const DOC_MIME = /pdf|word|excel|spreadsheet|presentation|csv|officedocument|rtf|epub|^text\//;
+/** Server-authoritative smart-view classification, computed ONCE at write time and stored.
+ * `isText` (a non-binary inline file) ⇒ code; else by mime. */
+export function classifyFileType(mime, isText = false) {
+    if (mime.startsWith('image/'))
+        return 'image';
+    if (mime.startsWith('video/'))
+        return 'video';
+    if (mime.startsWith('audio/'))
+        return 'audio';
+    if (isText)
+        return 'code';
+    if (DOC_MIME.test(mime))
+        return 'doc';
+    return 'other';
+}

package/dist/server/storage/imageThumbnail.d.ts

@@ -0,0 +1,3 @@
+/** True when a browser can render this image mime inline (no JPEG derivative needed). */
+export declare function isBrowserRenderableImage(mime: string): boolean;
+export declare function ffmpegImageThumbnail(bytes: Uint8Array, workDir: string, id: string, maxWidth?: number): Promise<Uint8Array | null>;

package/dist/server/storage/imageThumbnail.js

@@ -0,0 +1,50 @@
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { imageThumbnailArgs, runFfmpegProgress } from '../media-bun';
+// Image mimes browsers CANNOT render inline (so the full-view <img> needs a JPEG derivative, not
+// the original). Chrome/Firefox reject HEIC/HEIF; the rest (jpeg/png/webp/gif/avif/bmp/svg) render
+// natively. Safari can show HEIC, but we normalize for everyone.
+const BROWSER_INCOMPATIBLE_IMAGE_MIMES = new Set([
+    'image/heic',
+    'image/heif',
+    'image/heic-sequence',
+    'image/heif-sequence',
+]);
+/** True when a browser can render this image mime inline (no JPEG derivative needed). */
+export function isBrowserRenderableImage(mime) {
+    return mime.startsWith('image/') && !BROWSER_INCOMPATIBLE_IMAGE_MIMES.has(mime.toLowerCase());
+}
+// Produce a width-capped JPEG thumbnail from arbitrary image bytes using ffmpeg — the fallback for
+// formats sharp's prebuilt binary can't decode (notably HEIC/HEVC iPhone photos: the licensed-out
+// libheif build only accepts AVIF). Best-effort: returns null on any failure. Uses a temp file
+// because ffmpeg's HEIF demuxer needs seekable input (a pipe won't do).
+export async function ffmpegImageThumbnail(bytes, workDir, id, maxWidth = 512) {
+    const dir = path.join(workDir, '_imgthumb', id);
+    try {
+        await mkdir(dir, { recursive: true });
+        const inPath = path.join(dir, 'in.bin');
+        await Bun.write(inPath, bytes);
+        const outPath = path.join(dir, 'out.jpg');
+        let stderrTail = '';
+        const ok = await runFfmpegProgress(imageThumbnailArgs(inPath, outPath, maxWidth), 0, undefined, (tail) => {
+            stderrTail = tail;
+        });
+        if (!ok) {
+            // The "undecodable bytes" fixture test deliberately hits this path too — tagged
+            // `[expected-in-tests]` (grep-filterable) rather than silenced, so a real decode
+            // regression still surfaces.
+            console.warn(`[imageThumbnail][expected-in-tests] ffmpeg decode failed: ${stderrTail.slice(-400)}`);
+            return null;
+        }
+        const out = Bun.file(outPath);
+        if (!(await out.exists()))
+            return null;
+        return new Uint8Array(await out.arrayBuffer());
+    }
+    catch {
+        return null;
+    }
+    finally {
+        await rm(dir, { recursive: true, force: true }).catch(() => { });
+    }
+}

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

@@ -0,0 +1,15 @@
+export { DERIVATIVE_SUFFIXES, hlsMasterKeyFor, hlsPrefixFor, isDerivativeKey, posterKeyFor, spriteKeyFor, spriteVttKeyFor, webPlayableKeyFor, } from './videoDerivativeKeys';
+export type { BinaryServerConfig, FileTokenClaims, FileTokenSigner } from './binaryServerStore';
+export { createBinaryServerStore } from './binaryServerStore';
+export { type BinaryServerProcessingConfig, createBinaryServerProcessing, } from './binaryServerProcessing';
+export { createTranscodeJobClient, type TranscodeJobClient, type TranscodeJobClientConfig, type TranscodeJobResult, type TranscodeJobStatus, type TranscodeJobStatusBody, } from './transcodeJobs';
+export { createDiskStore } from './diskStore';
+export { type CatalogueStats, type ChunkedInit, type ChunkedUploadService, catalogueUploadKey, classifyFileType, createCatalogueMediaSource, createCataloguePhotoSource, createCatalogueVideoSource, createChunkedUploadService, createFilesStack, createFileToPlayable, createFileUrls, createLedgeredDeletes, createSqliteFileCatalogue, createStorageOpsLedger, createStorageReconciler, FILE_CATALOGUE_MIGRATIONS, type FileCatalogue, type FilePage, type FileRecord, type FilesStack, type FilesStackMountAuth, type FilesStackOptions, type FileToPlayable, type FileType, type FileUrls, fileBinaryKey, type ImageDerivatives, type ImageDerivativesOptions, type ListFilesOptions, type MintChunkUpload, type MountFileRoutesOptions, mountFileRoutes, type PrivateFileCatalogue, type PrivateFileItem, type PrivateKeyMode, type SqliteFileCatalogueOptions, type StorageAction, type StorageOpRow, type StorageOpsLedger, type StorageReconciler, type VideoProcessor, } from './files';
+export { type CorsResolver, type MountMediaOptions, mountMediaRoutes } from './mountMediaRoutes';
+export { createDiskSource, createMediaUrls, type DiskSource, type MediaUrls, SourceRegistry, } from './sources';
+export { createS3ObjectStore, type S3ClientLike, type S3ObjectHandle, type S3ObjectStoreOptions, type S3ObjectWriter, } from './s3ObjectStore';
+export { decodeRange, type RangeDecision, type ServeRangeOpts, serveRange } from './streamRange';
+export { createStreamTokenService, type StreamGrant, type StreamTokenService } from './streamToken';
+export { fsHlsFileKey, fsHlsMasterKey, fsHlsPrefix, fsMp4Key, fsPosterKey, fsSourceKey, fsSpriteKey, fsVttKey, type MediaCtx, type MediaGallerySource, type MediaSource, type MediaStore, type PhotoSource, privateFsKey, } from './types';
+export { type ProcessOptions, type ProcessResult, processVideo, } from './videoProcessor';
+export { objectStoreAsMediaStore } from './objectStoreMediaStore';

package/dist/server/storage/index.js

@@ -0,0 +1,27 @@
+// cursedbelt-server/storage — byte-storage layer for the media pipeline: MediaStore adapters
+// (disk / binary-server), a Range→Response helper, path-embedded stream tokens, a source
+// registry, and the ingest→derivatives orchestrator. Builds on `server/media` (codec work) +
+// `server/auth` (jose tokens). The `PlayableVideo` contract lives in `cursedbelt-core/media`.
+// The derivative NAME contract — the seam between binary-server (which writes these names),
+// satellite-kit (which re-exports them for the satellite apps) and this package's own token
+// minting. Pure string transforms: nothing here can resolve a stored object.
+export { DERIVATIVE_SUFFIXES, hlsMasterKeyFor, hlsPrefixFor, isDerivativeKey, posterKeyFor, spriteKeyFor, spriteVttKeyFor, webPlayableKeyFor, } from './videoDerivativeKeys';
+export { createBinaryServerStore } from './binaryServerStore';
+export { createBinaryServerProcessing, } from './binaryServerProcessing';
+// The transcode API as a plain job client, for apps whose binaries do NOT live in the file
+// catalogue (apps/notes keys attachments by sha256). One derivative pipeline, two doors.
+export { createTranscodeJobClient, } from './transcodeJobs';
+export { createDiskStore } from './diskStore';
+// The FileCatalogue: a SQLite-backed tagged flat file system over this storage layer — one
+// source of truth for a user's binaries (the video gallery is a video-filtered view over it).
+export { catalogueUploadKey, classifyFileType, createCatalogueMediaSource, createCataloguePhotoSource, createCatalogueVideoSource, createChunkedUploadService, createFilesStack, createFileToPlayable, createFileUrls, createLedgeredDeletes, createSqliteFileCatalogue, createStorageOpsLedger, createStorageReconciler, FILE_CATALOGUE_MIGRATIONS, fileBinaryKey, mountFileRoutes, } from './files';
+export { mountMediaRoutes } from './mountMediaRoutes';
+export { createDiskSource, createMediaUrls, SourceRegistry, } from './sources';
+// The saas profile's `ObjectStore` (08 §1b). Its local counterpart is
+// `createFsObjectStore` in `cwip/storage` — same interface, different issuer.
+export { createS3ObjectStore, } from './s3ObjectStore';
+export { decodeRange, serveRange } from './streamRange';
+export { createStreamTokenService } from './streamToken';
+export { fsHlsFileKey, fsHlsMasterKey, fsHlsPrefix, fsMp4Key, fsPosterKey, fsSourceKey, fsSpriteKey, fsVttKey, privateFsKey, } from './types';
+export { processVideo, } from './videoProcessor';
+export { objectStoreAsMediaStore } from './objectStoreMediaStore';

package/dist/server/storage/mountMediaRoutes.d.ts

@@ -0,0 +1,28 @@
+import type { Context, Hono } from 'hono';
+import type { SourceRegistry } from './sources';
+import type { StreamGrant, StreamTokenService } from './streamToken';
+import { type MediaCtx, type MediaStore } from './types';
+/** Resolves the Access-Control-Allow-Origin for a request origin: a fixed origin, an allowlist
+ * (echoes the request origin when allowed), or a custom resolver (return null to deny). */
+export type CorsResolver = string | string[] | ((requestOrigin: string | undefined) => string | null | undefined);
+export type MountMediaOptions = {
+    /** Byte backend shared by this mount (keys carry the owner). */
+    store: MediaStore;
+    /** Verifies the path token → owner/source/video grant. */
+    token: StreamTokenService;
+    /** On-server route mount path (path-only; must share its trailing path with the createMediaUrls
+     * baseUrl). Default '/_media'. */
+    basePath?: string;
+    /** Sources, for upload ingest. */
+    registry?: SourceRegistry;
+    /** Cross-origin access for split-origin deploys (media on a different origin than the SPA).
+     * Omit for same-origin. */
+    cors?: CorsResolver;
+    /** Authorizes an upload request (it CAN send the Bearer, unlike a media element). Return a
+     * MediaCtx to allow, or null to reject. Omit ⇒ uploads are disabled on this mount. */
+    authorizeUpload?: (c: Context) => Promise<MediaCtx | null> | MediaCtx | null;
+    /** Optional hook to decrypt bytes for the private (pfs/…) keyspace before serving. Wired by
+     * the private-media layer; omitted ⇒ all bytes served as stored. */
+    decryptStream?: (stream: ReadableStream<Uint8Array>, grant: StreamGrant) => ReadableStream<Uint8Array>;
+};
+export declare function mountMediaRoutes(app: Hono, opts: MountMediaOptions): void;

package/dist/server/storage/mountMediaRoutes.js

@@ -0,0 +1,141 @@
+import { serveRange } from './streamRange';
+import { fsDisplayKey, fsHlsFileKey, fsMp4Key, fsPosterKey, fsSourceKey, fsSpriteKey, fsVttKey, } from './types';
+const EXPOSE_HEADERS = 'Content-Range, Content-Length, Accept-Ranges';
+function resolveAcao(cors, reqOrigin) {
+    if (!cors)
+        return null;
+    if (typeof cors === 'string')
+        return cors;
+    if (Array.isArray(cors))
+        return reqOrigin && cors.includes(reqOrigin) ? reqOrigin : null;
+    return cors(reqOrigin) ?? null;
+}
+export function mountMediaRoutes(app, opts) {
+    const base = opts.basePath ?? '/_media';
+    const { store, token } = opts;
+    // Stamp CORS headers on a media response (and expose the range headers a cross-origin seeking
+    // <video> needs). A no-op when `cors` is unset (same-origin).
+    const cors = (c, res) => {
+        const acao = resolveAcao(opts.cors, c.req.header('origin'));
+        if (acao) {
+            res.headers.set('Access-Control-Allow-Origin', acao);
+            res.headers.set('Access-Control-Expose-Headers', EXPOSE_HEADERS);
+            res.headers.append('Vary', 'Origin');
+        }
+        return res;
+    };
+    // Preflight for cross-origin media/upload requests.
+    if (opts.cors) {
+        app.options(`${base}/*`, (c) => {
+            const acao = resolveAcao(opts.cors, c.req.header('origin'));
+            const headers = {
+                'Access-Control-Allow-Methods': 'GET, PUT, OPTIONS',
+                'Access-Control-Allow-Headers': 'Range, Content-Type, X-Filename, Authorization',
+                'Access-Control-Max-Age': '86400',
+            };
+            if (acao) {
+                headers['Access-Control-Allow-Origin'] = acao;
+                headers.Vary = 'Origin';
+            }
+            return c.body(null, 204, headers);
+        });
+    }
+    // Resolve + validate the token a serve route carries, and confirm it matches the source/video
+    // in the path (so a token minted for video A can't fetch video B).
+    const grantFor = async (c, expectSource, expectVideo) => {
+        const raw = c.req.param('token');
+        if (!raw)
+            return null;
+        const grant = await token.verify(raw);
+        if (!grant)
+            return null;
+        if (grant.sourceId !== expectSource || grant.videoId !== expectVideo)
+            return null;
+        return grant;
+    };
+    // GET progressive MP4 (Range). Prefers the faststart derivative; falls back to the raw source
+    // when the pipeline hasn't produced one (ffmpeg absent / still processing).
+    app.get(`${base}/s/:token/media/:source/:video`, async (c) => {
+        const grant = await grantFor(c, c.req.param('source'), c.req.param('video'));
+        if (!grant)
+            return c.body(null, 401);
+        const mp4 = fsMp4Key(grant.owner, grant.videoId);
+        const key = (await store.stat(mp4)) ? mp4 : fsSourceKey(grant.owner, grant.videoId);
+        if (store.redirectUrl) {
+            const url = await store.redirectUrl(key, { mime: 'video/mp4' });
+            if (url)
+                return cors(c, c.redirect(url, 303));
+        }
+        return cors(c, await serveRange(store, key, 'video/mp4', c.req.header('range'), {
+            contentDisposition: 'inline',
+        }));
+    });
+    // GET an HLS file (master.m3u8 / <height>/playlist.m3u8 / <height>/seg_*.ts). Relative URIs
+    // inside the playlists resolve under this same /s/:token/hls/:source/:video/ prefix.
+    app.get(`${base}/s/:token/hls/:source/:video/*`, async (c) => {
+        const grant = await grantFor(c, c.req.param('source'), c.req.param('video'));
+        if (!grant)
+            return c.body(null, 401);
+        const prefix = `${base}/s/${c.req.param('token')}/hls/${grant.sourceId}/${grant.videoId}/`;
+        const rel = c.req.path.slice(prefix.length);
+        if (!rel || rel.includes('..'))
+            return c.body(null, 400);
+        const mime = rel.endsWith('.m3u8') ? 'application/vnd.apple.mpegurl' : 'video/mp2t';
+        return cors(c, await serveRange(store, fsHlsFileKey(grant.owner, grant.videoId, rel), mime, c.req.header('range')));
+    });
+    app.get(`${base}/s/:token/poster/:source/:video`, async (c) => {
+        const grant = await grantFor(c, c.req.param('source'), c.req.param('video'));
+        if (!grant)
+            return c.body(null, 401);
+        return cors(c, await serveRange(store, fsPosterKey(grant.owner, grant.videoId), 'image/jpeg', c.req.header('range')));
+    });
+    // Full-size browser-safe JPEG for images the browser can't render natively (HEIC/HEIF). Serves
+    // the display derivative; falls back to the small poster if it isn't built yet (the boot backfill
+    // produces it, so the fallback is momentary) — never a raw HEIC the browser would fail on.
+    app.get(`${base}/s/:token/display/:source/:video`, async (c) => {
+        const grant = await grantFor(c, c.req.param('source'), c.req.param('video'));
+        if (!grant)
+            return c.body(null, 401);
+        const displayKey = fsDisplayKey(grant.owner, grant.videoId);
+        const key = (await store.stat(displayKey))
+            ? displayKey
+            : fsPosterKey(grant.owner, grant.videoId);
+        return cors(c, await serveRange(store, key, 'image/jpeg', c.req.header('range')));
+    });
+    // Sprite sheet + its WebVTT track, served as siblings so the VTT's relative 'sprites.jpg' cue
+    // targets resolve to the jpg route.
+    app.get(`${base}/s/:token/sprite/:source/:video/:file`, async (c) => {
+        const grant = await grantFor(c, c.req.param('source'), c.req.param('video'));
+        if (!grant)
+            return c.body(null, 401);
+        const file = c.req.param('file');
+        if (file === 'sprites.vtt') {
+            return cors(c, await serveRange(store, fsVttKey(grant.owner, grant.videoId), 'text/vtt', c.req.header('range')));
+        }
+        if (file === 'sprites.jpg') {
+            return cors(c, await serveRange(store, fsSpriteKey(grant.owner, grant.videoId), 'image/jpeg', c.req.header('range')));
+        }
+        return c.body(null, 404);
+    });
+    // PUT upload → ingest. Guarded by the app-supplied authorizer (a fetch CAN send the Bearer).
+    const { authorizeUpload, registry } = opts;
+    if (authorizeUpload && registry) {
+        app.put(`${base}/upload/:source`, async (c) => {
+            const ctx = await authorizeUpload(c);
+            if (!ctx)
+                return c.json({ error: 'unauthorized' }, 401);
+            const source = registry.get(c.req.param('source'));
+            if (!source?.ingest)
+                return c.json({ error: 'source not found' }, 404);
+            const body = c.req.raw.body;
+            if (!body)
+                return c.json({ error: 'empty body' }, 400);
+            const video = await source.ingest(ctx, {
+                name: c.req.header('x-filename') ?? 'upload',
+                mime: c.req.header('content-type') ?? 'application/octet-stream',
+                body,
+            });
+            return c.json({ video });
+        });
+    }
+}

package/dist/server/storage/objectStoreMediaStore.d.ts

@@ -0,0 +1,4 @@
+import type { ObjectStore } from 'cwip/storage';
+import type { MediaStore } from './types';
+/** Adapt an {@link ObjectStore} to the {@link MediaStore} contract `processVideo` expects. */
+export declare function objectStoreAsMediaStore(objects: ObjectStore): MediaStore;

package/dist/server/storage/objectStoreMediaStore.js

@@ -0,0 +1,57 @@
+// Bridge the framework's stream-based `ObjectStore` (cwip/storage) to the
+// byte/stream `MediaStore` the proven `processVideo` pipeline drives (§2d).
+//
+// `processVideo` predates the engine `ObjectStore`: it speaks `MediaStore`
+// (put(bytes)/putStream/get(bytes)/stat/localPath). The engine wires an
+// `ObjectStore` (put(stream)/get(stream)/stat/delete/signedUrl). Rather than
+// fork the whole transcode orchestrator onto a second store type, the asset
+// `transcode` handler wraps its `ObjectStore` in this adapter and reuses the
+// pipeline unchanged. There is deliberately NO `localPath`, so `processVideo`
+// materialises the source by download — correct for a stream store where the
+// bytes may live off-box (S3/R2).
+const streamToBytes = async (stream) => new Uint8Array(await new Response(stream).arrayBuffer());
+const bytesToStream = (bytes) => new ReadableStream({
+    start(controller) {
+        controller.enqueue(bytes);
+        controller.close();
+    },
+});
+/** Adapt an {@link ObjectStore} to the {@link MediaStore} contract `processVideo` expects. */
+export function objectStoreAsMediaStore(objects) {
+    return {
+        async put(key, bytes, mime) {
+            await objects.put(key, bytesToStream(bytes), { contentType: mime });
+        },
+        async putStream(key, body, mime) {
+            await objects.put(key, body, { contentType: mime });
+        },
+        async get(key) {
+            const stream = await objects.get(key);
+            return stream ? await streamToBytes(stream) : null;
+        },
+        async remove(key) {
+            await objects.delete(key);
+        },
+        async removePrefix() {
+            // The `ObjectStore` contract has no prefix delete, and `processVideo` never
+            // calls this — surface misuse loudly rather than silently no-op.
+            throw new Error('objectStoreAsMediaStore.removePrefix is not supported over an ObjectStore.');
+        },
+        async stat(key) {
+            const stat = await objects.stat(key);
+            return stat ? { size: stat.size } : null;
+        },
+        async getRange(key, range) {
+            const stream = await objects.get(key);
+            if (!stream)
+                return null;
+            if (!range)
+                return { stream };
+            // Whole-object read then slice: unused by `processVideo`, present only to
+            // satisfy the interface. A hot Range-serving path uses the real store.
+            const bytes = await streamToBytes(stream);
+            return { stream: bytesToStream(bytes.subarray(range.start, range.end + 1)) };
+        },
+        // No `localPath`: force `processVideo` down its download path (stream store).
+    };
+}