@chrischall/gemini-mcp 1.2.0 → 1.4.0

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,72 @@ 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;
+    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 ?? [];
@@ -58,6 +125,12 @@ function jobHandle(jobId, status) {
  * `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)
@@ -126,7 +199,10 @@ export class JobRegistry {
         if (hit) {
             if (async)
                 return jobHandle(hit.jobId, hit.status);
-            return annotateReused(await hit.promise, hit.jobId);
+            // 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(await hit.promise, this.resigner), hit.jobId);
         }
         const jobId = randomUUID();
         this.evict(now);

package/dist/media-cleanup.js

@@ -0,0 +1,75 @@
+/**
+ * Retention for generated media.
+ *
+ * Every hosted generation writes an object to R2 and nothing ever removed it,
+ * so the bucket grew without bound — and the signed links pointing into it are
+ * only useful for a couple of days anyway. A scheduled sweep keeps the two in
+ * step: objects live `MEDIA_TTL_DAYS` (default 7), and a signed URL's lifetime
+ * is clamped to that, so a link never outlives the object behind it.
+ *
+ * R2 lifecycle rules would be the cheaper mechanism, but they are configured on
+ * the bucket rather than in `wrangler.jsonc`, so a fresh deploy of this repo
+ * would silently have no retention at all. A cron in the Worker ships with the
+ * code.
+ */
+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.
+ */
+const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/'];
+/** 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. */
+export function retentionMsFromDays(days) {
+    const n = Number(days);
+    return (Number.isFinite(n) && n > 0 ? n : 7) * 24 * 60 * 60 * 1000;
+}
+/**
+ * Delete generated media older than `retentionMs`. Returns counts rather than
+ * logging them, so the caller decides what to do with the numbers and the sweep
+ * itself stays testable.
+ */
+export async function cleanupExpiredMedia(bucket, retentionMs, opts = {}) {
+    const now = opts.now?.() ?? Date.now();
+    const cutoff = now - retentionMs;
+    const maxObjects = opts.maxObjects ?? DEFAULT_MAX_OBJECTS;
+    const prefixes = opts.prefixes ?? LEGACY_AND_CURRENT_PREFIXES;
+    let scanned = 0;
+    let deleted = 0;
+    let truncated = false;
+    const doomed = [];
+    const flush = async (all) => {
+        while (doomed.length >= (all ? 1 : DELETE_BATCH)) {
+            const batch = doomed.splice(0, DELETE_BATCH);
+            await bucket.delete(batch);
+            deleted += batch.length;
+        }
+    };
+    for (const prefix of prefixes) {
+        let cursor;
+        for (;;) {
+            if (scanned >= maxObjects) {
+                truncated = true;
+                break;
+            }
+            const page = await bucket.list({ prefix, cursor, limit: Math.min(1000, maxObjects - scanned) });
+            for (const object of page.objects) {
+                scanned++;
+                if (object.uploaded.getTime() < cutoff)
+                    doomed.push(object.key);
+            }
+            await flush(false);
+            if (!page.truncated)
+                break;
+            if (scanned >= maxObjects) {
+                truncated = true;
+                break;
+            }
+            cursor = page.cursor;
+        }
+    }
+    await flush(true);
+    return { scanned, deleted, truncated };
+}

package/dist/media-endpoint.js

@@ -0,0 +1,160 @@
+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',
+        // 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,
+        headers: { 'content-type': 'text/plain; charset=utf-8', 'cache-control': 'no-store' },
+    });
+}
+/**
+ * Build the `/media` handler. `basePath` is stripped from the pathname to get
+ * the R2 key, so the key keeps its own prefix and the two never drift.
+ */
+export function createMediaHandler(env, basePath = '/media/') {
+    return async function handleMedia(request) {
+        if (request.method !== 'GET' && request.method !== 'HEAD') {
+            return problem(405, `Method ${request.method} not allowed; media links are GET-only.`);
+        }
+        const url = new URL(request.url);
+        if (!url.pathname.startsWith(basePath))
+            return problem(404, 'Not found');
+        // decodeURIComponent per segment, mirroring how the URL was built. A key
+        // cannot contain `..` (the sink sanitises every segment), and R2 has no
+        // path traversal to exploit anyway — a key is an opaque string, not a path.
+        const key = url.pathname
+            .slice(basePath.length)
+            .split('/')
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        })
+            .join('/');
+        if (!key)
+            return problem(404, 'Not found');
+        const now = env.now?.() ?? Date.now();
+        // Read-only: verification must never CREATE a signing secret. A stale KV
+        // read here would otherwise clobber the secret every outstanding link was
+        // signed with (see loadSigningKey). No secret ⇒ nothing was legitimately
+        // signed ⇒ refuse, without touching storage or the bucket.
+        const signingKey = await loadSigningKey(env.secret, env.store);
+        const check = signingKey
+            ? await verifyMediaSignature(signingKey, key, url.searchParams.get('exp'), url.searchParams.get('sig'), now)
+            : { ok: false, reason: 'invalid' };
+        if (!check.ok) {
+            if (check.reason === 'expired') {
+                return problem(410, 'This media link has expired. Generated media is retained for a limited time — re-run the generation to get a fresh link.');
+            }
+            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, 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 = baseHeaders(key, object, totalSize);
+        if (request.method === 'HEAD')
+            return new Response(null, { 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

@@ -0,0 +1,135 @@
+/**
+ * Signed URLs for generated media on the hosted connector.
+ *
+ * The problem these exist to solve: a chat client shows the user whatever the
+ * assistant *says*, and MCP inline image blocks are not that. On claude.ai and
+ * the mobile app the bytes arrive in the model's context and are never rendered
+ * — so a generation that billed successfully is invisible. A URL is the only
+ * portable answer: a human can tap it and an agent can curl it.
+ *
+ * That means the media route cannot sit behind the connector's OAuth, because
+ * a browser opening a link carries no bearer token. The signature IS the
+ * authorization: a URL is valid for one key until it expires, and nothing else
+ * in the bucket is reachable without one.
+ *
+ * Kept free of any Cloudflare import so the whole thing is testable under Node:
+ * WebCrypto is the only primitive used, and it exists on both runtimes.
+ */
+/** How long a freshly minted media URL stays valid. Matches Files API retention. */
+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) {
+    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) {
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const out = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        out[i] = binary.charCodeAt(i);
+    return out;
+}
+/** Import raw secret material as an HMAC key. */
+async function importKey(material) {
+    return crypto.subtle.importKey('raw', new TextEncoder().encode(material), { name: 'HMAC', hash: 'SHA-256' }, false, [
+        'sign',
+        'verify',
+    ]);
+}
+/**
+ * The HMAC key for **signing**, creating one if this deployment has never
+ * signed anything.
+ *
+ * `MEDIA_URL_SECRET` wins when an operator sets one. Otherwise a random 32-byte
+ * secret is generated once and persisted in KV — which is what makes the whole
+ * feature work with **zero configuration**, the entire point of this change.
+ *
+ * Creating is confined to this function, and this function is called only when
+ * minting a URL. {@link loadSigningKey} is what the verify path uses. That
+ * split is load-bearing, not stylistic — see the warning there.
+ *
+ * Deliberately NOT cached in a module-level variable: `src/` holds no
+ * module-scope mutable state (see session.ts), and a KV read per sign is cheap
+ * next to an image generation. There is a narrow first-use race — two isolates
+ * generating simultaneously — so the value is re-read after writing and the
+ * stored one wins, collapsing the window to URLs minted in that same instant.
+ */
+export async function resolveSigningKey(secret, store) {
+    let material = secret?.trim();
+    if (!material) {
+        material = (await store.get(SIGNING_SECRET_KV_KEY)) ?? undefined;
+        if (!material) {
+            const generated = base64UrlEncode(crypto.getRandomValues(new Uint8Array(32)));
+            await store.put(SIGNING_SECRET_KV_KEY, generated);
+            // Re-read so a concurrent generator's value wins consistently for both.
+            material = (await store.get(SIGNING_SECRET_KV_KEY)) ?? generated;
+        }
+    }
+    return importKey(material);
+}
+/**
+ * The HMAC key for **verifying**. Read-only: returns `undefined` when no secret
+ * is stored, and never creates one.
+ *
+ * This is not a stylistic split. KV is eventually consistent — a `put` on one
+ * isolate is not immediately visible to another — so the verify path can and
+ * will see a miss for a secret that exists. If verification created-on-miss
+ * (as it did originally), that transient miss would mint a NEW secret and
+ * overwrite the one every outstanding link was signed with, permanently 403ing
+ * media that had been signed perfectly correctly. A self-inflicted denial of
+ * service, triggered by ordinary traffic, and irreversible once the old secret
+ * is gone.
+ *
+ * No secret stored ⇒ nothing was ever legitimately signed ⇒ refuse.
+ */
+export async function loadSigningKey(secret, store) {
+    const material = secret?.trim() || (await store.get(SIGNING_SECRET_KV_KEY));
+    return material ? importKey(material) : undefined;
+}
+/** The bytes covered by a signature: the object key and the expiry, nothing else. */
+function payload(key, expiresAtMs) {
+    return new TextEncoder().encode(`${key}\n${expiresAtMs}`);
+}
+/** Sign one object key for use until `expiresAtMs`. */
+export async function signMediaKey(signingKey, key, expiresAtMs) {
+    return base64UrlEncode(await crypto.subtle.sign('HMAC', signingKey, payload(key, expiresAtMs)));
+}
+/**
+ * Check a `?exp=&sig=` pair against an object key.
+ *
+ * Verification goes through `crypto.subtle.verify` rather than a string
+ * comparison, so it is constant-time — a `===` on the signature would leak the
+ * expected value one byte at a time to anyone willing to time it.
+ */
+export async function verifyMediaSignature(signingKey, key, exp, sig, nowMs) {
+    if (!exp || !sig)
+        return { ok: false, reason: 'missing' };
+    const expiresAtMs = Number(exp);
+    if (!Number.isFinite(expiresAtMs))
+        return { ok: false, reason: 'invalid' };
+    let valid;
+    try {
+        valid = await crypto.subtle.verify('HMAC', signingKey, base64UrlDecode(sig), payload(key, expiresAtMs));
+    }
+    catch {
+        return { ok: false, reason: 'invalid' };
+    }
+    // Signature first, then expiry: an expired-but-authentic link deserves a
+    // different message from a forged one, and saying "expired" about a forgery
+    // would confirm the attacker got the signature right.
+    if (!valid)
+        return { ok: false, reason: 'invalid' };
+    if (nowMs > expiresAtMs)
+        return { ok: false, reason: 'expired' };
+    return { ok: true };
+}
+/** `<base>/<key>?exp=…&sig=…` — the URL handed back to the caller. */
+export function buildMediaUrl(baseUrl, key, expiresAtMs, signature) {
+    const path = key.split('/').map(encodeURIComponent).join('/');
+    return `${baseUrl.replace(/\/+$/, '')}/${path}?exp=${expiresAtMs}&sig=${signature}`;
+}

package/dist/storage/media.js

@@ -30,13 +30,20 @@ export function createDiskSink() {
             // Sequential on purpose: uniquePath checks the filesystem, so writing two
             // colliding names concurrently would race onto the same path.
             for (const it of items)
-                refs.push(await writeMedia(dir, it.base, it.base64, it.mimeType));
+                refs.push({ ref: await writeMedia(dir, it.base, it.base64, it.mimeType) });
             return refs;
         },
         note: () => undefined,
     };
 }
-const KEY_PREFIX_DEFAULT = 'media';
+/** Stable, non-reversible short tenant id from a per-session secret. */
+export async function tenantIdFor(secret) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
+    return [...new Uint8Array(digest).slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+// `gen`, not `media`: the objects are served at `/media/<key>`, and a `media`
+// prefix would make every URL read `/media/media/…`.
+const KEY_PREFIX_DEFAULT = 'gen';
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
 function safeKeySegment(base) {
     const cleaned = base
@@ -57,30 +64,83 @@ export function createR2Sink(bucket, opts) {
     const prefix = opts.prefix ?? KEY_PREFIX_DEFAULT;
     const now = opts.now ?? (() => new Date());
     const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
-    const base = opts.publicBaseUrl?.replace(/\/+$/, '');
+    const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
+    const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
+    const ttlMs = opts.urlTtlMs ?? 0;
+    /** `<prefix>/` or `<prefix>/<tenant>/` — every key this sink may touch. */
+    let ownPrefixCache;
+    const ownPrefix = () => (ownPrefixCache ??= (async () => {
+        const tenant = typeof opts.tenant === 'function' ? await opts.tenant() : opts.tenant;
+        return tenant ? `${prefix}/${tenant}/` : `${prefix}/`;
+    })());
+    /**
+     * Ownership gate for caller-supplied keys. A foreign key is refused without
+     * touching storage, so the refusal is indistinguishable from a swept object.
+     * With no tenant configured there is nothing to enforce (single-user shapes).
+     */
+    const owned = async (key) => !opts.tenant || key.startsWith(await ownPrefix());
     return {
         kind: 'r2',
         persistsFiles: false,
+        async read(key) {
+            if (!bucket.get || !(await owned(key)))
+                return undefined;
+            const object = await bucket.get(key);
+            if (!object)
+                return undefined;
+            return {
+                bytes: new Uint8Array(await object.arrayBuffer()),
+                mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
+            };
+        },
+        async resign(key) {
+            if (!(await owned(key)))
+                return undefined;
+            // Only for objects that still exist — re-signing a swept key would hand
+            // back a link that 404s, which is no better than the expired one.
+            if (bucket.get && !(await bucket.get(key)))
+                return undefined;
+            return describe(key, now().getTime() + ttlMs);
+        },
         async persist(items, _opts) {
             // `mediaExt` is pure string work but lives in images.ts next to node:fs
             // imports; the dynamic import keeps that module off a Worker's eager
             // module graph.
             const { mediaExt } = await import('../images.js');
+            const keyBase = await ownPrefix();
             const day = now().toISOString().slice(0, 10);
+            const expiresAtMs = now().getTime() + ttlMs;
             const refs = [];
             for (const it of items) {
-                const key = `${prefix}/${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
-                const bytes = base64ToBytes(it.base64);
-                await bucket.put(key, bytes, { httpMetadata: { contentType: it.mimeType } });
-                refs.push(base ? `${base}/${key}` : `r2://${opts.bucketName ?? 'media'}/${key}`);
+                const key = `${keyBase}${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
+                await bucket.put(key, base64ToBytes(it.base64), { httpMetadata: { contentType: it.mimeType } });
+                refs.push(await describe(key, expiresAtMs));
             }
             return refs;
         },
-        note: () => base
-            ? 'Generated media was uploaded to R2; the values above are public URLs, not local file paths. ' +
+        note: () => publicBase
+            ? 'Generated media was uploaded to R2 and the values above are public URLs (not local file paths) — open or download them directly. ' +
                 'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.'
-            : 'Generated media was uploaded to R2, which is not publicly served: the values above are object refs (r2://bucket/key), NOT fetchable URLs. ' +
-                'Set MEDIA_PUBLIC_BASE_URL on the Worker to get URLs, or pass inline: true to receive the bytes directly. ' +
-                'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.',
+            : signedBase
+                ? 'Generated media is served by this connector at the signed URLs above — open them in a browser or fetch them with curl; no auth header is needed, the signature is in the link. ' +
+                    'They expire (see media[].expires_at), and the objects behind them are cleaned up on a retention schedule. ' +
+                    'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.'
+                : 'Generated media was stored, but this connector has no public media URL configured and no signing route available, so the values above are bare object keys rather than fetchable links. ' +
+                    'Set MEDIA_PUBLIC_BASE_URL on the Worker, or pass inline: true to receive the bytes directly.',
     };
+    /** One stored object → the ref the caller sees, plus its key and expiry. */
+    async function describe(key, expiresAtMs) {
+        // A bucket served directly (r2.dev or a custom domain) needs no signature.
+        if (publicBase)
+            return { ref: `${publicBase}/${key}`, key };
+        if (signedBase && opts.sign) {
+            const { buildMediaUrl } = await import('../media-url.js');
+            const signature = await opts.sign(key, expiresAtMs);
+            return { ref: buildMediaUrl(signedBase, key, expiresAtMs, signature), key, expiresAt: new Date(expiresAtMs).toISOString() };
+        }
+        // Neither configured. Unreachable in the Worker (which always passes its
+        // own origin), so this is a misconfiguration rather than a mode — say so
+        // explicitly rather than returning something that looks like a filename.
+        return { ref: key, key, unavailable: true };
+    }
 }