@aexol/spectral 0.9.212 → 0.9.216

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

@@ -0,0 +1,168 @@
+/**
+ * Image source resolution for provider serialization.
+ *
+ * `ImageContent` can now carry either inline base64 (`data`) or a hosted
+ * `url`. Providers (OpenRouter, AWS Bedrock, OpenAI, ...) can only fetch
+ * images from PUBLIC urls — a `http://localhost:9002/...` MinIO url in dev is
+ * unreachable for them. This module resolves an `ImageContent` block into
+ * something a provider can actually consume:
+ *
+ * - `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
+ * - `url` local/private       -> fetched and inlined **at send time only**
+ *
+ * The inlining is deliberately scoped to a single request: the fetched bytes
+ * are written into a throw-away copy of the message list, never back into the
+ * session, so base64 never accumulates in persisted history.
+ *
+ * @module @spectral/ai/utils/image-source
+ */
+import type { Context, ImageContent } from "../types.js";
+/** Don't inline absurd payloads — 25 MiB of base64 would blow the request. */
+export declare const DEFAULT_MAX_INLINE_BYTES: number;
+/** Timeout for fetching a local image that has to be inlined. */
+export declare const DEFAULT_INLINE_FETCH_TIMEOUT_MS = 15000;
+export interface ResolveImageOptions {
+    /** Abort the inline fetch (e.g. when the request is cancelled). */
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxInlineBytes?: number;
+    /** Injectable for tests / alternative runtimes. */
+    fetchImpl?: typeof fetch;
+    /**
+     * Base url (usually the backend url) used to turn a relative image url
+     * (`/generated-images/<id>`) into an absolute one. May be a lazy getter so
+     * callers only pay the cost (e.g. reading config) when a relative url is
+     * 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 {
+    /** Value to place in `image_url.url` (data URI or http(s) url). */
+    url: string;
+    /** True when the bytes were fetched and base64-inlined. */
+    inlined: boolean;
+    mimeType: string;
+    /**
+     * Raw base64 payload WITHOUT the `data:` prefix, matching the
+     * `ImageContent.data` contract. Only set when the bytes are known
+     * (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
+ * unusable for a provider until it is joined with a base url.
+ */
+export declare function isRelativeImageUrl(rawUrl: string): boolean;
+/**
+ * Join a relative image url (`/generated-images/<id>`) with the backend base
+ * url. Absolute urls and missing base urls are returned untouched.
+ */
+export declare function resolveImageUrlAgainstBase(rawUrl: string, baseUrl?: string): string;
+/**
+ * True when a provider is unlikely to be able to fetch this URL itself and
+ * the image must therefore be inlined as base64 before sending.
+ *
+ * Covers: localhost, `*.local`, `*.localhost`, loopback IPs (v4 + v6),
+ * RFC1918 private ranges, link-local and CGNAT ranges, and non-http(s)
+ * schemes (except `data:`/`blob:` which need no fetch at all), plus
+ * container/metadata/reserved hosts and relative urls that still need to be
+ * 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;
+};
+/** Build a `data:` URI from base64 payload + mime type (idempotent). */
+export declare function dataUriForImage(data: string, mimeType: string): string;
+/**
+ * `ImageContent.data` is base64 WITHOUT a `data:` prefix, but legacy
+ * sessions may carry a full data URI. Strip it so consumers doing
+ * `Buffer.from(data, "base64")` get real bytes.
+ */
+export declare function base64FromImageData(data: string): string;
+/**
+ * Resolve an image block into a provider-sendable url.
+ *
+ * Returns `null` when the block carries neither data nor url (nothing sendable).
+ * Local/private urls are fetched and inlined; failures fall back to the raw
+ * url so the caller still emits *something* rather than dropping the image.
+ */
+export declare function resolveImageForProvider(image: ImageContent, options?: ResolveImageOptions): Promise<ResolvedImageSource | null>;
+/**
+ * Pre-pass used right before a request is built: any image block that only has
+ * a local/private `url` gets its bytes fetched and attached as `data` on a
+ * throw-away copy of the context.
+ *
+ * The returned context is a shallow clone (messages copied, unchanged messages
+ * shared by reference) and is discarded after the single request completes, so
+ * base64 never lands in session history. When there is nothing to inline the
+ * original context object is returned unchanged.
+ */
+export declare function resolveImagesForContext(context: Context, options?: ResolveImageOptions): Promise<Context>;
+/**
+ * Same as `resolveImagesForContext` but for the images API input list.
+ */
+export declare function resolveImagesForInput(input: Array<{
+    type: string;
+}>, options?: ResolveImageOptions): Promise<Array<{
+    type: string;
+}>>;
+/**
+ * Synchronous serializer used inside the (sync) param builders: after the
+ * `resolveImagesForContext` pre-pass there should be nothing local left, so
+ * this only has to choose between an existing `data` payload and a public url.
+ */
+export declare function imageSourceUrlForProvider(image: ImageContent, baseUrl?: string): string | undefined;
+//# sourceMappingURL=image-source.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"image-source.d.ts","sourceRoot":"","sources":["../../../../src/sdk/ai/utils/image-source.ts"],"names":[],"mappings":"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"}