@aexol/spectral 0.9.215 → 0.9.216

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

@@ -12,6 +12,18 @@
  *   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
@@ -64,6 +76,84 @@ export interface ConfirmResponse {
     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.

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

@@ -1 +1 @@
-{"version":3,"file":"generated-images.d.ts","sourceRoot":"","sources":["../../src/backend/generated-images.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;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;AAID;;;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"}
+{"version":3,"file":"generated-images.d.ts","sourceRoot":"","sources":["../../src/backend/generated-images.ts"],"names":[],"mappings":"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"}

package/dist/backend/generated-images.js

@@ -12,6 +12,18 @@
  *   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
@@ -23,6 +35,263 @@
  * @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.

package/dist/commands/logout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logout.d.ts","sourceRoot":"","sources":["../../src/commands/logout.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAa/C"}
+{"version":3,"file":"logout.d.ts","sourceRoot":"","sources":["../../src/commands/logout.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAOH,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC,CAgB/C"}

package/dist/commands/logout.js

@@ -5,10 +5,14 @@
  * filesystem itself misbehaves (in which case we surface the OS error).
  */
 import pc from "picocolors";
+import { invalidateHostedImageUrl } from "../backend/generated-images.js";
 import { CONFIG_FILE, deleteConfig } from "../config.js";
 export async function runLogout() {
     try {
         const removed = await deleteConfig();
+        // Presigned urls are minted under the (now deleted) credentials — drop
+        // them so a later login cannot hand out a url minted by the old identity.
+        invalidateHostedImageUrl();
         if (removed) {
             process.stdout.write(pc.green(`✓ Logged out. Removed ${CONFIG_FILE}\n`));
         }

package/dist/sdk/ai/providers/openai-completions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openai-completions.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/providers/openai-completions.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAMX,0BAA0B,EAE1B,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAGX,OAAO,EAGP,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EAEnB,cAAc,EACd,aAAa,EAMb,MAAM,aAAa,CAAC;AAmErB,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC9D,UAAU,CAAC,EACR,MAAM,GACN,MAAM,GACN,UAAU,GACV;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACpD,eAAe,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;CAClE;AAED,KAAK,+BAA+B,GAAG,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AAqRzE,eAAO,MAAM,uBAAuB,EAAE,cAAc,CACnD,oBAAoB,EACpB,wBAAwB,CAybxB,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,cAAc,CACzD,oBAAoB,EACpB,mBAAmB,CAyBnB,CAAC;AAsMF,wBAAgB,eAAe,CAC9B,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,+BAA+B,GACrC,0BAA0B,EAAE,CA0R9B"}
+{"version":3,"file":"openai-completions.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/providers/openai-completions.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAMX,0BAA0B,EAE1B,MAAM,sCAAsC,CAAC;AAG9C,OAAO,KAAK,EAGX,OAAO,EAGP,KAAK,EACL,uBAAuB,EACvB,mBAAmB,EAEnB,cAAc,EACd,aAAa,EAMb,MAAM,aAAa,CAAC;AAmErB,MAAM,WAAW,wBAAyB,SAAQ,aAAa;IAC9D,UAAU,CAAC,EACR,MAAM,GACN,MAAM,GACN,UAAU,GACV;QAAE,IAAI,EAAE,UAAU,CAAC;QAAC,QAAQ,EAAE;YAAE,IAAI,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACpD,eAAe,CAAC,EAAE,SAAS,GAAG,KAAK,GAAG,QAAQ,GAAG,MAAM,GAAG,OAAO,CAAC;CAClE;AAED,KAAK,+BAA+B,GAAG,QAAQ,CAAC,uBAAuB,CAAC,CAAC;AAqRzE,eAAO,MAAM,uBAAuB,EAAE,cAAc,CACnD,oBAAoB,EACpB,wBAAwB,CAocxB,CAAC;AAEF,eAAO,MAAM,6BAA6B,EAAE,cAAc,CACzD,oBAAoB,EACpB,mBAAmB,CAyBnB,CAAC;AAsMF,wBAAgB,eAAe,CAC9B,KAAK,EAAE,KAAK,CAAC,oBAAoB,CAAC,EAClC,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,+BAA+B,GACrC,0BAA0B,EAAE,CA0R9B"}

package/dist/sdk/ai/providers/openai-completions.js

@@ -1,4 +1,5 @@
 import OpenAI from "openai";
+import { backendHostedImageResolver } from "../utils/hosted-image-resolver.js";
 import { getApiUrl, readConfig } from "../../../config.js";
 import { getEnvApiKey } from "../env-api-keys.js";
 import { calculateCost, clampThinkingLevel } from "../models.js";
@@ -311,10 +312,21 @@ export const streamOpenAICompletions = (model, context, options) => {
             // downgraded by `buildParams` anyway, so fetching them would only
             // burn bandwidth and memory.
             const modelSupportsImages = model.input.includes("image");
+            // Handing `/generated-images/<id>` to the provider would be a 401 —
+            // swap it for a presigned url (lazy: only touches config/machine
+            // store when such an image is actually in the context).
+            const hostedImages = backendHostedImageResolver({
+                onWarn: options?.onWarn ?? defaultWarn,
+                // Explicit override (e.g. a local backend) wins; otherwise the
+                // backend url from the machine routing resolves relative urls.
+                baseUrl: () => backendImageBaseUrl(options?.imageBaseUrl),
+            });
             const requestContext = modelSupportsImages
                 ? await resolveImagesForContext(context, {
                     signal: options?.signal,
-                    baseUrl: () => backendImageBaseUrl(options?.imageBaseUrl),
+                    baseUrl: hostedImages.baseUrl,
+                    resolveHostedUrl: hostedImages.resolveHostedUrl,
+                    authHeaders: hostedImages.authHeaders,
                     onWarn: options?.onWarn ?? defaultWarn,
                 })
                 : context;

package/dist/sdk/ai/providers/openrouter-images.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openrouter-images.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/providers/openrouter-images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,eAAe,EAEf,aAAa,EACb,WAAW,EACX,qBAAqB,EAGrB,MAAM,aAAa,CAAC;AA8FrB,wBAAsB,wBAAwB,CAC7C,KAAK,EAAE,WAAW,CAAC,mBAAmB,CAAC,EACvC,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,eAAe,CAAC,CAyH1B"}
+{"version":3,"file":"openrouter-images.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/providers/openrouter-images.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACX,eAAe,EAEf,aAAa,EACb,WAAW,EACX,qBAAqB,EAGrB,MAAM,aAAa,CAAC;AA2GrB,wBAAsB,wBAAwB,CAC7C,KAAK,EAAE,WAAW,CAAC,mBAAmB,CAAC,EACvC,OAAO,EAAE,aAAa,EACtB,OAAO,GAAE,qBAA0B,GACjC,OAAO,CAAC,eAAe,CAAC,CAyH1B"}

package/dist/sdk/ai/providers/openrouter-images.js

@@ -1,5 +1,6 @@
 import { getEnvApiKey } from "../env-api-keys.js";
 import { imageSourceUrlForProvider, resolveImagesForInput } from "../utils/image-source.js";
+import { backendHostedImageResolver } from "../utils/hosted-image-resolver.js";
 /**
  * Image generation routing.
  *
@@ -39,10 +40,22 @@ function textFromContext(context) {
 async function referencesFromContext(context, options = {}) {
     const backendUrl = typeof options.backendUrl === "string" ? options.backendUrl : undefined;
     const onWarn = typeof options.onWarn === "function" ? options.onWarn : undefined;
+    // `/generated-images/<id>` is auth-gated: a 401 for anything that does not
+    // send our machine JWT. Exchange it for a presigned url instead.
+    // NOTE: `options.apiKey` is deliberately NOT used here — on the fallback
+    // path it is a local OpenRouter key that must never be sent to our
+    // backend. The machine JWT comes from `resolveBackendRouting()`, which is
+    // lazy + memoized (only awaited for hosted images) and returns null when
+    // the CLI is not logged in.
+    const hostedImages = backendHostedImageResolver({ onWarn, baseUrl: backendUrl });
     const input = await resolveImagesForInput(context.input, {
         // Backend-relative urls (`/generated-images/<id>`) resolve against the
         // same backend url this request is routed through.
-        baseUrl: backendUrl,
+        baseUrl: hostedImages.baseUrl,
+        resolveHostedUrl: hostedImages.resolveHostedUrl,
+        authHeaders: hostedImages.authHeaders,
+        // A cancelled request must not wait out the 60s resolve timeout.
+        signal: options.signal,
         onWarn,
     });
     return input

package/dist/sdk/ai/utils/hosted-image-resolver.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared wiring for backend-hosted images in provider requests.
+ *
+ * The backend serves conversation images from S3 behind
+ * `GET /generated-images/<id>`, which is AUTH-GATED: an LLM provider
+ * (OpenAI, Anthropic, OpenRouter, ...) fetching that url anonymously gets a
+ * 401 and the image is silently dropped. `GET /generated-images/<id>/url`
+ * — behind the machine JWT — returns a presigned S3 url that anyone can
+ * fetch, so that is what we hand to the provider.
+ *
+ * `resolveBackendRouting()` supplies both the backend url and the machine
+ * JWT. It is lazy (config + machine store are only read when a hosted image
+ * is actually present) and memoized per resolver instance, and it degrades to
+ * `null` when the CLI is not logged in — in which case every hook here is a
+ * no-op and behaviour falls back to whatever it was before.
+ *
+ * @module @spectral/ai/utils/hosted-image-resolver
+ */
+export interface BackendHostedImageResolverOptions {
+    /** Diagnostics sink — resolution failures are silent without it. */
+    onWarn?: (message: string) => void;
+    /**
+     * Explicit backend base url (or a lazy getter for it). Wins over the url
+     * from `resolveBackendRouting()`, so per-request overrides keep working;
+     * used to resolve backend-relative image urls (`/generated-images/<id>`).
+     */
+    baseUrl?: string | (() => string | undefined | Promise<string | undefined>);
+}
+export interface BackendHostedImageResolver {
+    /**
+     * Swap a hosted url for a presigned one. Returns `null` when the url is
+     * not resolvable (not logged in, foreign origin, backend error, ...) so
+     * the caller can fall back to downloading + inlining the bytes itself.
+     */
+    resolveHostedUrl: (url: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }) => Promise<string | null>;
+    /**
+     * `Authorization: Bearer <machine JWT>` for downloading the image bytes
+     * from our own backend. Only ever attached to hosted backend urls.
+     */
+    authHeaders: () => Promise<Record<string, string> | undefined>;
+    /** Backend base url for resolving backend-relative image urls. */
+    baseUrl: () => Promise<string | undefined>;
+    /**
+     * The backend url `resolveHostedUrl` authenticates against — i.e. the
+     * origin an absolute image url has to match to be considered ours.
+     * `undefined` when the CLI is not logged in (nothing is resolvable then).
+     */
+    backendUrl: () => Promise<string | undefined>;
+}
+/**
+ * Build the hosted-image hooks for a single request.
+ *
+ * Cheap to construct: nothing is read from disk/config until one of the
+ * returned functions is actually awaited.
+ */
+export declare function backendHostedImageResolver(options?: BackendHostedImageResolverOptions): BackendHostedImageResolver;
+//# sourceMappingURL=hosted-image-resolver.d.ts.map

package/dist/sdk/ai/utils/hosted-image-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hosted-image-resolver.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/utils/hosted-image-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,WAAW,iCAAiC;IACjD,oEAAoE;IACpE,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnC;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,0BAA0B;IAC1C;;;;OAIG;IACH,gBAAgB,EAAE,CACjB,GAAG,EAAE,MAAM,EACX,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,WAAW,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,KAClD,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B;;;OAGG;IACH,WAAW,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/D,kEAAkE;IAClE,OAAO,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC3C;;;;OAIG;IACH,UAAU,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CAC9C;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACzC,OAAO,GAAE,iCAAsC,GAC7C,0BAA0B,CA6C5B"}

package/dist/sdk/ai/utils/hosted-image-resolver.js

@@ -0,0 +1,75 @@
+/**
+ * Shared wiring for backend-hosted images in provider requests.
+ *
+ * The backend serves conversation images from S3 behind
+ * `GET /generated-images/<id>`, which is AUTH-GATED: an LLM provider
+ * (OpenAI, Anthropic, OpenRouter, ...) fetching that url anonymously gets a
+ * 401 and the image is silently dropped. `GET /generated-images/<id>/url`
+ * — behind the machine JWT — returns a presigned S3 url that anyone can
+ * fetch, so that is what we hand to the provider.
+ *
+ * `resolveBackendRouting()` supplies both the backend url and the machine
+ * JWT. It is lazy (config + machine store are only read when a hosted image
+ * is actually present) and memoized per resolver instance, and it degrades to
+ * `null` when the CLI is not logged in — in which case every hook here is a
+ * no-op and behaviour falls back to whatever it was before.
+ *
+ * @module @spectral/ai/utils/hosted-image-resolver
+ */
+import { isHostedImageUrl, resolveHostedImageUrl } from "../../../backend/generated-images.js";
+import { resolveBackendRouting } from "../../../backend/machine-routing.js";
+/**
+ * Build the hosted-image hooks for a single request.
+ *
+ * Cheap to construct: nothing is read from disk/config until one of the
+ * returned functions is actually awaited.
+ */
+export function backendHostedImageResolver(options = {}) {
+    const { onWarn, baseUrl } = options;
+    let routing;
+    // Memoized so a context with five hosted images reads the machine store
+    // once, and text-only requests never touch it at all.
+    const getRouting = () => (routing ??= resolveBackendRouting().catch(() => null));
+    const resolveExplicitBaseUrl = async () => {
+        if (baseUrl === undefined)
+            return undefined;
+        if (typeof baseUrl === "string")
+            return baseUrl.trim() || undefined;
+        try {
+            const value = await baseUrl();
+            return typeof value === "string" && value.trim() ? value.trim() : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return {
+        resolveHostedUrl: async (url, options) => {
+            const resolved = await getRouting();
+            if (!resolved)
+                return null;
+            // SECURITY: never send the machine JWT to (or mint a presigned url
+            // for) a host that is not our backend — a third-party url must not
+            // be able to impersonate `/generated-images/<id>`.
+            if (!isHostedImageUrl(url, resolved.backendUrl)) {
+                onWarn?.(`Refusing to resolve a hosted image url for a foreign origin: ${url}`);
+                return null;
+            }
+            const result = await resolveHostedImageUrl({
+                backendUrl: resolved.backendUrl,
+                token: resolved.machineJwt,
+                url,
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+                onWarn,
+            });
+            return result?.url ?? null;
+        },
+        authHeaders: async () => {
+            const resolved = await getRouting();
+            return resolved ? { Authorization: `Bearer ${resolved.machineJwt}` } : undefined;
+        },
+        baseUrl: async () => (await resolveExplicitBaseUrl()) ?? (await getRouting())?.backendUrl,
+        backendUrl: async () => (await getRouting())?.backendUrl,
+    };
+}

package/dist/sdk/ai/utils/image-source.d.ts

@@ -9,8 +9,11 @@
  *
  * - `data` present            -> `data:<mimeType>;base64,<data>` (unchanged, legacy safe)
  * - `url` public              -> passed through as-is (no base64 in the context!)
+ * - `url` backend-hosted      -> swapped for a presigned, headerless-fetchable
+ *                                url (`/generated-images/<id>` is what the
+ *                                backend returns; it is AUTH-GATED, so handing
+ *                                it to a provider only yields a 401)
  * - `url` relative            -> resolved against the backend base url first
- *                                (`/generated-images/<id>` is what the backend returns)
  * - `url` local/private       -> fetched and inlined **at send time only**
  *
  * The inlining is deliberately scoped to a single request: the fetched bytes
@@ -38,6 +41,29 @@ export interface ResolveImageOptions {
      * actually present.
      */
     baseUrl?: string | (() => string | undefined | Promise<string | undefined>);
+    /**
+     * Exchange a backend-hosted image url (`/generated-images/<id>`) for a
+     * short-lived presigned url that the provider can fetch WITHOUT any
+     * Authorization header (see `resolveHostedImageUrl` in
+     * `backend/generated-images.ts`).
+     *
+     * Return `null`/`undefined` to fall back to the download+inline path.
+     * Only ever called for urls where `isHostedBackendImageUrl()` is true —
+     * i.e. relative urls and absolute urls on the backend origin.
+     */
+    resolveHostedUrl?: (url: string, options?: {
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }) => Promise<string | null | undefined>;
+    /**
+     * Headers (in practice `Authorization: Bearer <machine JWT>`) used when the
+     * image bytes have to be downloaded for inlining. May be a lazy getter so
+     * the credentials are only read when a hosted image is actually present.
+     *
+     * SECURITY: these are only ever attached to a backend-hosted image url —
+     * never to a third-party host the credentials were not issued for.
+     */
+    authHeaders?: Record<string, string> | (() => Promise<Record<string, string> | undefined>);
     onWarn?: (message: string) => void;
 }
 export interface ResolvedImageSource {
@@ -52,6 +78,11 @@ export interface ResolvedImageSource {
      * (inline `data` present, or fetched from a local url).
      */
     data?: string;
+    /**
+     * True when `url` is a presigned url returned by `resolveHostedUrl` (i.e.
+     * it replaced an auth-gated `/generated-images/<id>` reference).
+     */
+    hostedResolved?: boolean;
 }
 /**
  * True when `rawUrl` has no scheme, i.e. it is relative and therefore
@@ -74,6 +105,22 @@ export declare function resolveImageUrlAgainstBase(rawUrl: string, baseUrl?: str
  * resolved against a base url.
  */
 export declare function isLocalOrPrivateImageUrl(rawUrl: string): boolean;
+/**
+ * True for a backend-hosted image reference, either backend-relative
+ * (`/generated-images/<id>`) or absolute
+ * (`https://api.aexol.ai/generated-images/<id>`).
+ *
+ * `backendUrl` is REQUIRED to accept an ABSOLUTE url: without it there is no
+ * origin to compare against, and a foreign host that happens to expose
+ * `/generated-images/<id>` must never be treated as ours (that would send the
+ * machine JWT to it, and would let it swap in a presigned url of one of our
+ * tenant's images). Relative urls are always accepted — they can only ever be
+ * resolved against the backend base url.
+ *
+ * Those endpoints are auth-gated: a provider fetching them without an
+ * `Authorization` header gets a 401 and never sees the image.
+ */
+export declare function isHostedBackendImageUrl(rawUrl: string, backendUrl?: string | null): boolean;
 export declare function hasInlineImageData(image: ImageContent): image is ImageContent & {
     data: string;
 };

package/dist/sdk/ai/utils/image-source.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image-source.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/utils/image-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAW,MAAM,aAAa,CAAC;AAElE,8EAA8E;AAC9E,eAAO,MAAM,wBAAwB,QAAmB,CAAC;AAEzD,iEAAiE;AACjE,eAAO,MAAM,+BAA+B,QAAS,CAAC;AAEtD,MAAM,WAAW,mBAAmB;IACnC,mEAAmE;IACnE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,mDAAmD;IACnD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,MAAM,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC5E,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,mBAAmB;IACnC,mEAAmE;IACnE,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACd;AAuCD;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAUnF;AAmBD;;;;;;;;;GASG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CA4BhE;AAcD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,YAAY,GAAG,KAAK,IAAI,YAAY,GAAG;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAEhG;AAED,wEAAwE;AACxE,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIxD;AAoBD;;;;;;GAMG;AACH,wBAAsB,uBAAuB,CAC5C,KAAK,EAAE,YAAY,EACnB,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAgErC;AAcD;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC5C,OAAO,EAAE,OAAO,EAChB,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAAC,OAAO,CAAC,CAoDlB;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAC1C,KAAK,EAAE,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9B,OAAO,GAAE,mBAAwB,GAC/B,OAAO,CAAC,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAsBlC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,YAAY,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAUnG"}
+{"version":3,"file":"image-source.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/utils/image-source.ts"],"names":[],"mappings":"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"}

package/dist/sdk/ai/utils/image-source.js

@@ -9,8 +9,11 @@
  *
  * - `data` present            -> `data:<mimeType>;base64,<data>` (unchanged, legacy safe)
  * - `url` public              -> passed through as-is (no base64 in the context!)
+ * - `url` backend-hosted      -> swapped for a presigned, headerless-fetchable
+ *                                url (`/generated-images/<id>` is what the
+ *                                backend returns; it is AUTH-GATED, so handing
+ *                                it to a provider only yields a 401)
  * - `url` relative            -> resolved against the backend base url first
- *                                (`/generated-images/<id>` is what the backend returns)
  * - `url` local/private       -> fetched and inlined **at send time only**
  *
  * The inlining is deliberately scoped to a single request: the fetched bytes
@@ -19,6 +22,7 @@
  *
  * @module @spectral/ai/utils/image-source
  */
+import { hostedImageIdFromUrl, isHostedImageUrl } from "../../../backend/generated-images.js";
 /** Don't inline absurd payloads — 25 MiB of base64 would blow the request. */
 export const DEFAULT_MAX_INLINE_BYTES = 25 * 1024 * 1024;
 /** Timeout for fetching a local image that has to be inlined. */
@@ -170,6 +174,44 @@ async function resolveBaseUrlOption(baseUrl) {
         return undefined;
     }
 }
+/**
+ * True for a backend-hosted image reference, either backend-relative
+ * (`/generated-images/<id>`) or absolute
+ * (`https://api.aexol.ai/generated-images/<id>`).
+ *
+ * `backendUrl` is REQUIRED to accept an ABSOLUTE url: without it there is no
+ * origin to compare against, and a foreign host that happens to expose
+ * `/generated-images/<id>` must never be treated as ours (that would send the
+ * machine JWT to it, and would let it swap in a presigned url of one of our
+ * tenant's images). Relative urls are always accepted — they can only ever be
+ * resolved against the backend base url.
+ *
+ * Those endpoints are auth-gated: a provider fetching them without an
+ * `Authorization` header gets a 401 and never sees the image.
+ */
+export function isHostedBackendImageUrl(rawUrl, backendUrl) {
+    return isHostedImageUrl(rawUrl, backendUrl ?? undefined);
+}
+/** Resolve (and normalize) the lazily supplied auth headers. */
+async function resolveAuthHeadersOption(authHeaders) {
+    if (!authHeaders)
+        return undefined;
+    let headers;
+    if (typeof authHeaders === "function") {
+        try {
+            headers = await authHeaders();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else {
+        headers = authHeaders;
+    }
+    if (!headers || Object.keys(headers).length === 0)
+        return undefined;
+    return headers;
+}
 export function hasInlineImageData(image) {
     return typeof image.data === "string" && image.data.length > 0;
 }
@@ -230,14 +272,46 @@ export async function resolveImageForProvider(image, options = {}) {
     let url = typeof image.url === "string" ? image.url.trim() : "";
     if (!url)
         return null;
+    // Resolve the backend base url lazily, and ONLY when the url even looks
+    // hosted (path-wise): public cdn urls must not pay for a config/machine
+    // store read. The base url doubles as the origin an absolute url has to
+    // match before it is accepted as ours.
+    const looksHosted = hostedImageIdFromUrl(url) !== null;
+    const backendUrl = looksHosted ? await resolveBaseUrlOption(options.baseUrl) : undefined;
     // Relative urls (`/generated-images/<id>`) must be joined with the backend
     // base url before anything else — otherwise the provider gets a path.
     if (isRelativeImageUrl(url)) {
-        url = resolveImageUrlAgainstBase(url, await resolveBaseUrlOption(options.baseUrl));
+        url = resolveImageUrlAgainstBase(url, backendUrl);
+    }
+    // A hosted url points at OUR backend, which authenticates every request:
+    // the provider would fetch it anonymously and get a 401. Swap it for a
+    // presigned url first (that one needs no headers at all).
+    const hosted = isHostedBackendImageUrl(url, backendUrl);
+    if (hosted && options.resolveHostedUrl) {
+        try {
+            const resolvedUrl = (await options.resolveHostedUrl(url, { signal: options.signal, timeoutMs: options.timeoutMs }))?.trim();
+            if (resolvedUrl) {
+                return { url: resolvedUrl, inlined: false, mimeType: image.mimeType, hostedResolved: true };
+            }
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            options.onWarn?.(`Could not resolve hosted image ${url} (${reason})`);
+        }
     }
-    if (!isLocalOrPrivateImageUrl(url)) {
+    // Only inline a hosted url when we can actually authenticate the download;
+    // without credentials the fetch is a guaranteed 401 anyway, so the plain
+    // pass-through (identical end result, one request less) is kept.
+    const authHeaders = hosted ? await resolveAuthHeadersOption(options.authHeaders) : undefined;
+    // Belt and braces: re-check the origin here, because `url` was rewritten
+    // above (relative -> absolute) and only a url that is still ours may carry
+    // credentials. The resolver refuses foreign origins too, this is the last
+    // gate before the token goes on the wire.
+    const authenticated = authHeaders !== undefined && isHostedBackendImageUrl(url, backendUrl);
+    if (!isLocalOrPrivateImageUrl(url) && !authenticated) {
         return { url, inlined: false, mimeType: image.mimeType };
     }
+    const requestHeaders = authenticated ? authHeaders : undefined;
     const doFetch = options.fetchImpl ?? fetch;
     const timeoutMs = options.timeoutMs ?? DEFAULT_INLINE_FETCH_TIMEOUT_MS;
     const maxInlineBytes = options.maxInlineBytes ?? DEFAULT_MAX_INLINE_BYTES;
@@ -249,7 +323,10 @@ export async function resolveImageForProvider(image, options = {}) {
         // An already-aborted signal never fires the listener above.
         if (options.signal?.aborted)
             throw new Error("aborted");
-        const response = await doFetch(url, { signal: controller.signal });
+        // `requestHeaders` is only set when the (possibly rewritten) url still
+        // resolves to the backend origin — a url on any other host is fetched
+        // anonymously, so the JWT cannot leak to a third party.
+        const response = await doFetch(url, requestHeaders ? { signal: controller.signal, headers: requestHeaders } : { signal: controller.signal });
         if (!response.ok)
             throw new Error(`HTTP ${response.status}`);
         // Reject oversized payloads from the declared length BEFORE reading
@@ -276,7 +353,7 @@ export async function resolveImageForProvider(image, options = {}) {
     }
     catch (error) {
         const reason = error instanceof Error ? error.message : String(error);
-        options.onWarn?.(`Could not inline local image ${url} (${reason}); sending url as-is`);
+        options.onWarn?.(`Could not inline local image ${url} (${reason}); sending url as-is${hosted ? " — the provider may not be able to fetch it (auth required)" : ""}`);
         return { url, inlined: false, mimeType: image.mimeType };
     }
     finally {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aexol/spectral",
-  "version": "0.9.215",
+  "version": "0.9.216",
   "description": "AI coding agent for Aexol with relay-based browser access.",
   "type": "module",
   "private": false,