@aexol/spectral 0.9.212 → 0.9.216

package/dist/backend/generated-images.d.ts

@@ -0,0 +1,180 @@
+/**
+ * Backend-hosted image storage client.
+ *
+ * Uploads raw image bytes to the Aexol backend so that sessions only ever
+ * carry a stable URL (`/generated-images/<imageId>`) instead of a base64
+ * payload. The three-step contract is:
+ *
+ *   1. `POST  {backendUrl}/generated-images/upload-url`
+ *      -> `{ imageId, uploadUrl, url, expiresIn, requiredHeaders? }`
+ *   2. `PUT   <uploadUrl>` (presigned, ~600s)
+ *      with `Content-Type` + every header from `requiredHeaders`
+ *   3. `POST  {backendUrl}/generated-images/<imageId>/confirm`
+ *      -> `{ id, size, url }`
+ *
+ * Downloading works the other way round and has two flavours:
+ *
+ *   A. `GET  {backendUrl}/generated-images/<imageId>` (authenticated)
+ *      -> 302 redirect to a short-lived presigned S3 GET.
+ *   B. `GET  {backendUrl}/generated-images/<imageId>/url`
+ *      (authenticated) -> `{ url, expiresIn }` where `url` is a presigned
+ *      S3 GET that needs NO headers at all.
+ *
+ * Flavour B is the one to hand to a third party that cannot authenticate
+ * against our backend (an LLM provider fetching an image, an `<img src>`,
+ * ...). See `resolveHostedImageUrl`.
+ *
+ * Errors from the backend have the shape
+ * `{ "error": { "message": "...", "type": "..." } }` and are surfaced as a
+ * `GeneratedImageUploadError` carrying the HTTP status and the step that
+ * failed, so callers can decide whether to degrade gracefully.
+ *
+ * Shared by `image_generate` (Phase 1) and — in a later phase — user
+ * screenshots/attachments, hence `kind` is a parameter rather than a constant.
+ *
+ * @module @spectral/backend/generated-images
+ */
+export type GeneratedImageKind = "generated" | "attachment";
+export type UploadStep = "upload-url" | "put" | "confirm";
+export interface UploadImageOptions {
+    /** Backend base url, e.g. `https://api.aexol.ai` (no trailing slash needed). */
+    backendUrl: string;
+    /** Machine JWT (`Authorization: Bearer <token>`). */
+    token: string;
+    /** Raw image bytes. */
+    bytes: Uint8Array;
+    /** MIME type of the bytes, e.g. `image/png`. */
+    contentType: string;
+    /** Storage bucket/kind on the backend. Defaults to `"generated"`. */
+    kind?: GeneratedImageKind;
+    /** Intrinsic pixel width, when known (optional metadata). */
+    width?: number;
+    /** Intrinsic pixel height, when known (optional metadata). */
+    height?: number;
+    /** Injectable for tests / alternative runtimes. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Abort the whole sequence (e.g. tool cancellation). */
+    signal?: AbortSignal;
+    /** Per-request timeout. Defaults to 60s. */
+    timeoutMs?: number;
+}
+export interface UploadImageResult {
+    imageId: string;
+    /** Backend-relative url (`/generated-images/<imageId>`) — safe to persist in a session. */
+    url: string;
+    size: number;
+}
+export interface UploadUrlResponse {
+    imageId: string;
+    uploadUrl: string;
+    url: string;
+    expiresIn?: number;
+    requiredHeaders?: Record<string, string>;
+}
+export interface ConfirmResponse {
+    id: string;
+    size: number;
+    url: string;
+}
+export interface ResolveHostedImageUrlOptions {
+    /** Backend base url, e.g. `https://api.aexol.ai`. */
+    backendUrl: string;
+    /** Machine JWT (`Authorization: Bearer <token>`). */
+    token: string;
+    /** Image id. Optional when `url` is given (it is parsed from there). */
+    imageId?: string;
+    /** Backend-relative (`/generated-images/<id>`) or absolute hosted url. */
+    url?: string;
+    /** Injectable for tests / alternative runtimes. Defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    signal?: AbortSignal;
+    /** Per-request timeout. Defaults to 60s. */
+    timeoutMs?: number;
+    /** Diagnostics sink — failures are silent unless this is provided. */
+    onWarn?: (message: string) => void;
+}
+export interface HostedImageUrlResult {
+    /**
+     * Presigned S3 GET url that is fetchable WITHOUT any Authorization header.
+     * Valid for `expiresIn` seconds (typically 3600).
+     */
+    url: string;
+    expiresIn: number;
+}
+/**
+ * Extract the hosted image id from a backend-relative path
+ * (`/generated-images/<id>`) or from an absolute url
+ * (`https://api.aexol.ai/generated-images/<id>?x=1`).
+ *
+ * Only the PATH is inspected: a query/fragment that happens to contain
+ * `/generated-images/<id>` does not make the url one of ours.
+ *
+ * Returns `null` when the value is not a hosted backend image reference, so
+ * callers can use it as a cheap "is this ours?" predicate.
+ */
+export declare function extractHostedImageId(urlOrPath: string): string | null;
+/**
+ * The hosted image id carried by `url`, or `null` when `url` is not a hosted
+ * backend image reference. Alias of `extractHostedImageId` kept for callers
+ * that read better with a url-oriented name.
+ */
+export declare function hostedImageIdFromUrl(url: string): string | null;
+/**
+ * True when `url` points at a backend-hosted image
+ * (`/generated-images/<id>`), either backend-relative or absolute.
+ *
+ * SECURITY: an absolute url is only "ours" when it actually points at OUR
+ * backend. `backendUrl` is therefore REQUIRED for absolute urls — without it
+ * there is nothing to compare against and the answer is `false`, so callers
+ * never attach the machine JWT to a host they cannot vouch for. Relative urls
+ * always match (they can only ever be resolved against the backend base url).
+ */
+export declare function isHostedImageUrl(url: string, backendUrl?: string): boolean;
+/**
+ * Drop cached presigned urls. Omit `imageId` to clear the whole cache (used
+ * by tests and after a logout/credential change).
+ */
+export declare function invalidateHostedImageUrl(imageId?: string, backendUrl?: string): void;
+/**
+ * Turn a hosted image reference into a presigned url that a third party (LLM
+ * provider, browser) can fetch WITHOUT authenticating against our backend.
+ *
+ * `GET {backendUrl}/generated-images/<id>/url` with the machine JWT returns
+ * `{ url, expiresIn }`; the plain `GET /generated-images/<id>` endpoint is
+ * auth-gated and 302-redirects, so handing it to a provider only produces a
+ * 401 and a silently dropped image.
+ *
+ * Results are cached per `<backendUrl>|<imageId>` until
+ * `PRESIGNED_REFRESH_MARGIN_MS` before their expiry (see
+ * `invalidateHostedImageUrl`), so repeated requests for the same image do not
+ * each pay a round trip.
+ *
+ * NEVER throws and never logs: returns `null` on any failure (missing token,
+ * non-2xx, network error, malformed body) so callers can fall back to their
+ * previous behaviour. Pass `onWarn` to see why.
+ */
+export declare function resolveHostedImageUrl(options: ResolveHostedImageUrlOptions): Promise<HostedImageUrlResult | null>;
+/**
+ * Thrown for every failure of the upload sequence (including presigned PUT
+ * failures). `status` is `undefined` for network-level errors.
+ */
+export declare class GeneratedImageUploadError extends Error {
+    readonly step: UploadStep;
+    readonly status?: number;
+    readonly type?: string;
+    constructor(message: string, options: {
+        step: UploadStep;
+        status?: number;
+        type?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Upload raw image bytes to backend storage and confirm them.
+ *
+ * @returns the image id, the backend-relative url and the confirmed byte size.
+ * @throws {GeneratedImageUploadError} on any HTTP or network failure, with a
+ *   human-readable message taken from the backend `error.message` when present.
+ */
+export declare function uploadImage(options: UploadImageOptions): Promise<UploadImageResult>;
+//# sourceMappingURL=generated-images.d.ts.map

package/dist/backend/generated-images.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-images.d.ts","sourceRoot":"","sources":["../../src/backend/generated-images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAEH,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,YAAY,CAAC;AAE5D,MAAM,MAAM,UAAU,GAAG,YAAY,GAAG,KAAK,GAAG,SAAS,CAAC;AAE1D,MAAM,WAAW,kBAAkB;IAClC,gFAAgF;IAChF,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,uBAAuB;IACvB,KAAK,EAAE,UAAU,CAAC;IAClB,gDAAgD;IAChD,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,IAAI,CAAC,EAAE,kBAAkB,CAAC;IAC1B,6DAA6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,yDAAyD;IACzD,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,2FAA2F;IAC3F,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,iBAAiB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzC;AAED,MAAM,WAAW,eAAe;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,4BAA4B;IAC5C,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sEAAsE;IACtE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,oBAAoB;IACpC;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CAClB;AAqFD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBrE;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE/D;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAW1E;AAoBD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAapF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,qBAAqB,CAC1C,OAAO,EAAE,4BAA4B,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CA2EtC;AAED;;;GAGG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAGtB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAQ/E;AA6ED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA0HzF"}

package/dist/backend/generated-images.js

@@ -0,0 +1,483 @@
+/**
+ * Backend-hosted image storage client.
+ *
+ * Uploads raw image bytes to the Aexol backend so that sessions only ever
+ * carry a stable URL (`/generated-images/<imageId>`) instead of a base64
+ * payload. The three-step contract is:
+ *
+ *   1. `POST  {backendUrl}/generated-images/upload-url`
+ *      -> `{ imageId, uploadUrl, url, expiresIn, requiredHeaders? }`
+ *   2. `PUT   <uploadUrl>` (presigned, ~600s)
+ *      with `Content-Type` + every header from `requiredHeaders`
+ *   3. `POST  {backendUrl}/generated-images/<imageId>/confirm`
+ *      -> `{ id, size, url }`
+ *
+ * Downloading works the other way round and has two flavours:
+ *
+ *   A. `GET  {backendUrl}/generated-images/<imageId>` (authenticated)
+ *      -> 302 redirect to a short-lived presigned S3 GET.
+ *   B. `GET  {backendUrl}/generated-images/<imageId>/url`
+ *      (authenticated) -> `{ url, expiresIn }` where `url` is a presigned
+ *      S3 GET that needs NO headers at all.
+ *
+ * Flavour B is the one to hand to a third party that cannot authenticate
+ * against our backend (an LLM provider fetching an image, an `<img src>`,
+ * ...). See `resolveHostedImageUrl`.
+ *
+ * Errors from the backend have the shape
+ * `{ "error": { "message": "...", "type": "..." } }` and are surfaced as a
+ * `GeneratedImageUploadError` carrying the HTTP status and the step that
+ * failed, so callers can decide whether to degrade gracefully.
+ *
+ * Shared by `image_generate` (Phase 1) and — in a later phase — user
+ * screenshots/attachments, hence `kind` is a parameter rather than a constant.
+ *
+ * @module @spectral/backend/generated-images
+ */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/**
+ * Presigned urls are refreshed this long before they actually expire, so a
+ * url handed to a provider (or an `<img src>`) never dies mid-flight.
+ * Mirrors the landing client's refresh margin.
+ */
+const PRESIGNED_REFRESH_MARGIN_MS = 60_000;
+/** `/generated-images/<id>` — matched against the PATHNAME only. */
+const HOSTED_IMAGE_PATH = /\/generated-images\/([^/?#\s]+)/;
+/**
+ * Storage ids the backend accepts. Mirrors `ID_PATTERN` / `isValidId` from
+ * `backend/src/routes/generated-images/index.ts` so an id that could never
+ * exist server-side is never turned into a request (or an S3 key).
+ */
+const HOSTED_IMAGE_ID = /^[A-Za-z0-9_-]{1,64}$/;
+const ABSOLUTE_URL_SCHEME = /^[a-z][a-z0-9+.-]*:/i;
+/** Upper bound on the presigned-url cache so a long session cannot grow it forever. */
+const HOSTED_IMAGE_URL_CACHE_MAX = 200;
+/** Assumed presigned-url lifetime when the backend omits/invalidates `expiresIn`. */
+const DEFAULT_PRESIGNED_TTL_SECONDS = 3600;
+/**
+ * `presigned url` cache keyed by `<backendUrl>|<token>|<imageId>`. Resolving a hosted
+ * image costs one authenticated round trip per image per request — with
+ * multi-turn image conversations (and retries) that is the same url minted
+ * over and over, so entries are reused until they are close to expiring.
+ */
+const hostedImageUrlCache = new Map();
+/**
+ * Normalized `scheme://host[:port]` origin of an absolute url, or `null` for
+ * relative/unparseable input. `URL` already drops default ports (`:443` for
+ * https), so `https://api.test:443/x` and `https://api.test/x` compare equal.
+ */
+function originOf(value) {
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Path portion of an absolute url (`new URL(v).pathname`) or of a relative
+ * reference (everything before `?`/`#`). Query and fragment are NEVER part of
+ * the result, so `https://cdn.test/a.png?next=/generated-images/abc` cannot
+ * masquerade as one of our hosted images.
+ */
+function pathnameOf(value) {
+    if (ABSOLUTE_URL_SCHEME.test(value)) {
+        try {
+            return new URL(value).pathname;
+        }
+        catch {
+            return null;
+        }
+    }
+    return value.split("#")[0].split("?")[0];
+}
+/** Drop expired entries and evict the oldest ones past the size cap. */
+function purgeHostedImageUrlCache(now = Date.now()) {
+    for (const [key, entry] of hostedImageUrlCache) {
+        if (entry.expiresAt <= now)
+            hostedImageUrlCache.delete(key);
+    }
+    // Map iteration is insertion-ordered, so the first key is the oldest.
+    while (hostedImageUrlCache.size > HOSTED_IMAGE_URL_CACHE_MAX) {
+        const oldest = hostedImageUrlCache.keys().next();
+        if (oldest.done)
+            break;
+        hostedImageUrlCache.delete(oldest.value);
+    }
+}
+/**
+ * Extract the hosted image id from a backend-relative path
+ * (`/generated-images/<id>`) or from an absolute url
+ * (`https://api.aexol.ai/generated-images/<id>?x=1`).
+ *
+ * Only the PATH is inspected: a query/fragment that happens to contain
+ * `/generated-images/<id>` does not make the url one of ours.
+ *
+ * Returns `null` when the value is not a hosted backend image reference, so
+ * callers can use it as a cheap "is this ours?" predicate.
+ */
+export function extractHostedImageId(urlOrPath) {
+    if (typeof urlOrPath !== "string")
+        return null;
+    const trimmed = urlOrPath.trim();
+    if (!trimmed)
+        return null;
+    const path = pathnameOf(trimmed);
+    if (!path)
+        return null;
+    const match = path.match(HOSTED_IMAGE_PATH);
+    const raw = match?.[1];
+    if (!raw)
+        return null;
+    // Strip an optional extension (`<id>.png`) — the id is the first segment.
+    const dot = raw.lastIndexOf(".");
+    let id = dot > 0 ? raw.slice(0, dot) : raw;
+    try {
+        id = decodeURIComponent(id);
+    }
+    catch {
+        // Malformed percent-encoding: keep the raw segment.
+    }
+    if (!HOSTED_IMAGE_ID.test(id))
+        return null;
+    return id;
+}
+/**
+ * The hosted image id carried by `url`, or `null` when `url` is not a hosted
+ * backend image reference. Alias of `extractHostedImageId` kept for callers
+ * that read better with a url-oriented name.
+ */
+export function hostedImageIdFromUrl(url) {
+    return extractHostedImageId(url);
+}
+/**
+ * True when `url` points at a backend-hosted image
+ * (`/generated-images/<id>`), either backend-relative or absolute.
+ *
+ * SECURITY: an absolute url is only "ours" when it actually points at OUR
+ * backend. `backendUrl` is therefore REQUIRED for absolute urls — without it
+ * there is nothing to compare against and the answer is `false`, so callers
+ * never attach the machine JWT to a host they cannot vouch for. Relative urls
+ * always match (they can only ever be resolved against the backend base url).
+ */
+export function isHostedImageUrl(url, backendUrl) {
+    if (typeof url !== "string")
+        return false;
+    const trimmed = url.trim();
+    if (!trimmed)
+        return false;
+    if (hostedImageIdFromUrl(trimmed) === null)
+        return false;
+    if (!ABSOLUTE_URL_SCHEME.test(trimmed))
+        return true;
+    const base = typeof backendUrl === "string" ? backendUrl.trim() : "";
+    if (!base)
+        return false;
+    const origin = originOf(trimmed);
+    const expected = originOf(base);
+    return origin !== null && expected !== null && origin === expected;
+}
+/**
+ * Cheap, non-cryptographic fingerprint of the credential: a cached presigned
+ * url must never be handed out under a different (possibly less privileged)
+ * machine JWT than the one that minted it, so the key carries the token too
+ * — without keeping the token itself in the map.
+ */
+function credentialFingerprint(token) {
+    let hash = 5381;
+    for (let index = 0; index < token.length; index += 1) {
+        hash = ((hash << 5) + hash + token.charCodeAt(index)) | 0;
+    }
+    return (hash >>> 0).toString(36);
+}
+function cacheKey(backendUrl, imageId, token) {
+    return `${baseUrlOf(backendUrl)}|${credentialFingerprint(token)}|${imageId}`;
+}
+/**
+ * Drop cached presigned urls. Omit `imageId` to clear the whole cache (used
+ * by tests and after a logout/credential change).
+ */
+export function invalidateHostedImageUrl(imageId, backendUrl) {
+    const id = typeof imageId === "string" ? imageId.trim() : "";
+    if (!id) {
+        hostedImageUrlCache.clear();
+        return;
+    }
+    const base = typeof backendUrl === "string" ? backendUrl.trim() : "";
+    const basePrefix = base ? `${baseUrlOf(base)}|` : "";
+    for (const key of [...hostedImageUrlCache.keys()]) {
+        if (!key.endsWith(`|${id}`))
+            continue;
+        if (basePrefix && !key.startsWith(basePrefix))
+            continue;
+        hostedImageUrlCache.delete(key);
+    }
+}
+/**
+ * Turn a hosted image reference into a presigned url that a third party (LLM
+ * provider, browser) can fetch WITHOUT authenticating against our backend.
+ *
+ * `GET {backendUrl}/generated-images/<id>/url` with the machine JWT returns
+ * `{ url, expiresIn }`; the plain `GET /generated-images/<id>` endpoint is
+ * auth-gated and 302-redirects, so handing it to a provider only produces a
+ * 401 and a silently dropped image.
+ *
+ * Results are cached per `<backendUrl>|<imageId>` until
+ * `PRESIGNED_REFRESH_MARGIN_MS` before their expiry (see
+ * `invalidateHostedImageUrl`), so repeated requests for the same image do not
+ * each pay a round trip.
+ *
+ * NEVER throws and never logs: returns `null` on any failure (missing token,
+ * non-2xx, network error, malformed body) so callers can fall back to their
+ * previous behaviour. Pass `onWarn` to see why.
+ */
+export async function resolveHostedImageUrl(options) {
+    const { backendUrl, token, url, fetchImpl, signal, timeoutMs, onWarn, } = options;
+    const explicitId = typeof options.imageId === "string" ? options.imageId.trim() : "";
+    const imageId = explicitId || (url ? extractHostedImageId(url) : null);
+    if (!backendUrl || !token || !imageId) {
+        onWarn?.(`Cannot resolve hosted image url: missing ${!backendUrl ? "backend url" : !token ? "machine token" : "image id"}`);
+        return null;
+    }
+    // SECURITY: `url` is data that came from an image block, i.e. attacker
+    // influenceable. Refuse anything that is not a hosted reference on OUR
+    // backend origin — otherwise the machine JWT below would be sent to a
+    // third-party host (and a foreign `/generated-images/<id>` path would be
+    // swapped for a presigned url of one of our tenant's images).
+    if (url && !isHostedImageUrl(url, backendUrl)) {
+        onWarn?.(`Refusing to resolve a hosted image url for a foreign origin: ${url}`);
+        return null;
+    }
+    const key = cacheKey(backendUrl, imageId, token);
+    purgeHostedImageUrlCache();
+    const cached = hostedImageUrlCache.get(key);
+    if (cached && cached.expireRefreshAt > Date.now()) {
+        return {
+            url: cached.url,
+            expiresIn: Math.max(0, Math.floor((cached.expiresAt - Date.now()) / 1000)),
+        };
+    }
+    const doFetch = fetchImpl ?? ((...args) => fetch(...args));
+    try {
+        const response = await fetchWithTimeout(joinUrl(baseUrlOf(backendUrl), `/generated-images/${encodeURIComponent(imageId)}/url`), { method: "GET", headers: { Authorization: `Bearer ${token}` } }, { timeoutMs: timeoutMs ?? DEFAULT_TIMEOUT_MS, signal, fetchImpl: doFetch });
+        const json = await readJson(response);
+        if (!response.ok) {
+            const { message } = errorMessageFrom(json, response.status);
+            onWarn?.(`Could not resolve hosted image url for ${imageId}: ${message}`);
+            return null;
+        }
+        const payload = isRecord(json) ? json : {};
+        const resolvedUrl = typeof payload.url === "string" ? payload.url.trim() : "";
+        if (!resolvedUrl) {
+            onWarn?.(`Backend response for hosted image ${imageId} is missing "url"`);
+            return null;
+        }
+        // A missing/invalid `expiresIn` must not disable caching (that used to
+        // mint a fresh presigned url for every single request) — assume the
+        // backend default instead.
+        const expiresIn = Number(payload.expiresIn);
+        const ttlSeconds = Number.isFinite(expiresIn) && expiresIn > 0 ? expiresIn : DEFAULT_PRESIGNED_TTL_SECONDS;
+        const expiresAt = Date.now() + ttlSeconds * 1000;
+        hostedImageUrlCache.set(key, {
+            url: resolvedUrl,
+            expiresAt,
+            expireRefreshAt: Math.max(expiresAt - PRESIGNED_REFRESH_MARGIN_MS, Date.now()),
+        });
+        purgeHostedImageUrlCache();
+        return { url: resolvedUrl, expiresIn: ttlSeconds };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        onWarn?.(`Could not resolve hosted image url for ${imageId}: ${message}`);
+        return null;
+    }
+}
+/**
+ * Thrown for every failure of the upload sequence (including presigned PUT
+ * failures). `status` is `undefined` for network-level errors.
+ */
+export class GeneratedImageUploadError extends Error {
+    step;
+    status;
+    type;
+    constructor(message, options) {
+        super(message, options.cause === undefined ? undefined : { cause: options.cause });
+        this.name = "GeneratedImageUploadError";
+        this.step = options.step;
+        this.status = options.status;
+        this.type = options.type;
+    }
+}
+function baseUrlOf(backendUrl) {
+    return backendUrl.replace(/\/+$/, "");
+}
+function joinUrl(base, path) {
+    return `${baseUrlOf(base)}${path.startsWith("/") ? path : `/${path}`}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+function errorMessageFrom(body, status) {
+    const error = isRecord(body) && isRecord(body.error) ? body.error : undefined;
+    const message = typeof error?.message === "string" && error.message ? error.message : undefined;
+    const type = typeof error?.type === "string" && error.type ? error.type : undefined;
+    return { message: message ?? `HTTP ${status}`, type };
+}
+/** Parse a JSON body, tolerating empty/invalid bodies (presigned S3 replies are empty). */
+async function readJson(response) {
+    const text = await response.text();
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function requireString(value, field, step) {
+    if (typeof value !== "string" || !value) {
+        throw new GeneratedImageUploadError(`Backend response is missing "${field}"`, { step });
+    }
+    return value;
+}
+/**
+ * Run a single request with an optional timeout + external abort signal.
+ *
+ * The timeout never outlives the call and an already-aborted external signal
+ * aborts immediately.
+ */
+async function fetchWithTimeout(url, init, options) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    if (options.signal) {
+        if (options.signal.aborted)
+            controller.abort();
+        else
+            options.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    try {
+        return await options.fetchImpl(url, { ...init, signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+        options.signal?.removeEventListener("abort", onAbort);
+    }
+}
+function networkError(step, error) {
+    if (error instanceof GeneratedImageUploadError)
+        return error;
+    const message = error instanceof Error ? error.message : String(error);
+    const aborted = error instanceof Error && error.name === "AbortError";
+    return new GeneratedImageUploadError(aborted
+        ? `Upload ${step} timed out or was cancelled (${message})`
+        : `Upload ${step} failed: ${message}`, { step, cause: error });
+}
+/**
+ * Upload raw image bytes to backend storage and confirm them.
+ *
+ * @returns the image id, the backend-relative url and the confirmed byte size.
+ * @throws {GeneratedImageUploadError} on any HTTP or network failure, with a
+ *   human-readable message taken from the backend `error.message` when present.
+ */
+export async function uploadImage(options) {
+    const { backendUrl, token, bytes, contentType, kind = "generated", width, height, fetchImpl, signal, timeoutMs, } = options;
+    if (!backendUrl) {
+        throw new GeneratedImageUploadError("Cannot upload image: no backend url configured", { step: "upload-url" });
+    }
+    if (!token) {
+        throw new GeneratedImageUploadError("Cannot upload image: not authenticated (missing machine token)", {
+            step: "upload-url",
+        });
+    }
+    const doFetch = fetchImpl ?? ((...args) => fetch(...args));
+    const base = baseUrlOf(backendUrl);
+    const authHeaders = { Authorization: `Bearer ${token}` };
+    // ── 1. mint an upload url ────────────────────────────────────────────────
+    let uploadUrlResponse;
+    try {
+        const body = {
+            contentType,
+            kind,
+            size: bytes.byteLength,
+        };
+        if (typeof width === "number" && Number.isFinite(width))
+            body.width = width;
+        if (typeof height === "number" && Number.isFinite(height))
+            body.height = height;
+        const response = await fetchWithTimeout(joinUrl(base, "/generated-images/upload-url"), {
+            method: "POST",
+            headers: { ...authHeaders, "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        }, { timeoutMs, signal, fetchImpl: doFetch });
+        const json = await readJson(response);
+        if (!response.ok) {
+            const { message, type } = errorMessageFrom(json, response.status);
+            throw new GeneratedImageUploadError(`Could not mint image upload url: ${message}`, {
+                step: "upload-url",
+                status: response.status,
+                type,
+            });
+        }
+        const payload = isRecord(json) ? json : {};
+        uploadUrlResponse = {
+            imageId: requireString(payload.imageId, "imageId", "upload-url"),
+            uploadUrl: requireString(payload.uploadUrl, "uploadUrl", "upload-url"),
+            url: requireString(payload.url, "url", "upload-url"),
+            expiresIn: payload.expiresIn,
+            requiredHeaders: payload.requiredHeaders,
+        };
+    }
+    catch (error) {
+        throw networkError("upload-url", error);
+    }
+    // ── 2. PUT the bytes to the presigned url ────────────────────────────────
+    try {
+        const headers = { "Content-Type": contentType };
+        // The backend signs extra headers (e.g. `x-amz-acl: private`) into the
+        // presigned url — they MUST be sent verbatim or S3 rejects the PUT.
+        if (isRecord(uploadUrlResponse.requiredHeaders)) {
+            for (const [key, value] of Object.entries(uploadUrlResponse.requiredHeaders)) {
+                if (typeof value === "string")
+                    headers[key] = value;
+            }
+        }
+        // Normalize to a standalone buffer so byteOffset/byteLength of a
+        // subarray (Buffer view) cannot leak extra bytes into the body.
+        const payload = new Uint8Array(bytes.byteLength);
+        payload.set(bytes);
+        const response = await fetchWithTimeout(uploadUrlResponse.uploadUrl, { method: "PUT", headers, body: payload }, { timeoutMs, signal, fetchImpl: doFetch });
+        if (!response.ok) {
+            const detail = await response.text().catch(() => "");
+            const snippet = detail.replace(/\s+/g, " ").trim().slice(0, 300);
+            throw new GeneratedImageUploadError(`Image upload to storage failed: HTTP ${response.status}${snippet ? ` (${snippet})` : ""}`, { step: "put", status: response.status });
+        }
+    }
+    catch (error) {
+        throw networkError("put", error);
+    }
+    // ── 3. confirm so the backend can serve the image ────────────────────────
+    try {
+        const response = await fetchWithTimeout(joinUrl(base, `/generated-images/${encodeURIComponent(uploadUrlResponse.imageId)}/confirm`), { method: "POST", headers: { ...authHeaders } }, { timeoutMs, signal, fetchImpl: doFetch });
+        const json = await readJson(response);
+        if (!response.ok) {
+            const { message, type } = errorMessageFrom(json, response.status);
+            throw new GeneratedImageUploadError(`Could not confirm uploaded image: ${message}`, {
+                step: "confirm",
+                status: response.status,
+                type,
+            });
+        }
+        const payload = isRecord(json) ? json : {};
+        const confirmedSize = Number(payload.size);
+        return {
+            imageId: typeof payload.id === "string" && payload.id ? payload.id : uploadUrlResponse.imageId,
+            url: typeof payload.url === "string" && payload.url ? payload.url : uploadUrlResponse.url,
+            size: Number.isFinite(confirmedSize) && confirmedSize > 0 ? confirmedSize : bytes.byteLength,
+        };
+    }
+    catch (error) {
+        throw networkError("confirm", error);
+    }
+}