cursedbelt-server 1.0.0

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

@@ -0,0 +1,63 @@
+import type { ObjectStore } from 'cwip/storage';
+/**
+ * The slice of `Bun.S3File` this store uses.
+ *
+ * Declared structurally rather than imported as `Bun.S3File` so the contract
+ * suite can drive BOTH implementations against an in-process fake bucket. A
+ * store whose only proof is "it compiles against the real SDK types" is a store
+ * whose behavior has never been tested.
+ */
+export interface S3ObjectHandle {
+    stream(): ReadableStream<Uint8Array>;
+    writer(options?: {
+        partSize?: number;
+        queueSize?: number;
+        retry?: number;
+    }): S3ObjectWriter;
+    exists(): Promise<boolean>;
+    stat(): Promise<{
+        size: number;
+        type?: string;
+        lastModified?: Date;
+        etag?: string;
+    }>;
+    delete(): Promise<void>;
+    presign(options?: {
+        expiresIn?: number;
+        method?: 'GET';
+    }): string;
+}
+export interface S3ObjectWriter {
+    write(chunk: Uint8Array): number | Promise<number>;
+    /** Passing an error aborts the multipart upload instead of completing it. */
+    end(error?: Error): number | Promise<number>;
+}
+export interface S3ClientLike {
+    file(key: string, options?: {
+        type?: string;
+    }): S3ObjectHandle;
+}
+export interface S3ObjectStoreOptions {
+    /** Pre-built client. Supply this OR the credential fields below. */
+    client?: S3ClientLike;
+    bucket?: string;
+    /** e.g. `https://<account>.r2.cloudflarestorage.com`. */
+    endpoint?: string;
+    region?: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    sessionToken?: string;
+    /**
+     * Namespace every key under this prefix, so ONE bucket can host many apps
+     * without collisions. Tenant scoping stays in the key shape (`<tenant>/<file>`)
+     * — the prefix is deployment topology, not a security boundary.
+     */
+    keyPrefix?: string;
+    /** Multipart part size. Default 8MiB. */
+    partSize?: number;
+    /** Default presigned-URL lifetime in seconds. */
+    defaultExpiresInSeconds?: number;
+    /** Ceiling on a caller-requested lifetime. */
+    maxExpiresInSeconds?: number;
+}
+export declare function createS3ObjectStore(options: S3ObjectStoreOptions): ObjectStore;

package/dist/server/storage/s3ObjectStore.js

@@ -0,0 +1,187 @@
+/**
+ * `createS3ObjectStore` — the SAAS profile's binary tier (08 §1b, 01 §2.5).
+ *
+ * The companion to `createFsObjectStore` (cwip): same `ObjectStore` contract,
+ * different issuer. Everything above this line — `AssetService`, the asset
+ * mixin, the client — is written against the interface, so switching profiles
+ * swaps this factory in and changes nothing else. That is the whole reason the
+ * local store bothers to sign its URLs.
+ *
+ * Built on `Bun.S3Client`, which ships in the runtime cursedbelt already
+ * requires — no `aws-sdk`, no transitive credential-chain surprises. Works
+ * against S3, R2, MinIO or any other S3-compatible endpoint.
+ *
+ * Three things this does that a naive `PutObject` wrapper does not:
+ *
+ *   * **Streams through a multipart writer.** A 4GB upload is fed part-by-part
+ *     (default 8MiB) straight from the request stream. Nothing buffers the
+ *     object, so request memory is O(part), not O(file).
+ *   * **Aborts the multipart on failure.** `NetworkSink.end(error)` tells Bun to
+ *     abort rather than complete the upload; an abandoned multipart otherwise
+ *     accrues storage cost that never appears in a bucket listing — an invisible
+ *     bill, which is the worst kind.
+ *   * **Presigns for real.** `signedUrl` returns a genuine presigned GET so the
+ *     bytes leave via the CDN/edge, not through the app process. The asset
+ *     mixin's bytes routes stay as the fallback for private/derived content.
+ *
+ * Credentials are OPTIONS, never `process.env`: the host resolves them from
+ * GuardEngine secrets or its deploy environment (01 §3.3) and injects them, so
+ * this module has no ambient authority and a test can hand it a fake client.
+ */
+import { assertObjectKey } from 'cwip/storage';
+import { AppError } from '../errors';
+const DEFAULT_PART_SIZE = 8 * 1024 * 1024;
+const DEFAULT_EXPIRES_IN_SECONDS = 300;
+const MAX_EXPIRES_IN_SECONDS = 86_400;
+const buildClient = (options) => {
+    if (options.client)
+        return options.client;
+    if (!options.bucket)
+        throw new AppError('createS3ObjectStore needs either a `client` or a `bucket` (plus credentials).', {
+            code: 'OBJECT_STORE_MISCONFIGURED',
+            status: 500,
+            category: 'storage',
+            isOperational: false,
+        });
+    const S3Client = Bun.S3Client;
+    if (typeof S3Client !== 'function')
+        throw new AppError('This Bun runtime has no S3Client; pass a `client` implementing the S3 subset instead.', {
+            code: 'OBJECT_STORE_MISCONFIGURED',
+            status: 500,
+            category: 'storage',
+            isOperational: false,
+        });
+    return new S3Client({
+        bucket: options.bucket,
+        endpoint: options.endpoint,
+        region: options.region,
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+        sessionToken: options.sessionToken,
+    });
+};
+export function createS3ObjectStore(options) {
+    const client = buildClient(options);
+    const partSize = options.partSize ?? DEFAULT_PART_SIZE;
+    const defaultExpiry = options.defaultExpiresInSeconds ?? DEFAULT_EXPIRES_IN_SECONDS;
+    const maxExpiry = options.maxExpiresInSeconds ?? MAX_EXPIRES_IN_SECONDS;
+    const prefix = options.keyPrefix ? `${options.keyPrefix.replace(/^\/+|\/+$/g, '')}/` : '';
+    /**
+     * The SAME key whitelist the fs store enforces.
+     *
+     * S3 has no directories, so traversal is not the risk here — divergence is. A
+     * key that one profile accepts and the other refuses turns a profile switch
+     * into a data-loss migration, so both stores validate identically and the
+     * contract suite asserts it.
+     */
+    const physical = (key) => {
+        assertObjectKey(key);
+        return `${prefix}${key}`;
+    };
+    const statOf = async (key) => {
+        const handle = client.file(physical(key));
+        try {
+            const info = await handle.stat();
+            return {
+                key,
+                size: info.size,
+                contentType: info.type,
+                modifiedAt: (info.lastModified ?? new Date()).toISOString(),
+            };
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return null;
+            throw error;
+        }
+    };
+    return {
+        async put(key, body, putOptions) {
+            const contentType = putOptions?.contentType;
+            const handle = client.file(physical(key), contentType ? { type: contentType } : undefined);
+            const writer = handle.writer({ partSize });
+            const reader = body.getReader();
+            let size = 0;
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    if (value.byteLength === 0)
+                        continue;
+                    await writer.write(value);
+                    size += value.byteLength;
+                }
+                await writer.end();
+            }
+            catch (error) {
+                // Abort, don't complete. Best-effort: if the abort itself fails there is
+                // nothing further this process can do, and swallowing it would mask the
+                // ORIGINAL upload failure, which is the one worth reporting.
+                await Promise.resolve(writer.end(error instanceof Error ? error : new Error(String(error)))).catch(() => { });
+                throw error;
+            }
+            finally {
+                reader.releaseLock();
+            }
+            return { key, size, contentType, modifiedAt: new Date().toISOString() };
+        },
+        async get(key) {
+            const handle = client.file(physical(key));
+            if (!(await handle.exists()))
+                return null;
+            try {
+                return handle.stream();
+            }
+            catch (error) {
+                // Raced with a delete between `exists` and `stream` — a missing object
+                // is `null`, not a 500.
+                if (isNotFound(error))
+                    return null;
+                throw error;
+            }
+        },
+        stat: statOf,
+        async delete(key) {
+            const existed = (await statOf(key)) !== null;
+            try {
+                await client.file(physical(key)).delete();
+            }
+            catch (error) {
+                if (!isNotFound(error))
+                    throw error;
+            }
+            return existed;
+        },
+        async signedUrl(key, urlOptions) {
+            const requested = urlOptions?.expiresInSeconds ?? defaultExpiry;
+            if (!Number.isFinite(requested) || requested <= 0)
+                throw new AppError(`Signed-url lifetime for '${key}' must be a positive number of seconds.`, {
+                    code: 'OBJECT_KEY_INVALID',
+                    status: 400,
+                    category: 'storage',
+                    context: { key, requested },
+                });
+            return client
+                .file(physical(key))
+                .presign({ expiresIn: Math.min(Math.floor(requested), maxExpiry), method: 'GET' });
+        },
+    };
+}
+/**
+ * Is this the store telling us the object is not there?
+ *
+ * S3-compatible endpoints disagree on the shape (`NoSuchKey`, `NotFound`, a
+ * bare 404), and Bun surfaces its own `code`. Matching all of them keeps a
+ * missing object a `null` on every backend rather than a 500 on MinIO and a
+ * `null` on R2.
+ */
+const isNotFound = (error) => {
+    if (!error || typeof error !== 'object')
+        return false;
+    const candidate = error;
+    const code = String(candidate.code ?? candidate.name ?? '');
+    if (/NoSuchKey|NotFound|ENOENT|ERR_S3_FILE_NOT_FOUND/i.test(code))
+        return true;
+    return candidate.status === 404 || candidate.statusCode === 404;
+};

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

@@ -0,0 +1,47 @@
+import type { ProcessingStatus } from 'cursedbelt-core/media';
+import type { StreamTokenService } from './streamToken';
+import { type MediaCtx, type MediaSource, type MediaStore } from './types';
+export interface MediaUrls {
+    build(ctx: MediaCtx, sourceId: string, videoId: string): Promise<{
+        streamUrl: string;
+        hlsUrl: string;
+        posterUrl: string;
+        displayUrl: string;
+        vttUrl: string;
+        spriteUrl: string;
+    }>;
+}
+export declare function createMediaUrls(opts: {
+    /** Public base for browser media URLs. Path-only ('/_media') for same-origin, or an absolute
+     * origin+path ('https://api.example.com/_media') for a split-origin deploy. Must share its
+     * trailing path with `mountMediaRoutes`' `basePath`. */
+    baseUrl: string;
+    token: StreamTokenService;
+    /** Owner keyspace segment for a request. Defaults to tenantId (a tenant-shared gallery). */
+    owner?: (ctx: MediaCtx) => string;
+}): MediaUrls;
+export declare class SourceRegistry {
+    private sources;
+    register(source: MediaSource): this;
+    get(id: string): MediaSource | undefined;
+    list(): MediaSource[];
+}
+export type DiskSource = MediaSource & {
+    /** Read current processing status (for the gallery's status poll / tests). */
+    status(ctx: MediaCtx, videoId: string): {
+        status: ProcessingStatus;
+        progress: number;
+    } | null;
+};
+export declare function createDiskSource(cfg: {
+    id: string;
+    title: string;
+    store: MediaStore;
+    /** ffmpeg scratch dir. */
+    workDir: string;
+    urls: MediaUrls;
+    /** Owner keyspace segment; defaults to tenantId. */
+    owner?: (ctx: MediaCtx) => string;
+    /** Injectable clock (tests). */
+    now?: () => number;
+}): DiskSource;

package/dist/server/storage/sources.js

@@ -0,0 +1,148 @@
+import { fsMp4Key, fsPosterKey, fsSourceKey, fsSpriteKey, fsVttKey, } from './types';
+import { processVideo } from './videoProcessor';
+export function createMediaUrls(opts) {
+    const ownerOf = opts.owner ?? ((c) => c.tenantId);
+    // Trim a trailing slash so 'https://api…/_media/' and '/_media' behave identically.
+    const base = opts.baseUrl.replace(/\/$/, '');
+    return {
+        async build(ctx, sourceId, videoId) {
+            const token = await opts.token.sign({ owner: ownerOf(ctx), sourceId, videoId });
+            const p = `${base}/s/${token}`;
+            return {
+                streamUrl: `${p}/media/${sourceId}/${videoId}`,
+                hlsUrl: `${p}/hls/${sourceId}/${videoId}/master.m3u8`,
+                posterUrl: `${p}/poster/${sourceId}/${videoId}`,
+                displayUrl: `${p}/display/${sourceId}/${videoId}`,
+                vttUrl: `${p}/sprite/${sourceId}/${videoId}/sprites.vtt`,
+                spriteUrl: `${p}/sprite/${sourceId}/${videoId}/sprites.jpg`,
+            };
+        },
+    };
+}
+// ── Source registry ───────────────────────────────────────────────────────────────
+export class SourceRegistry {
+    sources = new Map();
+    register(source) {
+        this.sources.set(source.id, source);
+        return this;
+    }
+    get(id) {
+        return this.sources.get(id);
+    }
+    list() {
+        return [...this.sources.values()];
+    }
+}
+export function createDiskSource(cfg) {
+    const ownerOf = cfg.owner ?? ((c) => c.tenantId);
+    const now = cfg.now ?? (() => Date.now());
+    const byTenant = new Map();
+    const bucket = (ctx) => {
+        let m = byTenant.get(ctx.tenantId);
+        if (!m) {
+            m = new Map();
+            byTenant.set(ctx.tenantId, m);
+        }
+        return m;
+    };
+    const toPlayable = async (ctx, meta) => {
+        const u = await cfg.urls.build(ctx, cfg.id, meta.id);
+        return {
+            id: meta.id,
+            name: meta.name,
+            streamUrl: u.streamUrl,
+            hlsUrl: meta.hasHls ? u.hlsUrl : undefined,
+            posterUrl: meta.hasPoster ? u.posterUrl : undefined,
+            vttUrl: meta.hasSprite ? u.vttUrl : undefined,
+            spriteUrl: meta.hasSprite ? u.spriteUrl : undefined,
+            durationSeconds: meta.durationSeconds,
+            tags: meta.tags,
+            processingStatus: meta.status,
+            processingProgress: meta.progress,
+        };
+    };
+    return {
+        id: cfg.id,
+        title: cfg.title,
+        async list(ctx, opts) {
+            const all = [...bucket(ctx).values()].sort((a, b) => b.createdAt - a.createdAt);
+            const q = opts.query?.trim().toLowerCase();
+            const filtered = all.filter((m) => (!opts.tag || m.tags.includes(opts.tag)) &&
+                (!q || m.name.toLowerCase().includes(q) || m.tags.some((t) => t.includes(q))));
+            const limit = opts.limit ?? 24;
+            const start = opts.cursor ? Number(opts.cursor) || 0 : 0;
+            const page = filtered.slice(start, start + limit);
+            const items = await Promise.all(page.map((m) => toPlayable(ctx, m)));
+            const next = start + limit;
+            return { items, nextCursor: next < filtered.length ? String(next) : undefined };
+        },
+        async resolve(ctx, videoId) {
+            const meta = bucket(ctx).get(videoId);
+            return meta ? toPlayable(ctx, meta) : null;
+        },
+        async tags(ctx) {
+            const set = new Set();
+            for (const m of bucket(ctx).values()) {
+                for (const t of m.tags)
+                    set.add(t);
+            }
+            return [...set].sort();
+        },
+        async ingest(ctx, upload) {
+            const owner = ownerOf(ctx);
+            const id = crypto.randomUUID();
+            await cfg.store.putStream(fsSourceKey(owner, id), upload.body, upload.mime, {
+                contentLength: upload.size,
+            });
+            const meta = {
+                id,
+                name: upload.name,
+                tags: [],
+                mime: upload.mime,
+                status: 'processing',
+                progress: 0,
+                hasHls: false,
+                hasSprite: false,
+                hasPoster: false,
+                createdAt: now(),
+            };
+            bucket(ctx).set(id, meta);
+            // Fire-and-forget the pipeline; the client polls status via the source's status()/list().
+            void processVideo({
+                store: cfg.store,
+                workDir: cfg.workDir,
+                owner,
+                id,
+                sourceKey: fsSourceKey(owner, id),
+                onProgress: (status, pct) => {
+                    meta.status = status;
+                    meta.progress = pct;
+                },
+            }).then((res) => {
+                meta.status = res.status;
+                meta.progress = res.status === 'ready' ? 100 : meta.progress;
+                meta.durationSeconds = res.durationSeconds || meta.durationSeconds;
+                meta.hasHls = res.hasHls;
+                meta.hasSprite = res.hasSprite;
+                meta.hasPoster = res.hasPoster;
+            });
+            return toPlayable(ctx, meta);
+        },
+        async remove(ctx, videoId) {
+            const owner = ownerOf(ctx);
+            await Promise.all([
+                cfg.store.remove(fsSourceKey(owner, videoId)),
+                cfg.store.remove(fsMp4Key(owner, videoId)),
+                cfg.store.remove(fsPosterKey(owner, videoId)),
+                cfg.store.remove(fsSpriteKey(owner, videoId)),
+                cfg.store.remove(fsVttKey(owner, videoId)),
+                cfg.store.removePrefix(`hls/${owner}/${videoId}`),
+            ]);
+            bucket(ctx).delete(videoId);
+        },
+        status(ctx, videoId) {
+            const meta = bucket(ctx).get(videoId);
+            return meta ? { status: meta.status, progress: meta.progress } : null;
+        },
+    };
+}

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

@@ -0,0 +1,19 @@
+import type { MediaStore } from './types';
+export type RangeDecision = {
+    kind: 'full';
+} | {
+    kind: 'partial';
+    start: number;
+    end: number;
+} | {
+    kind: 'unsatisfiable';
+};
+export declare function decodeRange(header: string | undefined | null, total: number): RangeDecision;
+export type ServeRangeOpts = {
+    /** Content-Disposition value, e.g. 'inline' or `attachment; filename="clip.mp4"`. */
+    contentDisposition?: string;
+    /** Overrides the default 'private, max-age=86400' (e.g. 'no-store' for private bytes). */
+    cacheControl?: string;
+    extraHeaders?: Record<string, string>;
+};
+export declare function serveRange(store: MediaStore, key: string, mime: string, rangeHeader: string | undefined | null, opts?: ServeRangeOpts): Promise<Response>;

package/dist/server/storage/streamRange.js

@@ -0,0 +1,69 @@
+// Parse a single-range `Range: bytes=start-end` header against a known total size. Only the
+// common single-range forms are supported (`a-b`, `a-`, `-n`); anything malformed falls back
+// to a full response, and an out-of-bounds range is rejected so the caller can answer 416.
+// End is clamped to the last byte; ranges are inclusive.
+export function decodeRange(header, total) {
+    if (!header)
+        return { kind: 'full' };
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match)
+        return { kind: 'full' };
+    const [, rawStart, rawEnd] = match;
+    if (rawStart === '' && rawEnd === '')
+        return { kind: 'full' };
+    let start;
+    let end;
+    if (rawStart === '') {
+        // Suffix range: the last N bytes.
+        const suffix = Number.parseInt(rawEnd, 10);
+        if (suffix <= 0)
+            return { kind: 'unsatisfiable' };
+        start = Math.max(0, total - suffix);
+        end = total - 1;
+    }
+    else {
+        start = Number.parseInt(rawStart, 10);
+        end = rawEnd === '' ? total - 1 : Number.parseInt(rawEnd, 10);
+    }
+    if (start > end || start >= total || start < 0)
+        return { kind: 'unsatisfiable' };
+    if (end >= total)
+        end = total - 1;
+    return { kind: 'partial', start, end };
+}
+// Build a Range-aware Response for a stored object. `rangeHeader` is the request's Range header
+// (Hono: `c.req.header('range')`). 404 if the key is gone, 416 for an unsatisfiable range, 206
+// for a partial hit, else 200.
+export async function serveRange(store, key, mime, rangeHeader, opts = {}) {
+    const meta = await store.stat(key);
+    if (!meta)
+        return new Response(null, { status: 404 });
+    const total = meta.size;
+    const headers = new Headers({
+        'Accept-Ranges': 'bytes',
+        'Content-Type': mime,
+        'Cache-Control': opts.cacheControl ?? 'private, max-age=86400',
+    });
+    if (opts.contentDisposition)
+        headers.set('Content-Disposition', opts.contentDisposition);
+    if (opts.extraHeaders) {
+        for (const [k, v] of Object.entries(opts.extraHeaders))
+            headers.set(k, v);
+    }
+    const decision = decodeRange(rangeHeader, total);
+    if (decision.kind === 'unsatisfiable') {
+        headers.set('Content-Range', `bytes */${total}`);
+        return new Response(null, { status: 416, headers });
+    }
+    const range = decision.kind === 'partial' ? decision : undefined;
+    const result = await store.getRange(key, range);
+    if (!result)
+        return new Response(null, { status: 404 });
+    if (range) {
+        headers.set('Content-Range', `bytes ${range.start}-${range.end}/${total}`);
+        headers.set('Content-Length', String(range.end - range.start + 1));
+        return new Response(result.stream, { status: 206, headers });
+    }
+    headers.set('Content-Length', String(total));
+    return new Response(result.stream, { status: 200, headers });
+}

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

@@ -0,0 +1,16 @@
+/** The scope a stream token authorizes: one video's whole derivative tree, under one owner. */
+export type StreamGrant = {
+    /** owner keyspace segment (the media lives under fs/<owner>/… , hls/<owner>/… , …). */
+    owner: string;
+    sourceId: string;
+    videoId: string;
+};
+export interface StreamTokenService {
+    sign(grant: StreamGrant, ttlSeconds?: number): Promise<string>;
+    verify(token: string): Promise<StreamGrant | null>;
+}
+export declare function createStreamTokenService(opts: {
+    secret: string;
+    /** Default 6h — long enough to survive a paused-and-resumed playback without a 401. */
+    defaultTtlSeconds?: number;
+}): StreamTokenService;

package/dist/server/storage/streamToken.js

@@ -0,0 +1,54 @@
+// 🔴 `../auth/jwt`, NOT `../auth`. The jose half is a REAL dependency — stream tokens are
+// signed and verified here, and jose is a plain `dependencies` entry every consumer already
+// installs. The BARREL was the accident: `../auth/index.ts` also reaches `totp.ts` → `otplib`,
+// an OPTIONAL peer, so every app that touched anything in `cursedbelt-server/storage` was made
+// to install a one-time-password library for code it never calls. Import the leaf module that
+// has what you need; never the index that has everything. `src/leafSubpathsImportNothing.spec.ts`
+// fails if this file (or anything else the storage barrel reaches) undoes it.
+import { signToken, verifyPurposeToken } from '../auth/jwt';
+// ── Stream tokens ───────────────────────────────────────────────────────────────
+// Media bytes are loaded by <video>/hls.js/<img>, which cannot send the platform Bearer
+// header an app's auth uses. So byte-serving routes live OUTSIDE the guarded API and
+// authorize each request with a short-lived, PATH-embedded token instead.
+//
+// Why path-embedded, not ?t=: hls.js resolves segment/playlist URIs RELATIVE to the master
+// playlist and does NOT inherit query strings — a `?t=` token would be dropped on segment
+// fetches. A token carried as a leading path segment (…/s/<token>/hls/…) is inherited by every
+// relative child URL, so one token authorizes the whole HLS tree.
+//
+// Reuses cursedbelt's ONE jose integration (`signToken`/`verifyPurposeToken`, HS256) — the
+// same primitive the vault/files/pm unlock tokens use — under a dedicated 'media-stream'
+// purpose so it can never be replayed as an access token (or vice-versa).
+const MEDIA_STREAM_PURPOSE = 'media-stream';
+export function createStreamTokenService(opts) {
+    const ttl = opts.defaultTtlSeconds ?? 6 * 60 * 60;
+    return {
+        async sign(grant, ttlSeconds = ttl) {
+            // userId carries the owner; src/vid are extra claims (JWTPayload allows them). sessionId
+            // is unused for stream tokens (they're not tied to a revocable session row) — a stable
+            // marker keeps the required-field contract without implying a session.
+            return signToken({
+                userId: grant.owner,
+                sessionId: 'media-stream',
+                roles: [],
+                purpose: MEDIA_STREAM_PURPOSE,
+                src: grant.sourceId,
+                vid: grant.videoId,
+            }, opts.secret, ttlSeconds);
+        },
+        async verify(token) {
+            try {
+                const p = await verifyPurposeToken(token, opts.secret, MEDIA_STREAM_PURPOSE);
+                const src = p.src;
+                const vid = p.vid;
+                if (typeof src !== 'string' || typeof vid !== 'string')
+                    return null;
+                return { owner: p.userId, sourceId: src, videoId: vid };
+            }
+            catch {
+                // Bad signature / expiry / purpose mismatch — deny.
+                return null;
+            }
+        },
+    };
+}

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

@@ -0,0 +1,65 @@
+export type TranscodeJobStatus = 'pending' | 'processing' | 'ready' | 'failed';
+export type TranscodeJobResult = {
+    durationSeconds?: number;
+    hasHls?: boolean;
+    hasPoster?: boolean;
+    hasSprite?: boolean;
+    hasThumbnail?: boolean;
+    hasDisplay?: boolean;
+};
+export type TranscodeJobStatusBody = {
+    status: TranscodeJobStatus;
+    progress?: number;
+    error?: string;
+    result?: TranscodeJobResult;
+};
+export type TranscodeJobClientConfig = {
+    /** e.g. 'https://binary-server.cursedalchemy.com' — same value as the byte store's baseUrl. */
+    baseUrl: string;
+    /** App namespace (path + token scope), e.g. 'notes'. Keys are sent app-scoped. */
+    appId: string;
+    /** Shared server-to-server secret (x-internal-secret). */
+    internalSecret: string;
+    /** Poll cadence while a job runs. */
+    pollMs?: number;
+    /** Give up after this long (the job keeps running server-side; the caller just stops waiting). */
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    /** Injectable clock/sleep for tests. */
+    sleep?: (ms: number) => Promise<void>;
+};
+export type TranscodeJobClient = {
+    /** Prefix a bare key with this client's app namespace, as the API expects. */
+    appKey: (key: string) => string;
+    submit: (body: Record<string, unknown>) => Promise<string>;
+    poll: (jobId: string, onProgress?: (pct: number) => void) => Promise<TranscodeJobStatusBody>;
+    /**
+     * Still-image derivatives: a width-bounded JPEG thumbnail at `thumbKey`, plus — only for
+     * formats browsers cannot render (HEIC/HEIF) — a full-size display JPEG at `displayKey`.
+     * Keys are bare (this client scopes them).
+     */
+    imageThumbnail: (opts: {
+        sourceKey: string;
+        thumbKey: string;
+        displayKey?: string;
+        /** Job label in binary-server's queue; defaults to the source key. */
+        nodeId?: string;
+    }) => Promise<{
+        hasThumbnail: boolean;
+        hasDisplay: boolean;
+    }>;
+    /**
+     * A video's poster frame ONLY — no ladder, no HLS, no sprite sheet. `posterOnly` collapses
+     * the library strategy to probe + poster, which is what a grid tile needs and is an order
+     * of magnitude cheaper than a transcode nobody asked for.
+     */
+    videoPoster: (opts: {
+        sourceKey: string;
+        posterKey: string;
+        nodeId?: string;
+    }) => Promise<{
+        hasPoster: boolean;
+        durationSeconds: number;
+    }>;
+};
+export declare function createTranscodeJobClient(cfg: TranscodeJobClientConfig): TranscodeJobClient;