@chrischall/gemini-mcp 1.3.0 → 1.5.0

package/dist/client.js

@@ -153,8 +153,17 @@ export class GeminiClient {
      * server is single-user, so its one singleton client is one session.
      */
     session = new SessionState();
+    /** Per-account character/style library — hosted connector only (see options). */
+    library;
+    /** Signed upload-URL minter — hosted connector only (see options). */
+    uploadUrls;
     constructor(opts = {}) {
         this.mediaSink = opts.mediaSink ?? createDiskSink();
+        this.library = opts.library;
+        this.uploadUrls = opts.uploadUrls;
+        // A replayed idempotent result must not hand back an expired media URL, so
+        // the job registry needs a way to re-sign from the stable r2_key.
+        this.session.jobs.resigner = this.mediaSink;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
         this.fetchImpl = opts.fetchImpl ?? fetch;
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -227,6 +236,21 @@ export class GeminiClient {
         // one unbounded network operation in the server.
         return fetchRemoteImage(url, { ...opts, fetchImpl: this.fetchImpl, timeoutMs: resolveTimeoutMs(opts.timeoutMs) });
     }
+    /**
+     * Read back media this connector generated, straight out of its own store.
+     *
+     * The alternative — fetching our own `/media` URL — needs a signature the
+     * caller cannot mint and returns 403, which is the loop this exists to close.
+     */
+    async readStoredMedia(key) {
+        const stored = await this.mediaSink.read?.(key.trim());
+        if (!stored) {
+            // Remediation goes in the MESSAGE: MCP serialization drops hints.
+            throw new McpToolError(`No stored media for r2_key "${key}" — objects are removed on a retention schedule, so an old key may be gone. ` +
+                'Re-run the generation, or upload the bytes with `url` / `data_base64`.', { hint: 'Use the exact media[].r2_key from a generation result.' });
+        }
+        return stored;
+    }
     /** The default model after env override (no per-call arg). */
     defaultModel() {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));

package/dist/inputs.js

@@ -7,6 +7,7 @@ export function hasImageInput(args) {
         args.images_base64?.length ||
         args.images_url?.length ||
         args.images_file_uris?.length ||
+        args.images_r2_keys?.length ||
         args.from_clipboard);
 }
 /** Conservative TTL when the API doesn't tell us: documented retention is ~48h. */
@@ -75,6 +76,40 @@ export async function resolveImageInputs(args, client) {
         (report.file_uris ??= []).push(file.name);
         inputs.push(input);
     }
+    // 6. r2_keys — the connector reads its OWN store (tenant-gated), so a signed
+    // upload or an earlier generation becomes a reference without a fetch, a
+    // signature, or a byte in the conversation. Deduped within the call, same as
+    // URLs, and — also same as URLs — a large object is promoted to a Files API
+    // reference rather than inlined, because `generateContent` caps a whole
+    // request near 20MB and two large inline references would fail it.
+    // `readStoredMedia` throws an actionable error for a swept/foreign key.
+    const seenKeys = new Map();
+    for (const key of args.images_r2_keys ?? []) {
+        const hit = seenKeys.get(key);
+        if (hit) {
+            inputs.push(hit);
+            continue;
+        }
+        const stored = await client.readStoredMedia(key);
+        const entry = {
+            r2_key: key.trim(),
+            mime_type: stored.mimeType,
+            bytes: stored.bytes.byteLength,
+        };
+        (report.r2_keys ??= []).push(entry);
+        let input;
+        if (stored.bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
+            input = { base64: bytesToBase64(stored.bytes), mimeType: stored.mimeType };
+        }
+        else {
+            const displayName = key.trim().split('/').pop() || 'image';
+            const uploaded = await client.uploadBytes(stored.bytes, stored.mimeType, displayName);
+            entry.file_uri = uploaded.name;
+            input = { uri: uploaded.uri, mimeType: uploaded.mimeType };
+        }
+        seenKeys.set(key, input);
+        inputs.push(input);
+    }
     return { inputs, report: Object.keys(report).length > 0 ? report : undefined };
 }
 /**
@@ -161,5 +196,6 @@ export function requireImageInput(args) {
     if (hasImageInput(args))
         return;
     throw new McpToolError('Provide at least one input image via `images_url` (an https URL the server fetches), `images_file_uris` ' +
-        '(from gemini_upload_file), `images` (a local path), `images_base64`, or `from_clipboard`.');
+        '(from gemini_upload_file), `images_r2_keys` (a hosted-connector upload or earlier generation), ' +
+        '`images` (a local path), `images_base64`, or `from_clipboard`.');
 }

package/dist/jobs.js

@@ -1,5 +1,6 @@
 import { randomUUID, createHash } from 'node:crypto';
 import { textResult, McpToolError } from '@chrischall/mcp-utils';
+import { downloadFilename } from './media-endpoint.js';
 /** Recently-completed jobs are reusable by key for this long, then evicted. */
 const JOB_TTL_MS = 600_000; // 10 min
 /** Hard cap on retained entries (oldest-settled evicted first). */
@@ -22,6 +23,91 @@ function isExpired(entry, now) {
 export function fingerprintRequest(toolName, parts) {
     return createHash('sha256').update(`${toolName}\u0000${JSON.stringify(parts)}`).digest('hex');
 }
+/**
+ * Re-mint any media URLs a recorded result carries, before it is replayed.
+ *
+ * A recorded result can outlive the signed URLs inside it — and after a change
+ * to the result shape it can even carry the OLD shape entirely. Either way the
+ * caller gets something that looks right and does not work. Re-signing from the
+ * `r2_key`, which is stable, fixes both: an expired link becomes a live one,
+ * and a legacy entry gains the `url`/`curl_hint` fields the current shape has.
+ *
+ * Best-effort by design. A replay that cannot be refreshed is still a valid
+ * replay — the point of idempotency is not billing twice, and failing here
+ * would trade a stale URL for no result at all.
+ */
+async function refreshMedia(result, sink) {
+    const first = result.content?.[0];
+    if (!sink?.resign || !first || first.type !== 'text')
+        return result;
+    let body;
+    try {
+        body = JSON.parse(first.text);
+    }
+    catch {
+        return result;
+    }
+    const entries = Array.isArray(body.media) ? body.media : [];
+    if (!entries.some((e) => typeof e.r2_key === 'string'))
+        return result;
+    // Per ENTRY, not per key: filtering first would shift every assignment after
+    // an entry without an r2_key and truncate the flat list below.
+    const refreshed = await Promise.all(entries.map(async (e) => {
+        if (typeof e.r2_key !== 'string')
+            return undefined;
+        try {
+            return await sink.resign(e.r2_key);
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    if (refreshed.every((r) => r === undefined))
+        return result;
+    const mediaKeyName = ['images', 'videos', 'audios'].find((k) => Array.isArray(body[k]));
+    const refs = [];
+    refreshed.forEach((fresh, i) => {
+        if (!fresh) {
+            refs.push(String(entries[i]?.url ?? ''));
+            return;
+        }
+        // Drop the recorded expiry rather than carrying it over: a re-signed URL
+        // has its own deadline (or none, on a public-bucket sink), and the old one
+        // would mislabel a live link as expired.
+        const { expires_at: _stale, ...rest } = entries[i];
+        entries[i] = {
+            ...rest,
+            url: fresh.ref,
+            ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
+            curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? 'media')} "${fresh.ref}"`,
+        };
+        refs.push(fresh.ref);
+    });
+    body.media = entries;
+    if (mediaKeyName)
+        body[mediaKeyName] = refs;
+    // A multi-image set also carries a bundle zip; its link expires like any
+    // other and re-signs from its own r2_key. Best-effort, like the rest.
+    const bundle = body.bundle;
+    if (bundle && typeof bundle.r2_key === 'string') {
+        try {
+            const fresh = await sink.resign(bundle.r2_key);
+            if (fresh) {
+                const { expires_at: _staleBundle, ...rest } = bundle;
+                body.bundle = {
+                    ...rest,
+                    url: fresh.ref,
+                    ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
+                    curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? 'media')} "${fresh.ref}"`,
+                };
+                body.bundle_url = fresh.ref;
+            }
+        }
+        catch { /* an un-refreshed bundle link is still a valid replay */ }
+    }
+    body.media_urls_refreshed = true;
+    return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
+}
 /** Clone `result`, adding `reused: true` + `reused_job_id` to its meta block. */
 function annotateReused(result, jobId) {
     const content = result.content ?? [];
@@ -52,12 +138,31 @@ function jobHandle(jobId, status) {
         hint: `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`,
     });
 }
+/**
+ * Await `promise` for at most `waitMs`; `undefined` means the budget expired
+ * with the work still pending (rejections propagate as usual). The timer never
+ * holds the process open, and a late rejection after the budget expired is
+ * already handled by the registry's own settle handlers.
+ */
+function awaitWithBudget(promise, waitMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), waitMs);
+        timer.unref?.();
+        promise.then((result) => { clearTimeout(timer); resolve(result); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
 /**
  * One session's jobs. Construct one per session and never share it — see the
  * cross-tenant note at the top of this file. Reachable as
  * `client.session.jobs`.
  */
 export class JobRegistry {
+    /**
+     * Lets a replayed result have its media URLs re-minted. Set by the session
+     * that owns this registry; absent on stdio, where refs are file paths that
+     * never expire.
+     */
+    resigner;
     jobs = new Map();
     byKey = new Map(); // idempotencyKey -> jobId
     runningByFingerprint = new Map(); // fingerprint -> jobId (only while running)
@@ -108,7 +213,7 @@ export class JobRegistry {
      * different registry and therefore a genuinely separate generation.
      */
     async dispatch(opts, work) {
-        const { toolName, fingerprint, idempotencyKey, async } = opts;
+        const { toolName, fingerprint, idempotencyKey, async, waitMs } = opts;
         const now = Date.now();
         let hit;
         if (idempotencyKey !== undefined) {
@@ -126,7 +231,15 @@ export class JobRegistry {
         if (hit) {
             if (async)
                 return jobHandle(hit.jobId, hit.status);
-            return annotateReused(await hit.promise, hit.jobId);
+            const settled = waitMs !== undefined && hit.status === 'running'
+                ? await awaitWithBudget(hit.promise, waitMs)
+                : await hit.promise;
+            if (settled === undefined)
+                return jobHandle(hit.jobId, 'running');
+            // Refresh before annotating: a recorded result can outlive the signed
+            // URLs inside it, and replaying an expired link is its own kind of wrong
+            // answer — it looks like success.
+            return annotateReused(await refreshMedia(settled, this.resigner), hit.jobId);
         }
         const jobId = randomUUID();
         this.evict(now);
@@ -146,6 +259,13 @@ export class JobRegistry {
         });
         if (async)
             return jobHandle(jobId, 'running');
+        if (waitMs !== undefined) {
+            const settled = await awaitWithBudget(promise, waitMs);
+            // Budget expired with the work still running: hand back the job id — the
+            // work continues and the caller polls, exactly as with `async: true`,
+            // except a fast result would have been returned in-band.
+            return settled ?? jobHandle(jobId, 'running');
+        }
         return promise;
     }
     /**

package/dist/library.js

@@ -0,0 +1,151 @@
+/**
+ * The per-account reference library: named characters (a reference image + a
+ * description) and named styles (a reusable prompt fragment, optionally with a
+ * reference image of its own).
+ *
+ * Why it exists: keeping a recurring subject consistent across generations
+ * means re-supplying the same reference image and the same description every
+ * session — re-uploading the photo, re-typing the description, re-explaining
+ * the style. The library makes each of those a NAME: save once, then pass
+ * `characters: ["finn"]` / `style: "bold-cartoon-sports"` on any generation.
+ *
+ * Storage is the connector's R2 bucket under `lib/<tenant>/…`:
+ *
+ *  - `lib/<tenant>/characters/<name>.json` — the record
+ *  - `lib/<tenant>/characters/<name>.img`  — the reference image bytes
+ *  - `lib/<tenant>/styles/<name>.json` (+ `.img` when a reference was given)
+ *
+ * Two properties are load-bearing:
+ *
+ *  - **No expiry.** The retention cron sweeps `gen/`, `media/` and `up/` but
+ *    deliberately never `lib/` (media-cleanup.ts) — a saved character outlives
+ *    every signed URL and every upload. That is why saving COPIES the image
+ *    bytes into `lib/` rather than storing an `r2_key` pointer: a pointer into
+ *    `gen/` or `up/` would dangle after the next sweep.
+ *  - **Tenant scoping by construction.** Every key this module touches is
+ *    derived from the session's own tenant id; caller-supplied names are
+ *    validated against a strict slug charset, so no name can address another
+ *    account's namespace (or escape `lib/` at all).
+ *
+ * Worker-safe: no node imports, no module-scope state, structural bucket type.
+ */
+/** Key prefix for the library — the one prefix the retention sweep must skip. */
+export const LIBRARY_KEY_PREFIX = 'lib';
+/**
+ * Library names are slugs: 1–40 chars, lowercase alphanumerics plus `-`/`_`,
+ * starting alphanumeric. Doubles as key-safety (no `/`, `.`, whitespace).
+ */
+export const LIBRARY_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+export function isValidLibraryName(name) {
+    return LIBRARY_NAME_PATTERN.test(name);
+}
+/** Build the R2-backed library for one session. */
+export function createR2Library(bucket, opts) {
+    const now = opts.now ?? (() => new Date());
+    let tenantCache;
+    const tenantId = () => (tenantCache ??= Promise.resolve(typeof opts.tenant === 'function' ? opts.tenant() : opts.tenant));
+    const assertName = (name) => {
+        if (!isValidLibraryName(name)) {
+            throw new Error(`Invalid library name "${name}" — use 1-40 lowercase letters, digits, "-" or "_" (e.g. "finn", "bold-cartoon-sports").`);
+        }
+        return name;
+    };
+    const keyFor = async (kind, name, ext) => `${LIBRARY_KEY_PREFIX}/${await tenantId()}/${kind}/${assertName(name)}.${ext}`;
+    async function readJson(key) {
+        const object = await bucket.get(key);
+        if (!object)
+            return undefined;
+        try {
+            return JSON.parse(new TextDecoder().decode(await object.arrayBuffer()));
+        }
+        catch {
+            // A malformed record is unreadable, not fatal — callers treat it as absent.
+            return undefined;
+        }
+    }
+    async function readImage(kind, name) {
+        const object = await bucket.get(await keyFor(kind, name, 'img'));
+        if (!object)
+            return undefined;
+        return {
+            bytes: new Uint8Array(await object.arrayBuffer()),
+            mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
+        };
+    }
+    async function listRecords(kind) {
+        const prefix = `${LIBRARY_KEY_PREFIX}/${await tenantId()}/${kind}/`;
+        const keys = [];
+        let cursor;
+        for (;;) {
+            const page = await bucket.list({ prefix, cursor, limit: 1000 });
+            keys.push(...page.objects.map((o) => o.key).filter((k) => k.endsWith('.json')));
+            if (!page.truncated)
+                break;
+            cursor = page.cursor;
+        }
+        const records = await Promise.all(keys.map((k) => readJson(k)));
+        return records
+            .filter((r) => r !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async function deleteEntry(kind, name) {
+        const jsonKey = await keyFor(kind, name, 'json');
+        const existed = (await bucket.get(jsonKey)) !== null;
+        await bucket.delete([jsonKey, await keyFor(kind, name, 'img')]);
+        return existed;
+    }
+    return {
+        async saveCharacter({ name, description, image }) {
+            const jsonKey = await keyFor('characters', name, 'json');
+            const imageKey = await keyFor('characters', name, 'img');
+            const at = now().toISOString();
+            const existing = await readJson(jsonKey);
+            const record = {
+                name,
+                description,
+                image_key: imageKey,
+                mime_type: image.mimeType,
+                created_at: existing?.created_at ?? at,
+                updated_at: at,
+            };
+            await bucket.put(imageKey, image.bytes, { httpMetadata: { contentType: image.mimeType } });
+            await bucket.put(jsonKey, JSON.stringify(record, null, 2), { httpMetadata: { contentType: 'application/json' } });
+            return record;
+        },
+        async getCharacter(name) {
+            return readJson(await keyFor('characters', name, 'json'));
+        },
+        readCharacterImage: (name) => readImage('characters', name),
+        listCharacters: () => listRecords('characters'),
+        deleteCharacter: (name) => deleteEntry('characters', name),
+        async saveStyle({ name, promptFragment, image }) {
+            const jsonKey = await keyFor('styles', name, 'json');
+            const imageKey = await keyFor('styles', name, 'img');
+            const at = now().toISOString();
+            const existing = await readJson(jsonKey);
+            const record = {
+                name,
+                prompt_fragment: promptFragment,
+                ...(image ? { image_key: imageKey, mime_type: image.mimeType } : {}),
+                created_at: existing?.created_at ?? at,
+                updated_at: at,
+            };
+            if (image) {
+                await bucket.put(imageKey, image.bytes, { httpMetadata: { contentType: image.mimeType } });
+            }
+            else if (existing?.image_key) {
+                // Re-saving without an image REPLACES the style — a stale reference
+                // image left behind would silently keep steering generations.
+                await bucket.delete(imageKey);
+            }
+            await bucket.put(jsonKey, JSON.stringify(record, null, 2), { httpMetadata: { contentType: 'application/json' } });
+            return record;
+        },
+        async getStyle(name) {
+            return readJson(await keyFor('styles', name, 'json'));
+        },
+        readStyleImage: (name) => readImage('styles', name),
+        listStyles: () => listRecords('styles'),
+        deleteStyle: (name) => deleteEntry('styles', name),
+    };
+}

package/dist/media-cleanup.js

@@ -17,8 +17,11 @@ const DEFAULT_MAX_OBJECTS = 5_000;
  * `gen/` is where media is written now; `media/` is where it was written before
  * the rename that made URLs read `/media/gen/…` instead of `/media/media/…`.
  * Both are swept — retention that ignores the existing backlog is not retention.
+ * `up/` (signed uploads) is swept on the same schedule: a reference photo worth
+ * keeping gets copied into the character library (`lib/`), which is the ONE
+ * prefix deliberately absent here — saved characters and styles have no expiry.
  */
-const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/'];
+const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/', 'up/'];
 /** R2 accepts bulk deletes in batches; 1000 is the documented ceiling. */
 const DELETE_BATCH = 1_000;
 /** Days → ms, defaulting to 7 for anything missing or nonsensical. */

package/dist/media-endpoint.js

@@ -1,4 +1,81 @@
 import { loadSigningKey, verifyMediaSignature } from './media-url.js';
+/**
+ * Human-friendly download name from an object key.
+ *
+ * Keys look like `gen/<tenant>/2026-07-29/ab12cd34-a-cat.png`; the random component is
+ * there to make the key unique, not to be read. Stripping it turns a saved file
+ * into `a-cat.png`, which matters because the reliable way to show a user an
+ * image in a chat client is for the agent to download it and attach it — and an
+ * attachment called `ab12cd34-a-cat.png` looks like a machine artefact.
+ */
+export function downloadFilename(key) {
+    const last = key.split('/').pop() || 'media';
+    const stripped = last.replace(/^[0-9a-f]{6,12}-/i, '');
+    return stripped || last;
+}
+/**
+ * Parse a single-range `Range: bytes=a-b` header. Multi-range is unsupported,
+ * and an unknown object size means no range handling at all (Range is advisory
+ * — `undefined` degrades to a full 200, never an error).
+ */
+function parseRange(header, size) {
+    if (!header || size === undefined)
+        return undefined;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match)
+        return undefined;
+    const [, startText, endText] = match;
+    if (startText === '' && endText === '')
+        return undefined;
+    if (startText === '') {
+        // Suffix range: the last N bytes.
+        const suffix = Number(endText);
+        if (!suffix)
+            return undefined;
+        const offset = Math.max(0, size - suffix);
+        return { offset, length: size - offset };
+    }
+    const offset = Number(startText);
+    if (offset >= size)
+        return 'unsatisfiable';
+    const end = endText === '' ? size - 1 : Number(endText);
+    if (end < offset)
+        return 'unsatisfiable';
+    return { offset, length: end - offset + 1 };
+}
+const MISSING = 'That media object no longer exists — it may have been cleaned up. Re-run the generation to get a fresh one.';
+/**
+ * Response headers shared by GET, HEAD and 206. `Content-Disposition` carries a
+ * readable filename because the reliable way to show a user an image in a chat
+ * client is for the agent to download it and attach it.
+ */
+function baseHeaders(key, object, size) {
+    const headers = new Headers({
+        'content-type': object.httpMetadata?.contentType ?? 'application/octet-stream',
+        // The URL is signed and expiring, so it is safe to cache for its lifetime;
+        // `private` keeps shared caches from serving it to anyone else.
+        'cache-control': 'private, max-age=3600',
+        'content-disposition': `inline; filename="${downloadFilename(key)}"`,
+        // The bytes are model output being handed to a browser — never let a
+        // sniffed content type turn an image response into something executable.
+        'x-content-type-options': 'nosniff',
+        // Defense in depth against stored XSS: this route serves user-influenced
+        // bytes from the SAME ORIGIN as the connector's OAuth pages, so if a
+        // scriptable document type (SVG, HTML) ever slipped past the raster-only
+        // upload gates, this neutralizes it — no script, no fetch, and a unique
+        // opaque origin via sandbox. Pixels don't need any of what this disables.
+        'content-security-policy': "default-src 'none'; sandbox",
+        // Range support is cheap on R2 and is what makes a resumable `curl -C -`
+        // work against a large video.
+        'accept-ranges': 'bytes',
+    });
+    const etag = object.httpEtag ?? object.etag;
+    if (etag)
+        headers.set('etag', etag);
+    if (size !== undefined)
+        headers.set('content-length', String(size));
+    return headers;
+}
 function problem(status, message) {
     return new Response(`${message}\n`, {
         status,
@@ -49,24 +126,41 @@ export function createMediaHandler(env, basePath = '/media/') {
             }
             return problem(403, 'Invalid or missing media signature. Media links must be used exactly as returned by the tool, including the exp and sig parameters.');
         }
+        const rangeHeader = request.headers.get('range');
+        // HEAD is what a link-preview fetcher and `curl -I` send first; serve it
+        // from a metadata read where the bucket offers one, rather than opening a
+        // body we are about to throw away.
+        if (request.method === 'HEAD' && env.bucket.head) {
+            const meta = await env.bucket.head(key);
+            if (!meta)
+                return problem(404, MISSING);
+            return new Response(null, { status: 200, headers: baseHeaders(key, meta, meta.size) });
+        }
+        // Fetch whole and slice on the way out rather than pushing the range into
+        // R2: the objects here are single images and short clips, and a typed
+        // range option is not expressible against both the real binding and a test
+        // fake without casting away the very types that make this safe.
         const object = await env.bucket.get(key);
-        if (!object) {
-            return problem(404, 'That media object no longer exists — it may have been cleaned up. Re-run the generation to get a fresh one.');
+        if (!object)
+            return problem(404, MISSING);
+        const totalSize = object.size;
+        const range = parseRange(rangeHeader, totalSize);
+        if (range === 'unsatisfiable') {
+            return new Response('Requested range not satisfiable\n', {
+                status: 416,
+                headers: { 'content-range': `bytes */${totalSize ?? 0}`, 'content-type': 'text/plain; charset=utf-8' },
+            });
         }
-        const headers = new Headers({
-            'content-type': object.httpMetadata?.contentType ?? 'application/octet-stream',
-            // The URL is signed and expiring, so it is safe to cache for its lifetime;
-            // `private` keeps shared caches from serving it to anyone else.
-            'cache-control': 'private, max-age=3600',
-            'content-disposition': `inline; filename="${key.split('/').pop() ?? 'media'}"`,
-            // The bytes are model output being handed to a browser — never let a
-            // sniffed content type turn an image response into something executable.
-            'x-content-type-options': 'nosniff',
-        });
-        if (object.size !== undefined)
-            headers.set('content-length', String(object.size));
+        const headers = baseHeaders(key, object, totalSize);
         if (request.method === 'HEAD')
             return new Response(null, { status: 200, headers });
-        return new Response(object.body, { status: 200, headers });
+        if (range && totalSize !== undefined && object.arrayBuffer) {
+            const length = Math.min(range.length, totalSize - range.offset);
+            const slice = (await object.arrayBuffer()).slice(range.offset, range.offset + length);
+            headers.set('content-length', String(slice.byteLength));
+            headers.set('content-range', `bytes ${range.offset}-${range.offset + slice.byteLength - 1}/${totalSize}`);
+            return new Response(slice, { status: 206, headers });
+        }
+        return new Response(object.body ?? null, { status: 200, headers });
     };
 }

package/dist/media-url.js

@@ -19,14 +19,14 @@
 export const MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1000;
 /** KV key holding the lazily-generated signing secret (zero-config path). */
 export const SIGNING_SECRET_KV_KEY = 'media:url-signing-secret';
-function base64UrlEncode(bytes) {
+export function base64UrlEncode(bytes) {
     const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
     let binary = '';
     for (let i = 0; i < view.length; i++)
         binary += String.fromCharCode(view[i]);
     return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-function base64UrlDecode(text) {
+export function base64UrlDecode(text) {
     const padded = text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '=');
     const binary = atob(padded);
     const out = new Uint8Array(binary.length);