@devosurf/tesser-server 0.1.0-alpha.0

package/src/broker/connections.ts

@@ -0,0 +1,278 @@
+// Wires the broker into the engine: builds ctx.connections (typed clients whose every
+// call gets the credential injected at call time) and ctx.secrets. The automation never
+// sees a value that isn't masked in logs.
+
+import { TerminalError, type AutomationDef, type HarnessRunResult, type Logger, type NormalizedModelResponse } from "@devosurf/tesser-sdk";
+import type {
+  ActionCtx,
+  AnyAction,
+  AuthDecl,
+  ConnectorInstance,
+  OAuth2ProviderFacts,
+  ProviderFacts,
+} from "@devosurf/tesser-sdk/connector";
+import {
+  buildConnectorClient,
+  createHttpClient,
+  isRetrySafe,
+  runAction,
+  type HarnessCallInfo,
+  type ModelCallInfo,
+  type TesserHttpConfig,
+} from "@devosurf/tesser-sdk/internal";
+import type { Db } from "../db/db.js";
+import type { ActiveStepHooks, EngineDeps, RunRow } from "../engine/types.js";
+import type { Broker, ConnectionRow } from "./broker.js";
+
+export function authDeclFor(spec: ConnectorInstance<any, any>["__connector"], mode: string): AuthDecl {
+  const auth = spec.auth as AuthDecl | Record<string, AuthDecl>;
+  if ("kind" in auth && typeof auth.kind === "string") return auth as AuthDecl;
+  const decl = (auth as Record<string, AuthDecl>)[mode];
+  if (!decl) throw new TerminalError(`connector ${spec.id}: unknown auth mode "${mode}"`);
+  return decl;
+}
+
+export function providerFactsOf(spec: ConnectorInstance<any, any>["__connector"]): ProviderFacts | undefined {
+  return typeof spec.provider === "object" ? spec.provider : undefined;
+}
+
+export function applyAuthFor(decl: AuthDecl, fields: Record<string, string>): TesserHttpConfig["applyAuth"] {
+  switch (decl.kind) {
+    case "oauth2":
+      return ({ headers }) => {
+        headers.set("authorization", `Bearer ${fields["access_token"] ?? ""}`);
+      };
+    case "apiKey": {
+      const value = (decl.prefix ?? "") + (fields["api_key"] ?? "");
+      if (decl.in === "query") {
+        return ({ url }) => {
+          url.searchParams.set(decl.name, fields["api_key"] ?? "");
+        };
+      }
+      return ({ headers }) => {
+        headers.set(decl.name, value);
+      };
+    }
+    case "basic":
+      return ({ headers }) => {
+        headers.set(
+          "authorization",
+          `Basic ${Buffer.from(`${fields["username"] ?? ""}:${fields["password"] ?? ""}`).toString("base64")}`,
+        );
+      };
+    case "custom":
+      return (req) => decl.sign(req, fields);
+  }
+}
+
+export interface BindingDeps {
+  db: Db;
+  broker: Broker;
+  fetchImpl?: typeof fetch;
+}
+
+async function workspaceOf(db: Db, projectId: string): Promise<string> {
+  const { rows } = await db.query<{ workspace_id: string }>(
+    `SELECT workspace_id FROM projects WHERE id=$1`,
+    [projectId],
+  );
+  if (!rows[0]) throw new TerminalError(`project ${projectId} not found`);
+  return rows[0].workspace_id;
+}
+
+export function makeEngineBindings(deps: BindingDeps): Pick<EngineDeps, "buildConnections" | "resolveSecrets" | "callModel" | "callHarness"> {
+  async function connectionFor(run: RunRow, def: AutomationDef<any, any, any, any, any, any, any>, reqKey: string) {
+    const connector = ((def.connections ?? {}) as Record<string, ConnectorInstance<any, any>>)[reqKey];
+    if (!connector) throw new TerminalError(`connection "${reqKey}" is not declared`);
+    const workspaceId = await workspaceOf(deps.db, run.project_id);
+    const endUserId = (run.trigger["endUserId"] as string | undefined) ?? undefined;
+    const conn = await deps.broker.resolveBinding({
+      workspaceId,
+      projectId: run.project_id,
+      automationId: run.automation_id,
+      env: run.env,
+      reqKey,
+      connectorId: connector.id,
+      scope: connector.scope ?? "workspace",
+      endUserId,
+    });
+    if (!conn) {
+      throw new TerminalError(
+        `no ready ${connector.id} connection for "${reqKey}" — run \`tesser connect\` (deploy should have halted; ADR-0005)`,
+      );
+    }
+    return { workspaceId, connector, conn };
+  }
+
+  return {
+    async buildConnections(run: RunRow, def: AutomationDef<any, any, any, any, any, any, any>, hooks: ActiveStepHooks) {
+      const out: Record<string, unknown> = {};
+      const entries = Object.entries((def.connections ?? {}) as Record<string, ConnectorInstance<any, any>>);
+      if (entries.length === 0) return out;
+      const workspaceId = await workspaceOf(deps.db, run.project_id);
+
+      for (const [reqKey, connector] of entries) {
+        const spec = connector.__connector;
+        const facts = providerFactsOf(spec);
+        const endUserId = (run.trigger["endUserId"] as string | undefined) ?? undefined;
+
+        out[reqKey] = buildConnectorClient(connector, async (path, actionDef, input) => {
+          const step = hooks.current();
+          if (!step) {
+            throw new TerminalError(
+              `connector call ${connector.id}.${path.join(".")} outside ctx.step — side effects live inside steps (ADR-0002)`,
+            );
+          }
+          const { conn } = await connectionFor(run, def, reqKey);
+          if (!isRetrySafe(actionDef as AnyAction, spec.idempotencyHeader !== undefined)) {
+            step.markUnsafeWrite();
+          }
+          const decl = authDeclFor(spec, conn.auth_mode);
+          const bundle = await deps.broker.freshCredential(conn.id, facts?.oauth2);
+
+          const actx = makeActionCtx({
+            spec,
+            decl,
+            conn,
+            facts,
+            fields: bundle.fields,
+            broker: deps.broker,
+            idempotencyKey: step.idempotencyKey,
+            ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+            ...(actionDef.classifyError !== undefined ? { classifyError: actionDef.classifyError } : {}),
+          });
+          return runAction(actionDef as AnyAction, actx, input, `${connector.id}.${path.join(".")}`);
+        });
+      }
+      return out;
+    },
+
+    async resolveSecrets(run: RunRow, def: AutomationDef<any, any, any, any, any, any, any>) {
+      const names = Object.keys((def.secrets ?? {}) as Record<string, unknown>);
+      if (names.length === 0) return {};
+      const workspaceId = await workspaceOf(deps.db, run.project_id);
+      const out: Record<string, string> = {};
+      for (const name of names) {
+        const value = await deps.broker.getSecretValue(workspaceId, name);
+        if (value === null) {
+          throw new TerminalError(`secret "${name}" is not set — deploy should have halted (ADR-0005)`);
+        }
+        out[name] = value;
+      }
+      return out;
+    },
+
+    async callModel(
+      run: RunRow,
+      def: AutomationDef<any, any, any, any, any, any, any>,
+      hooks: ActiveStepHooks,
+      info: ModelCallInfo,
+    ): Promise<NormalizedModelResponse> {
+      const step = hooks.current();
+      if (!step) {
+        throw new TerminalError(`model call ${info.operatorKey}.${info.modelKey} outside ctx.step`);
+      }
+      const { connector, conn } = await connectionFor(run, def, info.model.connection);
+      const spec = connector.__connector;
+      if (!spec.modelProvider) {
+        throw new TerminalError(`connection "${info.model.connection}" (${connector.id}) is not model-capable`);
+      }
+      const facts = providerFactsOf(spec);
+      const decl = authDeclFor(spec, conn.auth_mode);
+      const bundle = await deps.broker.freshCredential(conn.id, facts?.oauth2);
+      const actx = makeActionCtx({
+        spec,
+        decl,
+        conn,
+        facts,
+        fields: bundle.fields,
+        broker: deps.broker,
+        idempotencyKey: step.idempotencyKey,
+        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+      });
+      return spec.modelProvider.call(actx, info.request);
+    },
+
+    async callHarness(
+      run: RunRow,
+      def: AutomationDef<any, any, any, any, any, any, any>,
+      hooks: ActiveStepHooks,
+      info: HarnessCallInfo,
+    ): Promise<HarnessRunResult<unknown>> {
+      const step = hooks.current();
+      if (!step) throw new TerminalError(`harness.${info.harnessKey} ran outside ctx.step`);
+      const { connector, conn } = await connectionFor(run, def, info.harness.connection);
+      const spec = connector.__connector;
+      if (!spec.harnessProvider) {
+        throw new TerminalError(`connection "${info.harness.connection}" (${connector.id}) is not harness-capable`);
+      }
+      const facts = providerFactsOf(spec);
+      const decl = authDeclFor(spec, conn.auth_mode);
+      const bundle = await deps.broker.freshCredential(conn.id, facts?.oauth2);
+      const actx = makeActionCtx({
+        spec,
+        decl,
+        conn,
+        facts,
+        fields: bundle.fields,
+        broker: deps.broker,
+        idempotencyKey: step.idempotencyKey,
+        ...(deps.fetchImpl !== undefined ? { fetchImpl: deps.fetchImpl } : {}),
+      });
+      return spec.harnessProvider.run(actx, info.request, info.harness);
+    },
+  };
+}
+
+/** Build a pre-authed ActionCtx for one connector call — also used by the trigger
+ *  registrar and pollers (ADR-0013 shares the broker boundary). */
+export function makeActionCtx(opts: {
+  spec: ConnectorInstance<any, any>["__connector"];
+  decl: AuthDecl;
+  conn: ConnectionRow;
+  facts: ProviderFacts | undefined;
+  fields: Record<string, string>;
+  broker: Broker;
+  idempotencyKey?: string | undefined;
+  fetchImpl?: typeof fetch | undefined;
+  classifyError?: AnyAction["classifyError"] | undefined;
+  logger?: Logger;
+}): ActionCtx {
+  const baseUrl = opts.spec.baseUrl ?? opts.facts?.baseUrl;
+  const oauthFacts: OAuth2ProviderFacts | undefined = opts.facts?.oauth2;
+  let fields = opts.fields;
+
+  const http = createHttpClient({
+    ...(baseUrl !== undefined ? { baseUrl } : {}),
+    ...(opts.spec.defaultHeaders !== undefined ? { defaultHeaders: opts.spec.defaultHeaders } : {}),
+    ...(opts.fetchImpl !== undefined ? { fetchImpl: opts.fetchImpl } : {}),
+    ...(opts.classifyError !== undefined ? { classifyError: opts.classifyError } : {}),
+    applyAuth: async (req) => {
+      const apply = applyAuthFor(opts.decl, fields);
+      await apply?.(req);
+    },
+    ...(opts.decl.kind === "oauth2" && oauthFacts !== undefined
+      ? {
+          onUnauthorized: async () => {
+            const refreshed = await opts.broker.refreshConnection(opts.conn.id, oauthFacts);
+            if (refreshed) {
+              fields = (await opts.broker.getCredential(opts.conn.id)).fields;
+            }
+            return refreshed;
+          },
+        }
+      : {}),
+  });
+
+  const silent: Logger = { info() {}, warn() {}, error() {} };
+  return {
+    http,
+    auth: {
+      kind: opts.decl.kind,
+      ...(opts.conn.auth_mode !== "default" ? { mode: opts.conn.auth_mode } : {}),
+      fields,
+    },
+    logger: opts.logger ?? silent,
+    ...(opts.idempotencyKey !== undefined ? { idempotencyKey: opts.idempotencyKey } : {}),
+  };
+}

package/src/broker/crypto.ts

@@ -0,0 +1,39 @@
+// Envelope encryption (ADR-0005): master key (env/file) wraps per-workspace data keys;
+// data keys encrypt credential/secret values at rest. AES-256-GCM, versioned format.
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+
+const VERSION = "v1";
+
+export function encrypt(key: Buffer, plaintext: string | Buffer): string {
+  if (key.length !== 32) throw new Error("encryption key must be 32 bytes");
+  const iv = randomBytes(12);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const data = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return [VERSION, iv.toString("base64"), tag.toString("base64"), data.toString("base64")].join(":");
+}
+
+export function decrypt(key: Buffer, payload: string): Buffer {
+  const [version, ivB64, tagB64, dataB64] = payload.split(":");
+  if (version !== VERSION || !ivB64 || !tagB64 || !dataB64) {
+    throw new Error("unrecognized ciphertext format");
+  }
+  const decipher = createDecipheriv("aes-256-gcm", key, Buffer.from(ivB64, "base64"));
+  decipher.setAuthTag(Buffer.from(tagB64, "base64"));
+  return Buffer.concat([decipher.update(Buffer.from(dataB64, "base64")), decipher.final()]);
+}
+
+export function generateDataKey(): Buffer {
+  return randomBytes(32);
+}
+
+export function wrapDataKey(masterKey: Buffer, dataKey: Buffer): string {
+  return encrypt(masterKey, dataKey);
+}
+
+export function unwrapDataKey(masterKey: Buffer, wrapped: string): Buffer {
+  const key = decrypt(masterKey, wrapped);
+  if (key.length !== 32) throw new Error("unwrapped data key has wrong length");
+  return key;
+}

package/src/broker/masking.ts

@@ -0,0 +1,32 @@
+// Log masking (ADR-0005): every decrypted credential value (≥ 8 chars — shorter values
+// would mask common words) is registered here; every string headed to logs passes
+// through mask(). The broker is the only place values are decrypted, so registration
+// is structurally complete.
+
+const MIN_LENGTH = 8;
+
+export class Masker {
+  private values = new Map<string, string>(); // value → label
+
+  add(value: string, label = "secret"): void {
+    if (typeof value !== "string" || value.length < MIN_LENGTH) return;
+    this.values.set(value, label);
+  }
+
+  addFields(fields: Record<string, string>, prefix: string): void {
+    for (const [k, v] of Object.entries(fields)) this.add(v, `${prefix}.${k}`);
+  }
+
+  mask(text: string): string {
+    if (typeof text !== "string" || text.length === 0) return text;
+    let out = text;
+    for (const [value, label] of this.values) {
+      if (out.includes(value)) out = out.split(value).join(`[masked:${label}]`);
+    }
+    return out;
+  }
+
+  get size(): number {
+    return this.values.size;
+  }
+}

package/src/broker/oauth.ts

@@ -0,0 +1,170 @@
+// Our own OAuth2 executor (ADR-0004): auth-code + PKCE, refresh, client-credentials —
+// driven entirely by Catalog provider facts. No third-party OAuth code ships.
+
+import { createHash, randomBytes } from "node:crypto";
+import type { OAuth2ProviderFacts } from "@devosurf/tesser-sdk/connector";
+
+export interface TokenSet {
+  accessToken: string;
+  refreshToken?: string;
+  /** Epoch ms; undefined = non-expiring (e.g. GitHub OAuth-app tokens). */
+  expiresAt?: number;
+  tokenType?: string;
+  scope?: string;
+  raw: Record<string, unknown>;
+}
+
+export class OAuthError extends Error {
+  constructor(
+    message: string,
+    readonly providerResponse?: unknown,
+  ) {
+    super(message);
+    this.name = "OAuthError";
+  }
+}
+
+function b64url(buf: Buffer): string {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = b64url(randomBytes(48));
+  const challenge = b64url(createHash("sha256").update(verifier).digest());
+  return { verifier, challenge };
+}
+
+export function buildAuthorizeUrl(opts: {
+  facts: OAuth2ProviderFacts;
+  clientId: string;
+  redirectUri: string;
+  scopes: readonly string[];
+  state: string;
+  codeChallenge?: string | undefined;
+}): string {
+  const url = new URL(opts.facts.authorizeUrl);
+  url.searchParams.set("client_id", opts.clientId);
+  url.searchParams.set("redirect_uri", opts.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("state", opts.state);
+  if (opts.scopes.length > 0) {
+    url.searchParams.set("scope", opts.scopes.join(opts.facts.scopeSeparator ?? " "));
+  }
+  if (opts.codeChallenge !== undefined) {
+    url.searchParams.set("code_challenge", opts.codeChallenge);
+    url.searchParams.set("code_challenge_method", "S256");
+  }
+  for (const [k, v] of Object.entries(opts.facts.extraAuthorizeParams ?? {})) {
+    url.searchParams.set(k, v);
+  }
+  return url.toString();
+}
+
+async function tokenRequest(
+  facts: OAuth2ProviderFacts,
+  clientId: string,
+  clientSecret: string | undefined,
+  params: Record<string, string>,
+  fetchImpl: typeof fetch,
+): Promise<TokenSet> {
+  const body = new URLSearchParams(params);
+  const headers = new Headers({
+    "content-type": "application/x-www-form-urlencoded",
+    // GitHub answers form-encoded unless asked for JSON.
+    accept: "application/json",
+  });
+  if ((facts.clientAuth ?? "body") === "basic") {
+    headers.set("authorization", `Basic ${Buffer.from(`${clientId}:${clientSecret ?? ""}`).toString("base64")}`);
+  } else {
+    body.set("client_id", clientId);
+    if (clientSecret !== undefined) body.set("client_secret", clientSecret);
+  }
+  for (const [k, v] of Object.entries(facts.extraTokenParams ?? {})) body.set(k, v);
+
+  let res: Response;
+  try {
+    res = await fetchImpl(facts.tokenUrl, { method: "POST", headers, body });
+  } catch (cause) {
+    throw new OAuthError(`token endpoint unreachable: ${String(cause)}`);
+  }
+  const text = await res.text();
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    parsed = Object.fromEntries(new URLSearchParams(text)); // form-encoded fallback
+  }
+  if (!res.ok || parsed["error"] !== undefined || typeof parsed["access_token"] !== "string") {
+    throw new OAuthError(
+      `token endpoint ${res.status}: ${String(parsed["error"] ?? text.slice(0, 200))}`,
+      parsed,
+    );
+  }
+  const expiresIn = Number(parsed["expires_in"]);
+  return {
+    accessToken: parsed["access_token"] as string,
+    ...(typeof parsed["refresh_token"] === "string" ? { refreshToken: parsed["refresh_token"] } : {}),
+    ...(Number.isFinite(expiresIn) && expiresIn > 0 ? { expiresAt: Date.now() + expiresIn * 1000 } : {}),
+    ...(typeof parsed["token_type"] === "string" ? { tokenType: parsed["token_type"] } : {}),
+    ...(typeof parsed["scope"] === "string" ? { scope: parsed["scope"] } : {}),
+    raw: parsed,
+  };
+}
+
+export async function exchangeCode(opts: {
+  facts: OAuth2ProviderFacts;
+  clientId: string;
+  clientSecret?: string | undefined;
+  code: string;
+  redirectUri: string;
+  codeVerifier?: string | undefined;
+  fetchImpl?: typeof fetch;
+}): Promise<TokenSet> {
+  return tokenRequest(
+    opts.facts,
+    opts.clientId,
+    opts.clientSecret,
+    {
+      grant_type: "authorization_code",
+      code: opts.code,
+      redirect_uri: opts.redirectUri,
+      ...(opts.codeVerifier !== undefined ? { code_verifier: opts.codeVerifier } : {}),
+    },
+    opts.fetchImpl ?? fetch,
+  );
+}
+
+export async function refreshToken(opts: {
+  facts: OAuth2ProviderFacts;
+  clientId: string;
+  clientSecret?: string | undefined;
+  refreshToken: string;
+  fetchImpl?: typeof fetch;
+}): Promise<TokenSet> {
+  return tokenRequest(
+    opts.facts,
+    opts.clientId,
+    opts.clientSecret,
+    { grant_type: "refresh_token", refresh_token: opts.refreshToken },
+    opts.fetchImpl ?? fetch,
+  );
+}
+
+export async function clientCredentials(opts: {
+  facts: OAuth2ProviderFacts;
+  clientId: string;
+  clientSecret: string;
+  scopes: readonly string[];
+  fetchImpl?: typeof fetch;
+}): Promise<TokenSet> {
+  return tokenRequest(
+    opts.facts,
+    opts.clientId,
+    opts.clientSecret,
+    {
+      grant_type: "client_credentials",
+      ...(opts.scopes.length > 0 ? { scope: opts.scopes.join(opts.facts.scopeSeparator ?? " ") } : {}),
+    },
+    opts.fetchImpl ?? fetch,
+  );
+}

package/src/config.ts

@@ -0,0 +1,128 @@
+// Instance configuration — env-driven, defaults tuned for `tesser dev` (embedded PGlite,
+// auto master key). Production fails fast on missing or unsafe required env.
+
+import { mkdirSync, readFileSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+
+export interface ServerConfig {
+  port: number;
+  /** Public base URL for webhooks/connect links (defaults to http://localhost:<port>). */
+  baseUrl: string;
+  databaseUrl: string | undefined;
+  dataDir: string;
+  masterKey: Buffer;
+  /** Which duties this process performs. */
+  roles: { api: boolean; worker: boolean; scheduler: boolean; reconciler: boolean };
+  workerTags: string[] | undefined;
+  pollIntervalMs: number;
+  env: "production" | "development";
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): ServerConfig {
+  const port = Number(env["PORT"] ?? env["TESSER_PORT"] ?? 8377);
+  const mode: ServerConfig["env"] = env["NODE_ENV"] === "production" ? "production" : "development";
+  const production = mode === "production";
+  const dataDir = env["TESSER_DATA_DIR"] ?? join(process.cwd(), ".tesser");
+  const databaseUrl = env["DATABASE_URL"] ?? env["TESSER_DATABASE_URL"];
+  const baseUrl = env["TESSER_BASE_URL"] ?? (production ? undefined : `http://localhost:${port}`);
+  const rolesEnv = env["TESSER_ROLES"]; // e.g. "api,worker" — dev default: everything
+
+  if (production) {
+    const missing = [
+      ...(databaseUrl ? [] : ["DATABASE_URL"]),
+      ...(baseUrl ? [] : ["TESSER_BASE_URL"]),
+      ...(env["TESSER_MASTER_KEY"] ? [] : ["TESSER_MASTER_KEY"]),
+      ...(rolesEnv ? [] : ["TESSER_ROLES"]),
+    ];
+    if (missing.length > 0) {
+      throw new Error(`production configuration missing required env: ${missing.join(", ")}`);
+    }
+  }
+
+  const normalizedBaseUrl = validateBaseUrl(baseUrl!, { production, allowLocalhost: env["TESSER_ALLOW_LOCALHOST_BASE_URL"] === "true" });
+  ensureWritableDataDir(dataDir);
+
+  let masterKey: Buffer;
+  const fromEnv = env["TESSER_MASTER_KEY"];
+  if (fromEnv) {
+    masterKey = Buffer.from(fromEnv, "base64");
+    if (masterKey.length !== 32) {
+      throw new Error("TESSER_MASTER_KEY must be 32 bytes, base64-encoded");
+    }
+  } else {
+    // Dev convenience: generate once into the data dir, loudly. Production should set
+    // TESSER_MASTER_KEY explicitly (custody/rotation: docs/SCOPES.md §4).
+    const keyPath = join(dataDir, "master.key");
+    if (existsSync(keyPath)) {
+      masterKey = Buffer.from(readFileSync(keyPath, "utf8").trim(), "base64");
+    } else {
+      masterKey = randomBytes(32);
+      writeFileSync(keyPath, masterKey.toString("base64") + "\n", { mode: 0o600 });
+      console.error(
+        `[tesser] generated a development master key at ${keyPath} — set TESSER_MASTER_KEY in production`,
+      );
+    }
+  }
+
+  const roleSet = parseRoles(rolesEnv ?? "api,worker,scheduler,reconciler");
+
+  return {
+    port,
+    baseUrl: normalizedBaseUrl,
+    databaseUrl,
+    dataDir,
+    masterKey,
+    roles: {
+      api: roleSet.has("api"),
+      worker: roleSet.has("worker"),
+      scheduler: roleSet.has("scheduler"),
+      reconciler: roleSet.has("reconciler"),
+    },
+    workerTags: env["TESSER_WORKER_TAGS"]?.split(",").map((tag) => tag.trim()).filter(Boolean),
+    pollIntervalMs: Number(env["TESSER_QUEUE_POLL_MS"] ?? 250),
+    env: mode,
+  };
+}
+
+function validateBaseUrl(input: string, opts: { production: boolean; allowLocalhost: boolean }): string {
+  let parsed: URL;
+  try {
+    parsed = new URL(input);
+  } catch {
+    throw new Error("TESSER_BASE_URL must be an absolute URL");
+  }
+  if (parsed.pathname !== "/" || parsed.search || parsed.hash) {
+    throw new Error("TESSER_BASE_URL must be an origin only, for example https://tesser.example.com");
+  }
+  if (opts.production && !opts.allowLocalhost && isLocalhost(parsed.hostname)) {
+    throw new Error("TESSER_BASE_URL must not be localhost in production; set a public origin");
+  }
+  return parsed.origin;
+}
+
+function isLocalhost(hostname: string): boolean {
+  const host = hostname.toLowerCase();
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+
+function parseRoles(input: string): Set<string> {
+  const allowed = new Set(["api", "worker", "scheduler", "reconciler"]);
+  const roles = input.split(",").map((role) => role.trim()).filter(Boolean);
+  const unknown = roles.filter((role) => !allowed.has(role));
+  if (unknown.length > 0) throw new Error(`TESSER_ROLES includes unknown role(s): ${unknown.join(", ")}`);
+  if (roles.length === 0) throw new Error("TESSER_ROLES must include at least one role");
+  return new Set(roles);
+}
+
+function ensureWritableDataDir(dataDir: string): void {
+  try {
+    mkdirSync(dataDir, { recursive: true });
+    const probe = join(dataDir, `.tesser-write-probe-${randomBytes(8).toString("hex")}`);
+    writeFileSync(probe, "ok", { flag: "wx" });
+    rmSync(probe, { force: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`TESSER_DATA_DIR must be writable for runtime data and artifacts: ${message}`);
+  }
+}