feat(webapp): let the deployment S2 endpoint be overridden

The S2 SDK honours only endpoints passed to its constructor. S2Environment.parse(),
which reads the endpoint variables, is an opt-in helper the webapp never called, so
deployment event logs always went to hosted S2 and could not be pointed at the local
s2 container in docker compose. Realtime streams already had this knob.

S2_DEPLOYMENT_ENDPOINT is a single value covering both the account and basin hosts.
Two separate variables would let a half-set config send the access token to the hosted
service while the operator believed the client was entirely local.

With the variable unset the options object carries no endpoints key at all, so the call
into the SDK is the one production already makes. An endpoints key with undefined
members resolves to the same hosted URLs, so no assertion on the built client would
catch a regression there; the options builder is asserted directly instead, from a
module that reads no environment.

The value is trimmed and validated: https anywhere, http only for a loopback host. The
access token is sent to whatever is configured as a bearer token, so cleartext off the
machine would leak it. Zod url() is too weak for this on its own, accepting both
"htp:/localhost" and a plain http host.

Author: d-cs

apps/webapp/app/env.server.ts

@@ -4,6 +4,7 @@ import { BoolEnv } from "./utils/boolEnv";
 import { isValidDatabaseUrl } from "./utils/db";
 import { parseRunOpsShards, validateShardListAgainstNewUrl } from "~/v3/runOpsShards.server";
 import { isValidRegex } from "./utils/regex";
+import { isValidS2Endpoint } from "./utils/s2Endpoint";
 import { isValidDuration } from "./services/realtime/duration.server";
 
 // `z.string()` constrained to a `parseDuration`-parseable string (e.g.
@@ -79,6 +80,19 @@ const S2EnvSchema = z.preprocess(
       S2_ACCESS_TOKEN: z.string(),
       S2_DEPLOYMENT_LOGS_BASIN_NAME: z.string(),
       S2_DEPLOYMENT_STREAMS_LOCAL: z.string().default("0"),
+      // Points deployment event logs at an S2 service other than the hosted one, e.g. the
+      // local s2-lite in docker compose. One value covers both the account and basin
+      // endpoints: splitting them lets a half-set config send the access token to the
+      // hosted service while the operator believes they are entirely local.
+      S2_DEPLOYMENT_ENDPOINT: z
+        .string()
+        .trim()
+        .transform((value) => (value === "" ? undefined : value))
+        .refine(
+          (value) => value === undefined || isValidS2Endpoint(value),
+          "must be an http(s) URL; http is only allowed for a loopback host, because the S2 access token is sent to it as a bearer token"
+        )
+        .optional(),
     }),
     z.object({
       S2_ENABLED: z.literal("0"),

apps/webapp/app/presenters/v3/DeploymentPresenter.server.ts

@@ -13,7 +13,7 @@ import { type User } from "~/models/user.server";
 import { getUsername } from "~/utils/username";
 import { processGitMetadata } from "./BranchesPresenter.server";
 import { VercelProjectIntegrationDataSchema } from "~/v3/vercel/vercelProjectIntegrationSchema";
-import { S2 } from "@s2-dev/streamstore";
+import { createDeploymentS2Client } from "~/v3/s2Client.server";
 import { env } from "~/env.server";
 import { createRedisClient } from "~/redis.server";
 import { tryCatch } from "@trigger.dev/core";
@@ -30,7 +30,7 @@ const s2TokenRedis = createRedisClient("s2-token-cache", {
   clusterMode: env.CACHE_REDIS_CLUSTER_MODE_ENABLED === "1",
 });
 
-const s2 = env.S2_ENABLED === "1" ? new S2({ accessToken: env.S2_ACCESS_TOKEN }) : undefined;
+const s2 = createDeploymentS2Client();
 
 export type ErrorData = {
   name: string;

apps/webapp/app/utils/s2Endpoint.ts

@@ -0,0 +1,18 @@
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
+
+// The S2 access token is sent as a bearer header to whatever endpoint is configured, so cleartext
+// is only acceptable when the endpoint cannot leave the machine.
+export function isValidS2Endpoint(value: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(value);
+  } catch {
+    return false;
+  }
+
+  if (url.protocol === "https:") {
+    return true;
+  }
+
+  return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+}

apps/webapp/app/v3/s2Client.server.ts

@@ -0,0 +1,14 @@
+import type { S2 } from "@s2-dev/streamstore";
+import { env } from "~/env.server";
+import { buildDeploymentS2Client } from "~/v3/s2ClientConfig";
+
+export function createDeploymentS2Client(): S2 | undefined {
+  if (env.S2_ENABLED !== "1") {
+    return undefined;
+  }
+
+  return buildDeploymentS2Client({
+    accessToken: env.S2_ACCESS_TOKEN,
+    endpoint: env.S2_DEPLOYMENT_ENDPOINT,
+  });
+}

apps/webapp/app/v3/s2ClientConfig.ts

@@ -0,0 +1,30 @@
+import { S2 } from "@s2-dev/streamstore";
+
+export type DeploymentS2Config = {
+  accessToken: string;
+  endpoint?: string;
+};
+
+type DeploymentS2ClientOptions = {
+  accessToken: string;
+  endpoints?: { account: string; basin: string };
+};
+
+// Exported so a test can pin the shape handed to the SDK: with no endpoint the options must carry
+// no `endpoints` key, matching the call production already makes.
+export function deploymentS2ClientOptions({
+  accessToken,
+  endpoint,
+}: DeploymentS2Config): DeploymentS2ClientOptions {
+  if (endpoint === undefined) {
+    return { accessToken };
+  }
+
+  // One value drives both hosts. Overriding just one would send the access token to the hosted
+  // service while the other half went elsewhere.
+  return { accessToken, endpoints: { account: endpoint, basin: endpoint } };
+}
+
+export function buildDeploymentS2Client(config: DeploymentS2Config): S2 {
+  return new S2(deploymentS2ClientOptions(config));
+}

apps/webapp/app/v3/services/deployment.server.ts

@@ -23,7 +23,8 @@ import {
 import { FEATURE_FLAG, type FeatureFlagKey } from "../featureFlags";
 import { flags } from "../featureFlags.server";
 import { globalFlagsRegistry } from "../globalFlagsRegistry.server";
-import { AppendInput, AppendRecord, S2 } from "@s2-dev/streamstore";
+import { AppendInput, AppendRecord } from "@s2-dev/streamstore";
+import { createDeploymentS2Client } from "~/v3/s2Client.server";
 import { createRedisClient } from "~/redis.server";
 
 const S2_TOKEN_KEY_PREFIX = "s2-token:read:deployment-event-stream:project:";
@@ -35,7 +36,7 @@ const s2TokenRedis = createRedisClient("s2-token-cache", {
   tlsDisabled: env.CACHE_REDIS_TLS_DISABLED === "true",
   clusterMode: env.CACHE_REDIS_CLUSTER_MODE_ENABLED === "1",
 });
-const s2 = env.S2_ENABLED === "1" ? new S2({ accessToken: env.S2_ACCESS_TOKEN }) : undefined;
+const s2 = createDeploymentS2Client();
 
 const DEPLOY_BUILD_PATH_ENV_FLAG: Partial<Record<RuntimeEnvironmentType, FeatureFlagKey>> = {
   PREVIEW: FEATURE_FLAG.deployBuildPathPreview,

apps/webapp/test/s2ClientConfig.test.ts

@@ -0,0 +1,53 @@
+import { describe, expect, it } from "vitest";
+import { buildDeploymentS2Client, deploymentS2ClientOptions } from "~/v3/s2ClientConfig";
+
+const BASIN = "trigger-local";
+
+describe("buildDeploymentS2Client", () => {
+  // The SDK resolves an endpoints key with undefined members to the same hosted URLs, so nothing
+  // on the built client distinguishes the two calls. Assert on the options instead.
+  it("hands the SDK no endpoints key at all when no endpoint is configured", () => {
+    expect(deploymentS2ClientOptions({ accessToken: "token" })).toEqual({ accessToken: "token" });
+    expect(deploymentS2ClientOptions({ accessToken: "token" })).not.toHaveProperty("endpoints");
+  });
+
+  it("hands the SDK one endpoint for both hosts when configured", () => {
+    expect(
+      deploymentS2ClientOptions({ accessToken: "token", endpoint: "http://localhost:4566" })
+    ).toEqual({
+      accessToken: "token",
+      endpoints: { account: "http://localhost:4566", basin: "http://localhost:4566" },
+    });
+  });
+
+  it("still resolves the SDK's hosted defaults when no endpoint is configured", () => {
+    const client = buildDeploymentS2Client({ accessToken: "token" });
+
+    expect(client.endpoints.accountBaseUrl()).toBe("https://a.s2.dev/v1");
+    expect(client.endpoints.basinBaseUrl(BASIN)).toBe(`https://${BASIN}.b.s2.dev/v1`);
+    expect(client.endpoints.includeBasinHeader).toBe(false);
+  });
+
+  it("points both the account and basin hosts at a configured endpoint", () => {
+    const client = buildDeploymentS2Client({
+      accessToken: "token",
+      endpoint: "http://localhost:4566",
+    });
+
+    expect(client.endpoints.accountBaseUrl()).toBe("http://localhost:4566/v1");
+    expect(client.endpoints.basinBaseUrl(BASIN)).toBe("http://localhost:4566/v1");
+    expect(client.endpoints.includeBasinHeader).toBe(true);
+  });
+
+  // A split configuration would send the access token to the hosted service while the operator
+  // believed the client was entirely local, so one value has to drive both hosts.
+  it("never leaves one host hosted while the other is overridden", () => {
+    const client = buildDeploymentS2Client({
+      accessToken: "token",
+      endpoint: "http://localhost:4566",
+    });
+
+    expect(client.endpoints.accountBaseUrl()).not.toContain("s2.dev");
+    expect(client.endpoints.basinBaseUrl(BASIN)).not.toContain("s2.dev");
+  });
+});

apps/webapp/test/s2Endpoint.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { isValidS2Endpoint } from "~/utils/s2Endpoint";
+
+describe("isValidS2Endpoint", () => {
+  it("accepts https anywhere", () => {
+    expect(isValidS2Endpoint("https://a.s2.dev")).toBe(true);
+    expect(isValidS2Endpoint("https://s2.internal:4566/v1")).toBe(true);
+  });
+
+  it("accepts http only for a loopback host", () => {
+    expect(isValidS2Endpoint("http://localhost:4566")).toBe(true);
+    expect(isValidS2Endpoint("http://127.0.0.1:4566")).toBe(true);
+    expect(isValidS2Endpoint("http://[::1]:4566")).toBe(true);
+  });
+
+  // The access token is sent to whatever is configured, so cleartext off-box is a credential leak.
+  it("rejects http to a non-loopback host", () => {
+    expect(isValidS2Endpoint("http://s2.example.com")).toBe(false);
+    expect(isValidS2Endpoint("http://10.0.0.5:4566")).toBe(false);
+  });
+
+  // All four pass zod's `.url()`, which is why the schema refines on this instead.
+  it("rejects malformed and non-http schemes", () => {
+    expect(isValidS2Endpoint("htp:/localhost:4566")).toBe(false);
+    expect(isValidS2Endpoint("ftp://localhost")).toBe(false);
+    expect(isValidS2Endpoint("not a url")).toBe(false);
+    expect(isValidS2Endpoint("")).toBe(false);
+  });
+});