@oh-my-pi/pi-catalog 17.4.0 → 17.4.2

package/src/wire/image-fetchers.ts

@@ -0,0 +1,159 @@
+/**
+ * Identification of provider-side image fetchers.
+ *
+ * A request may carry an image either inline (base64) or as a URL. With a URL,
+ * the provider's backend performs its own server-side GET against that URL, so
+ * a local blob server sees an inbound request from vendor infrastructure rather
+ * than from the client. This module names those fetchers, letting a blob server
+ * attribute an inbound GET to the vendor that issued it — which is how a caller
+ * learns where a request actually landed when a router sits between them and
+ * the model.
+ *
+ * NOT an authentication mechanism. Every value here is a request header chosen
+ * by the caller and is trivially forged. Authorize blob reads with an
+ * unguessable URL (single-use capability token, short TTL) and treat a fetcher
+ * match as attribution/telemetry only.
+ *
+ * Each entry was captured from a live fetch triggered by handing that vendor's
+ * API a URL-sourced image.
+ */
+
+/** Vendor whose infrastructure performed an inbound fetch. */
+export type ImageFetcherVendor = "openai" | "anthropic" | "xai" | "google";
+
+/** Registry key for a known fetcher. */
+export type ImageFetcherId =
+	| "openai-file-downloader"
+	| "anthropic-claude-user"
+	| "anthropic-claude-user-preview"
+	| "xai-image-api-fetch"
+	| "google";
+
+/** Request signature of one provider-side fetcher. */
+export interface ImageFetcherIdentity {
+	vendor: ImageFetcherVendor;
+	/** Human-readable name for logs and UI. */
+	label: string;
+	/**
+	 * `User-Agent` contract: an exact string for fetchers that send a fixed
+	 * value, or a pattern for those embedding a client version.
+	 */
+	userAgent: string | RegExp;
+	/**
+	 * Vendor-proprietary headers observed alongside the agent, used to
+	 * corroborate a `User-Agent` claim. Generic infrastructure headers
+	 * (`traceparent`, `x-cloud-trace-context`) are deliberately excluded: they
+	 * are emitted by unrelated infrastructure and corroborate nothing. Empty
+	 * means the agent string is the only available signal, so
+	 * {@link ImageFetcherMatch.corroborated} can never be true for that entry.
+	 */
+	markerHeaders: readonly string[];
+	/** API surface the capture came from. */
+	observedVia: string;
+	/** Operational caveats a blob server should account for. */
+	note?: string;
+}
+
+/**
+ * Known provider-side fetchers.
+ *
+ * Agent contracts do not overlap — exact strings never collide with the
+ * versioned patterns — so lookup order carries no meaning.
+ */
+export const IMAGE_FETCHERS: Readonly<Record<ImageFetcherId, ImageFetcherIdentity>> = {
+	"openai-file-downloader": {
+		vendor: "openai",
+		label: "OpenAI File Downloader",
+		userAgent: "OpenAI File Downloader",
+		markerHeaders: ["openai-internal-smokescreener"],
+		observedVia: "chatgpt.com/backend-api/codex/responses, input_image.image_url",
+		note: "Issues two near-simultaneous GETs per image; a blob server must treat a duplicate hit as expected rather than as replay.",
+	},
+	"anthropic-claude-user": {
+		vendor: "anthropic",
+		label: "Claude image fetcher",
+		userAgent: "Claude-User",
+		markerHeaders: [],
+		observedVia: "api.anthropic.com/v1/messages, image.source.type=url",
+		note: "Sends only generic trace headers, so the bare agent string is the sole signal. Distinct from the versioned Claude-User/<version> agent used for links appearing in conversation text.",
+	},
+	"anthropic-claude-user-preview": {
+		vendor: "anthropic",
+		label: "Claude link fetcher",
+		userAgent: /\bClaude-User\/\d+(?:\.\d+)*\b/,
+		markerHeaders: [],
+		observedVia:
+			"unsolicited fetch after a URL appeared in assistant output; never observed serving an image request",
+		note: "Not an image fetcher. Listed so a blob server can separate it from the image path instead of counting it as a provider image fetch.",
+	},
+	"xai-image-api-fetch": {
+		vendor: "xai",
+		label: "xAI image API fetch",
+		userAgent: /^XaiImageApiFetch\/\d+(?:\.\d+)*\s/,
+		markerHeaders: ["x-xaifetchid"],
+		observedVia: "api.x.ai/v1/responses, input_image.image_url",
+		note: "Sends an image-only `accept` allowlist and rejects any other content type before the model sees the response.",
+	},
+	google: {
+		vendor: "google",
+		label: "Google",
+		userAgent: "Google",
+		markerHeaders: [],
+		observedVia: "cloudcode-pa.googleapis.com v1internal:streamGenerateContent, fileData.fileUri",
+		note: "Weakest signal of the set: the agent string is a bare vendor name with no version and no proprietary header.",
+	},
+};
+
+/** Attribution outcome for one inbound request. */
+export interface ImageFetcherMatch {
+	id: ImageFetcherId;
+	identity: ImageFetcherIdentity;
+	/**
+	 * Whether every proprietary marker header for the matched identity is
+	 * present. Always false for identities declaring no markers — absence of
+	 * corroboration is not evidence against the match.
+	 */
+	corroborated: boolean;
+}
+
+/** Inbound header bag, as exposed by either `fetch` or a Node-style server. */
+export type InboundHeaders = Headers | Readonly<Record<string, string | readonly string[] | undefined>>;
+
+function headerValue(headers: InboundHeaders, name: string): string | undefined {
+	if (headers instanceof Headers) return headers.get(name) ?? undefined;
+	const direct = headers[name];
+	if (direct !== undefined) return Array.isArray(direct) ? direct[0] : (direct as string);
+	for (const key in headers) {
+		if (key.toLowerCase() !== name) continue;
+		const value = headers[key];
+		return Array.isArray(value) ? value[0] : (value as string | undefined);
+	}
+	return undefined;
+}
+
+/**
+ * Attribute an inbound blob request to a known provider-side fetcher, or
+ * `null` when the agent matches none.
+ *
+ * Matches on `User-Agent` alone and reports marker-header corroboration
+ * separately; callers MUST NOT treat either as proof of origin. Gate access on
+ * the unguessable URL.
+ */
+export function identifyImageFetcher(headers: InboundHeaders): ImageFetcherMatch | null {
+	const agent = headerValue(headers, "user-agent");
+	if (!agent) return null;
+	for (const id in IMAGE_FETCHERS) {
+		const identity = IMAGE_FETCHERS[id as ImageFetcherId];
+		const { userAgent } = identity;
+		const matched = typeof userAgent === "string" ? agent === userAgent : userAgent.test(agent);
+		if (!matched) continue;
+		return {
+			id: id as ImageFetcherId,
+			identity,
+			corroborated:
+				identity.markerHeaders.length > 0 &&
+				identity.markerHeaders.every(header => headerValue(headers, header) !== undefined),
+		};
+	}
+	return null;
+}