app/lib/operator/upload-media.server.ts

Functions

Imports

It imports app/lib/bytes.mjs, app/lib/error-message.mjs, app/lib/media/upload-contract.mjs, app/lib/media/upload.server.ts, app/lib/operator/auth.server.ts, app/lib/operator/descriptors.ts. Imported by app/lib/operator/api.server.ts.

Source

1import { ALLOWED, MAX_BYTES, uploadSuccessBody } from "~/lib/media/upload-contract.mjs";
2import { storeUpload } from "~/lib/media/upload.server";
3import { errorMessage } from "~/lib/error-message.mjs";
4import { readCappedBytes } from "@dustinedwards/site-runtime/body";
5import { base64ToBytes } from "~/lib/bytes.mjs";
6import type { OperatorEnv } from "./auth.server";
7import type { ToolResult } from "./descriptors";
8
9// The bytes and the resolved type, or the refusal to send back as the tool's answer.
10type Sourced = { ok: true; bytes: Uint8Array; type: string } | Extract<ToolResult, { ok: false }>;
11
12// Base64 only: silently mis-decoding a percent-encoded URI would store rubbish under a valid-looking digest.
13function readDataUri(value: string): { type: string; payload: string } | null {
14  const match = /^data:([^;,]*)(;base64)?,/i.exec(value);
15  if (!match) return null;
16  if (!match[2]) return null;
17  return { type: (match[1] ?? "").toLowerCase(), payload: value.slice(match[0].length) };
18}
19
20function decodeBase64(payload: string): Uint8Array | null {
21  // Null rather than a throw: the caller answers the agent that sent it with a 400 that says why.
22  try {
23    return base64ToBytes(payload);
24  } catch {
25    return null;
26  }
27}
28
29function defaultName(type: string, url: string): string {
30  if (url) {
31    try {
32      const base = new URL(url).pathname.split("/").filter(Boolean).pop();
33      if (base) return decodeURIComponent(base);
34    } catch {
35      // Unreachable: the protocol was already checked. Caught rather than thrown from a naming helper.
36    }
37  }
38  const extension = ALLOWED.get(type);
39  // Never stored: a type outside the allowlist is refused next. `upload.bin` would be a substitution.
40  return extension ? `upload.${extension}` : "upload";
41}
42
43function bytesFromData(data: string, declaredType: string): Sourced {
44  let type = declaredType;
45  const uri = readDataUri(data);
46  if (data.startsWith("data:") && !uri) {
47    return {
48      ok: false,
49      status: 400,
50      error:
51        "`data` looks like a data: URI but is not base64-encoded. Send " +
52        "`data:<type>;base64,<payload>` or bare base64.",
53    };
54  }
55
56  if (!type && uri) type = uri.type;
57
58  // Refused on the encoded length before `atob` allocates. Generous: `validateUpload` states the real limit.
59  const packedLength = (uri ? uri.payload : data).replace(/\s+/g, "").length;
60  if (packedLength > Math.ceil(MAX_BYTES / 3) * 4 + 4) {
61    return {
62      ok: false,
63      status: 413,
64      error:
65        `That base64 payload decodes to more than the ` +
66        `${MAX_BYTES / (1024 * 1024)} MB limit. Upload it with \`url\` instead.`,
67    };
68  }
69
70  const decoded = decodeBase64(uri ? uri.payload : data);
71  if (!decoded) {
72    return { ok: false, status: 400, error: "`data` is not valid base64." };
73  }
74  return { ok: true, bytes: decoded, type };
75}
76
77async function bytesFromUrl(url: string, declaredType: string): Promise<Sourced> {
78  let type = declaredType;
79  let parsed: URL;
80  try {
81    parsed = new URL(url);
82  } catch {
83    return { ok: false, status: 400, error: `\`url\` is not a URL: ${JSON.stringify(url)}.` };
84  }
85  if (parsed.protocol !== "https:") {
86    return {
87      ok: false,
88      status: 400,
89      error: `upload_media fetches https only, not ${parsed.protocol.replace(":", "")}.`,
90    };
91  }
92
93  let response: Response;
94  try {
95    response = await fetch(parsed, { headers: { accept: "image/*" } });
96  } catch (error) {
97    return {
98      ok: false,
99      status: 502,
100      error: `Fetching ${parsed.href} failed: ${errorMessage(error)}`,
101    };
102  }
103  // Checked again where it LANDED: `fetch` follows redirects, and https may redirect to http.
104  let landed = "";
105  try {
106    landed = new URL(response.url || parsed.href).protocol;
107  } catch {
108    landed = "";
109  }
110  if (landed !== "https:") {
111    return {
112      ok: false,
113      status: 400,
114      error:
115        `${parsed.href} redirected to ${response.url || "somewhere unparseable"}, ` +
116        `which is not https. upload_media fetches https only, redirects included.`,
117    };
118  }
119
120  if (!response.ok) {
121    return {
122      ok: false,
123      status: 502,
124      error: `${parsed.href} answered ${response.status}.`,
125    };
126  }
127  if (!response.body) {
128    return { ok: false, status: 502, error: `${parsed.href} answered with no body.` };
129  }
130
131  const read = await readCappedBytes(response, MAX_BYTES);
132  if (!read) {
133    return {
134      ok: false,
135      status: 413,
136      error:
137        `${parsed.href} is over the ${MAX_BYTES / (1024 * 1024)} MB limit; the ` +
138        `download was abandoned.`,
139    };
140  }
141
142  // Split on `;`: a charset parameter is normal, and the allowlist holds bare types.
143  if (!type) {
144    type = (response.headers.get("content-type") ?? "").split(";")[0]?.trim().toLowerCase() ?? "";
145  }
146  return { ok: true, bytes: read, type };
147}
148
149// An adapter: `storeUpload` is the write. The token and rate limiter are the primary control; HTTPS only,
150// a capped read and `validateUpload` are secondary. The declared type wins because good PNGs are often
151// served as octet-stream, and it is still checked against the allowlist and the bytes.
152export async function uploadMediaTool(
153  env: OperatorEnv,
154  args: Record<string, unknown>,
155): Promise<ToolResult> {
156  const data = typeof args.data === "string" ? args.data.trim() : "";
157  const url = typeof args.url === "string" ? args.url.trim() : "";
158  const declaredType = typeof args.type === "string" ? args.type.trim().toLowerCase() : "";
159  const declaredName = typeof args.name === "string" ? args.name.trim() : "";
160
161  // Both sources is refused, not resolved: picking one could store the wrong image under a valid digest.
162  if (data && url) {
163    return {
164      ok: false,
165      status: 400,
166      error: "upload_media takes `data` or `url`, never both. Send one.",
167    };
168  }
169  if (!data && !url) {
170    return {
171      ok: false,
172      status: 400,
173      error:
174        "upload_media needs either `data` (base64 bytes or a data: URI) or " +
175        "`url` (an https URL this API will fetch).",
176    };
177  }
178
179  const source = data ? bytesFromData(data, declaredType) : await bytesFromUrl(url, declaredType);
180  if (!source.ok) return source;
181  const { bytes, type } = source;
182
183  // A fresh ArrayBuffer, not `bytes.buffer`: that is the whole allocation, not the view, so a later change
184  // to a producer could hash and store the wrong bytes.
185  const payload = new ArrayBuffer(bytes.byteLength);
186  new Uint8Array(payload).set(bytes);
187
188  const stored = await storeUpload(env, {
189    bytes: payload,
190    type,
191    name: declaredName || defaultName(type, url),
192  });
193
194  if (!stored.ok) {
195    return { ok: false, status: stored.status, error: stored.message, detail: { code: stored.code } };
196  }
197
198  return {
199    ok: true,
200    data: {
201      // The editor's own builder, so the string an agent puts in markdown is the one the editor inserts.
202      ...uploadSuccessBody(stored.key),
203      bytes: stored.bytes,
204      width: stored.width,
205      height: stored.height,
206      // `false` means the object landed and the row did not; `sync_media` re-derives it.
207      recorded: stored.recorded,
208    },
209  };
210}