Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat: add external media storage integration (#18320)

Tobias Wochingera8f548c33276
diff --git a/.env.dev.example b/.env.dev.example
index 6d3a7cfce5..3b060175ae 100644
--- a/.env.dev.example
+++ b/.env.dev.example
@@ -256,6 +256,10 @@ LANGFUSE_AI_FEATURES_PROJECT_ID=7a88fb47-b4e2-43b8-a06c-a5ce950dc53a
# LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_HOST=localhost
# LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IPS=127.0.0.1,::1
# LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS=127.0.0.0/8
+# Self-hosted only: allow internal hosts/IPs for external media storage endpoints.
+# LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST=localhost
+# LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS=127.0.0.1,::1
+# LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS=127.0.0.0/8
# Allow internal IdP hosts/IPs for SSO OIDC discovery validation.
# LANGFUSE_SSO_DISCOVERY_WHITELISTED_HOST=localhost
# LANGFUSE_SSO_DISCOVERY_WHITELISTED_IPS=127.0.0.1,::1
diff --git a/.env.prod.example b/.env.prod.example
index 6f67bf59e3..0c389446e4 100644
--- a/.env.prod.example
+++ b/.env.prod.example
@@ -461,6 +461,10 @@ LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG=true
# LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_HOST=
# LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IPS=
# LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS=
+# Self-hosted only: allow internal hosts/IPs for external media storage endpoints.
+# LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST=
+# LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS=
+# LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS=
# Allow internal IdP hosts/IPs for SSO OIDC discovery validation.
# LANGFUSE_SSO_DISCOVERY_WHITELISTED_HOST=
# LANGFUSE_SSO_DISCOVERY_WHITELISTED_IPS=
diff --git a/packages/shared/prisma/migrations/20261006111500_add_external_media_storage_integration/migration.sql b/packages/shared/prisma/migrations/20261006111500_add_external_media_storage_integration/migration.sql
new file mode 100644
index 0000000000..0eb17f8843
--- /dev/null
+++ b/packages/shared/prisma/migrations/20261006111500_add_external_media_storage_integration/migration.sql
@@ -0,0 +1,23 @@
+CREATE TYPE "ExternalMediaStorageIntegrationType" AS ENUM (
+ 'S3',
+ 'S3_COMPATIBLE'
+);
+
+CREATE TABLE "external_media_storage_integrations" (
+ "project_id" TEXT NOT NULL,
+ "type" "ExternalMediaStorageIntegrationType" NOT NULL,
+ "bucket_name" TEXT NOT NULL,
+ "prefix" TEXT,
+ "access_key_id" TEXT,
+ "secret_access_key" TEXT,
+ "region" TEXT NOT NULL,
+ "endpoint" TEXT,
+ "force_path_style" BOOLEAN NOT NULL,
+ "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+ "updated_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+ CONSTRAINT "external_media_storage_integrations_pkey" PRIMARY KEY ("project_id"),
+ CONSTRAINT "external_media_storage_integrations_project_id_fkey"
+ FOREIGN KEY ("project_id") REFERENCES "projects"("id")
+ ON DELETE CASCADE ON UPDATE CASCADE
+);
diff --git a/packages/shared/prisma/schema.prisma b/packages/shared/prisma/schema.prisma
index 9be0469e73..b29f7da1e2 100644
--- a/packages/shared/prisma/schema.prisma
+++ b/packages/shared/prisma/schema.prisma
@@ -164,6 +164,7 @@ model Project {
PosthogIntegration PosthogIntegration[]
MixpanelIntegration MixpanelIntegration[]
BlobStorageIntegration BlobStorageIntegration[]
+ ExternalMediaStorageIntegration ExternalMediaStorageIntegration?
webCalloutEndpoints WebCalloutEndpoint[]
scoreConfig ScoreConfig[]
BatchExport BatchExport[]
@@ -1397,6 +1398,25 @@ model BlobStorageIntegration {
@@map("blob_storage_integrations")
}
+model ExternalMediaStorageIntegration {
+ projectId String @id @map("project_id")
+ project Project @relation(fields: [projectId], references: [id], onDelete: Cascade)
+
+ type ExternalMediaStorageIntegrationType @map("type")
+ bucketName String @map("bucket_name")
+ prefix String? @map("prefix")
+ accessKeyId String? @map("access_key_id")
+ secretAccessKey String? @map("secret_access_key")
+ region String @map("region")
+ endpoint String? @map("endpoint")
+ forcePathStyle Boolean @map("force_path_style")
+
+ createdAt DateTime @default(now()) @map("created_at")
+ updatedAt DateTime @default(now()) @updatedAt @map("updated_at")
+
+ @@map("external_media_storage_integrations")
+}
+
model WebCalloutEndpoint {
id String @id @default(cuid())
createdAt DateTime @default(now()) @map("created_at")
@@ -1434,6 +1454,11 @@ enum BlobStorageIntegrationType {
@@map("BlobStorageIntegrationType")
}
+enum ExternalMediaStorageIntegrationType {
+ S3
+ S3_COMPATIBLE
+}
+
enum BlobStorageExportMode {
FULL_HISTORY
FROM_TODAY
diff --git a/packages/shared/src/env.ts b/packages/shared/src/env.ts
index b645bc0ba6..7b8ba5331a 100644
--- a/packages/shared/src/env.ts
+++ b/packages/shared/src/env.ts
@@ -533,6 +533,24 @@ const EnvSchema = z.object({
.transform((s) =>
s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
),
+ LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS: z
+ .string()
+ .optional()
+ .transform((s) =>
+ s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
+ ),
+ LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS: z
+ .string()
+ .optional()
+ .transform((s) =>
+ s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
+ ),
+ LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST: z
+ .string()
+ .optional()
+ .transform((s) =>
+ s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
+ ),
LANGFUSE_SSO_DISCOVERY_WHITELISTED_IPS: z
.string()
.optional()
diff --git a/packages/shared/src/in-app-agent/server/mcpPolicy.ts b/packages/shared/src/in-app-agent/server/mcpPolicy.ts
index 6285e319e6..946d86e444 100644
--- a/packages/shared/src/in-app-agent/server/mcpPolicy.ts
+++ b/packages/shared/src/in-app-agent/server/mcpPolicy.ts
@@ -212,6 +212,22 @@ export const IN_APP_AGENT_LANGFUSE_MCP_TOOL_POLICIES = {
approval: "auto",
availability: { scope: "project:read" },
},
+ getExternalMediaStorage: {
+ approval: "auto",
+ availability: { scope: "project:read" },
+ },
+ configureExternalMediaStorage: {
+ approval: "approval",
+ availability: { scope: "integrations:CRUD" },
+ },
+ deleteExternalMediaStorage: {
+ approval: "approval",
+ availability: { scope: "integrations:CRUD" },
+ },
+ testExternalMediaStorage: {
+ approval: "auto",
+ availability: { scope: "integrations:CRUD" },
+ },
queryMetrics: {
approval: "auto",
availability: { scope: "project:read" },
diff --git a/packages/shared/src/index.ts b/packages/shared/src/index.ts
index a92b7ebd9e..363158452d 100644
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -129,6 +129,7 @@ export * from "./domain";
// io representation
export * from "./utils/IORepresentation";
export * from "./utils/mediaReferences";
+export * from "./utils/s3Uri";
// analytics integrations (client-safe)
export * from "./features/analytics-integrations";
diff --git a/packages/shared/src/server/index.ts b/packages/shared/src/server/index.ts
index 88edc31d10..097234cbc8 100644
--- a/packages/shared/src/server/index.ts
+++ b/packages/shared/src/server/index.ts
@@ -67,6 +67,7 @@ export * from "./llm/ai-sdk/providers/vertex";
export * from "./llm/ai-sdk/providers/vertexAuth";
export * from "./outbound-url";
export * from "./services/blobStorageEndpointValidation";
+export * from "./services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation";
export * from "./llm/getInternalTracingHandler";
export * from "./utils/DatabaseReadStream";
export * from "./utils/transforms";
diff --git a/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.cloud.test.ts b/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.cloud.test.ts
new file mode 100644
index 0000000000..d91c651fd9
--- /dev/null
+++ b/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.cloud.test.ts
@@ -0,0 +1,23 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { validateExternalMediaStorageEndpoint } from "./externalMediaStorageEndpointValidation";
+
+vi.mock("../../../env", () => ({
+ env: {
+ NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: "EU",
+ },
+}));
+
+describe("validateExternalMediaStorageEndpoint on Langfuse Cloud", () => {
+ it("requires HTTPS even when an HTTP endpoint is otherwise allowlisted", async () => {
+ await expect(
+ validateExternalMediaStorageEndpoint("http://storage.example.com", {
+ hosts: ["storage.example.com"],
+ ips: [],
+ ip_ranges: [],
+ }),
+ ).rejects.toMatchObject({
+ code: "https-required",
+ });
+ });
+});
diff --git a/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.test.ts b/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.test.ts
new file mode 100644
index 0000000000..70ea741a1c
--- /dev/null
+++ b/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.test.ts
@@ -0,0 +1,46 @@
+import { describe, expect, it, vi } from "vitest";
+import { OutboundUrlValidationError } from "../../outbound-url";
+import { validateExternalMediaStorageEndpoint } from "./externalMediaStorageEndpointValidation";
+
+vi.mock("../../../env", () => ({
+ env: {
+ NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: undefined,
+ LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST: [],
+ LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS: [],
+ LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS: [],
+ },
+}));
+
+const strictWhitelist = { hosts: [], ips: [], ip_ranges: [] };
+
+describe("validateExternalMediaStorageEndpoint", () => {
+ it.each(["http://127.0.0.1", "http://169.254.169.254", "http://10.0.0.1"])(
+ "rejects private endpoint %s without an allowlist",
+ async (endpoint) => {
+ await expect(
+ validateExternalMediaStorageEndpoint(endpoint, strictWhitelist),
+ ).rejects.toBeInstanceOf(OutboundUrlValidationError);
+ },
+ );
+
+ it("rejects endpoints with embedded credentials", async () => {
+ await expect(
+ validateExternalMediaStorageEndpoint(
+ "https://user:[email protected]",
+ strictWhitelist,
+ ),
+ ).rejects.toMatchObject({
+ code: "url-credentials-not-allowed",
+ });
+ });
+
+ it("allows an explicitly allowlisted private endpoint", async () => {
+ await expect(
+ validateExternalMediaStorageEndpoint("http://10.0.0.1", {
+ hosts: [],
+ ips: ["10.0.0.1"],
+ ip_ranges: [],
+ }),
+ ).resolves.toBeUndefined();
+ });
+});
diff --git a/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.ts b/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.ts
new file mode 100644
index 0000000000..4da131da92
--- /dev/null
+++ b/packages/shared/src/server/services/externalMediaStorageEndpointValidation/externalMediaStorageEndpointValidation.ts
@@ -0,0 +1,90 @@
+import { env } from "../../../env";
+import {
+ type OutboundUrlConnectionValidationOptions,
+ type OutboundUrlValidationWhitelist,
+ OutboundUrlValidationError,
+ parseOutboundUrl,
+ validateOutboundUrlHost,
+} from "../../outbound-url";
+
+const EXTERNAL_MEDIA_STORAGE_ENDPOINT_VALIDATION_LOG_CONTEXT =
+ "External media storage endpoint";
+
+const STRICT_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELIST: OutboundUrlValidationWhitelist =
+ {
+ hosts: [],
+ ips: [],
+ ip_ranges: [],
+ };
+
+function isLangfuseCloud() {
+ return Boolean(env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION);
+}
+
+export function externalMediaStorageEndpointWhitelistFromEnv(): OutboundUrlValidationWhitelist {
+ if (isLangfuseCloud()) {
+ return STRICT_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELIST;
+ }
+
+ return {
+ hosts: env.LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST || [],
+ ips: env.LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS || [],
+ ip_ranges:
+ env.LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS ||
+ [],
+ };
+}
+
+export async function validateExternalMediaStorageEndpoint(
+ endpoint: string,
+ whitelist: OutboundUrlValidationWhitelist = externalMediaStorageEndpointWhitelistFromEnv(),
+) {
+ const effectiveWhitelist = isLangfuseCloud()
+ ? STRICT_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELIST
+ : whitelist;
+ const url = parseOutboundUrl(endpoint);
+
+ if (!["https:", "http:"].includes(url.protocol)) {
+ throw new OutboundUrlValidationError(
+ "protocol-not-allowed",
+ "Only HTTP and HTTPS protocols are allowed",
+ );
+ }
+
+ if (isLangfuseCloud() && url.protocol !== "https:") {
+ throw new OutboundUrlValidationError(
+ "https-required",
+ "Only HTTPS external media storage endpoints are allowed on Langfuse Cloud",
+ );
+ }
+
+ try {
+ await validateOutboundUrlHost({
+ url,
+ whitelist: effectiveWhitelist,
+ logContext: EXTERNAL_MEDIA_STORAGE_ENDPOINT_VALIDATION_LOG_CONTEXT,
+ shouldSkipDnsCheckForLiteralIps: true,
+ });
+ } catch (error) {
+ if (error instanceof OutboundUrlValidationError) {
+ throw new OutboundUrlValidationError(
+ error.code,
+ `${error.message}${getSelfHostedWhitelistGuidance()}`,
+ );
+ }
+ throw error;
+ }
+}
+
+export function externalMediaStorageEndpointConnectionValidationOptions(): OutboundUrlConnectionValidationOptions {
+ return {
+ whitelist: externalMediaStorageEndpointWhitelistFromEnv(),
+ logContext: EXTERNAL_MEDIA_STORAGE_ENDPOINT_VALIDATION_LOG_CONTEXT,
+ };
+}
+
+function getSelfHostedWhitelistGuidance() {
+ if (isLangfuseCloud()) return "";
+
+ return " For self-hosted deployments with internal external media storage endpoints, configure LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST, LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS, or LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS.";
+}
diff --git a/packages/shared/src/utils/s3Uri.test.ts b/packages/shared/src/utils/s3Uri.test.ts
new file mode 100644
index 0000000000..5c7d150074
--- /dev/null
+++ b/packages/shared/src/utils/s3Uri.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vitest";
+import { isS3KeyWithinPrefix, parseS3Uri } from "./s3Uri";
+
+describe("parseS3Uri", () => {
+ it("parses a canonical bucket and object key", () => {
+ expect(parseS3Uri("s3://media-bucket/customer/image.png")).toEqual({
+ bucket: "media-bucket",
+ key: "customer/image.png",
+ });
+ });
+
+ it.each([
+ "https://media-bucket/customer/image.png",
+ "s3://media-bucket",
+ "s3:///customer/image.png",
+ "s3://media-bucket/",
+ "s3://media-bucket//image.png",
+ "s3://media-bucket/image.png?versionId=1",
+ "s3://media-bucket/image.png#fragment",
+ ])("rejects non-canonical URI %s", (value) => {
+ expect(parseS3Uri(value)).toBeNull();
+ });
+});
+
+describe("isS3KeyWithinPrefix", () => {
+ it("rejects an empty prefix", () => {
+ expect(isS3KeyWithinPrefix("customer/image.png", "")).toBe(false);
+ });
+
+ it("accepts keys inside the configured prefix", () => {
+ expect(isS3KeyWithinPrefix("customer/image.png", "customer/")).toBe(true);
+ });
+
+ it("rejects similarly named sibling prefixes", () => {
+ expect(isS3KeyWithinPrefix("customer-other/image.png", "customer/")).toBe(
+ false,
+ );
+ expect(isS3KeyWithinPrefix("customer-other/image.png", "customer")).toBe(
+ false,
+ );
+ });
+});
diff --git a/packages/shared/src/utils/s3Uri.ts b/packages/shared/src/utils/s3Uri.ts
new file mode 100644
index 0000000000..c97c571429
--- /dev/null
+++ b/packages/shared/src/utils/s3Uri.ts
@@ -0,0 +1,40 @@
+const S3_URI_PREFIX = "s3://";
+const MAX_S3_URI_LENGTH = 2048;
+
+export type ParsedS3Uri = {
+ bucket: string;
+ key: string;
+};
+
+export function parseS3Uri(value: string): ParsedS3Uri | null {
+ if (!value.startsWith(S3_URI_PREFIX) || value.length > MAX_S3_URI_LENGTH) {
+ return null;
+ }
+
+ const withoutScheme = value.slice(S3_URI_PREFIX.length);
+ const separatorIndex = withoutScheme.indexOf("/");
+ if (separatorIndex <= 0 || separatorIndex === withoutScheme.length - 1) {
+ return null;
+ }
+
+ const bucket = withoutScheme.slice(0, separatorIndex);
+ const key = withoutScheme.slice(separatorIndex + 1);
+
+ if (
+ !bucket ||
+ !key ||
+ key.startsWith("/") ||
+ value.includes("?") ||
+ value.includes("#")
+ ) {
+ return null;
+ }
+
+ return { bucket, key };
+}
+
+export function isS3KeyWithinPrefix(key: string, prefix: string): boolean {
+ if (!prefix) return false;
+ const directoryPrefix = prefix.endsWith("/") ? prefix : `${prefix}/`;
+ return key.startsWith(directoryPrefix);
+}
diff --git a/web/src/__tests__/server/external-media-storage-service.servertest.ts b/web/src/__tests__/server/external-media-storage-service.servertest.ts
new file mode 100644
index 0000000000..1848a05c23
--- /dev/null
+++ b/web/src/__tests__/server/external-media-storage-service.servertest.ts
@@ -0,0 +1,195 @@
+import { randomUUID } from "crypto";
+import type { Mock } from "vitest";
+
+import { encrypt } from "@langfuse/shared/encryption";
+import { prisma } from "@langfuse/shared/src/db";
+import {
+ createOrgProjectAndApiKey,
+ StorageServiceFactory,
+} from "@langfuse/shared/src/server";
+
+import { createExternalMediaStorageService } from "@/src/features/external-media-storage/server";
+
+vi.mock("@langfuse/shared/src/server", async () => {
+ const actual = await vi.importActual("@langfuse/shared/src/server");
+ return {
+ ...actual,
+ StorageServiceFactory: {
+ getInstance: vi.fn(),
+ },
+ };
+});
+
+const orgIds: string[] = [];
+
+async function enableExternalMediaStorage(orgId: string) {
+ await prisma.organization.update({
+ where: { id: orgId },
+ data: { featureFlagOrgDefaults: ["externalMediaStorage"] },
+ });
+}
+
+async function prepareIntegration({
+ bucketName = "media-bucket",
+ prefix,
+}: {
+ bucketName?: string;
+ prefix: string | null;
+}) {
+ const { org, project } = await createOrgProjectAndApiKey();
+ orgIds.push(org.id);
+ await enableExternalMediaStorage(org.id);
+ await prisma.externalMediaStorageIntegration.create({
+ data: {
+ projectId: project.id,
+ type: "S3",
+ bucketName,
+ prefix,
+ accessKeyId: `access-${randomUUID()}`,
+ secretAccessKey: encrypt("test-secret-key"),
+ region: "us-east-1",
+ endpoint: null,
+ forcePathStyle: false,
+ },
+ });
+ return project;
+}
+
+describe("external media storage service", () => {
+ afterEach(() => {
+ vi.clearAllMocks();
+ });
+
+ afterAll(async () => {
+ await prisma.organization.deleteMany({ where: { id: { in: orgIds } } });
+ });
+
+ it("uses the organization default as the feature gate", async () => {
+ const { org, project } = await createOrgProjectAndApiKey();
+ orgIds.push(org.id);
+ const service = createExternalMediaStorageService(prisma);
+
+ await expect(service.isFeatureEnabled(project.id)).resolves.toBe(false);
+ await expect(service.getConfiguration(project.id)).rejects.toThrow(
+ "External media storage is not enabled for this organization",
+ );
+
+ await enableExternalMediaStorage(org.id);
+
+ await expect(service.isFeatureEnabled(project.id)).resolves.toBe(true);
+ await expect(service.getConfiguration(project.id)).resolves.toBeNull();
+ });
+
+ it("never returns the stored secret in configuration responses", async () => {
+ const project = await prepareIntegration({ prefix: null });
+
+ const configuration = await createExternalMediaStorageService(
+ prisma,
+ ).getConfiguration(project.id);
+
+ expect(configuration).not.toHaveProperty("secretAccessKey");
+ expect(configuration?.secretAccessKeyDisplay).not.toContain(
+ "test-secret-key",
+ );
+ });
+
+ it("clears S3-compatible endpoint settings when switching to Amazon S3", async () => {
+ const project = await prepareIntegration({ prefix: null });
+ await prisma.externalMediaStorageIntegration.update({
+ where: { projectId: project.id },
+ data: {
+ type: "S3_COMPATIBLE",
+ endpoint: "https://storage.example.com",
+ forcePathStyle: true,
+ },
+ });
+
+ await createExternalMediaStorageService(prisma).saveConfiguration({
+ actor: { apiKeyId: "test-api-key", orgId: project.orgId },
+ projectId: project.id,
+ values: {
+ type: "S3",
+ bucketName: "media-bucket",
+ endpoint: "https://stale.example.com",
+ region: "us-east-1",
+ accessKeyId: "access-key",
+ secretAccessKey: "",
+ prefix: "",
+ forcePathStyle: true,
+ },
+ });
+
+ await expect(
+ prisma.externalMediaStorageIntegration.findUniqueOrThrow({
+ where: { projectId: project.id },
+ select: { endpoint: true, forcePathStyle: true },
+ }),
+ ).resolves.toEqual({ endpoint: null, forcePathStyle: false });
+ });
+
+ it("signs an object within the configured bucket and prefix", async () => {
+ const getSignedUrl = vi.fn().mockResolvedValue("https://signed.example");
+ (StorageServiceFactory.getInstance as Mock).mockReturnValue({
+ getSignedUrl,
+ });
+ const project = await prepareIntegration({ prefix: "customer/" });
+
+ const result = await createExternalMediaStorageService(prisma).resolveUrl({
+ projectId: project.id,
+ uri: "s3://media-bucket/customer/image.png",
+ });
+
+ expect(result.url).toBe("https://signed.example");
+ expect(getSignedUrl).toHaveBeenCalledWith("customer/image.png", 300, false);
+ });
+
+ it("allows any object in the bucket when no prefix is configured", async () => {
+ const getSignedUrl = vi.fn().mockResolvedValue("https://signed.example");
+ (StorageServiceFactory.getInstance as Mock).mockReturnValue({
+ getSignedUrl,
+ });
+ const project = await prepareIntegration({ prefix: null });
+
+ await createExternalMediaStorageService(prisma).resolveUrl({
+ projectId: project.id,
+ uri: "s3://media-bucket/any/directory/image.png",
+ });
+
+ expect(getSignedUrl).toHaveBeenCalledWith(
+ "any/directory/image.png",
+ 300,
+ false,
+ );
+ });
+
+ it.each([
+ ["a sibling prefix", "s3://media-bucket/customer-other/image.png"],
+ ["another bucket", "s3://other-bucket/customer/image.png"],
+ ])("rejects %s", async (_case, uri) => {
+ const project = await prepareIntegration({ prefix: "customer/" });
+
+ await expect(
+ createExternalMediaStorageService(prisma).resolveUrl({
+ projectId: project.id,
+ uri,
+ }),
+ ).rejects.toThrow("External media is not available");
+ expect(StorageServiceFactory.getInstance).not.toHaveBeenCalled();
+ });
+
+ it("does not use another project's integration", async () => {
+ const configuredProject = await prepareIntegration({ prefix: null });
+ const { org, project: otherProject } = await createOrgProjectAndApiKey();
+ orgIds.push(org.id);
+ await enableExternalMediaStorage(org.id);
+
+ await expect(
+ createExternalMediaStorageService(prisma).resolveUrl({
+ projectId: otherProject.id,
+ uri: "s3://media-bucket/image.png",
+ }),
+ ).rejects.toThrow("External media is not available");
+ expect(configuredProject.id).not.toBe(otherProject.id);
+ expect(StorageServiceFactory.getInstance).not.toHaveBeenCalled();
+ });
+});
diff --git a/web/src/__tests__/server/mcp-tools-write.servertest.ts b/web/src/__tests__/server/mcp-tools-write.servertest.ts
index c27849beae..eb05783cd6 100644
--- a/web/src/__tests__/server/mcp-tools-write.servertest.ts
+++ b/web/src/__tests__/server/mcp-tools-write.servertest.ts
@@ -92,6 +92,13 @@ import {
handleTestEvaluator,
testEvaluatorTool,
} from "@/src/features/mcp/server/evals/tools/testEvaluator";
+import {
+ deleteExternalMediaStorageTool,
+ handleConfigureExternalMediaStorage,
+ handleDeleteExternalMediaStorage,
+ handleGetExternalMediaStorage,
+} from "@/src/features/mcp/server/externalMediaStorage/tools";
+import { externalMediaStorageFeature } from "@/src/features/mcp/server/externalMediaStorage";
import { evalsFeature } from "@/src/features/mcp/server/evals";
import { handleGetEvaluationRule } from "@/src/features/mcp/server/evals/tools/getEvaluationRule";
import { EvaluatorService } from "@/src/features/evals/v2/server/evaluators/evaluatorService";
@@ -1973,6 +1980,71 @@ describe("MCP Write Tools", () => {
});
});
+ describe("external media storage tools", () => {
+ it("configures, reads, and deletes project storage with audit logs", async () => {
+ const setup = await createMcpTestSetup();
+
+ await expect(
+ externalMediaStorageFeature.isEnabled(setup.context),
+ ).resolves.toBe(false);
+ await prisma.organization.update({
+ where: { id: setup.context.orgId },
+ data: { featureFlagOrgDefaults: ["externalMediaStorage"] },
+ });
+ await expect(
+ externalMediaStorageFeature.isEnabled(setup.context),
+ ).resolves.toBe(true);
+
+ await expect(
+ handleConfigureExternalMediaStorage(
+ {
+ type: "S3",
+ bucketName: "media-bucket",
+ region: "us-east-1",
+ accessKeyId: "test-access-key",
+ secretAccessKey: "test-secret-key",
+ prefix: "media/",
+ forcePathStyle: false,
+ },
+ setup.context,
+ ),
+ ).resolves.toEqual({ success: true });
+
+ await expect(
+ handleGetExternalMediaStorage({}, setup.context),
+ ).resolves.toMatchObject({
+ bucketName: "media-bucket",
+ prefix: "media/",
+ secretAccessKeyDisplay: expect.not.stringContaining("test-secret-key"),
+ });
+ await expect(
+ verifyAuditLog({
+ projectId: setup.projectId,
+ apiKeyId: setup.apiKeyId,
+ resourceType: "externalMediaStorageIntegration",
+ resourceId: setup.projectId,
+ action: "update",
+ }),
+ ).resolves.toBeDefined();
+
+ verifyToolAnnotations(deleteExternalMediaStorageTool, {
+ destructiveHint: true,
+ });
+ await expect(
+ handleDeleteExternalMediaStorage({}, setup.context),
+ ).resolves.toEqual({ success: true });
+ await expect(
+ verifyAuditLog({
+ projectId: setup.projectId,
+ apiKeyId: setup.apiKeyId,
+ resourceType: "externalMediaStorageIntegration",
+ resourceId: setup.projectId,
+ action: "delete",
+ }),
+ ).resolves.toBeDefined();
+ });
+ });
+
describe("in-app-agent protected prompt labels", () => {
it.each([
{
diff --git a/web/src/__tests__/server/organization-feature-flags.servertest.ts b/web/src/__tests__/server/organization-feature-flags.servertest.ts
index b9495bb538..44b0c03272 100644
--- a/web/src/__tests__/server/organization-feature-flags.servertest.ts
+++ b/web/src/__tests__/server/organization-feature-flags.servertest.ts
@@ -133,6 +133,21 @@ describe("organization feature preview defaults", () => {
).rejects.toMatchObject({ code: "PRECONDITION_FAILED" });
});
+ it("enables organization-only previews without a personal preview", async () => {
+ const { caller, org } = await prepare();
+
+ await expect(
+ caller.organizations.setFeatureFlagOrgDefault({
+ orgId: org.id,
+ flag: "externalMediaStorage",
+ enabled: true,
+ }),
+ ).resolves.toMatchObject({
+ defaults: ["externalMediaStorage"],
+ enabled: true,
+ });
+ });
+
it("rejects internal flags at the input boundary", async () => {
const { caller, org } = await prepare();
@@ -232,6 +247,7 @@ describe("organization feature preview defaults", () => {
// not a registered preview, so it is filtered out rather than surfacing
// here. Asserting that two REGISTERED defaults resolve differently needs
// a second preview; add that half back with the next one.
+ externalMediaStorage: false,
modernSession: false,
sessionTimeline: false,
});
@@ -492,6 +508,7 @@ describe("organization member feature preview overrides", () => {
// The state map surfaces every preview; the raw `featureFlags` array stays
// hidden, which is what this guards.
expect(row?.featurePreviews).toEqual({
+ externalMediaStorage: false,
modernSession: true,
sessionTimeline: false,
});
diff --git a/web/src/components/MediaTag/MediaTag.tsx b/web/src/components/MediaTag/MediaTag.tsx
index 85200831b5..c4e869fb91 100644
--- a/web/src/components/MediaTag/MediaTag.tsx
+++ b/web/src/components/MediaTag/MediaTag.tsx
@@ -47,6 +47,8 @@ export interface MediaTagProps {
label?: string;
/** Optional context shown above the preview in the peek popover. */
description?: string;
+ /** Optional raw reference shown inside the unavailable-media fallback. */
+ errorDetail?: string;
/** Optional text label for the open action. The default is icon-only. */
openActionLabel?: string;
/** Visual framing for the collapsed chip. */
@@ -174,18 +176,25 @@ function PeekBody({
kind,
status,
url,
+ errorDetail,
onPreviewError,
}: {
kind: MediaKind;
status: MediaTagStatus;
url?: string;
+ errorDetail?: string;
onPreviewError: () => void;
}) {
if (status === "error") {
return (
- <div className="text-muted-foreground flex h-24 w-64 flex-col items-center justify-center gap-2">
+ <div className="text-muted-foreground flex min-h-24 w-64 flex-col items-center justify-center gap-2 p-2">
<ImageOff className="icon-lg" />
<span className="text-xs">Failed to load media</span>
+ {errorDetail ? (
+ <code className="max-w-full text-left text-[10px] leading-4 break-all select-text">
+ {errorDetail}
+ </code>
+ ) : null}
</div>
);
}
@@ -214,6 +223,7 @@ export const MediaTag = React.forwardRef<HTMLButtonElement, MediaTagProps>(
contentLength,
label,
description,
+ errorDetail,
openActionLabel,
intent,
open,
@@ -305,6 +315,7 @@ export const MediaTag = React.forwardRef<HTMLButtonElement, MediaTagProps>(
kind={kind}
status={previewStatus}
url={url}
+ errorDetail={errorDetail}
onPreviewError={() => setFailedPreviewUrl(url ?? null)}
/>
</div>
diff --git a/web/src/components/ui/MarkdownJsonView.tsx b/web/src/components/ui/MarkdownJsonView.tsx
index b2c82e96a2..7a13fb5d22 100644
--- a/web/src/components/ui/MarkdownJsonView.tsx
+++ b/web/src/components/ui/MarkdownJsonView.tsx
@@ -1,5 +1,6 @@
/* eslint-disable @repo/no-style-props */
import {
+ OpenAIContentParts,
OpenAIContentSchema,
type OpenAIOutputAudioType,
} from "@langfuse/shared";
@@ -12,6 +13,7 @@ import { useMemo, useState } from "react";
import { type z } from "zod";
import { useMarkdownRenderCharacterLimit } from "@/src/hooks/useMarkdownRenderCharacterLimit";
import { cn } from "@/src/utils/tailwind";
+import { classifyMediaValue } from "@/src/components/ui/media/mediaUtils";
type MarkdownJsonViewHeaderProps = {
title: string | React.ReactNode;
@@ -99,10 +101,36 @@ export const canRenderContentAsMarkdown = (
content: unknown,
characterLimit: number,
): content is z.input<typeof OpenAIContentSchema> =>
- OpenAIContentSchema.safeParse(content).success &&
+ (OpenAIContentSchema.safeParse(content).success ||
+ isOpenAIContentWithExternalS3Image(content)) &&
// Don't render if markdown content is huge
JSON.stringify(content || {}).length <= characterLimit;
+const isOpenAIContentWithExternalS3Image = (content: unknown) => {
+ if (!Array.isArray(content)) return false;
+
+ let hasExternalS3Image = false;
+ const hasOnlyRenderableParts = content.every((part) => {
+ if (
+ typeof part === "object" &&
+ part !== null &&
+ part.type === "image_url" &&
+ typeof part.image_url === "object" &&
+ part.image_url !== null
+ ) {
+ const descriptor = classifyMediaValue(part.image_url.url);
+ if (descriptor?.kind === "s3") {
+ hasExternalS3Image = true;
+ return true;
+ }
+ }
+
+ return OpenAIContentParts.safeParse([part]).success;
+ });
+
+ return hasExternalS3Image && hasOnlyRenderableParts;
+};
+
// MarkdownJsonView renders markdown whenever the content is valid markdown
// (see canRenderContentAsMarkdown), otherwise it falls back to JSON.
export function MarkdownJsonView({
diff --git a/web/src/components/ui/MarkdownViewer.clienttest.tsx b/web/src/components/ui/MarkdownViewer.clienttest.tsx
index 7a9523ce68..aaa0879739 100644
--- a/web/src/components/ui/MarkdownViewer.clienttest.tsx
+++ b/web/src/components/ui/MarkdownViewer.clienttest.tsx
@@ -1,12 +1,13 @@
/* eslint-disable @repo/prefer-stories-over-client-tests */
-import { render } from "@testing-library/react";
+import { render, screen } from "@testing-library/react";
import {
MarkdownView,
prependBasePathToInternalHref,
} from "@/src/components/ui/MarkdownViewer";
+import { MarkdownJsonView } from "@/src/components/ui/MarkdownJsonView";
vi.mock("next/router", () => ({
- useRouter: () => ({ query: {} }),
+ useRouter: () => ({ query: { projectId: "project-1" } }),
}));
vi.mock("next-themes", () => ({
@@ -17,9 +18,71 @@ vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({
usePostHogClientCapture: () => vi.fn(),
}));
+const { resolveExternalMediaQueryMock } = vi.hoisted(() => ({
+ resolveExternalMediaQueryMock: vi.fn(() => ({
+ isError: false,
+ data: undefined,
+ refetch: vi.fn(),
+ })),
+}));
+
+vi.mock("@/src/utils/api", () => ({
+ api: {
+ media: {
+ resolveExternalMedia: {
+ useQuery: resolveExternalMediaQueryMock,
+ },
+ },
+ },
+}));
+
+vi.mock("@/src/features/feature-flags", () => ({
+ useIsFeatureEnabled: () => true,
+}));
+
const renderMarkdown = (markdown: string) =>
render(<MarkdownView markdown={markdown} />);
+describe("MarkdownView external S3 media", () => {
+ it("renders a standalone S3 media URI as external media", () => {
+ const uri = "s3://customer-bucket/media/photo.png";
+
+ renderMarkdown(uri);
+
+ expect(
+ screen.getByRole("button", { name: "PNG media" }),
+ ).toBeInTheDocument();
+ expect(resolveExternalMediaQueryMock).toHaveBeenCalledWith(
+ { projectId: "project-1", uri },
+ expect.objectContaining({ enabled: false }),
+ );
+ });
+
+ it("renders a Markdown S3 image and preserves its alt text", () => {
+ const uri = "s3://customer-bucket/media/photo.png";
+
+ renderMarkdown(`![Product photo](${uri})`);
+
+ expect(
+ screen.getByRole("button", { name: "Product photo media" }),
+ ).toBeInTheDocument();
+ });
+
+ it("renders an OpenAI image_url S3 URI as external media", () => {
+ const uri = "s3://customer-bucket/media/photo.png";
+
+ render(
+ <MarkdownJsonView
+ content={[{ type: "image_url", image_url: { url: uri } }]}
+ />,
+ );
+
+ expect(
+ screen.getByRole("button", { name: "PNG media" }),
+ ).toBeInTheDocument();
+ });
+});
+
describe("MarkdownView link rendering", () => {
it("renders an external link as a native anchor opening in a new tab", () => {
const { container } = renderMarkdown("[example](https://example.com/page)");
diff --git a/web/src/components/ui/MarkdownViewer.tsx b/web/src/components/ui/MarkdownViewer.tsx
index 4700c5bd72..0ded7e7d63 100644
--- a/web/src/components/ui/MarkdownViewer.tsx
+++ b/web/src/components/ui/MarkdownViewer.tsx
@@ -14,6 +14,7 @@ import {
import ReactMarkdown, {
type Options,
type ExtraProps as ReactMarkdownExtraProps,
+ defaultUrlTransform,
} from "react-markdown";
import remarkGfm from "remark-gfm";
import { Codeblock as CodeBlock } from "@/src/components/design-system/Codeblock/Codeblock";
@@ -28,7 +29,6 @@ import {
type OpenAIContentSchema,
type OpenAIOutputAudioType,
isOpenAITextContentPart,
- isOpenAIImageContentPart,
isMediaReferencePart,
isAiSdkFileContentPart,
} from "@langfuse/shared";
@@ -59,6 +59,11 @@ import {
} from "@/src/components/ui/markdown-media.utils";
import { exceedsMarkdownRenderLimits } from "@/src/components/ui/markdown-render-limits";
import { useMarkdownRenderCharacterLimit } from "@/src/hooks/useMarkdownRenderCharacterLimit";
+import {
+ classifyMediaValue,
+ type MediaDescriptor,
+} from "@/src/components/ui/media/mediaUtils";
+import { MediaReferenceTag } from "@/src/components/ui/media/MediaReferenceTag";
type ReactMarkdownNode = ReactMarkdownExtraProps["node"];
type ReactMarkdownNodeChildren = Exclude<
@@ -253,6 +258,15 @@ function MarkdownCode({
const remarkPluginsDefault = [remarkGfm];
const remarkPluginsWithPromptRefs = [remarkGfm, remarkPromptReferences];
+const markdownUrlTransform: NonNullable<Options["urlTransform"]> = (
+ url,
+ key,
+) => {
+ const descriptor = classifyMediaValue(url);
+ return key === "src" && descriptor?.kind === "s3"
+ ? url
+ : defaultUrlTransform(url);
+};
// Module-level so custom-element types stay stable across parent re-renders.
// Inline renderers (especially `pre`, which wraps fenced `code`) are a new
@@ -356,6 +370,13 @@ const markdownComponents: NonNullable<Options["components"]> = {
);
},
img({ src, alt }) {
+ const descriptor = classifyMediaValue(src);
+ if (descriptor?.kind === "s3") {
+ return (
+ <MediaReferenceTag descriptor={descriptor} label={alt || undefined} />
+ );
+ }
+
const safeSrc = typeof src === "string" ? getSafeImageUrl(src) : null;
return safeSrc ? <ResizableImage src={safeSrc} alt={alt} /> : null;
},
@@ -442,6 +463,7 @@ function MarkdownRenderer({
: remarkPluginsDefault
}
components={markdownComponents}
+ urlTransform={markdownUrlTransform}
>
{markdown}
</MemoizedReactMarkdown>
@@ -511,6 +533,8 @@ export function MarkdownView({
const markdownContent =
typeof markdown === "string" ? markdown : parseOpenAIContentParts(markdown);
+ const standaloneMediaDescriptor: MediaDescriptor | null =
+ typeof markdown === "string" ? classifyMediaValue(markdown) : null;
// Collapse preview is built from text parts only: serialized image/audio
// parts (media-reference strings, base64 data URIs) neither survive the
@@ -589,7 +613,9 @@ export function MarkdownView({
>
{typeof markdown === "string" ? (
// plain string
- inlineMediaReferenceStrings.length > 0 ? (
+ standaloneMediaDescriptor?.kind === "s3" ? (
+ <MediaReferenceTag descriptor={standaloneMediaDescriptor} />
+ ) : inlineMediaReferenceStrings.length > 0 ? (
inlineMediaReferenceStrings.map((referenceString, index) => (
<LangfuseMediaView
key={`${referenceString}-${index}`}
@@ -677,8 +703,14 @@ export function MarkdownView({
return <MarkdownRenderer key={index} markdown={content.text} />;
}
- if (isOpenAIImageContentPart(content)) {
+ if (content.type === "image_url") {
const imageUrl = content.image_url.url;
+ const descriptor = classifyMediaValue(imageUrl);
+
+ if (descriptor?.kind === "s3") {
+ return <MediaReferenceTag key={index} descriptor={descriptor} />;
+ }
+
const safeImageUrl =
typeof imageUrl === "string" &&
OpenAIUrlImageUrl.safeParse(imageUrl).success
diff --git a/web/src/components/ui/media/MediaReferenceTag.tsx b/web/src/components/ui/media/MediaReferenceTag.tsx
index 55c5ddcbde..7cee646469 100644
--- a/web/src/components/ui/media/MediaReferenceTag.tsx
+++ b/web/src/components/ui/media/MediaReferenceTag.tsx
@@ -1,10 +1,29 @@
import { useState } from "react";
-import { MediaTag } from "../../MediaTag/MediaTag";
+import { MediaTag, type MediaTagStatus } from "../../MediaTag/MediaTag";
import { useResolvedMedia } from "./useResolvedMedia";
import { type MediaDescriptor } from "./mediaUtils";
import { OBSERVATION_FIELD_SIZE_LIMIT_MEDIA_SOURCE } from "@langfuse/shared";
+import { api } from "@/src/utils/api";
+import { useRouter } from "next/router";
+import { useIsFeatureEnabled } from "@/src/features/feature-flags";
type LangfuseRefDescriptor = Extract<MediaDescriptor, { kind: "langfuseRef" }>;
+type S3Descriptor = Extract<MediaDescriptor, { kind: "s3" }>;
+
+function getS3MediaStatus({
+ armed,
+ isError,
+ hasData,
+}: {
+ armed: boolean;
+ isError: boolean;
+ hasData: boolean;
+}): MediaTagStatus {
+ if (!armed) return "idle";
+ if (isError) return "error";
+ if (hasData) return "ready";
+ return "loading";
+}
/**
* Container that connects a classified media value to the pure `MediaTag`: it
@@ -13,9 +32,15 @@ type LangfuseRefDescriptor = Extract<MediaDescriptor, { kind: "langfuseRef" }>;
*/
export function MediaReferenceTag({
descriptor,
+ label,
}: {
descriptor: MediaDescriptor;
+ label?: string;
}) {
+ if (descriptor.kind === "s3") {
+ return <S3MediaTag descriptor={descriptor} label={label} />;
+ }
+
if (descriptor.kind !== "langfuseRef") {
return (
<MediaTag
@@ -29,6 +54,65 @@ export function MediaReferenceTag({
return <LangfuseRefMediaTag descriptor={descriptor} />;
}
+function S3MediaTag({
+ descriptor,
+ label,
+}: {
+ descriptor: S3Descriptor;
+ label?: string;
+}) {
+ const router = useRouter();
+ const projectId =
+ typeof router.query.projectId === "string"
+ ? router.query.projectId
+ : undefined;
+ const isFeatureEnabled = useIsFeatureEnabled("externalMediaStorage", {
+ enableForAdmins: false,
+ projectId,
+ });
+ const [armed, setArmed] = useState(false);
+ const [open, setOpen] = useState(false);
+ const resolved = api.media.resolveExternalMedia.useQuery(
+ { projectId: projectId ?? "", uri: descriptor.uri },
+ {
+ enabled: armed && isFeatureEnabled && Boolean(projectId),
+ staleTime: 4 * 60 * 1000,
+ refetchInterval: open ? 4 * 60 * 1000 : false,
+ retry: false,
+ meta: { silentHttpCodes: [404] },
+ },
+ );
+
+ if (!isFeatureEnabled) return descriptor.uri;
+
+ const isSignedUrlExpired =
+ resolved.data?.expiresAt !== undefined &&
+ resolved.data.expiresAt.getTime() <= Date.now();
+ const status = getS3MediaStatus({
+ armed,
+ isError: resolved.isError,
+ hasData: Boolean(resolved.data) && !isSignedUrlExpired,
+ });
+
+ return (
+ <MediaTag
+ contentType={descriptor.contentType}
+ label={label}
+ status={status}
+ url={isSignedUrlExpired ? undefined : resolved.data?.url}
+ errorDetail={descriptor.uri}
+ open={open}
+ onOpenChange={(nextOpen) => {
+ setOpen(nextOpen);
+ if (nextOpen) {
+ if (armed && isSignedUrlExpired) resolved.refetch();
+ setArmed(true);
+ }
+ }}
+ />
+ );
+}
+
function LangfuseRefMediaTag({
descriptor,
}: {
diff --git a/web/src/components/ui/media/mediaUtils.clienttest.ts b/web/src/components/ui/media/mediaUtils.clienttest.ts
index 98df0c8fd5..3dfe7564d6 100644
--- a/web/src/components/ui/media/mediaUtils.clienttest.ts
+++ b/web/src/components/ui/media/mediaUtils.clienttest.ts
@@ -144,6 +144,17 @@ describe("classifyMediaValue", () => {
).toBe("audio/mpeg");
});
+ it("classifies S3 media URIs by object extension", () => {
+ expect(classifyMediaValue("s3://media-bucket/path/image.png")).toEqual({
+ kind: "s3",
+ contentType: "image/png",
+ uri: "s3://media-bucket/path/image.png",
+ });
+ expect(
+ classifyMediaValue("s3://media-bucket/path/no-extension"),
+ ).toBeNull();
+ });
+
it("ignores non-media and malformed inputs", () => {
expect(classifyMediaValue("https://example.com/page")).toBeNull();
expect(classifyMediaValue("just a string")).toBeNull();
diff --git a/web/src/components/ui/media/mediaUtils.ts b/web/src/components/ui/media/mediaUtils.ts
index 6ea8f3c15c..9ffa613825 100644
--- a/web/src/components/ui/media/mediaUtils.ts
+++ b/web/src/components/ui/media/mediaUtils.ts
@@ -1,4 +1,4 @@
-import { MediaReferenceStringSchema } from "@langfuse/shared";
+import { MediaReferenceStringSchema, parseS3Uri } from "@langfuse/shared";
const LANGFUSE_MEDIA_PREFIX = "@@@langfuseMedia:";
const LANGFUSE_MEDIA_REFERENCE_PATTERN = /@@@langfuseMedia:[^@]*@@@/g;
@@ -101,6 +101,14 @@ export function classifyMediaValue(value: unknown) {
return { kind: "url" as const, contentType, src: value };
}
+ if (value.startsWith("s3://")) {
+ const parsed = parseS3Uri(value);
+ if (!parsed) return null;
+ const contentType = mimeFromPath(parsed.key);
+ if (!contentType) return null;
+ return { kind: "s3" as const, contentType, uri: value };
+ }
+
return null;
}
@@ -153,6 +161,10 @@ function mimeFromUrl(url: string) {
} catch {
return null;
}
+ return mimeFromPath(pathname);
+}
+
+function mimeFromPath(pathname: string) {
const ext = pathname.split(".").pop()?.toLowerCase();
if (!ext || ext === pathname) return null;
return URL_EXTENSION_TO_MIME[ext] ?? null;
diff --git a/web/src/features/audit-logs/auditLog.ts b/web/src/features/audit-logs/auditLog.ts
index 4513e26ce5..7d1877e58f 100644
--- a/web/src/features/audit-logs/auditLog.ts
+++ b/web/src/features/audit-logs/auditLog.ts
@@ -37,6 +37,7 @@ type AuditableResource =
| "evalTemplate"
| "job"
| "blobStorageIntegration"
+ | "externalMediaStorageIntegration"
| "posthogIntegration"
| "mixpanelIntegration"
| "webCalloutEndpoint"
diff --git a/web/src/features/external-media-storage/ExternalMediaStoragePage.tsx b/web/src/features/external-media-storage/ExternalMediaStoragePage.tsx
new file mode 100644
index 0000000000..8e7499b97d
--- /dev/null
+++ b/web/src/features/external-media-storage/ExternalMediaStoragePage.tsx
@@ -0,0 +1,260 @@
+import Link from "next/link";
+import { useRouter } from "next/router";
+
+import ContainerPage from "@/src/components/layouts/container-page";
+import Header from "@/src/components/layouts/header";
+import { Button as DesignSystemButton } from "@/src/components/design-system/Button/Button";
+import { ConfirmationDialogController } from "@/src/components/design-system/ConfirmationDialogController/ConfirmationDialogController";
+import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
+import { Tooltip } from "@/src/components/design-system/Tooltip/Tooltip";
+import { Button } from "@/src/components/ui/button";
+import { Card } from "@/src/components/ui/card";
+import { IntegrationSettingsSkeleton } from "@/src/features/analytics-integrations";
+import { ExternalMediaStorageForm } from "@/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm";
+import { TestMediaObjectDialog } from "@/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog";
+import { testSignedMediaUrlCors } from "@/src/features/external-media-storage/fns/testSignedMediaUrlCors";
+import { type ExternalMediaStorageFormValues } from "@/src/features/external-media-storage/types";
+import { useHasProjectAccess } from "@/src/features/rbac";
+import { showErrorToast, showSuccessToast } from "@/src/features/notifications";
+import { api } from "@/src/utils/api";
+
+const EXTERNAL_MEDIA_STORAGE_FORM_ID = "external-media-storage-form";
+
+const defaultValues: ExternalMediaStorageFormValues = {
+ type: "S3",
+ bucketName: "",
+ endpoint: null,
+ region: "us-east-1",
+ accessKeyId: "",
+ secretAccessKey: "",
+ prefix: "",
+ forcePathStyle: false,
+};
+
+export default function ExternalMediaStoragePage() {
+ const router = useRouter();
+ const projectId = router.query.projectId as string;
+ const hasAccess = useHasProjectAccess({
+ projectId,
+ scope: "integrations:CRUD",
+ });
+ const featureAvailability =
+ api.externalMediaStorage.isFeatureEnabled.useQuery(
+ { projectId },
+ { enabled: Boolean(projectId) },
+ );
+ const isFeatureEnabled = featureAvailability.data === true;
+ const canLoadConfig = Boolean(projectId && hasAccess && isFeatureEnabled);
+ const utils = api.useUtils();
+ const configuration = api.externalMediaStorage.get.useQuery(
+ { projectId },
+ { enabled: canLoadConfig },
+ );
+ const updateMutation = api.externalMediaStorage.update.useMutation({
+ onSuccess: async () => {
+ await utils.externalMediaStorage.get.invalidate({ projectId });
+ showSuccessToast({
+ title: "External media storage saved",
+ description: "The integration configuration has been saved.",
+ });
+ },
+ onError: (error) => {
+ showErrorToast("Failed to save external media storage", error.message);
+ },
+ });
+ const deleteMutation = api.externalMediaStorage.delete.useMutation({
+ onSuccess: async () => {
+ await utils.externalMediaStorage.get.invalidate({ projectId });
+ showSuccessToast({
+ title: "External media storage deleted",
+ description: "The integration configuration has been deleted.",
+ });
+ },
+ onError: (error) => {
+ showErrorToast("Failed to delete external media storage", error.message);
+ },
+ });
+ const testMutation = api.externalMediaStorage.testObject.useMutation();
+ const config = configuration.data?.config;
+ const initialValues: ExternalMediaStorageFormValues = config
+ ? {
+ type: config.type,
+ bucketName: config.bucketName,
+ endpoint: config.endpoint,
+ region: config.region,
+ accessKeyId: config.accessKeyId ?? "",
+ secretAccessKey: "",
+ prefix: config.prefix ?? "",
+ forcePathStyle: config.forcePathStyle,
+ }
+ : defaultValues;
+
+ const renderTestAction = () => {
+ if (config) {
+ return (
+ <DialogController
+ renderDialog={() => (
+ <TestMediaObjectDialog
+ isPending={testMutation.isPending}
+ onTest={async (uri) => {
+ try {
+ const result = await testMutation.mutateAsync({
+ projectId,
+ uri,
+ });
+ await testSignedMediaUrlCors(result.signedUrl);
+ return result.signedUrl;
+ } catch (error) {
+ showErrorToast(
+ "External media test failed",
+ error instanceof Error
+ ? error.message
+ : "The media object could not be loaded.",
+ );
+ return null;
+ }
+ }}
+ />
+ )}
+ >
+ {({ openDialog }) => (
+ <DesignSystemButton
+ text="Test"
+ variant="secondary"
+ onClick={openDialog}
+ />
+ )}
+ </DialogController>
+ );
+ }
+
+ if (!config) {
+ return (
+ <Tooltip label="Save the integration before running the validation.">
+ {({ getTriggerProps }) => (
+ <span {...getTriggerProps()}>
+ <DesignSystemButton text="Test" variant="secondary" disabled />
+ </span>
+ )}
+ </Tooltip>
+ );
+ }
+
+ return null;
+ };
+
+ return (
+ <ContainerPage
+ headerProps={{
+ title: "External Media Storage",
+ breadcrumb: [
+ { name: "Settings", href: `/project/${projectId}/settings` },
+ ],
+ actionButtonsRight: (
+ <Button asChild variant="secondary">
+ <Link
+ href="https://langfuse.com/docs/observability/features/multi-modality#external-s3-media"
+ target="_blank"
+ >
+ Integration Docs ↗
+ </Link>
+ </Button>
+ ),
+ }}
+ >
+ <p className="text-primary mb-4 text-sm">
+ Resolve media referenced by s3:// URIs from your own Amazon S3 or
+ S3-compatible bucket.
+ </p>
+ {(() => {
+ if (featureAvailability.isPending) {
+ return <IntegrationSettingsSkeleton />;
+ }
+
+ if (!isFeatureEnabled) {
+ return (
+ <p className="text-sm">
+ This feature is not enabled for this project.
+ </p>
+ );
+ }
+
+ if (!hasAccess) {
+ return (
+ <p className="text-sm">
+ Your current role does not grant you access to these settings,
+ please reach out to your project admin or owner.
+ </p>
+ );
+ }
+
+ return (
+ <>
+ <Header title="Configuration" />
+ {configuration.isLoading || !configuration.data ? (
+ <Card className="p-3">
+ <IntegrationSettingsSkeleton />
+ </Card>
+ ) : (
+ <ExternalMediaStorageForm
+ key={config?.updatedAt?.toString() ?? "new"}
+ formId={EXTERNAL_MEDIA_STORAGE_FORM_ID}
+ initialValues={initialValues}
+ secretAccessKeyDisplay={config?.secretAccessKeyDisplay}
+ onSubmit={(values) =>
+ updateMutation.mutate({ projectId, ...values })
+ }
+ renderActions={({ isDirty }) => (
+ <>
+ {renderTestAction()}
+ {config ? (
+ <ConfirmationDialogController
+ title="Delete external media storage?"
+ text="Media stored in this bucket will no longer be resolved in Langfuse."
+ confirmLabel="Delete"
+ variant="destructive"
+ loading={deleteMutation.isPending}
+ onConfirm={() =>
+ deleteMutation.mutateAsync({ projectId })
+ }
+ >
+ {({ openDialog }) => (
+ <DesignSystemButton
+ text="Delete"
+ variant="destructive"
+ onClick={openDialog}
+ />
+ )}
+ </ConfirmationDialogController>
+ ) : null}
+ {!isDirty ? (
+ <Tooltip label="Make a change before saving.">
+ {({ getTriggerProps }) => (
+ <span {...getTriggerProps()}>
+ <DesignSystemButton
+ text="Save"
+ form={EXTERNAL_MEDIA_STORAGE_FORM_ID}
+ type="submit"
+ disabled
+ />
+ </span>
+ )}
+ </Tooltip>
+ ) : (
+ <DesignSystemButton
+ text="Save"
+ form={EXTERNAL_MEDIA_STORAGE_FORM_ID}
+ type="submit"
+ loading={updateMutation.isPending}
+ />
+ )}
+ </>
+ )}
+ />
+ )}
+ </>
+ );
+ })()}
+ </ContainerPage>
+ );
+}
diff --git a/web/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm.stories.tsx b/web/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm.stories.tsx
new file mode 100644
index 0000000000..0d93c6c39c
--- /dev/null
+++ b/web/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm.stories.tsx
@@ -0,0 +1,110 @@
+import { expect, fn, userEvent, within } from "storybook/test";
+
+import preview from "../../../../../.storybook/preview";
+import { Button } from "@/src/components/design-system/Button/Button";
+import { type ExternalMediaStorageFormValues } from "@/src/features/external-media-storage/types";
+
+import { ExternalMediaStorageForm } from "./ExternalMediaStorageForm";
+
+const defaultValues: ExternalMediaStorageFormValues = {
+ type: "S3",
+ bucketName: "",
+ endpoint: null,
+ region: "us-east-1",
+ accessKeyId: "",
+ secretAccessKey: "",
+ prefix: "",
+ forcePathStyle: false,
+};
+
+const onSubmit = fn();
+
+const meta = preview.meta({
+ component: ExternalMediaStorageForm,
+ args: {
+ formId: "external-media-storage-story-form",
+ initialValues: defaultValues,
+ onSubmit,
+ secretAccessKeyDisplay: null,
+ },
+ render: (args) => (
+ <div className="max-w-xl p-6">
+ <ExternalMediaStorageForm
+ {...args}
+ renderActions={({ isDirty }) => (
+ <Button
+ text="Save"
+ form="external-media-storage-story-form"
+ type="submit"
+ disabled={!isDirty}
+ />
+ )}
+ />
+ </div>
+ ),
+});
+
+export const NewAmazonS3 = meta.story({});
+
+export const S3Compatible = meta.story({
+ args: {
+ initialValues: {
+ ...defaultValues,
+ type: "S3_COMPATIBLE",
+ bucketName: "media",
+ endpoint: "https://s3.example.com",
+ forcePathStyle: true,
+ },
+ },
+});
+
+export const SavedCredentials = meta.story({
+ args: {
+ initialValues: {
+ ...defaultValues,
+ bucketName: "production-media",
+ accessKeyId: "AKIAEXAMPLE",
+ prefix: "langfuse-media/",
+ },
+ secretAccessKeyDisplay: "••••••••••••••••",
+ },
+});
+
+export const Submits = meta.story({
+ name: "(Test) Submits",
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ onSubmit.mockClear();
+
+ const saveButton = canvas.getByRole("button", { name: "Save" });
+ const bucketNameInput = canvas.getByLabelText("Bucket Name");
+ await expect(saveButton).toBeDisabled();
+ await userEvent.type(bucketNameInput, "temporary");
+ await expect(saveButton).toBeEnabled();
+ await userEvent.clear(bucketNameInput);
+ await expect(saveButton).toBeDisabled();
+
+ await userEvent.type(canvas.getByLabelText("Bucket Name"), "media-bucket");
+ await userEvent.type(canvas.getByLabelText("Access Key ID"), "access-key");
+ await userEvent.type(
+ canvas.getByLabelText("Secret Access Key"),
+ "secret-key",
+ );
+ await userEvent.type(
+ canvas.getByLabelText("Media Prefix (optional)"),
+ "media/",
+ );
+ await userEvent.click(saveButton);
+
+ await expect(onSubmit).toHaveBeenCalledWith(
+ {
+ ...defaultValues,
+ bucketName: "media-bucket",
+ accessKeyId: "access-key",
+ secretAccessKey: "secret-key",
+ prefix: "media/",
+ },
+ expect.anything(),
+ );
+ },
+});
diff --git a/web/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm.tsx b/web/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm.tsx
new file mode 100644
index 0000000000..267ebe2054
--- /dev/null
+++ b/web/src/features/external-media-storage/components/ExternalMediaStorageForm/ExternalMediaStorageForm.tsx
@@ -0,0 +1,231 @@
+import { zodResolver } from "@hookform/resolvers/zod";
+import { type ReactNode } from "react";
+import { useForm, useWatch } from "react-hook-form";
+
+import { PasswordInput } from "@/src/components/design-system/PasswordInput/PasswordInput";
+import { SelectInput } from "@/src/components/design-system/SelectInput/SelectInput";
+import { Switch } from "@/src/components/design-system/Switch/Switch";
+import { Card } from "@/src/components/ui/card";
+import {
+ Form,
+ FormControl,
+ FormDescription,
+ FormField,
+ FormItem,
+ FormLabel,
+ FormMessage,
+} from "@/src/components/ui/form";
+import { Input } from "@/src/components/ui/input";
+import {
+ externalMediaStorageFormSchema,
+ type ExternalMediaStorageFormValues,
+} from "@/src/features/external-media-storage/types";
+
+export function ExternalMediaStorageForm({
+ formId,
+ initialValues,
+ secretAccessKeyDisplay,
+ onSubmit,
+ renderActions,
+}: {
+ formId: string;
+ initialValues: ExternalMediaStorageFormValues;
+ secretAccessKeyDisplay: string | null | undefined;
+ onSubmit: (values: ExternalMediaStorageFormValues) => void;
+ renderActions?: (state: { isDirty: boolean }) => ReactNode;
+}) {
+ const form = useForm({
+ resolver: zodResolver(externalMediaStorageFormSchema),
+ defaultValues: initialValues,
+ });
+ const type = useWatch({ control: form.control, name: "type" }) ?? "S3";
+
+ return (
+ <Form {...form}>
+ <>
+ <Card className="p-3">
+ <form
+ id={formId}
+ className="space-y-4"
+ onSubmit={form.handleSubmit(onSubmit)}
+ >
+ <FormField
+ control={form.control}
+ name="type"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Storage Provider</FormLabel>
+ <FormControl>
+ <SelectInput
+ value={field.value}
+ onValueChange={(value) => {
+ field.onChange(value);
+ if (value === "S3") {
+ form.setValue("endpoint", null);
+ form.setValue("forcePathStyle", false);
+ }
+ }}
+ placeholder="Select a storage provider"
+ options={[
+ {
+ value: "S3",
+ label: "Amazon S3",
+ },
+ {
+ value: "S3_COMPATIBLE",
+ label: "S3 Compatible Storage",
+ },
+ ]}
+ />
+ </FormControl>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+
+ <FormField
+ control={form.control}
+ name="bucketName"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Bucket Name</FormLabel>
+ <FormControl>
+ <Input {...field} />
+ </FormControl>
+ <FormDescription>
+ The S3 bucket containing media.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+
+ {type === "S3_COMPATIBLE" ? (
+ <>
+ <FormField
+ control={form.control}
+ name="endpoint"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Endpoint URL</FormLabel>
+ <FormControl>
+ <Input {...field} value={field.value ?? ""} />
+ </FormControl>
+ <FormDescription>
+ The endpoint for your S3-compatible storage.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+ <FormField
+ control={form.control}
+ name="forcePathStyle"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Force Path Style</FormLabel>
+ <FormControl>
+ <Switch
+ checked={field.value}
+ onCheckedChange={field.onChange}
+ />
+ </FormControl>
+ <FormDescription>
+ Enable for MinIO and providers requiring path-style
+ URLs.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+ </>
+ ) : null}
+
+ <FormField
+ control={form.control}
+ name="region"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Region</FormLabel>
+ <FormControl>
+ <Input {...field} />
+ </FormControl>
+ <FormDescription>
+ AWS or S3-compatible storage region.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+
+ <FormField
+ control={form.control}
+ name="accessKeyId"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Access Key ID</FormLabel>
+ <FormControl>
+ <Input {...field} />
+ </FormControl>
+ <FormDescription>
+ Access key used to read media objects.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+
+ <FormField
+ control={form.control}
+ name="secretAccessKey"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>Secret Access Key</FormLabel>
+ <FormControl>
+ <PasswordInput
+ {...field}
+ value={field.value ?? ""}
+ placeholder={
+ secretAccessKeyDisplay ?? "********************"
+ }
+ />
+ </FormControl>
+ <FormDescription>
+ Leave empty to keep the saved secret.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+
+ <FormField
+ control={form.control}
+ name="prefix"
+ render={({ field }) => (
+ <FormItem>
+ <FormLabel>
+ Media Prefix{" "}
+ <span className="text-muted-foreground">(optional)</span>
+ </FormLabel>
+ <FormControl>
+ <Input {...field} value={field.value ?? ""} />
+ </FormControl>
+ <FormDescription>
+ Restrict media access to this path, for example
+ &quot;langfuse-media/&quot;.
+ </FormDescription>
+ <FormMessage />
+ </FormItem>
+ )}
+ />
+ </form>
+ </Card>
+ {renderActions ? (
+ <div className="mt-3 flex justify-end gap-2">
+ {renderActions({ isDirty: form.formState.isDirty })}
+ </div>
+ ) : null}
+ </>
+ </Form>
+ );
+}
diff --git a/web/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog.stories.tsx b/web/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog.stories.tsx
new file mode 100644
index 0000000000..3cfb304c96
--- /dev/null
+++ b/web/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog.stories.tsx
@@ -0,0 +1,69 @@
+import { expect, fn, userEvent, waitFor, within } from "storybook/test";
+
+import preview from "../../../../../.storybook/preview";
+import { DialogController } from "@/src/components/design-system/DialogController/DialogController";
+
+import { TestMediaObjectDialog } from "./TestMediaObjectDialog";
+
+const previewImage =
+ "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='320' height='180'%3E%3Crect width='320' height='180' fill='%23f1f5f9'/%3E%3Ctext x='160' y='90' text-anchor='middle' dominant-baseline='middle' font-family='sans-serif'%3EMedia preview%3C/text%3E%3C/svg%3E";
+
+function TestMediaObjectDialogStory({
+ isPending,
+ onTest,
+}: {
+ isPending: boolean;
+ onTest: (uri: string) => Promise<string | null>;
+}) {
+ return (
+ <DialogController
+ renderDialog={() => (
+ <TestMediaObjectDialog isPending={isPending} onTest={onTest} />
+ )}
+ >
+ {({ openDialog }) => (
+ <button type="button" onClick={openDialog}>
+ Test media object
+ </button>
+ )}
+ </DialogController>
+ );
+}
+
+const onTest = fn(async () => previewImage);
+
+const meta = preview.meta({
+ component: TestMediaObjectDialogStory,
+ args: {
+ isPending: false,
+ onTest,
+ },
+});
+
+export const Default = meta.story({});
+
+export const TestsAndPreviewsImage = meta.story({
+ name: "(Test) Tests and previews image",
+ play: async ({ canvasElement }) => {
+ const canvas = within(canvasElement);
+ const body = within(canvasElement.ownerDocument.body);
+ onTest.mockClear();
+
+ await userEvent.click(
+ canvas.getByRole("button", { name: "Test media object" }),
+ );
+ await userEvent.type(
+ body.getByLabelText("S3 URI"),
+ "s3://media-bucket/images/example.png",
+ );
+ await userEvent.click(body.getByRole("button", { name: "Test" }));
+
+ await expect(onTest).toHaveBeenCalledWith(
+ "s3://media-bucket/images/example.png",
+ );
+ await waitFor(() => expect(body.getByText("Preview")).toBeInTheDocument());
+ await expect(
+ body.getByRole("img", { name: "Preview example.png" }),
+ ).toBeVisible();
+ },
+});
diff --git a/web/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog.tsx b/web/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog.tsx
new file mode 100644
index 0000000000..15d7d01538
--- /dev/null
+++ b/web/src/features/external-media-storage/components/TestMediaObjectDialog/TestMediaObjectDialog.tsx
@@ -0,0 +1,152 @@
+import { parseS3Uri } from "@langfuse/shared";
+import Image from "next/image";
+import { useId, useState, type SyntheticEvent } from "react";
+
+import { MediaFileCard } from "@/src/components/MediaFileCard/MediaFileCard";
+import { Dialog } from "@/src/components/design-system/Dialog/Dialog";
+import { Input } from "@/src/components/ui/input";
+import { Label } from "@/src/components/ui/label";
+import { classifyMediaValue } from "@/src/components/ui/media/mediaUtils";
+
+export function TestMediaObjectDialog({
+ isPending,
+ onTest,
+}: {
+ isPending: boolean;
+ onTest: (uri: string) => Promise<string | null>;
+}) {
+ const [uri, setUri] = useState("");
+ const [preview, setPreview] = useState<{
+ signedUrl: string;
+ uri: string;
+ } | null>(null);
+ const formId = useId();
+ const inputId = useId();
+
+ const handleSubmit = async (event: SyntheticEvent<HTMLFormElement>) => {
+ event.preventDefault();
+ const submittedUri = uri.trim();
+ setPreview(null);
+ const signedUrl = await onTest(submittedUri);
+ setPreview(signedUrl ? { signedUrl, uri: submittedUri } : null);
+ };
+
+ return (
+ <Dialog
+ closeOnInteractionOutside
+ title="Test external media object"
+ actions={[
+ {
+ disabled: !uri.trim(),
+ form: formId,
+ label: "Test",
+ loading: isPending,
+ type: "submit",
+ },
+ ]}
+ >
+ <Dialog.Body>
+ <p className="text-muted-foreground text-sm">
+ Enter an s3:// URI to check object access and browser CORS.
+ </p>
+ <form id={formId} className="grid gap-2" onSubmit={handleSubmit}>
+ <Label htmlFor={inputId}>S3 URI</Label>
+ <Input
+ id={inputId}
+ value={uri}
+ placeholder="s3://bucket/media/image.png"
+ disabled={isPending}
+ onChange={(event) => {
+ setUri(event.target.value);
+ setPreview(null);
+ }}
+ />
+ </form>
+ {preview ? (
+ <MediaObjectPreview
+ key={preview.signedUrl}
+ signedUrl={preview.signedUrl}
+ uri={preview.uri}
+ />
+ ) : null}
+ </Dialog.Body>
+ </Dialog>
+ );
+}
+
+function MediaObjectPreview({
+ signedUrl,
+ uri,
+}: {
+ signedUrl: string;
+ uri: string;
+}) {
+ const [hasLoadError, setHasLoadError] = useState(false);
+ const descriptor = classifyMediaValue(uri);
+ const contentType = descriptor?.contentType ?? "application/octet-stream";
+ const fileName =
+ parseS3Uri(uri)?.key.split("/").pop() || "external media object";
+ const mediaType = contentType.split("/")[0];
+
+ const previewContent = (() => {
+ switch (mediaType) {
+ case "image":
+ return (
+ <Image
+ className="max-h-80 max-w-full rounded border object-contain"
+ src={signedUrl}
+ alt={`Preview ${fileName}`}
+ width={640}
+ height={360}
+ unoptimized
+ onError={() => setHasLoadError(true)}
+ />
+ );
+ case "audio":
+ return (
+ <audio
+ aria-label={`Preview ${fileName}`}
+ controls
+ className="w-full"
+ preload="metadata"
+ onError={() => setHasLoadError(true)}
+ src={signedUrl}
+ />
+ );
+ case "video":
+ return (
+ <video
+ aria-label={`Preview ${fileName}`}
+ controls
+ className="w-full"
+ preload="metadata"
+ playsInline
+ onError={() => setHasLoadError(true)}
+ src={signedUrl}
+ />
+ );
+ default:
+ return (
+ <MediaFileCard
+ contentType={contentType}
+ fileName={fileName}
+ onClick={() =>
+ window.open(signedUrl, "_blank", "noopener,noreferrer")
+ }
+ />
+ );
+ }
+ })();
+
+ return (
+ <div className="flex flex-col gap-2" aria-live="polite">
+ <p className="text-sm font-bold">Preview</p>
+ {previewContent}
+ {hasLoadError ? (
+ <p className="text-destructive text-sm">
+ The media preview could not be loaded.
+ </p>
+ ) : null}
+ </div>
+ );
+}
diff --git a/web/src/features/external-media-storage/fns/testSignedMediaUrlCors.clienttest.ts b/web/src/features/external-media-storage/fns/testSignedMediaUrlCors.clienttest.ts
new file mode 100644
index 0000000000..21595e4037
--- /dev/null
+++ b/web/src/features/external-media-storage/fns/testSignedMediaUrlCors.clienttest.ts
@@ -0,0 +1,30 @@
+import { testSignedMediaUrlCors } from "./testSignedMediaUrlCors";
+
+describe("testSignedMediaUrlCors", () => {
+ afterEach(() => {
+ vi.unstubAllGlobals();
+ });
+
+ it("requests one byte without browser credentials and closes the body", async () => {
+ const cancel = vi.fn().mockResolvedValue(undefined);
+ const fetchMock = vi.fn().mockResolvedValue({
+ body: { cancel },
+ ok: true,
+ status: 206,
+ });
+ vi.stubGlobal("fetch", fetchMock);
+
+ await testSignedMediaUrlCors("https://signed.example/object");
+
+ expect(fetchMock).toHaveBeenCalledWith(
+ "https://signed.example/object",
+ expect.objectContaining({
+ credentials: "omit",
+ headers: { Range: "bytes=0-0" },
+ mode: "cors",
+ referrerPolicy: "no-referrer",
+ }),
+ );
+ expect(cancel).toHaveBeenCalledOnce();
+ });
+});
diff --git a/web/src/features/external-media-storage/fns/testSignedMediaUrlCors.ts b/web/src/features/external-media-storage/fns/testSignedMediaUrlCors.ts
new file mode 100644
index 0000000000..34b884c4ce
--- /dev/null
+++ b/web/src/features/external-media-storage/fns/testSignedMediaUrlCors.ts
@@ -0,0 +1,26 @@
+export async function testSignedMediaUrlCors(signedUrl: string) {
+ let response: Response;
+ try {
+ response = await fetch(signedUrl, {
+ cache: "no-store",
+ credentials: "omit",
+ headers: { Range: "bytes=0-0" },
+ mode: "cors",
+ referrerPolicy: "no-referrer",
+ });
+ } catch {
+ throw new Error(
+ "The browser could not read the signed URL. Check the bucket CORS policy for this Langfuse origin.",
+ );
+ }
+
+ try {
+ if (!response.ok) {
+ throw new Error(
+ `The browser request returned HTTP ${response.status}. Check the bucket CORS policy and object access.`,
+ );
+ }
+ } finally {
+ await response.body?.cancel();
+ }
+}
diff --git a/web/src/features/external-media-storage/server/index.ts b/web/src/features/external-media-storage/server/index.ts
new file mode 100644
index 0000000000..9ce3e28f6f
--- /dev/null
+++ b/web/src/features/external-media-storage/server/index.ts
@@ -0,0 +1,2 @@
+export { externalMediaStorageRouter } from "@/src/features/external-media-storage/server/router";
+export { createExternalMediaStorageService } from "@/src/features/external-media-storage/server/service";
diff --git a/web/src/features/external-media-storage/server/repository.ts b/web/src/features/external-media-storage/server/repository.ts
new file mode 100644
index 0000000000..01cec0b462
--- /dev/null
+++ b/web/src/features/external-media-storage/server/repository.ts
@@ -0,0 +1,72 @@
+import {
+ type ExternalMediaStorageIntegration,
+ type Prisma,
+ type PrismaClient,
+} from "@langfuse/shared/src/db";
+
+export function createExternalMediaStorageRepository(prisma: PrismaClient) {
+ return {
+ async isFeatureEnabled(projectId: string) {
+ const project = await prisma.project.findUnique({
+ where: { id: projectId },
+ select: {
+ organization: {
+ select: { featureFlagOrgDefaults: true },
+ },
+ },
+ });
+
+ return (
+ project?.organization.featureFlagOrgDefaults.includes(
+ "externalMediaStorage",
+ ) ?? false
+ );
+ },
+
+ findByProjectId(projectId: string) {
+ return prisma.externalMediaStorageIntegration.findUnique({
+ where: { projectId },
+ });
+ },
+
+ findByProjectAndBucket({
+ projectId,
+ bucketName,
+ }: {
+ projectId: string;
+ bucketName: string;
+ }) {
+ return prisma.externalMediaStorageIntegration.findFirst({
+ where: {
+ projectId,
+ bucketName,
+ },
+ });
+ },
+
+ upsert({
+ projectId,
+ data,
+ }: {
+ projectId: string;
+ data: Omit<
+ Prisma.ExternalMediaStorageIntegrationUncheckedCreateInput,
+ "projectId"
+ >;
+ }) {
+ return prisma.externalMediaStorageIntegration.upsert({
+ where: { projectId },
+ create: { projectId, ...data },
+ update: data,
+ });
+ },
+
+ async deleteByProjectId(projectId: string) {
+ await prisma.externalMediaStorageIntegration.delete({
+ where: { projectId },
+ });
+ },
+ };
+}
+
+export type ExternalMediaStorageRecord = ExternalMediaStorageIntegration;
diff --git a/web/src/features/external-media-storage/server/router.ts b/web/src/features/external-media-storage/server/router.ts
new file mode 100644
index 0000000000..a2c7f83703
--- /dev/null
+++ b/web/src/features/external-media-storage/server/router.ts
@@ -0,0 +1,144 @@
+import { ForbiddenError, InvalidRequestError } from "@langfuse/shared";
+import { logger } from "@langfuse/shared/src/server";
+import { TRPCError } from "@trpc/server";
+import { z } from "zod";
+
+import { createExternalMediaStorageService } from "@/src/features/external-media-storage/server/service";
+import { externalMediaStorageFormSchema } from "@/src/features/external-media-storage/types";
+import { throwIfNoProjectAccess } from "@/src/features/rbac";
+import {
+ createTRPCRouter,
+ protectedProjectProcedure,
+ protectedProjectProcedureWithoutTracing,
+} from "@/src/server/api/trpc";
+
+function asBadRequest(error: unknown): never {
+ if (error instanceof InvalidRequestError) {
+ throw new TRPCError({ code: "BAD_REQUEST", message: error.message });
+ }
+ throw error;
+}
+
+export const externalMediaStorageRouter = createTRPCRouter({
+ isFeatureEnabled: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ throwIfNoProjectAccess({
+ projectId: input.projectId,
+ session: ctx.session,
+ scope: "project:read",
+ });
+ return createExternalMediaStorageService(ctx.prisma).isFeatureEnabled(
+ ctx.session.projectId,
+ );
+ }),
+
+ get: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .query(async ({ input, ctx }) => {
+ throwIfNoProjectAccess({
+ projectId: input.projectId,
+ session: ctx.session,
+ scope: "integrations:CRUD",
+ });
+ return {
+ config: await createExternalMediaStorageService(
+ ctx.prisma,
+ ).getConfiguration(ctx.session.projectId),
+ };
+ }),
+
+ update: protectedProjectProcedureWithoutTracing
+ .input(
+ externalMediaStorageFormSchema.extend({
+ projectId: z.string(),
+ }),
+ )
+ .mutation(async ({ input, ctx }) => {
+ throwIfNoProjectAccess({
+ projectId: input.projectId,
+ session: ctx.session,
+ scope: "integrations:CRUD",
+ });
+
+ const { projectId: _projectId, ...values } = input;
+ try {
+ const result = await createExternalMediaStorageService(
+ ctx.prisma,
+ ).saveConfiguration({
+ actor: { session: ctx.session },
+ projectId: ctx.session.projectId,
+ values,
+ });
+ return result;
+ } catch (error) {
+ if (error instanceof ForbiddenError) {
+ throw error;
+ }
+ logger.error("Failed to update external media storage integration", {
+ projectId: ctx.session.projectId,
+ error,
+ });
+ return asBadRequest(error);
+ }
+ }),
+
+ delete: protectedProjectProcedure
+ .input(z.object({ projectId: z.string() }))
+ .mutation(async ({ input, ctx }) => {
+ throwIfNoProjectAccess({
+ projectId: input.projectId,
+ session: ctx.session,
+ scope: "integrations:CRUD",
+ });
+
+ try {
+ await createExternalMediaStorageService(ctx.prisma).deleteConfiguration(
+ {
+ actor: { session: ctx.session },
+ projectId: ctx.session.projectId,
+ },
+ );
+ } catch (error) {
+ if (error instanceof ForbiddenError) {
+ throw error;
+ }
+ logger.error("Failed to delete external media storage integration", {
+ projectId: ctx.session.projectId,
+ error,
+ });
+ return asBadRequest(error);
+ }
+ }),
+
+ testObject: protectedProjectProcedure
+ .input(z.object({ projectId: z.string(), uri: z.string() }))
+ .mutation(async ({ input, ctx }) => {
+ throwIfNoProjectAccess({
+ projectId: input.projectId,
+ session: ctx.session,
+ scope: "integrations:CRUD",
+ });
+
+ try {
+ return await createExternalMediaStorageService(ctx.prisma).testObject({
+ projectId: ctx.session.projectId,
+ uri: input.uri,
+ });
+ } catch (error) {
+ if (error instanceof ForbiddenError) {
+ throw error;
+ }
+ if (error instanceof InvalidRequestError) {
+ throw new TRPCError({ code: "BAD_REQUEST", message: error.message });
+ }
+ throw new TRPCError({
+ code: "BAD_REQUEST",
+ message:
+ error instanceof Error
+ ? `Storage access failed: ${error.message}`
+ : "Storage access failed",
+ });
+ }
+ }),
+});
diff --git a/web/src/features/external-media-storage/server/service.ts b/web/src/features/external-media-storage/server/service.ts
new file mode 100644
index 0000000000..da9a95d578
--- /dev/null
+++ b/web/src/features/external-media-storage/server/service.ts
@@ -0,0 +1,268 @@
+import {
+ BLOB_STORAGE_REGION_INVALID_MESSAGE,
+ BlobStorageIntegrationType,
+ ForbiddenError,
+ InvalidRequestError,
+ isS3KeyWithinPrefix,
+ normalizeBlobStorageRegion,
+ parseS3Uri,
+} from "@langfuse/shared";
+import { decrypt, encrypt } from "@langfuse/shared/encryption";
+import { type PrismaClient } from "@langfuse/shared/src/db";
+import {
+ StorageServiceFactory,
+ externalMediaStorageEndpointConnectionValidationOptions,
+ validateExternalMediaStorageEndpoint,
+} from "@langfuse/shared/src/server";
+
+import { getDisplayCredential } from "@/src/features/analytics-integrations/server";
+import { auditLog } from "@/src/features/audit-logs/server";
+import { type ExternalMediaStorageFormValues } from "@/src/features/external-media-storage/types";
+import {
+ createExternalMediaStorageRepository,
+ type ExternalMediaStorageRecord,
+} from "@/src/features/external-media-storage/server/repository";
+
+const EXTERNAL_MEDIA_URL_TTL_SECONDS = 5 * 60;
+
+type AuditLogInput = Parameters<typeof auditLog>[0];
+type AuditLogSession = Extract<AuditLogInput, { session: unknown }>["session"];
+
+export type ExternalMediaStorageAuditActor =
+ | { session: AuditLogSession }
+ | { apiKeyId: string; orgId: string };
+
+async function auditConfigurationChange({
+ action,
+ actor,
+ projectId,
+}: {
+ action: "update" | "delete";
+ actor: ExternalMediaStorageAuditActor;
+ projectId: string;
+}) {
+ const event = {
+ action,
+ resourceType: "externalMediaStorageIntegration" as const,
+ resourceId: projectId,
+ };
+
+ await auditLog(
+ "session" in actor
+ ? { ...event, session: actor.session }
+ : { ...event, ...actor, projectId },
+ );
+}
+
+function isKeyWithinPrefix(key: string, prefix: string | null) {
+ const normalizedPrefix = prefix?.trim().replace(/\/+$/, "");
+ return !normalizedPrefix || isS3KeyWithinPrefix(key, normalizedPrefix);
+}
+
+function createStorageService(integration: ExternalMediaStorageRecord) {
+ return StorageServiceFactory.getInstance({
+ accessKeyId: integration.accessKeyId ?? undefined,
+ secretAccessKey: integration.secretAccessKey
+ ? decrypt(integration.secretAccessKey)
+ : undefined,
+ bucketName: integration.bucketName,
+ endpoint: integration.endpoint ?? undefined,
+ region: integration.region,
+ forcePathStyle: integration.forcePathStyle,
+ useAzureBlob: false,
+ useGoogleCloudStorage: false,
+ useOCIObjectStorage: false,
+ googleCloudCredentials: undefined,
+ awsSse: undefined,
+ awsSseKmsKeyId: undefined,
+ externalEndpoint: undefined,
+ connectionValidation:
+ externalMediaStorageEndpointConnectionValidationOptions(),
+ });
+}
+
+export function createExternalMediaStorageService(prisma: PrismaClient) {
+ const repository = createExternalMediaStorageRepository(prisma);
+ const assertFeatureEnabled = async (projectId: string) => {
+ if (!(await repository.isFeatureEnabled(projectId))) {
+ throw new ForbiddenError(
+ "External media storage is not enabled for this organization",
+ );
+ }
+ };
+
+ return {
+ isFeatureEnabled(projectId: string) {
+ return repository.isFeatureEnabled(projectId);
+ },
+
+ async getConfiguration(projectId: string) {
+ await assertFeatureEnabled(projectId);
+ const integration = await repository.findByProjectId(projectId);
+ if (!integration) return null;
+
+ const { secretAccessKey, ...configuration } = integration;
+ return {
+ ...configuration,
+ secretAccessKeyDisplay: secretAccessKey
+ ? getDisplayCredential(decrypt(secretAccessKey))
+ : null,
+ };
+ },
+
+ async saveConfiguration({
+ actor,
+ projectId,
+ values,
+ }: {
+ actor: ExternalMediaStorageAuditActor;
+ projectId: string;
+ values: ExternalMediaStorageFormValues;
+ }) {
+ await assertFeatureEnabled(projectId);
+ const endpoint =
+ values.type === BlobStorageIntegrationType.S3_COMPATIBLE
+ ? values.endpoint?.trim() || null
+ : null;
+ if (
+ values.type === BlobStorageIntegrationType.S3_COMPATIBLE &&
+ !endpoint
+ ) {
+ throw new InvalidRequestError(
+ "Endpoint URL is required for S3-compatible storage",
+ );
+ }
+ if (endpoint) {
+ await validateExternalMediaStorageEndpoint(endpoint);
+ }
+
+ let region: string;
+ try {
+ region = normalizeBlobStorageRegion(values.region);
+ } catch {
+ throw new InvalidRequestError(BLOB_STORAGE_REGION_INVALID_MESSAGE);
+ }
+
+ const existing = await repository.findByProjectId(projectId);
+ const accessKeyId = values.accessKeyId?.trim() || null;
+ const secretAccessKey = values.secretAccessKey?.trim() || null;
+ const encryptedSecretAccessKey = secretAccessKey
+ ? encrypt(secretAccessKey)
+ : existing?.secretAccessKey;
+
+ if (!accessKeyId || !encryptedSecretAccessKey) {
+ throw new InvalidRequestError(
+ "Access Key ID and Secret Access Key are required",
+ );
+ }
+
+ await repository.upsert({
+ projectId,
+ data: {
+ type: values.type,
+ bucketName: values.bucketName.trim(),
+ prefix: values.prefix?.trim() || null,
+ accessKeyId,
+ secretAccessKey: encryptedSecretAccessKey ?? null,
+ region,
+ endpoint,
+ forcePathStyle:
+ values.type === BlobStorageIntegrationType.S3_COMPATIBLE
+ ? values.forcePathStyle
+ : false,
+ },
+ });
+
+ await auditConfigurationChange({ action: "update", actor, projectId });
+ },
+
+ async deleteConfiguration({
+ actor,
+ projectId,
+ }: {
+ actor: ExternalMediaStorageAuditActor;
+ projectId: string;
+ }) {
+ await assertFeatureEnabled(projectId);
+ const existing = await repository.findByProjectId(projectId);
+ if (!existing) {
+ throw new InvalidRequestError(
+ "External media storage integration not found",
+ );
+ }
+ await repository.deleteByProjectId(projectId);
+ await auditConfigurationChange({ action: "delete", actor, projectId });
+ },
+
+ async resolveUrl({ projectId, uri }: { projectId: string; uri: string }) {
+ await assertFeatureEnabled(projectId);
+ const parsed = parseS3Uri(uri);
+ if (!parsed) {
+ throw new InvalidRequestError(
+ "External media must use s3://<bucket>/<key>",
+ );
+ }
+
+ const integration = await repository.findByProjectAndBucket({
+ projectId,
+ bucketName: parsed.bucket,
+ });
+ if (!integration || !isKeyWithinPrefix(parsed.key, integration.prefix)) {
+ throw new InvalidRequestError("External media is not available");
+ }
+
+ if (integration.endpoint) {
+ await validateExternalMediaStorageEndpoint(integration.endpoint);
+ }
+
+ const url = await createStorageService(integration).getSignedUrl(
+ parsed.key,
+ EXTERNAL_MEDIA_URL_TTL_SECONDS,
+ false,
+ );
+
+ return {
+ url,
+ expiresAt: new Date(Date.now() + EXTERNAL_MEDIA_URL_TTL_SECONDS * 1000),
+ };
+ },
+
+ async testObject({ projectId, uri }: { projectId: string; uri: string }) {
+ await assertFeatureEnabled(projectId);
+ const parsed = parseS3Uri(uri);
+ if (!parsed) {
+ throw new InvalidRequestError(
+ "External media must use s3://<bucket>/<key>",
+ );
+ }
+
+ const integration = await repository.findByProjectAndBucket({
+ projectId,
+ bucketName: parsed.bucket,
+ });
+ if (!integration) {
+ throw new InvalidRequestError(
+ "The external media storage integration is not available",
+ );
+ }
+ if (!isKeyWithinPrefix(parsed.key, integration.prefix)) {
+ throw new InvalidRequestError(
+ "The media object must be within the configured prefix",
+ );
+ }
+
+ if (integration.endpoint) {
+ await validateExternalMediaStorageEndpoint(integration.endpoint);
+ }
+
+ const storageService = createStorageService(integration);
+ const signedUrl = await storageService.getSignedUrl(
+ parsed.key,
+ EXTERNAL_MEDIA_URL_TTL_SECONDS,
+ false,
+ );
+
+ return { signedUrl };
+ },
+ };
+}
diff --git a/web/src/features/external-media-storage/types.clienttest.ts b/web/src/features/external-media-storage/types.clienttest.ts
new file mode 100644
index 0000000000..f6e905551a
--- /dev/null
+++ b/web/src/features/external-media-storage/types.clienttest.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { externalMediaStorageFormSchema } from "@/src/features/external-media-storage/types";
+
+const validConfiguration = {
+ type: "S3" as const,
+ bucketName: "media-bucket",
+ endpoint: null,
+ region: "us-east-1",
+ accessKeyId: "access-key",
+ secretAccessKey: "secret-key",
+ prefix: "",
+ forcePathStyle: false,
+};
+
+describe("externalMediaStorageFormSchema", () => {
+ it("requires an endpoint for S3-compatible storage", () => {
+ expect(
+ externalMediaStorageFormSchema.safeParse({
+ ...validConfiguration,
+ type: "S3_COMPATIBLE",
+ }).success,
+ ).toBe(false);
+ });
+
+ it("requires an access key", () => {
+ expect(
+ externalMediaStorageFormSchema.safeParse({
+ ...validConfiguration,
+ accessKeyId: "",
+ }).success,
+ ).toBe(false);
+ });
+});
diff --git a/web/src/features/external-media-storage/types.ts b/web/src/features/external-media-storage/types.ts
new file mode 100644
index 0000000000..708e69a748
--- /dev/null
+++ b/web/src/features/external-media-storage/types.ts
@@ -0,0 +1,42 @@
+import {
+ BLOB_STORAGE_REGION_INVALID_MESSAGE,
+ BLOB_STORAGE_REGION_REGEX,
+} from "@langfuse/shared";
+import { z } from "zod";
+
+export const externalMediaStorageFormSchema = z
+ .object({
+ type: z.enum(["S3", "S3_COMPATIBLE"]),
+ bucketName: z.string().trim().min(1, "Bucket name is required"),
+ endpoint: z.url().optional().nullable(),
+ region: z
+ .string()
+ .trim()
+ .min(1, "Region is required")
+ .regex(BLOB_STORAGE_REGION_REGEX, {
+ message: BLOB_STORAGE_REGION_INVALID_MESSAGE,
+ }),
+ accessKeyId: z.string().trim().min(1, "Access Key ID is required"),
+ secretAccessKey: z.string().nullable().optional(),
+ prefix: z
+ .string()
+ .refine((value) => !value || value.endsWith("/"), {
+ message: "Prefix must end with a forward slash (/)",
+ })
+ .optional()
+ .or(z.literal("")),
+ forcePathStyle: z.boolean(),
+ })
+ .superRefine((values, ctx) => {
+ if (values.type === "S3_COMPATIBLE" && !values.endpoint) {
+ ctx.addIssue({
+ code: "custom",
+ path: ["endpoint"],
+ message: "Endpoint URL is required for S3-compatible storage",
+ });
+ }
+ });
+
+export type ExternalMediaStorageFormValues = z.infer<
+ typeof externalMediaStorageFormSchema
+>;
diff --git a/web/src/features/feature-flags/available-flags.ts b/web/src/features/feature-flags/available-flags.ts
index cd7abdfd9c..0b994133e0 100644
--- a/web/src/features/feature-flags/available-flags.ts
+++ b/web/src/features/feature-flags/available-flags.ts
@@ -1,16 +1,34 @@
import { assertUnreachable } from "@langfuse/shared";
-export const featurePreviewFlags = [
+export const organizationOnlyFeaturePreviewFlags = [
+ "externalMediaStorage",
+] as const;
+
+export const userFeaturePreviewFlags = [
"modernSession",
"sessionTimeline",
] as const;
+export type UserFeaturePreviewFlag = (typeof userFeaturePreviewFlags)[number];
+
+export const featurePreviewFlags = [
+ ...organizationOnlyFeaturePreviewFlags,
+ ...userFeaturePreviewFlags,
+] as const;
+
export type FeaturePreviewFlag = (typeof featurePreviewFlags)[number];
+export const isOrganizationOnlyFeaturePreviewFlag = (
+ flag: FeaturePreviewFlag,
+): flag is (typeof organizationOnlyFeaturePreviewFlags)[number] =>
+ organizationOnlyFeaturePreviewFlags.some(
+ (organizationFlag) => organizationFlag === flag,
+ );
+
const adminOnlyFeaturePreviewFlags = ["langfuseTopics"] as const;
export const personalFeaturePreviewFlags = [
- ...featurePreviewFlags,
+ ...userFeaturePreviewFlags,
...adminOnlyFeaturePreviewFlags,
] as const;
@@ -53,10 +71,11 @@ export const filterFeaturePreviewFlags = (
): FeaturePreviewFlag[] => flags.filter(isFeaturePreviewFlag);
export const featurePreviewLabels = {
+ externalMediaStorage: "External Media Storage",
modernSession: "Compact Session View",
sessionTimeline: "Session Timeline",
langfuseTopics: "Langfuse Topics",
-} satisfies Record<PersonalFeaturePreviewFlag, string>;
+} satisfies Record<FeaturePreviewFlag | PersonalFeaturePreviewFlag, string>;
export type FeaturePreviewAvailabilityContext = {
v4BetaEnabled: boolean;
@@ -66,6 +85,9 @@ export const isFeaturePreviewAvailable = (
flag: FeaturePreviewFlag,
context: FeaturePreviewAvailabilityContext,
) => {
+ if (flag === "externalMediaStorage") {
+ return true;
+ }
if (flag === "modernSession" || flag === "sessionTimeline") {
return context.v4BetaEnabled;
}
@@ -74,7 +96,8 @@ export const isFeaturePreviewAvailable = (
};
export const availableFlags = [
- ...personalFeaturePreviewFlags,
+ ...featurePreviewFlags,
+ ...adminOnlyFeaturePreviewFlags,
...restrictedFlags,
INTERNAL_FEATURE_FLAG,
"searchBar",
diff --git a/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.clienttest.tsx b/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.clienttest.tsx
index 628661d1b8..2169189382 100644
--- a/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.clienttest.tsx
+++ b/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.clienttest.tsx
@@ -195,6 +195,11 @@ describe("OrganizationFeaturePreviewsSettings", () => {
name: "Toggle Compact Session View organization default",
}),
).toBeDisabled();
+ expect(
+ screen.getByRole("checkbox", {
+ name: "Toggle External Media Storage organization default",
+ }),
+ ).toBeEnabled();
const personalEnablementRequirements = screen.getAllByText(
/enable this preview in your personal feature preview settings/i,
);
diff --git a/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.tsx b/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.tsx
index 7435da0089..cd96325a2e 100644
--- a/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.tsx
+++ b/web/src/features/feature-flags/components/OrganizationFeaturePreviewsSettings.tsx
@@ -19,6 +19,7 @@ import { Card } from "@/src/components/ui/card";
import {
featurePreviewFlags,
featurePreviewLabels,
+ isOrganizationOnlyFeaturePreviewFlag,
type FeaturePreviewFlag,
} from "@/src/features/feature-flags/available-flags";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
@@ -110,7 +111,10 @@ export function OrganizationFeaturePreviewsSettings({
const selected = selectedDefaults.has(flag);
const enabledForAdmin =
session.data?.user?.featureFlags[flag] === true;
- const requiresPersonalEnablement = !selected && !enabledForAdmin;
+ const requiresPersonalEnablement =
+ !isOrganizationOnlyFeaturePreviewFlag(flag) &&
+ !selected &&
+ !enabledForAdmin;
return (
<Card
key={flag}
@@ -144,8 +148,8 @@ export function OrganizationFeaturePreviewsSettings({
</div>
<p className="text-muted-foreground text-xs">
- Defaults apply only in this organization. A user&apos;s global personal
- opt-out always wins.
+ Defaults apply only in this organization. Personal opt-outs apply to
+ user-level previews.
</p>
<AlertDialog
@@ -169,7 +173,8 @@ export function OrganizationFeaturePreviewsSettings({
organization defaults.
</AlertDialogDescription>
</AlertDialogHeader>
- {proposedChange?.enabled ? (
+ {proposedChange?.enabled &&
+ !isOrganizationOnlyFeaturePreviewFlag(proposedChange.flag) ? (
<Alert>
<Alert.Title>Already enabled for you</Alert.Title>
<Alert.Description>
diff --git a/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx b/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx
index b3faefd099..b756ef84bc 100644
--- a/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx
+++ b/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.clienttest.tsx
@@ -3,7 +3,7 @@ import type { ComponentProps, ReactNode } from "react";
import type { HoverCard } from "@/src/components/design-system/HoverCard/HoverCard";
import { UserFeaturePreviewsControl } from "./UserFeaturePreviewsPopover";
-import { featurePreviewFlags } from "../available-flags";
+import { userFeaturePreviewFlags } from "../available-flags";
const mocks = vi.hoisted(() => ({
capture: vi.fn(),
@@ -124,6 +124,7 @@ describe("UserFeaturePreviewsControl", () => {
orgId: "org-1",
userId: "user-1",
featurePreviews: {
+ externalMediaStorage: false,
modernSession: false,
sessionTimeline: false,
},
@@ -139,9 +140,9 @@ describe("UserFeaturePreviewsControl", () => {
).toBeInTheDocument();
expect(
screen.getByRole("button", {
- // Derived: the counter's denominator is the number of registered
- // previews, so a new preview must not fail this test.
- name: new RegExp(`0/${featurePreviewFlags.length} enabled`, "i"),
+ // Derived: the counter's denominator is the number of user previews,
+ // so a new preview must not fail this test.
+ name: new RegExp(`0/${userFeaturePreviewFlags.length} enabled`, "i"),
}),
).toBeDisabled();
});
@@ -151,12 +152,18 @@ describe("UserFeaturePreviewsControl", () => {
orgId: "org-1",
userId: "user-1",
featurePreviews: {
+ externalMediaStorage: false,
modernSession: false,
sessionTimeline: false,
},
management: { allowed: true },
});
+ expect(
+ screen.queryByRole("checkbox", {
+ name: "Toggle External Media Storage for user",
+ }),
+ ).not.toBeInTheDocument();
fireEvent.click(
screen.getByRole("checkbox", {
name: "Toggle Compact Session View for user",
@@ -187,6 +194,7 @@ describe("UserFeaturePreviewsControl", () => {
orgId: "org-1",
userId: "user-1",
featurePreviews: {
+ externalMediaStorage: false,
modernSession: false,
sessionTimeline: false,
},
@@ -214,6 +222,7 @@ describe("UserFeaturePreviewsControl", () => {
orgId: "org-1",
userId: "user-1",
featurePreviews: {
+ externalMediaStorage: false,
modernSession: false,
sessionTimeline: false,
},
diff --git a/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.tsx b/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.tsx
index 5ce572660b..230855a416 100644
--- a/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.tsx
+++ b/web/src/features/feature-flags/components/UserFeaturePreviewsPopover.tsx
@@ -7,8 +7,8 @@ import { Button } from "@/src/components/ui/button";
import { HoverCard } from "@/src/components/design-system/HoverCard/HoverCard";
import { PopoverContent } from "@/src/components/ui/popover";
import {
- featurePreviewFlags,
featurePreviewLabels,
+ userFeaturePreviewFlags,
type FeaturePreviewFlag,
} from "@/src/features/feature-flags/available-flags";
import { usePostHogClientCapture } from "@/src/features/posthog-analytics";
@@ -66,8 +66,10 @@ export function UserFeaturePreviewsControl({
);
},
});
- const enabledCount = Object.values(featurePreviews).filter(Boolean).length;
- const totalCount = featurePreviewFlags.length;
+ const enabledCount = userFeaturePreviewFlags.filter(
+ (flag) => featurePreviews[flag],
+ ).length;
+ const totalCount = userFeaturePreviewFlags.length;
if (!management.allowed) {
return (
@@ -111,7 +113,7 @@ export function UserFeaturePreviewsControl({
Changes apply to this user in every organization.
</p>
</div>
- {featurePreviewFlags.map((flag) => (
+ {userFeaturePreviewFlags.map((flag) => (
<div key={flag} className="flex items-center justify-between gap-4">
<span className="text-sm">{featurePreviewLabels[flag]}</span>
<Switch
diff --git a/web/src/features/feature-flags/server/index.ts b/web/src/features/feature-flags/server/index.ts
index 5b90d93003..fbb4dc26fd 100644
--- a/web/src/features/feature-flags/server/index.ts
+++ b/web/src/features/feature-flags/server/index.ts
@@ -1,8 +1,10 @@
// The feature-flags feature's public server surface (RFC rules 8 and 10).
export {
featurePreviewFlags,
+ userFeaturePreviewFlags,
personalFeaturePreviewFlags,
isAdminOnlyFeaturePreviewFlag,
+ isOrganizationOnlyFeaturePreviewFlag,
INTERNAL_FEATURE_FLAG,
filterFeaturePreviewFlags,
} from "@/src/features/feature-flags/available-flags";
diff --git a/web/src/features/feature-flags/server/organizationFeatureFlags.ts b/web/src/features/feature-flags/server/organizationFeatureFlags.ts
index 07e85d2f77..f22116345e 100644
--- a/web/src/features/feature-flags/server/organizationFeatureFlags.ts
+++ b/web/src/features/feature-flags/server/organizationFeatureFlags.ts
@@ -9,6 +9,7 @@ import {
filterFeaturePreviewFlags,
featurePreviewFlags,
type FeaturePreviewFlag,
+ type UserFeaturePreviewFlag,
type UserFeatureFlag,
INTERNAL_FEATURE_FLAG,
} from "@/src/features/feature-flags/available-flags";
@@ -260,7 +261,7 @@ export async function setUserFeaturePreviewWithAuthorization({
actorIsPlatformAdmin: boolean;
currentOrgId: string;
targetUserId: string;
- flag: FeaturePreviewFlag;
+ flag: UserFeaturePreviewFlag;
enabled: boolean;
demoOrgId?: string;
}): Promise<
diff --git a/web/src/features/feature-flags/types.ts b/web/src/features/feature-flags/types.ts
index c39ce01726..91105cd3a7 100644
--- a/web/src/features/feature-flags/types.ts
+++ b/web/src/features/feature-flags/types.ts
@@ -7,6 +7,7 @@ export type Flag = (typeof availableFlags)[number];
export type Flags = {
[key in Exclude<
Flag,
+ | "externalMediaStorage"
| "modernSession"
| "aiGateway"
| "sessionTimeline"
@@ -14,6 +15,7 @@ export type Flags = {
>]: boolean;
} & {
// Optional while older sessions and test fixtures roll across new flags.
+ externalMediaStorage?: boolean;
modernSession?: boolean;
aiGateway?: boolean;
sessionTimeline?: boolean;
diff --git a/web/src/features/feature-flags/utils.clienttest.ts b/web/src/features/feature-flags/utils.clienttest.ts
index 058cca01f9..7701c0b2c5 100644
--- a/web/src/features/feature-flags/utils.clienttest.ts
+++ b/web/src/features/feature-flags/utils.clienttest.ts
@@ -125,6 +125,21 @@ describe("parseFlags", () => {
expect(optedOut.modernSession).toBe(false);
});
+ it("enables organization-only previews exclusively through organization defaults", () => {
+ const personalOnly = parseFlags(["externalMediaStorage"], {
+ email: "[email protected]",
+ v4BetaEnabled: true,
+ });
+ const organizationEnabled = parseFlagsWithOrganizationDefaults(
+ ["feature-preview:externalMediaStorage:disabled"],
+ ["externalMediaStorage"],
+ { email: "[email protected]", v4BetaEnabled: true },
+ );
+
+ expect(personalOnly.externalMediaStorage).toBe(false);
+ expect(organizationEnabled.externalMediaStorage).toBe(true);
+ });
+
it("does not apply a Session Timeline organization default without Compact Session", () => {
const flags = parseFlagsWithOrganizationDefaults([], ["sessionTimeline"], {
diff --git a/web/src/features/feature-flags/utils.ts b/web/src/features/feature-flags/utils.ts
index 7e57fb0d21..249fa42f0d 100644
--- a/web/src/features/feature-flags/utils.ts
+++ b/web/src/features/feature-flags/utils.ts
@@ -1,10 +1,12 @@
/* eslint-disable no-nested-ternary */
import {
availableFlags,
+ featurePreviewFlags,
filterFeaturePreviewFlags,
isRestrictedFlag,
isInternalFlag,
isFeaturePreviewFlag,
+ isOrganizationOnlyFeaturePreviewFlag,
isFeaturePreviewAvailable,
isAdminOnlyFeaturePreviewFlag,
type FeaturePreviewAvailabilityContext,
@@ -59,6 +61,14 @@ export const parseFlags = (
return;
}
+ if (
+ isFeaturePreviewFlag(flag) &&
+ isOrganizationOnlyFeaturePreviewFlag(flag)
+ ) {
+ parsedFlags[flag] = false;
+ return;
+ }
+
if (
(isFeaturePreviewFlag(flag) || isAdminOnlyFeaturePreviewFlag(flag)) &&
dbFlags.includes(getFeaturePreviewOptOutFlag(flag))
@@ -97,7 +107,13 @@ export const parseFlagsWithOrganizationDefaults = (
const featurePreviewDefaults =
filterFeaturePreviewFlags(organizationDefaults);
- return parseFlags(dbFlags.concat(featurePreviewDefaults), context);
+ const flags = parseFlags(dbFlags.concat(featurePreviewDefaults), context);
+ for (const flag of featurePreviewFlags) {
+ if (isOrganizationOnlyFeaturePreviewFlag(flag)) {
+ flags[flag] = featurePreviewDefaults.includes(flag);
+ }
+ }
+ return flags;
};
type ContextualFeatureFlagUser = {
diff --git a/web/src/features/in-app-agent/components/utils/side-effects.ts b/web/src/features/in-app-agent/components/utils/side-effects.ts
index 1ccef24360..a3fb5d7fce 100644
--- a/web/src/features/in-app-agent/components/utils/side-effects.ts
+++ b/web/src/features/in-app-agent/components/utils/side-effects.ts
@@ -18,6 +18,7 @@ export type InAppAgentTrpcInvalidationTarget =
| "datasets"
| "evals"
| "experiments"
+ | "externalMediaStorage"
| "models"
| "prompts"
| "scoreAnalytics"
@@ -88,6 +89,10 @@ const IN_APP_AGENT_TOOL_TRPC_INVALIDATION_TARGETS = {
langfuse_getHealth: [],
langfuse_getV4MigrationData: [],
langfuse_getMedia: [],
+ langfuse_getExternalMediaStorage: [],
+ langfuse_configureExternalMediaStorage: ["externalMediaStorage"],
+ langfuse_deleteExternalMediaStorage: ["externalMediaStorage"],
+ langfuse_testExternalMediaStorage: [],
langfuse_queryMetrics: [],
langfuse_getMetricsSchema: [],
langfuse_listModels: [],
@@ -187,6 +192,9 @@ function performTargetInvalidation(
if (target === "experiments") {
return utils.experiments.invalidate();
}
+ if (target === "externalMediaStorage") {
+ return utils.externalMediaStorage.invalidate();
+ }
if (target === "models") {
return utils.models.invalidate();
}
diff --git a/web/src/features/in-app-agent/components/utils/utils.ts b/web/src/features/in-app-agent/components/utils/utils.ts
index d2914bb55b..1af2afcea3 100644
--- a/web/src/features/in-app-agent/components/utils/utils.ts
+++ b/web/src/features/in-app-agent/components/utils/utils.ts
@@ -55,6 +55,7 @@ const IN_APP_AGENT_TOOL_PROGRESS_LABEL_OVERRIDES: Record<string, string> = {
addDashboardPlacement: "Adding widget to dashboard",
bash: "Running command",
batchUpsertDatasetItems: "Saving dataset items",
+ configureExternalMediaStorage: "Configuring external media storage",
createAnnotationQueueAssignment: "Assigning annotation queue",
createAnnotationQueueItem: "Adding to annotation queue",
createChatPrompt: "Creating chat prompt",
@@ -63,8 +64,10 @@ const IN_APP_AGENT_TOOL_PROGRESS_LABEL_OVERRIDES: Record<string, string> = {
deleteAnnotationQueueAssignment: "Unassigning annotation queue",
deleteDashboardPlacement: "Removing widget from dashboard",
deleteDashboardWidget: "Deleting widget",
+ deleteExternalMediaStorage: "Deleting external media storage",
edit: "Editing file",
getDashboardWidget: "Inspecting widget",
+ getExternalMediaStorage: "Inspecting external media storage",
getHealth: "Checking health",
getMetricsSchema: "Checking metrics",
getObservationFieldSchema: "Checking observation fields",
@@ -79,6 +82,7 @@ const IN_APP_AGENT_TOOL_PROGRESS_LABEL_OVERRIDES: Record<string, string> = {
read: "Reading file",
submitFeedback: "Submitting user feedback",
testEvaluator: "Testing evaluator",
+ testExternalMediaStorage: "Testing external media storage",
updateDashboardPlacement: "Moving widget",
updateDashboardWidget: "Updating widget",
updatePromptLabels: "Updating prompt labels",
diff --git a/web/src/features/mcp/server/bootstrap.ts b/web/src/features/mcp/server/bootstrap.ts
index e0ef06993d..d96f56b79e 100644
--- a/web/src/features/mcp/server/bootstrap.ts
+++ b/web/src/features/mcp/server/bootstrap.ts
@@ -25,6 +25,7 @@ import { evalsFeature } from "./evals";
import { dashboardWidgetsFeature } from "./dashboardWidgets";
import { feedbackFeature } from "./feedback";
import { experimentsFeature } from "./experiments";
+import { externalMediaStorageFeature } from "./externalMediaStorage";
import { monitorsFeature } from "./monitors";
import { v4MigrationFeature } from "./v4Migration";
@@ -43,6 +44,7 @@ const MCP_FEATURES = [
dashboardWidgetsFeature,
feedbackFeature,
experimentsFeature,
+ externalMediaStorageFeature,
monitorsFeature,
v4MigrationFeature,
] as const satisfies readonly McpFeatureModule[];
diff --git a/web/src/features/mcp/server/externalMediaStorage/index.ts b/web/src/features/mcp/server/externalMediaStorage/index.ts
new file mode 100644
index 0000000000..81356302b5
--- /dev/null
+++ b/web/src/features/mcp/server/externalMediaStorage/index.ts
@@ -0,0 +1,43 @@
+import { prisma } from "@langfuse/shared/src/db";
+
+import { createExternalMediaStorageService } from "@/src/features/external-media-storage/server";
+import { type McpFeatureModule } from "@/src/features/mcp/server/registry";
+
+import {
+ configureExternalMediaStorageTool,
+ deleteExternalMediaStorageTool,
+ getExternalMediaStorageTool,
+ handleConfigureExternalMediaStorage,
+ handleDeleteExternalMediaStorage,
+ handleGetExternalMediaStorage,
+ handleTestExternalMediaStorage,
+ testExternalMediaStorageTool,
+} from "./tools";
+
+export const externalMediaStorageFeature = {
+ name: "external-media-storage",
+ description:
+ "Configure S3 external media storage for the current Langfuse project",
+ tools: [
+ {
+ definition: getExternalMediaStorageTool,
+ handler: handleGetExternalMediaStorage,
+ },
+ {
+ definition: configureExternalMediaStorageTool,
+ handler: handleConfigureExternalMediaStorage,
+ },
+ {
+ definition: deleteExternalMediaStorageTool,
+ handler: handleDeleteExternalMediaStorage,
+ },
+ {
+ definition: testExternalMediaStorageTool,
+ handler: handleTestExternalMediaStorage,
+ },
+ ],
+ isEnabled: (context) =>
+ createExternalMediaStorageService(prisma).isFeatureEnabled(
+ context.projectId,
+ ),
+} as const satisfies McpFeatureModule;
diff --git a/web/src/features/mcp/server/externalMediaStorage/tools.ts b/web/src/features/mcp/server/externalMediaStorage/tools.ts
new file mode 100644
index 0000000000..efc6ad6031
--- /dev/null
+++ b/web/src/features/mcp/server/externalMediaStorage/tools.ts
@@ -0,0 +1,130 @@
+import { prisma } from "@langfuse/shared/src/db";
+import { z } from "zod";
+
+import { createExternalMediaStorageService } from "@/src/features/external-media-storage/server";
+import { externalMediaStorageFormSchema } from "@/src/features/external-media-storage/types";
+import { defineTool } from "@/src/features/mcp/core/define-tool";
+import { runMcpTool } from "@/src/features/mcp/core/run-mcp-tool";
+
+const EmptyInputSchema = z.object({});
+const ExternalMediaStorageBaseSchema = z.object({
+ type: z.enum(["S3", "S3_COMPATIBLE"]),
+ bucketName: z.string(),
+ endpoint: z.string().optional(),
+ region: z.string(),
+ accessKeyId: z.string(),
+ secretAccessKey: z.string().optional(),
+ prefix: z.string().optional(),
+ forcePathStyle: z.boolean(),
+});
+const TestObjectInputSchema = z.object({
+ uri: z.string().describe("S3 URI in the form s3://bucket/path/to/object"),
+});
+
+function getService(context: {
+ apiKeyId: string;
+ orgId: string;
+ projectId: string;
+}) {
+ return {
+ actor: {
+ apiKeyId: context.apiKeyId,
+ orgId: context.orgId,
+ },
+ service: createExternalMediaStorageService(prisma),
+ };
+}
+
+export const [getExternalMediaStorageTool, handleGetExternalMediaStorage] =
+ defineTool({
+ name: "getExternalMediaStorage",
+ description:
+ "Get the external media storage configuration for the current project. Secret credentials are never returned.",
+ action: "integrations:CRUD",
+ baseSchema: EmptyInputSchema,
+ inputSchema: EmptyInputSchema,
+ handler: async (_input, context) =>
+ runMcpTool({
+ spanName: "mcp.external_media_storage.get",
+ context,
+ fn: async () =>
+ getService(context).service.getConfiguration(context.projectId),
+ }),
+ readOnlyHint: true,
+ });
+
+export const [
+ configureExternalMediaStorageTool,
+ handleConfigureExternalMediaStorage,
+] = defineTool({
+ name: "configureExternalMediaStorage",
+ description:
+ "Create or update the S3 external media storage configuration for the current project. Leave secretAccessKey empty to retain the saved secret.",
+ action: "integrations:CRUD",
+ baseSchema: ExternalMediaStorageBaseSchema,
+ inputSchema: externalMediaStorageFormSchema,
+ handler: async (input, context) =>
+ runMcpTool({
+ spanName: "mcp.external_media_storage.configure",
+ context,
+ attributes: {
+ "mcp.storage_type": input.type,
+ },
+ fn: async () => {
+ const { actor, service } = getService(context);
+ await service.saveConfiguration({
+ actor,
+ projectId: context.projectId,
+ values: input,
+ });
+ return { success: true };
+ },
+ }),
+});
+
+export const [
+ deleteExternalMediaStorageTool,
+ handleDeleteExternalMediaStorage,
+] = defineTool({
+ name: "deleteExternalMediaStorage",
+ description:
+ "Delete the external media storage configuration for the current project.",
+ action: "integrations:CRUD",
+ baseSchema: EmptyInputSchema,
+ inputSchema: EmptyInputSchema,
+ handler: async (_input, context) =>
+ runMcpTool({
+ spanName: "mcp.external_media_storage.delete",
+ context,
+ fn: async () => {
+ const { actor, service } = getService(context);
+ await service.deleteConfiguration({
+ actor,
+ projectId: context.projectId,
+ });
+ return { success: true };
+ },
+ }),
+ destructiveHint: true,
+});
+
+export const [testExternalMediaStorageTool, handleTestExternalMediaStorage] =
+ defineTool({
+ name: "testExternalMediaStorage",
+ description:
+ "Generate a short-lived signed URL for an existing S3 object using the current project's external media storage configuration.",
+ action: "integrations:CRUD",
+ baseSchema: TestObjectInputSchema,
+ inputSchema: TestObjectInputSchema,
+ handler: async (input, context) =>
+ runMcpTool({
+ spanName: "mcp.external_media_storage.test",
+ context,
+ fn: async () =>
+ getService(context).service.testObject({
+ projectId: context.projectId,
+ uri: input.uri,
+ }),
+ }),
+ readOnlyHint: true,
+ });
diff --git a/web/src/features/organizations/server/organizationRouter.ts b/web/src/features/organizations/server/organizationRouter.ts
index f1c1038def..495f85a26b 100644
--- a/web/src/features/organizations/server/organizationRouter.ts
+++ b/web/src/features/organizations/server/organizationRouter.ts
@@ -27,6 +27,7 @@ import { getSfdcService } from "@/src/ee/features/sfdc-sync/server";
import {
featurePreviewFlags,
filterFeaturePreviewFlags,
+ isOrganizationOnlyFeaturePreviewFlag,
setOrganizationFeatureFlagDefault,
parseFlags,
} from "@/src/features/feature-flags/server";
@@ -129,6 +130,7 @@ export const organizationsRouter = createTRPCRouter({
if (
input.enabled &&
+ !isOrganizationOnlyFeaturePreviewFlag(input.flag) &&
env.LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES !== "true"
) {
const actor = await ctx.prisma.user.findUnique({
diff --git a/web/src/features/projects/ProjectSettingsPage.tsx b/web/src/features/projects/ProjectSettingsPage.tsx
index f504c58382..080f37b602 100644
--- a/web/src/features/projects/ProjectSettingsPage.tsx
+++ b/web/src/features/projects/ProjectSettingsPage.tsx
@@ -407,6 +407,10 @@ const Integrations = (props: { projectId: string }) => {
projectId: props.projectId,
scope: "integrations:CRUD",
});
+ const showExternalMediaStorage =
+ api.externalMediaStorage.isFeatureEnabled.useQuery({
+ projectId: props.projectId,
+ }).data === true;
const allowBlobStorageIntegration = useHasEntitlement(
"scheduled-blob-exports",
@@ -494,6 +498,33 @@ const Integrations = (props: { projectId: string }) => {
</div>
</Card>
+ {showExternalMediaStorage ? (
+ <Card className="p-3">
+ <span className="font-bold">External Media Storage</span>
+ <p className="text-primary mb-4 text-sm">
+ Resolve media referenced by s3:// URIs from your own Amazon S3 or
+ S3-compatible bucket.
+ </p>
+ <div className="flex items-center gap-2">
+ <ActionButton
+ variant="secondary"
+ hasAccess={hasAccess}
+ href={`/project/${props.projectId}/settings/integrations/external-media-storage`}
+ >
+ Configure
+ </ActionButton>
+ <Button asChild variant="ghost">
+ <Link
+ href="https://langfuse.com/docs/observability/features/multi-modality#external-s3-media"
+ target="_blank"
+ >
+ Integration Docs ↗
+ </Link>
+ </Button>
+ </div>
+ </Card>
+ ) : null}
+
<Card className="p-3">
<div className="mb-4 flex items-center gap-2">
<SiSlack className="text-foreground icon-lg" />
diff --git a/web/src/features/rbac/server/membersRouter.ts b/web/src/features/rbac/server/membersRouter.ts
index d11e82ced1..1e5ef9ad61 100644
--- a/web/src/features/rbac/server/membersRouter.ts
+++ b/web/src/features/rbac/server/membersRouter.ts
@@ -36,7 +36,7 @@ import { allMembersRoutes } from "@/src/features/rbac/server/allMembersRoutes";
import { allInvitesRoutes } from "@/src/features/rbac/server/allInvitesRoutes";
import { orderedRoles } from "@/src/features/rbac/constants/orderedRoles";
import {
- featurePreviewFlags,
+ userFeaturePreviewFlags,
setUserFeaturePreviewWithAuthorization,
} from "@/src/features/feature-flags/server";
@@ -731,7 +731,7 @@ export const membersRouter = createTRPCRouter({
z.object({
orgId: z.string(),
userId: z.string(),
- flag: z.enum(featurePreviewFlags),
+ flag: z.enum(userFeaturePreviewFlags),
enabled: z.boolean(),
}),
)
diff --git a/web/src/pages/project/[projectId]/settings/integrations/external-media-storage.tsx b/web/src/pages/project/[projectId]/settings/integrations/external-media-storage.tsx
new file mode 100644
index 0000000000..91b5da327b
--- /dev/null
+++ b/web/src/pages/project/[projectId]/settings/integrations/external-media-storage.tsx
@@ -0,0 +1 @@
+export { default } from "@/src/features/external-media-storage/ExternalMediaStoragePage";
diff --git a/web/src/server/api/root.ts b/web/src/server/api/root.ts
index e724be447f..092bafae46 100644
--- a/web/src/server/api/root.ts
+++ b/web/src/server/api/root.ts
@@ -22,6 +22,7 @@ import { evaluatorRouter } from "@/src/features/evals/v2/server/evaluators/evalu
import { posthogIntegrationRouter } from "@/src/features/posthog-integration/posthog-integration-router";
import { mixpanelIntegrationRouter } from "@/src/features/mixpanel-integration/mixpanel-integration-router";
import { blobStorageIntegrationRouter } from "@/src/features/blobstorage-integration/blobstorage-integration-router";
+import { externalMediaStorageRouter } from "@/src/features/external-media-storage/server";
import { llmApiKeyRouter } from "@/src/features/llm-api-key/server/router";
import { llmSchemaRouter } from "@/src/features/llm-schemas/server/router";
import { llmToolRouter } from "@/src/features/llm-tools/server/router";
@@ -108,6 +109,7 @@ export const appRouter = createTRPCRouter({
posthogIntegration: posthogIntegrationRouter,
mixpanelIntegration: mixpanelIntegrationRouter,
blobStorageIntegration: blobStorageIntegrationRouter,
+ externalMediaStorage: externalMediaStorageRouter,
llmApiKey: llmApiKeyRouter,
llmSchemas: llmSchemaRouter,
llmTools: llmToolRouter,
diff --git a/web/src/server/api/routers/media.ts b/web/src/server/api/routers/media.ts
index 4d914283e2..8d2f2ff580 100644
--- a/web/src/server/api/routers/media.ts
+++ b/web/src/server/api/routers/media.ts
@@ -12,8 +12,42 @@ import {
type MediaReturnType,
} from "@/src/features/media/server";
import { type MediaEnabledFields } from "@/src/features/media/validation";
+import { createExternalMediaStorageService } from "@/src/features/external-media-storage/server";
+import { throwIfNoProjectAccess } from "@/src/features/rbac";
+import { InvalidRequestError } from "@langfuse/shared";
+import { logger } from "@langfuse/shared/src/server";
export const mediaRouter = createTRPCRouter({
+ resolveExternalMedia: protectedProjectProcedure
+ .input(z.object({ projectId: z.string(), uri: z.string() }))
+ .query(async ({ input, ctx }) => {
+ const projectId = ctx.session.projectId;
+ throwIfNoProjectAccess({
+ session: ctx.session,
+ projectId,
+ scope: "project:read",
+ });
+
+ try {
+ return await createExternalMediaStorageService(ctx.prisma).resolveUrl({
+ projectId,
+ uri: input.uri,
+ });
+ } catch (error) {
+ if (!(error instanceof InvalidRequestError)) {
+ logger.error("Unexpected external media resolution failure", {
+ projectId,
+ operation: "media.resolveExternalMedia",
+ errorType: error instanceof Error ? error.name : typeof error,
+ });
+ }
+ throw new TRPCError({
+ code: "NOT_FOUND",
+ message: "External media is not available",
+ });
+ }
+ }),
+
getById: protectedProjectProcedure
.input(z.object({ mediaId: z.string(), projectId: z.string() }))
.query(async ({ input, ctx }) => {