@aotter/mantle 0.2.1 → 0.2.2-alpha.1

package/dist/kernel/media.d.ts

@@ -2,7 +2,7 @@
 import { ContractError, type Row } from "./contracts.js";
 import type { Bound } from "./binds.js";
 import type { Dialect } from "./dialect/common.js";
-import type { MediaAsset, MediaLibrary, MediaStorage, MediaPurposePolicy } from "./site-types.js";
+import type { MediaAsset, MediaLibrary, MediaStorageOption, MediaPurposePolicy } from "./site-types.js";
 export interface MediaDatabase {
     read(sql: string, binds: unknown[]): Row[] | PromiseLike<Row[]>;
     write(steps: readonly Bound[]): Promise<Row[][]>; /** Positive native evidence that the write rolled back; absence is uncertain. */
@@ -13,9 +13,10 @@ export interface MediaDatabase {
  * outside this module raising these codes uses it: core `statusOf` maps only the core codes.
  */
 export declare const mediaError: (code: string, message: string, path?: string, options?: ErrorOptions) => ContractError;
-export declare function mediaLibrary(driver: MediaDatabase, d: Pick<Dialect, "param" | "escapeLike" | "likeEscape" | "like">, storage: MediaStorage, policies: readonly MediaPurposePolicy[], now?: () => number): MediaLibrary;
+export declare function mediaLibrary(driver: MediaDatabase, d: Pick<Dialect, "param" | "escapeLike" | "likeEscape" | "like">, option: MediaStorageOption, policies: readonly MediaPurposePolicy[], now?: () => number): MediaLibrary;
 /** The 0.2 Admin library item's convenience fields, without changing the storage DTO. */
 export declare function mediaItem(asset: MediaAsset): {
+    visibility?: "private" | undefined;
     id: string;
     variants: readonly import("./site-types.js").MediaVariant[];
     primaryUrl: string | null;
@@ -25,3 +26,15 @@ export declare function mediaItem(asset: MediaAsset): {
     caption: string | null;
     createdAt: number;
 };
+/** Where `upload_media` puts the upload targets for an MCP App: the result `_meta`, which the host gives the App and not the model. */
+export declare const UPLOAD_META = "net.aotter.mantle/upload";
+/**
+ * `upload_media`, one mode per call: `{ uploadId }` commits; `variants` returns the targets (in the result `_meta` when the
+ * client renders MCP Apps, else in the data, for an agent that PUTs itself); `sourceUrl` or `file` fetches one public image
+ * and commits it; a bare purpose returns the policy. `policies` are the site's expanded purposes.
+ */
+export declare function uploadMedia(library: MediaLibrary, policies: readonly MediaPurposePolicy[], input: Record<string, unknown>, call: {
+    readonly apps: boolean;
+}): Promise<unknown>;
+/** `find_media`: `ids` reads those assets (ids not found are listed in `missing`), else the newest-first list. */
+export declare function findMedia(library: MediaLibrary, input: Record<string, unknown>): Promise<unknown>;

package/dist/kernel/media.js

@@ -1,8 +1,10 @@
 import { ContractError } from "./contracts.js";
+import { withResultMeta } from "./result-meta.js";
 const P = "media";
 const STATUS = new Map(Object.entries({
     MEDIA_PURPOSE_REJECTED: 400, MEDIA_SVG_REJECTED: 400, MEDIA_MIME_REJECTED: 400, MEDIA_VARIANTS_INCOMPLETE: 400, MEDIA_VARIANT_SIZE_EXCEEDED: 400, MEDIA_VARIANTS_SUSPICIOUS_SIZE: 400,
-    MEDIA_ASSET_NOT_FOUND: 404, MEDIA_OBJECT_NOT_FOUND: 409, MEDIA_UPLOAD_EXPIRED: 410, SITE_NOT_CONFIGURED: 501, MEDIA_NOT_CONFIGURED: 501, PARTIAL_FAILURE: 503,
+    MEDIA_SOURCE_REJECTED: 400, MEDIA_ASSET_NOT_FOUND: 404, MEDIA_NOT_OWNED: 404, MEDIA_OBJECT_NOT_FOUND: 409, MEDIA_UPLOAD_MISMATCH: 409, MEDIA_UPLOAD_EXPIRED: 410,
+    SITE_NOT_CONFIGURED: 501, MEDIA_NOT_CONFIGURED: 501, MEDIA_SOURCE_FAILED: 502, MEDIA_STORAGE_FAILED: 502, PARTIAL_FAILURE: 503,
 }));
 const extra = (code) => ({ status: STATUS.get(code), ...(code === "PARTIAL_FAILURE" ? { fields: { failure: { outcome: "partial", retry: "safe", resource: "media" } } } : {}) });
 export const mediaError = (code, message, path = P, options) => new ContractError(code, message, path, { ...options, ...extra(code) });
@@ -15,6 +17,9 @@ const ALLOWED = new Set(["image/png", "image/jpeg", "image/webp", "image/avif",
 const MODERN = new Set(["image/avif", "image/webp"]);
 const ROLES = new Set(["primary", "alternate", "fallback"]);
 const TTL_MS = 15 * 60 * 1000;
+const MAX_READ_SECONDS = 7 * 24 * 3600;
+const TAG_KEY = "media_id_tag";
+const TAGGED = /^([0-9a-f]{12})_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const obj = (v) => (v !== null && typeof v === "object" && !Array.isArray(v) ? v : {});
 const MAX_TEXT = 1000;
 const MAX_FILENAME = 255;
@@ -48,9 +53,11 @@ function checkVariants(policy, variants) {
         throw fail("MEDIA_VARIANTS_SUSPICIOUS_SIZE", `${heavy.mimeType} (${heavy.byteSize}B) is larger than ${fallback.mimeType} (${fallback.byteSize}B): optimize it before uploading`);
 }
 const COLUMNS = "id, created_at, alt, caption, variants, metadata";
+const hidden = (variants) => variants.length > 0 && variants.every((v) => v.publicUrl === undefined);
 function assetOf(r) {
+    const variants = JSON.parse(String(r.variants));
     return {
-        id: String(r.id), variants: JSON.parse(String(r.variants)), createdAt: Number(r.created_at),
+        id: String(r.id), variants, createdAt: Number(r.created_at), ...(hidden(variants) ? { visibility: "private" } : {}),
         ...(r.alt === null ? {} : { alt: String(r.alt) }), ...(r.caption === null ? {} : { caption: String(r.caption) }),
         ...(r.metadata === null ? {} : { metadata: JSON.parse(String(r.metadata)) }),
     };
@@ -59,16 +66,39 @@ const save = (a, p) => ({
     sql: `INSERT INTO media_assets (id, created_at, owner_id, alt, caption, variants, metadata) VALUES (${p(1)}, ${p(2)}, NULL, ${p(3)}, ${p(4)}, ${p(5)}, ${p(6)}) ON CONFLICT(id) DO NOTHING`,
     binds: [a.id, a.createdAt, a.alt ?? null, a.caption ?? null, JSON.stringify(a.variants), a.metadata ? JSON.stringify(a.metadata) : null],
 });
-export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
+export function mediaLibrary(driver, d, option, policies, now = Date.now) {
+    const split = "public" in option;
+    const pub = split ? option.public : option, priv = split ? option.private : undefined;
+    const closed = policies.filter((policy) => policy.visibility === "private").map((policy) => `'${policy.name}'`);
+    if (closed.length && !priv)
+        throw fail("MEDIA_NOT_CONFIGURED", `media purpose(s) ${closed.join(", ")} are private, but the media option has no private storage; pass { public, private }`);
+    const storeOf = (isPrivate) => {
+        if (isPrivate && !priv)
+            throw fail("MEDIA_NOT_CONFIGURED", "This asset is private, but the media option has no private storage; pass { public, private }");
+        return isPrivate ? priv : pub;
+    };
     const p = d.param;
     const one = async (sql, binds) => (await driver.read(sql, binds))[0];
     const byId = (id) => one(`SELECT ${COLUMNS} FROM media_assets WHERE id = ${p(1)}`, [id]);
     const unpend = (id) => ({ sql: `DELETE FROM pending_media_uploads WHERE id = ${p(1)}`, binds: [id] });
-    const removeAll = (variants) => Promise.allSettled(variants.map((v) => storage.deleteObject({ storageKey: v.storageKey })));
+    const removeAll = (variants, storage) => Promise.allSettled(variants.map((v) => storage.deleteObject({ storageKey: v.storageKey })));
+    const ownTag = async () => (await one(`SELECT value FROM site_config WHERE key = ${p(1)}`, [TAG_KEY]))?.value;
+    const tag = async () => {
+        const found = await ownTag();
+        if (found)
+            return found;
+        await driver.write([{ sql: `INSERT INTO site_config (key, value) VALUES (${p(1)}, ${p(2)}) ON CONFLICT(key) DO NOTHING`, binds: [TAG_KEY, crypto.randomUUID().slice(0, 13).replace("-", "")] }]);
+        return (await ownTag());
+    };
+    const missing = async (id, what, code, message) => {
+        const foreign = TAGGED.exec(id)?.[1];
+        return foreign && foreign !== await ownTag() ? fail("MEDIA_NOT_OWNED", `not ${what} of this server; use the server that created it`) : fail(code, message);
+    };
+    const notFound = (id) => missing(id, "a media asset", "MEDIA_ASSET_NOT_FOUND", `no media asset '${id}'`);
     const get = async (id) => {
         const r = await byId(id);
         if (!r)
-            throw fail("MEDIA_ASSET_NOT_FOUND", `no media asset '${id}'`);
+            throw await notFound(id);
         return assetOf(r);
     };
     return {
@@ -88,7 +118,8 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             checkVariants(policy, asked);
             const at = now();
             const expiresAt = at + TTL_MS;
-            const uploadGroupId = crypto.randomUUID();
+            const uploadGroupId = `${await tag()}_${crypto.randomUUID()}`;
+            const isPrivate = policy.visibility === "private", storage = storeOf(isPrivate);
             const specs = asked.map(({ mimeType, byteSize, role }) => ({ mimeType, byteSize, role, maxBytes: policy.maxBytes[mimeType] }));
             let capabilities;
             try {
@@ -98,7 +129,7 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
                 throw own(error);
             }
             const record = {
-                purpose, filename, ...described, expiresAt, createdAt: at,
+                purpose, ...(isPrivate ? { private: true } : {}), filename, ...described, expiresAt, createdAt: at,
                 variants: capabilities.map((c, i) => ({ mimeType: c.mimeType, role: c.role, storageKey: c.storageKey, expectedSize: specs[i].byteSize, maxBytes: specs[i].maxBytes })),
             };
             await driver.write([
@@ -114,14 +145,18 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
                 return assetOf(committed);
             const row = await one(`SELECT record FROM pending_media_uploads WHERE id = ${p(1)}`, [uploadGroupId]);
             const record = row ? JSON.parse(String(row.record)) : null;
-            const discard = () => removeAll(record?.variants ?? []);
+            const storage = storeOf(record?.private);
+            const discard = () => removeAll(record?.variants ?? [], storage);
             if (!record || record.expiresAt <= now()) {
                 if (record) {
                     await discard();
                     await driver.write([unpend(uploadGroupId)]);
                 }
-                throw fail("MEDIA_UPLOAD_EXPIRED", `upload group '${uploadGroupId}' is unknown or expired; create a new upload`);
+                throw await missing(uploadGroupId, "an upload", "MEDIA_UPLOAD_EXPIRED", `upload group '${uploadGroupId}' is unknown or expired; create a new upload`);
             }
+            const named = obj(request).purpose;
+            if (named !== undefined && named !== record.purpose)
+                throw fail("MEDIA_UPLOAD_MISMATCH", `upload '${uploadGroupId}' was created for purpose '${record.purpose}', not '${String(named)}'`);
             let asset;
             try {
                 asset = await storage.commitUpload({
@@ -143,9 +178,16 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             }
             if (asset.id !== uploadGroupId)
                 throw new ContractError("OUTCOME_UNKNOWN", "Storage returned a different asset id; reconcile this upload group.", P);
+            if (asset.variants.some((v) => record.private ? v.publicUrl !== undefined : typeof v.publicUrl !== "string")) {
+                const failed = rejected(await removeAll(asset.variants, storage));
+                await discard();
+                if (failed.length)
+                    throw fail("PARTIAL_FAILURE", "Some copied variants could not be removed. Retry the same upload group.", { cause: new AggregateError(failed.map(r => r.reason)) });
+                throw fail("MEDIA_NOT_CONFIGURED", record.private ? "The private media storage returned a publicUrl: its objects would be public." : "The public media storage returned a variant without a publicUrl.");
+            }
             await driver.write([save(asset, p), unpend(uploadGroupId)]).catch(async (error) => {
                 if (driver.definitive?.(error) === true) {
-                    const failed = rejected(await removeAll(asset.variants));
+                    const failed = rejected(await removeAll(asset.variants, storage));
                     if (failed.length)
                         throw fail("PARTIAL_FAILURE", "The write rolled back, but some attempt copies could not be removed. Reconcile storage before retrying.", { cause: new AggregateError([error, ...failed.map(r => r.reason)]) });
                     throw error;
@@ -154,7 +196,7 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             });
             const durable = await get(uploadGroupId);
             const selected = new Set(durable.variants.map(v => v.storageKey));
-            if (rejected(await removeAll(asset.variants.filter(v => !selected.has(v.storageKey)))).length)
+            if (rejected(await removeAll(asset.variants.filter(v => !selected.has(v.storageKey)), storage)).length)
                 throw new ContractError("OUTCOME_UNKNOWN", "The asset is committed, but unselected upload copies need storage reconciliation.", P);
             await discard();
             return durable;
@@ -167,8 +209,8 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
             if (!Number.isInteger(n) || n < 1 || n > 500 || !Number.isSafeInteger(offset) || offset < 0 || (cursor !== undefined && String(offset) !== cursor))
                 throw bad("limit 1..500 and a cursor this list returned");
             const term = search ? d.escapeLike(search) : undefined;
-            const where = term ? `WHERE id ${d.like(true)} ${p(3)}${d.likeEscape} OR alt ${d.like(true)} ${p(3)}${d.likeEscape} OR caption ${d.like(true)} ${p(3)}${d.likeEscape}` : "";
-            const page = await driver.read(`SELECT ${COLUMNS} FROM media_assets ${where} ORDER BY created_at DESC, id DESC LIMIT ${p(1)} OFFSET ${p(2)}`, [n + 1, offset, ...(term ? [`%${term}%`] : [])]);
+            const where = term ? `WHERE id = ${p(4)} OR alt ${d.like(true)} ${p(3)}${d.likeEscape} OR caption ${d.like(true)} ${p(3)}${d.likeEscape}` : "";
+            const page = await driver.read(`SELECT ${COLUMNS} FROM media_assets ${where} ORDER BY created_at DESC, id DESC LIMIT ${p(1)} OFFSET ${p(2)}`, [n + 1, offset, ...(term ? [`%${term}%`, search] : [])]);
             const rows = page.slice(0, n).map(assetOf);
             return { rows, ...(page.length > n ? { nextCursor: String(offset + n) } : {}) };
         },
@@ -179,12 +221,31 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
                 return get(id);
             const [r] = (await driver.write([{ sql: `UPDATE media_assets SET ${patch.map(([k], i) => `${k} = ${p(i + 2)}`).join(", ")} WHERE id = ${p(1)} RETURNING ${COLUMNS}`, binds: [id, ...patch.map(([, v]) => v)] }]))[0];
             if (!r)
-                throw fail("MEDIA_ASSET_NOT_FOUND", `no media asset '${id}'`);
+                throw await notFound(id);
             return assetOf(r);
         },
+        async signRead(id, expiresIn = 300) {
+            if (!Number.isSafeInteger(expiresIn) || expiresIn < 1 || expiresIn > MAX_READ_SECONDS)
+                throw bad(`expiresIn: whole seconds, 1..${MAX_READ_SECONDS}`);
+            const asset = await get(id);
+            if (!asset.visibility)
+                return { id, variants: asset.variants.map(({ mimeType, role, publicUrl }) => ({ mimeType, role, url: publicUrl })) };
+            const storage = storeOf(true);
+            if (!storage.signRead)
+                throw fail("MEDIA_NOT_CONFIGURED", "The private media storage cannot sign reads: it has no signRead.");
+            const expiresAt = now() + expiresIn * 1000;
+            let variants;
+            try {
+                variants = await Promise.all(asset.variants.map(async ({ mimeType, role, storageKey }) => ({ mimeType, role, url: await storage.signRead({ storageKey, expiresIn }) })));
+            }
+            catch (error) {
+                throw own(error);
+            }
+            return { id, variants, expiresAt };
+        },
         async delete(id) {
             const asset = await get(id);
-            const failed = rejected(await removeAll(asset.variants));
+            const failed = rejected(await removeAll(asset.variants, storeOf(asset.visibility)));
             if (failed.length)
                 throw fail("PARTIAL_FAILURE", "Some objects could not be removed. Retry deleting the same asset.", { cause: new AggregateError(failed.map(r => r.reason)) });
             await driver.write([{ sql: `DELETE FROM media_assets WHERE id = ${p(1)}`, binds: [id] }]);
@@ -194,5 +255,66 @@ export function mediaLibrary(driver, d, storage, policies, now = Date.now) {
 }
 export function mediaItem(asset) {
     const primary = asset.variants.find(v => v.role === "primary") ?? asset.variants[0];
-    return { id: asset.id, variants: asset.variants, primaryUrl: primary?.publicUrl ?? null, mime: primary?.mimeType ?? null, byteSize: primary?.byteSize ?? null, alt: asset.alt ?? null, caption: asset.caption ?? null, createdAt: asset.createdAt };
+    return { id: asset.id, variants: asset.variants, primaryUrl: primary?.publicUrl ?? null, mime: primary?.mimeType ?? null, byteSize: primary?.byteSize ?? null, alt: asset.alt ?? null, caption: asset.caption ?? null, createdAt: asset.createdAt, ...(asset.visibility ? { visibility: asset.visibility } : {}) };
+}
+export const UPLOAD_META = "net.aotter.mantle/upload";
+export async function uploadMedia(library, policies, input, call) {
+    const { uploadId, sourceUrl, file, variants, purpose, filename, ...described } = input;
+    const present = (keys) => keys.filter(key => input[key] !== undefined);
+    if (uploadId !== undefined) {
+        if (present(["variants", "filename", "sourceUrl", "file"]).length)
+            throw bad("{ uploadId, purpose?, alt?, caption? }: filename, variants, sourceUrl and file belong to the first call");
+        return library.commitUpload(String(uploadId), { ...described, ...(purpose !== undefined ? { purpose } : {}) });
+    }
+    if (sourceUrl !== undefined || file !== undefined) {
+        if (present(["sourceUrl", "file", "variants"]).length > 1)
+            throw bad("one of variants, sourceUrl or file");
+        const policy = policies.find(p => p.name === purpose);
+        if (!policy)
+            throw fail("MEDIA_PURPOSE_REJECTED", `purpose '${String(purpose)}' is not declared`);
+        if (policy.required.length !== 1)
+            throw fail("MEDIA_VARIANTS_INCOMPLETE", `purpose '${policy.name}' takes ${policy.required.length} variants, and a fetched file is one: prepare the variants locally and send them as variants`);
+        const accepts = policy.required[0].split(",");
+        const url = sourceUrl ?? obj(file).download_url;
+        if (typeof url !== "string")
+            throw bad("sourceUrl: string, or file: { download_url, file_id }");
+        const fetched = await (await import("./media-fetch.js")).fetchImage(url, Math.max(...accepts.map(mime => policy.maxBytes[mime] ?? 0)));
+        if (!accepts.includes(fetched.mimeType))
+            throw fail("MEDIA_MIME_REJECTED", `the source is ${fetched.mimeType}; purpose '${policy.name}' takes ${accepts.join(" or ")}`);
+        const created = await library.createUpload({ ...described, purpose, filename: filename ?? fetched.filename, variants: [{ mimeType: fetched.mimeType, byteSize: fetched.bytes.byteLength, role: "primary" }] });
+        for (const target of created.capabilities) {
+            let status = 0;
+            try {
+                const response = await fetch(target.uploadUrl, { method: target.method, headers: target.requiredHeaders ?? {}, body: fetched.bytes });
+                status = response.status;
+                await response.body?.cancel();
+            }
+            catch { }
+            if (status < 200 || status > 299)
+                throw fail("MEDIA_STORAGE_FAILED", `storage did not accept the upload${status ? ` (${status})` : ""}; call upload_media again`);
+        }
+        return library.commitUpload(created.uploadGroupId);
+    }
+    if (variants !== undefined) {
+        const created = await library.createUpload(input);
+        const targets = created.capabilities.map(({ role, mimeType, method, uploadUrl, requiredHeaders }) => ({ role, mimeType, method, url: uploadUrl, headers: requiredHeaders ?? {} }));
+        const data = { uploadId: created.uploadGroupId, expiresAt: created.expiresAt };
+        return call.apps ? withResultMeta(data, { [UPLOAD_META]: { targets } }) : { ...data, targets };
+    }
+    if (present(["filename", "alt", "caption"]).length)
+        throw bad("variants, sourceUrl or file with filename, alt and caption");
+    const listed = policies.filter(p => purpose === undefined || p.name === purpose);
+    if (purpose !== undefined && !listed.length)
+        throw fail("MEDIA_PURPOSE_REJECTED", `purpose '${String(purpose)}' is not declared`);
+    return { purposes: listed, ...(call.apps ? { card: "The upload card is open: the person picks the file there, and the card reports the committed asset id." } : {}) };
+}
+export async function findMedia(library, input) {
+    const { ids, ...query } = input;
+    if (ids === undefined)
+        return library.list(query);
+    if (Object.values(query).some(value => value !== undefined) || !Array.isArray(ids) || ids.some(id => typeof id !== "string"))
+        throw bad("ids: string[] alone, or limit, cursor and search");
+    const found = await Promise.all([...new Set(ids)].map(id => library.get(id).catch(error => { if (error instanceof ContractError && (error.code === "MEDIA_ASSET_NOT_FOUND" || error.code === "MEDIA_NOT_OWNED"))
+        return id; throw error; })));
+    return { rows: found.filter(row => typeof row !== "string"), missing: found.filter(row => typeof row === "string") };
 }

package/dist/kernel/r2-media.d.ts

@@ -22,7 +22,7 @@ export interface R2Bucket {
 /** `aws4fetch`'s `AwsClient` has this shape. */
 export interface S3Signer {
     sign(url: string, init: {
-        method: "PUT";
+        method: "PUT" | "GET";
         aws: {
             signQuery: true;
             service: "s3";
@@ -36,7 +36,8 @@ export interface R2MediaStorageOptions {
     readonly signer: S3Signer;
     /** This bucket's S3 endpoint, e.g. `https://<bucket>.<account>.r2.cloudflarestorage.com`. */
     readonly endpoint: string;
-    readonly publicBase: string;
+    /** The bucket's public URL, or `null` for a private bucket: its variants then get no `publicUrl`, and reads go through `signRead`. */
+    readonly publicBase: string | null;
 }
 export declare function r2MediaStorage({ bucket, signer, endpoint, publicBase }: R2MediaStorageOptions): MediaStorage;
 export {};

package/dist/kernel/r2-media.js

@@ -6,20 +6,23 @@ const fail = (code, message, options) => mediaError(code, message, "media/r2", o
 const ext = (mimeType) => EXT[mimeType] ?? "bin";
 const cancel = (o) => o?.body.cancel().catch(() => undefined);
 export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
-    if (!publicBase)
-        throw fail("MEDIA_NOT_CONFIGURED", "R2 media storage needs publicBase, the bucket's public URL");
-    const base = publicBase.replace(/\/+$/, "");
+    if (!publicBase && publicBase !== null)
+        throw fail("MEDIA_NOT_CONFIGURED", "R2 media storage needs publicBase, the bucket's public URL, or null for a private bucket");
+    const base = publicBase?.replace(/\/+$/, "");
     const s3 = endpoint.replace(/\/+$/, "");
+    const signed = async (method, storageKey, seconds) => {
+        const target = new URL(`${s3}/${storageKey}`);
+        target.searchParams.set("X-Amz-Expires", String(seconds));
+        return (await signer.sign(target.href, { method, aws: { signQuery: true, service: "s3" } })).url;
+    };
     return {
+        uploadOrigin: new URL(s3).origin,
         async createUpload({ uploadGroupId, purpose, variants, now, expiresAt }) {
             const ttl = Math.max(60, Math.floor((expiresAt - now) / 1000));
             return {
                 capabilities: await Promise.all(variants.map(async (v) => {
                     const storageKey = `${UPLOADS}${purpose}/${uploadGroupId}/${v.role}.${ext(v.mimeType)}`;
-                    const target = new URL(`${s3}/${storageKey}`);
-                    target.searchParams.set("X-Amz-Expires", String(ttl));
-                    const { url } = await signer.sign(target.href, { method: "PUT", aws: { signQuery: true, service: "s3" } });
-                    return { mimeType: v.mimeType, role: v.role, method: "PUT", uploadUrl: url, storageKey, requiredHeaders: { "Content-Type": v.mimeType } };
+                    return { mimeType: v.mimeType, role: v.role, method: "PUT", uploadUrl: await signed("PUT", storageKey, ttl), storageKey, requiredHeaders: { "Content-Type": v.mimeType } };
                 })),
             };
         },
@@ -45,7 +48,7 @@ export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
                         await cancel(o);
                         throw fail("MEDIA_OBJECT_NOT_FOUND", `variant ${spec.role} of '${uploadGroupId}' changed during commit`);
                     }
-                    out.push({ mimeType: spec.mimeType, publicUrl: `${base}/${key}`, storageKey: key, byteSize: o.size, role: spec.role });
+                    out.push({ mimeType: spec.mimeType, ...(base === undefined ? {} : { publicUrl: `${base}/${key}` }), storageKey: key, byteSize: o.size, role: spec.role });
                     try {
                         await bucket.put(key, o.body, {
                             httpMetadata: { contentType: spec.mimeType },
@@ -67,5 +70,6 @@ export function r2MediaStorage({ bucket, signer, endpoint, publicBase }) {
             return { id: uploadGroupId, variants: out, createdAt: now, metadata: { filename }, ...(alt !== undefined ? { alt } : {}), ...(caption !== undefined ? { caption } : {}) };
         },
         deleteObject: ({ storageKey }) => bucket.delete(storageKey),
+        signRead: ({ storageKey, expiresIn }) => signed("GET", storageKey, expiresIn),
     };
 }

package/dist/kernel/result-meta.d.ts

@@ -0,0 +1,10 @@
+/** What `withResultMeta` returns: `data` is the tool result as usual, `_meta` goes only to the `tools/call` result `_meta`. */
+export interface ResultWithMeta<T> {
+    readonly data: T;
+    readonly _meta: Readonly<Record<string, unknown>>;
+}
+/**
+ * Returned from a tool's `run`: MCP sends `data` exactly as an unwrapped return, and `meta` only in the result `_meta`
+ * (beside `net.aotter.mantle/tool`, which it cannot replace). `callTool` returns the wrapper itself; drop `_meta` before forwarding to a model.
+ */
+export declare const withResultMeta: <T>(data: T, meta: Readonly<Record<string, unknown>>) => ResultWithMeta<T>;

package/dist/kernel/result-meta.js

@@ -0,0 +1 @@
+export const withResultMeta = (data, meta) => ({ [Symbol.for("net.aotter.mantle/result")]: true, data, _meta: meta });

package/dist/kernel/site-types.d.ts

@@ -9,6 +9,13 @@ export interface MediaPurposePolicy {
     readonly name: string;
     readonly required: readonly string[];
     readonly maxBytes: Readonly<Record<string, number>>;
+    /**
+     * `"public"` (the default when omitted) stores this purpose's assets in the public storage, each variant with a
+     * permanent `publicUrl`. `"private"` stores them in the `private` storage of the `media` option and gives them no
+     * URL on any surface; read one through `MediaLibrary.signRead` or `MediaStorage.signRead`. A purpose's visibility
+     * does not change: moving it means moving its objects.
+     */
+    readonly visibility?: "public" | "private";
 }
 export interface SiteDefaults {
     readonly brand?: string;
@@ -42,13 +49,17 @@ export interface MantleSite {
     /** Stored operator values over generated defaults; deployment fields are code constants. */
     read(): Promise<SiteConfig>;
     updateSettings(values: SiteSettings): Promise<SiteConfig>;
-    /** The media library over this site's tables, its objects in `storage`. */
-    media(storage: MediaStorage): MediaLibrary;
+    /**
+     * The media library over this site's tables, its objects in `storage`. A private purpose with no private storage is
+     * `MEDIA_NOT_CONFIGURED` here.
+     */
+    media(storage: MediaStorageOption): MediaLibrary;
 }
 export type MediaVariantRole = "primary" | "alternate" | "fallback";
 export interface MediaVariant {
     readonly mimeType: string;
-    readonly publicUrl: string;
+    /** Absent on a private asset. */
+    readonly publicUrl?: string;
     readonly storageKey: string;
     readonly byteSize: number;
     readonly role: MediaVariantRole;
@@ -61,9 +72,21 @@ export interface MediaAsset {
     readonly caption?: string;
     readonly createdAt: number;
     readonly metadata?: Readonly<Record<string, string>>;
+    /** `"private"` when the asset's purpose is private: its variants have no `publicUrl`. Absent means public. */
+    readonly visibility?: "private";
 }
-/** Object storage for media, public bucket only. The bytes go to `uploadUrl` directly, never through the Worker. */
+/**
+ * The `media` option: one `MediaStorage`, which holds every purpose's objects and serves them publicly, or a public
+ * and a private storage. Private purposes go to `private`.
+ */
+export type MediaStorageOption = MediaStorage | {
+    readonly public: MediaStorage;
+    readonly private: MediaStorage;
+};
+/** Object storage for media. The bytes go to `uploadUrl` directly, never through the Worker. */
 export interface MediaStorage {
+    /** The origin every `uploadUrl` PUTs to, such as the bucket's S3 endpoint: what an MCP App that uploads declares in its CSP `connectDomains`. */
+    readonly uploadOrigin?: string;
     /** One short-lived PUT capability per variant, keyed under `uploadGroupId`. */
     createUpload(args: {
         readonly uploadGroupId: string;
@@ -109,6 +132,17 @@ export interface MediaStorage {
     deleteObject(args: {
         readonly storageKey: string;
     }): Promise<void>;
+    /**
+     * A short-lived read URL for one committed object, valid for `expiresIn` seconds. Optional; a private storage
+     * implements it so its assets can be read at all. Mantle calls it only from `MediaLibrary.signRead`: no list, get or
+     * commit signs anything. An application that lets other callers read a private asset calls it itself, after its own
+     * check (for example in a `ref` handler), with a `storageKey` from the asset's variants. A signed URL is a bearer
+     * capability: an MCP tool returns it only in the result `_meta` (`withResultMeta`), never in model-visible content.
+     */
+    signRead?(args: {
+        readonly storageKey: string;
+        readonly expiresIn: number;
+    }): Promise<string>;
 }
 /** The media use cases. Each checks its own input, so any surface can hand it a request body. */
 export interface MediaLibrary {
@@ -124,9 +158,9 @@ export interface MediaLibrary {
         }[];
         readonly expiresAt: number;
     }>;
-    /** An unknown or expired group is `MEDIA_UPLOAD_EXPIRED`. */
+    /** An unknown or expired group is `MEDIA_UPLOAD_EXPIRED`; one another server created is `MEDIA_NOT_OWNED`, as is its asset id in the calls below. */
     commitUpload(uploadGroupId: string, request?: unknown): Promise<MediaAsset>;
-    /** Newest first; `search` matches id, alt and caption. */
+    /** Newest first; `search` matches the exact id, or text in alt or caption. */
     list(query: {
         readonly limit?: number;
         readonly cursor?: string;
@@ -138,6 +172,20 @@ export interface MediaLibrary {
     get(id: string): Promise<MediaAsset>;
     /** `{ alt?, caption? }`: an omitted field is unchanged, an empty string clears it. */
     update(id: string, request: unknown): Promise<MediaAsset>;
+    /**
+     * Read URLs for each variant: a public asset's `publicUrl`, or a private asset's `MediaStorage.signRead` URL valid
+     * for `expiresIn` seconds (default 300), with `expiresAt` in milliseconds. A private storage without `signRead` is
+     * `MEDIA_NOT_CONFIGURED`.
+     */
+    signRead(id: string, expiresIn?: number): Promise<{
+        readonly id: string;
+        readonly variants: readonly {
+            readonly mimeType: string;
+            readonly role: MediaVariantRole;
+            readonly url: string;
+        }[];
+        readonly expiresAt?: number;
+    }>;
     /** The objects first, then the row, so a partial failure can be retried with the same id. */
     delete(id: string): Promise<{
         readonly deleted: true;

package/dist/kernel/site.d.ts

@@ -3,7 +3,7 @@ import { type Caller } from "./contracts.js";
 import { type MediaDatabase } from "./media.js";
 import type { Dialect } from "./dialect/common.js";
 import type { MantleSite, SiteDefaults, SiteConfig, MediaPurposePolicy } from "./site-types.js";
-export type { MantleSite, SiteDefaults, SiteConfig, MediaStorage, MediaAsset, MediaLibrary, MediaPurposePolicy } from "./site-types.js";
+export type { MantleSite, SiteDefaults, SiteConfig, MediaStorage, MediaStorageOption, MediaAsset, MediaLibrary, MediaPurposePolicy } from "./site-types.js";
 export declare function createSite(db: MediaDatabase, d: Pick<Dialect, "param" | "escapeLike" | "likeEscape" | "like">, caller: Caller, defaults: SiteDefaults, policies: readonly MediaPurposePolicy[]): MantleSite;
 /** 0.2 /admin/api/site projection; the app supplies its selected capabilities. */
 export declare function siteInfo(config: SiteConfig, options: {

package/dist/usecase/generate.js

@@ -15,7 +15,7 @@ import { refuseDeclarations } from "./refusals.js";
 import { emitHandlers } from "./handlers.js";
 import { emitAdminDescriptors } from "./adminDescriptors.js";
 import { emitAdminClient } from "./adminClient.js";
-import { emitSite } from "./site.js";
+import { emitSite, mediaPolicies } from "./site.js";
 import { emitTranslations } from "./translations.js";
 import { emitAdminBindings } from "./adminBindings.js";
 import { emitRest } from "./rest.js";
@@ -144,7 +144,7 @@ export function generate(input) {
     emitTtl(plan, isSqlite, declarations, procedures, entries, refuse);
     emitPublishing(plan, isSqlite, declarations, procedures, entries, values, refuse, input.locks);
     const stores = emitStores(plan.schemas, isSqlite, newId, refuse, hasHandlers, input.locks);
-    const surfaces = { ...emitPaging(plan, lowered, target, refuse, paging), ...emitPaging(plan, input.wireLowered ?? lowered, target, refuse, paging, true), ...emitValidation(plan, refuse), ...emitRest(plan, lowered, target, input.description), ...emitWeb(plan, lowered, target), ...emitMcp(plan, lowered, target, input.description, refuse, !!site), ...emitAdminDescriptors({ plan, admin }, diagnostics), ...emitAdminBindings(input, refuse), ...(admin ? emitAdminClient(plan, typeOf) : {}), ...emitSite(target, site, refuse, Object.keys(plan.schemas)), ...emitTranslations(plan, target) };
+    const surfaces = { ...emitPaging(plan, lowered, target, refuse, paging), ...emitPaging(plan, input.wireLowered ?? lowered, target, refuse, paging, true), ...emitValidation(plan, refuse), ...emitRest(plan, lowered, target, input.description), ...emitWeb(plan, lowered, target), ...emitMcp(plan, lowered, target, input.description, refuse, site ? mediaPolicies(site) : undefined), ...emitAdminDescriptors({ plan, admin }, diagnostics), ...emitAdminBindings(input, refuse), ...(admin ? emitAdminClient(plan, typeOf) : {}), ...emitSite(target, site, refuse, Object.keys(plan.schemas)), ...emitTranslations(plan, target) };
     if (diagnostics.length)
         return { ok: false, diagnostics };
     const storeProcedures = hasHandlers ? "storeProcedures" : "procedures";

package/dist/usecase/mcp-media.js

@@ -1,15 +1,27 @@
 import { emitValidation } from "./validation.js";
 import { mediaDefinitions } from "../domain/generated-tools.js";
 export { mediaDefinitions };
+const library = "site(db,caller).media(storage())";
+const invoke = {
+    upload: `(db,caller,input:Record<string,unknown>,_handlers:unknown,call:ToolCall) => uploadMedia(${library},policies,input,call)`,
+    find: `(db,caller,input:Record<string,unknown>) => findMedia(${library},input)`,
+    policy: 'async (db,caller) => ({purposes:(await site(db,caller).read()).media.purposes})',
+    create: `(db,caller,input:Record<string,unknown>) => ${library}.createUpload(input)`,
+    commit: `(db,caller,input:Record<string,unknown>) => ${library}.commitUpload(input.uploadGroupId as string,input)`,
+    list: `(db,caller,input:Record<string,unknown>) => ${library}.list(input)`,
+    get: `(db,caller,input:Record<string,unknown>) => ${library}.get(input.id as string)`,
+    update: `(db,caller,input:Record<string,unknown>) => ${library}.update(input.id as string,input)`,
+    delete: `(db,caller,input:Record<string,unknown>) => ${library}.delete(input.id as string)`,
+};
 export function emitMcpMedia(definitions, refuse) {
     const inputs = Object.fromEntries(definitions.map(tool => [tool.name, { input: tool.inputSchema }]));
     const checks = Object.fromEntries(Object.entries(emitValidation({ views: {}, procedures: inputs }, refuse)).map(([path, code]) => [path.replace("validation/procedures/", "validation/media/"), code]));
-    const invoke = { policy: 'async (db,caller) => ({purposes:(await site(db,caller).read()).media.purposes})', create: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).createUpload(input)', commit: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).commitUpload(input.uploadGroupId as string,input)', list: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).list(input)', get: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).get(input.id as string)', update: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).update(input.id as string,input)', delete: '(db,caller,input:Record<string,unknown>) => site(db,caller).media(storage()).delete(input.id as string)' };
-    return { ...checks, "mcp-media.ts": `import { site } from "./site.js";
-import type { MediaStorage } from "@aotter/mantle/site";
-import type { Tool } from "@aotter/mantle/mcp";
+    return { ...checks, "mcp-media.ts": `import { policies, site } from "./site.js";
+import type { MediaStorageOption } from "@aotter/mantle/site";
+import { findMedia, uploadMedia } from "@aotter/mantle/media";
+import type { Tool, ToolCall } from "@aotter/mantle/mcp";
 ${definitions.map((tool, i) => `import { validate as v${i} } from "./validation/media/${tool.name}.js";`).join("\n")}
-export function mediaTools<Handlers = never>(storage: () => MediaStorage): Tool<Parameters<typeof site>[0], Handlers>[] { return [
+export function mediaTools<Handlers = never>(storage: () => MediaStorageOption): Tool<Parameters<typeof site>[0], Handlers>[] { return [
 ${definitions.map(({ action, ...tool }, i) => `{...${JSON.stringify({ ...tool, ...(tool.annotations.readOnlyHint ? { readOnly: true } : {}) })},surface:"admin",closed:true,validate:v${i},run:${invoke[action]}}`).join(",\n")}
 ]; }
 ` };

package/dist/usecase/mcp.js

@@ -6,13 +6,14 @@ import { authLines, conversions } from "../domain/input.js";
 import { publishingAnnotations, publishingInput } from "./publishing.js";
 import { versioned } from "./tool-version.js";
 import { boundaryPage, outputConversions } from "../domain/columns.js";
-export function emitMcp(plan, lowered, target, description, refuse, media = false) {
+export function emitMcp(plan, lowered, target, description, refuse, policies) {
+    const media = !!policies;
     if (!Object.values(plan.views).some(view => view.surface !== "internal") && !Object.values(plan.triggers).some(trigger => trigger.source.kind === "mcp"))
         return {};
     const reads = [];
     const imports = plan.access ? ['import { userBinds } from "@aotter/mantle/user-fields";'] : [], tools = [];
-    const mediaTools = media ? mediaDefinitions().map(({ action, ...tool }) => ({ action, ...versioned({ ...tool, title: toolTitle(tool.name) }) })) : [];
-    const files = media ? emitMcpMedia(mediaTools, refuse) : {};
+    const mediaTools = policies ? mediaDefinitions(policies).map(({ action, ...tool }) => { const { meta, ...listed } = tool; return { action, ...versioned({ ...listed, title: toolTitle(tool.name) }), ...(meta ? { meta } : {}) }; }) : [];
+    const files = policies ? emitMcpMedia(mediaTools, refuse) : {};
     let hasRef = false, hasWire = false;
     const names = new Set(mediaTools.map(tool => "admin:" + tool.name));
     const guard = (requires, path, binds = [], trustedOnly = false) => {
@@ -81,10 +82,10 @@ export function emitMcp(plan, lowered, target, description, refuse, media = fals
         if (count > 1 && schema)
             shared.set(schema, `schema${shared.size}`);
     return { ...files, "mcp.ts": `${[`import { mcp as serve, type Options as McpOptions, type Tool } from "@aotter/mantle/mcp";`, databaseImport(target),
-            ...(media ? ['import type { MediaStorage } from "@aotter/mantle/site";'] : []),
+            ...(media ? ['import type { MediaStorageOption } from "@aotter/mantle/site";'] : []),
             'import type { Handlers } from "./generated.js";', ...(hasRef ? ['import { store } from "./generated.js";'] : []), ...imports,
             ...[...shared].map(([schema, name]) => `const ${name} = ${schema};`)].join("\n")}
-export type Options<Env = unknown> = McpOptions<Env, Database> & { handlers${refs ? "" : "?"}: Handlers }${media ? " & { media?: (env: Env) => MediaStorage }" : ""};
+export type Options<Env = unknown> = McpOptions<Env, Database> & { handlers${refs ? "" : "?"}: Handlers }${media ? " & { media?: (env: Env) => MediaStorageOption }" : ""};
 /** The generated tools, exported so an app can compose them with its own tools and MCP Apps. */
 export const tools: readonly Tool<Database, Handlers>[] = [
 ${tools.map(({ fields, schema }) => `  { ${fields.map(field => field === "inputSchema" ? `inputSchema: ${shared.get(schema) ?? schema}` : field).join(", ")} },`).join("\n")}

package/dist/usecase/site.js

@@ -1,5 +1,6 @@
 import { assertSiteDefaultsCanonical, canonicalizeLocaleList, expandPolicyRequired } from "../build/compiler.js";
 import { driverFor, isSqlite, q } from "../domain/entry.js";
+export const mediaPolicies = (defaults) => defaults?.media?.purposes?.map(p => ({ ...p, required: expandPolicyRequired(p.required).map(slot => slot.join(",")) })) ?? [];
 export function emitSite(target, defaults, refuse, schemaNames) {
     if (!defaults)
         return {};
@@ -17,7 +18,7 @@ export function emitSite(target, defaults, refuse, schemaNames) {
         refuse("site/media/purposes", "Media purpose names must be unique.");
     defaults = { ...defaults, ...(defaults.locales ? { locales: canonicalizeLocaleList(defaults.locales).valid } : {}) };
     const pg = !isSqlite(target), driver = driverFor(target);
-    const policies = defaults.media?.purposes?.map(p => ({ ...p, required: expandPolicyRequired(p.required).map(slot => slot.join(",")) })) ?? [];
+    const policies = mediaPolicies(defaults);
     const seed = ["brand", "title", "description"].filter(key => defaults[key]).map(key => `INSERT INTO site_config (key,value) VALUES ('${key}','${defaults[key].replaceAll("'", "''")}') ON CONFLICT(key) DO NOTHING;`).join("\n");
     const root = "@aotter/mantle";
     return { "site.ts": `import { createSite } from "${root}/site";
@@ -26,7 +27,8 @@ import type { ${pg ? "Postgres" : "Handle"} as Database } from "${root}/${pg ? "
 import * as DRIVER from "${root}/driver/${driver}";
 import { param, escapeLike, likeEscape, like } from "${root}/dialect/${pg ? "postgres" : "sqlite"}";
 export const siteDefaults = ${q(defaults)} as const;
-const policies = ${q(policies)} as const;
+/** The site's media purposes, expanded; the library and upload_media check against them. */
+export const policies = ${q(policies)} as const;
 export function site(db: Database, caller: Caller) { return createSite({read:(sql,values)=>DRIVER.read(db,sql,values),write:steps=>DRIVER.procedure(db,steps,"site"),definitive:DRIVER.definitive},{param,escapeLike,likeEscape,like},caller,siteDefaults,policies); }
 `, "site-seed.sql": seed + "\n", "site-schema.sql": `CREATE TABLE site_config (key TEXT PRIMARY KEY, value TEXT NOT NULL);
 CREATE TABLE media_assets (id TEXT PRIMARY KEY, created_at ${pg ? "BIGINT" : "INTEGER"} NOT NULL, owner_id TEXT, alt TEXT, caption TEXT, variants TEXT NOT NULL, metadata TEXT);