@devosurf/tesser-server 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@devosurf/tesser-server",
+  "version": "0.1.0-alpha.0",
+  "description": "Tesser runtime, scheduler, credential broker, git-sync and control-plane.",
+  "license": "AGPL-3.0-only",
+  "type": "module",
+  "bin": {
+    "tesser-server": "./bin/tesser-server.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./dist/main.js"
+    }
+  },
+  "dependencies": {
+    "@electric-sql/pglite": "^0.5.2",
+    "@hono/node-server": "^2.0.4",
+    "croner": "^10.0.1",
+    "esbuild": "^0.28.1",
+    "hono": "^4.12.25",
+    "pg": "^8.21.0",
+    "@devosurf/tesser-brand": "0.1.0-alpha.0",
+    "@devosurf/tesser-sdk": "0.1.0-alpha.0",
+    "@devosurf/tesser-testing": "^0.1.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.20.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/main.js",
+  "types": "./src/index.ts",
+  "files": [
+    "bin",
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/src/broker/broker.ts

@@ -0,0 +1,332 @@
+// The Credential broker (ADR-0004/0005): the ONLY place credential values are decrypted.
+// Automations hold handles; the broker injects values at call time and registers every
+// decrypted value with the log masker. Refresh is single-flight per connection.
+
+import type { OAuth2ProviderFacts } from "@devosurf/tesser-sdk/connector";
+import type { Db } from "../db/db.js";
+import { decrypt, encrypt, generateDataKey, unwrapDataKey, wrapDataKey } from "./crypto.js";
+import { Masker } from "./masking.js";
+import { refreshToken } from "./oauth.js";
+
+export interface ConnectionRow {
+  id: string;
+  workspace_id: string;
+  connector_id: string;
+  provider: string | null;
+  auth_mode: string;
+  scope: string;
+  end_user_id: string | null;
+  label: string | null;
+  credential_cipher: string | null;
+  credential_meta: { expiresAt?: number; scope?: string; tokenType?: string };
+  status: string;
+}
+
+export interface CredentialBundle {
+  fields: Record<string, string>;
+  meta: ConnectionRow["credential_meta"];
+}
+
+export class Broker {
+  private dataKeys = new Map<string, Buffer>();
+  private refreshing = new Map<string, Promise<boolean>>();
+
+  constructor(
+    private readonly db: Db,
+    private readonly masterKey: Buffer,
+    readonly masker: Masker,
+    private readonly fetchImpl: typeof fetch = fetch,
+  ) {}
+
+  // ---- workspaces & data keys ----
+
+  async ensureDefaultWorkspace(): Promise<string> {
+    const existing = await this.db.query<{ id: string }>(
+      `SELECT id FROM workspaces ORDER BY created_at LIMIT 1`,
+    );
+    if (existing.rows[0]) return existing.rows[0].id;
+    const wrapped = wrapDataKey(this.masterKey, generateDataKey());
+    const created = await this.db.query<{ id: string }>(
+      `INSERT INTO workspaces (name, data_key_cipher) VALUES ('default', $1) RETURNING id`,
+      [wrapped],
+    );
+    return created.rows[0]!.id;
+  }
+
+  private async dataKey(workspaceId: string): Promise<Buffer> {
+    const cached = this.dataKeys.get(workspaceId);
+    if (cached) return cached;
+    const { rows } = await this.db.query<{ data_key_cipher: string }>(
+      `SELECT data_key_cipher FROM workspaces WHERE id = $1`,
+      [workspaceId],
+    );
+    if (!rows[0]) throw new Error(`workspace ${workspaceId} not found`);
+    const key = unwrapDataKey(this.masterKey, rows[0].data_key_cipher);
+    this.dataKeys.set(workspaceId, key);
+    return key;
+  }
+
+  // ---- secrets (raw values, ADR-0010) ----
+
+  async setSecret(workspaceId: string, name: string, value: string): Promise<void> {
+    const cipher = encrypt(await this.dataKey(workspaceId), value);
+    await this.db.query(
+      `INSERT INTO secrets (workspace_id, name, value_cipher) VALUES ($1,$2,$3)
+       ON CONFLICT (workspace_id, name) DO UPDATE SET value_cipher = EXCLUDED.value_cipher, updated_at = now()`,
+      [workspaceId, name, cipher],
+    );
+    this.masker.add(value, `secret.${name}`);
+  }
+
+  async getSecretValue(workspaceId: string, name: string): Promise<string | null> {
+    const { rows } = await this.db.query<{ value_cipher: string }>(
+      `SELECT value_cipher FROM secrets WHERE workspace_id=$1 AND name=$2`,
+      [workspaceId, name],
+    );
+    if (!rows[0]) return null;
+    const value = decrypt(await this.dataKey(workspaceId), rows[0].value_cipher).toString("utf8");
+    this.masker.add(value, `secret.${name}`);
+    return value;
+  }
+
+  async listSecretNames(workspaceId: string): Promise<Array<{ name: string; updatedAt: string }>> {
+    const { rows } = await this.db.query<{ name: string; updated_at: string }>(
+      `SELECT name, updated_at FROM secrets WHERE workspace_id=$1 ORDER BY name`,
+      [workspaceId],
+    );
+    return rows.map((r) => ({ name: r.name, updatedAt: String(r.updated_at) }));
+  }
+
+  async deleteSecret(workspaceId: string, name: string): Promise<boolean> {
+    const { rowCount } = await this.db.query(`DELETE FROM secrets WHERE workspace_id=$1 AND name=$2`, [
+      workspaceId,
+      name,
+    ]);
+    return rowCount > 0;
+  }
+
+  // ---- connections ----
+
+  async createConnection(opts: {
+    workspaceId: string;
+    connectorId: string;
+    provider?: string | undefined;
+    authMode?: string;
+    scope?: "workspace" | "per_user";
+    endUserId?: string;
+    label?: string;
+  }): Promise<string> {
+    const { rows } = await this.db.query<{ id: string }>(
+      `INSERT INTO connections (workspace_id, connector_id, provider, auth_mode, scope, end_user_id, label, status)
+       VALUES ($1,$2,$3,$4,$5,$6,$7,'pending') RETURNING id`,
+      [
+        opts.workspaceId,
+        opts.connectorId,
+        opts.provider ?? null,
+        opts.authMode ?? "default",
+        opts.scope ?? "workspace",
+        opts.endUserId ?? null,
+        opts.label ?? null,
+      ],
+    );
+    return rows[0]!.id;
+  }
+
+  async setConnectionCredential(
+    connectionId: string,
+    fields: Record<string, string>,
+    meta: ConnectionRow["credential_meta"] = {},
+  ): Promise<void> {
+    const { rows } = await this.db.query<{ workspace_id: string; connector_id: string }>(
+      `SELECT workspace_id, connector_id FROM connections WHERE id=$1`,
+      [connectionId],
+    );
+    if (!rows[0]) throw new Error(`connection ${connectionId} not found`);
+    const cipher = encrypt(await this.dataKey(rows[0].workspace_id), JSON.stringify(fields));
+    await this.db.query(
+      `UPDATE connections SET credential_cipher=$2, credential_meta=$3::jsonb, status='ready', error=NULL, updated_at=now()
+       WHERE id=$1`,
+      [connectionId, cipher, JSON.stringify(meta)],
+    );
+    this.masker.addFields(fields, `connection.${rows[0].connector_id}`);
+  }
+
+  async getConnection(connectionId: string): Promise<ConnectionRow | null> {
+    const { rows } = await this.db.query<ConnectionRow>(`SELECT * FROM connections WHERE id=$1`, [connectionId]);
+    return rows[0] ?? null;
+  }
+
+  async getCredential(connectionId: string): Promise<CredentialBundle> {
+    const row = await this.getConnection(connectionId);
+    if (!row || row.status !== "ready" || !row.credential_cipher) {
+      throw new Error(`connection ${connectionId} is not ready`);
+    }
+    const fields = JSON.parse(
+      decrypt(await this.dataKey(row.workspace_id), row.credential_cipher).toString("utf8"),
+    ) as Record<string, string>;
+    this.masker.addFields(fields, `connection.${row.connector_id}`);
+    return { fields, meta: row.credential_meta ?? {} };
+  }
+
+  async listConnections(workspaceId: string): Promise<
+    Array<{ id: string; connectorId: string; authMode: string; scope: string; label: string | null; status: string; endUserId: string | null }>
+  > {
+    const { rows } = await this.db.query<ConnectionRow>(
+      `SELECT * FROM connections WHERE workspace_id=$1 ORDER BY created_at`,
+      [workspaceId],
+    );
+    return rows.map((r) => ({
+      id: r.id,
+      connectorId: r.connector_id,
+      authMode: r.auth_mode,
+      scope: r.scope,
+      label: r.label,
+      status: r.status,
+      endUserId: r.end_user_id,
+    }));
+  }
+
+  /** Resolve an automation's `connections.<reqKey>` to a concrete ready Connection —
+   *  the persisted binding wins; otherwise auto-bind when exactly one candidate exists. */
+  async resolveBinding(opts: {
+    workspaceId: string;
+    projectId: string;
+    automationId: string;
+    env: string;
+    reqKey: string;
+    connectorId: string;
+    scope: "workspace" | "per_user";
+    endUserId?: string | undefined;
+  }): Promise<ConnectionRow | null> {
+    if (opts.scope === "workspace") {
+      const bound = await this.db.query<{ connection_id: string }>(
+        `SELECT connection_id FROM requirement_bindings
+         WHERE project_id=$1 AND automation_id=$2 AND env=$3 AND req_key=$4`,
+        [opts.projectId, opts.automationId, opts.env, opts.reqKey],
+      );
+      if (bound.rows[0]) {
+        const conn = await this.getConnection(bound.rows[0].connection_id);
+        if (conn?.status === "ready") return conn;
+      }
+    }
+    const endUserFilter = opts.scope === "per_user" ? `AND end_user_id = $4` : `AND scope = 'workspace'`;
+    const params: unknown[] =
+      opts.scope === "per_user"
+        ? [opts.workspaceId, opts.connectorId, "ready", opts.endUserId ?? null]
+        : [opts.workspaceId, opts.connectorId, "ready"];
+    const { rows } = await this.db.query<ConnectionRow>(
+      `SELECT * FROM connections WHERE workspace_id=$1 AND connector_id=$2 AND status=$3 ${endUserFilter}
+       ORDER BY created_at`,
+      params,
+    );
+    if (rows.length !== 1) return null; // 0 = missing; >1 = ambiguous → must bind explicitly
+    const conn = rows[0]!;
+    if (opts.scope === "workspace") {
+      await this.db.query(
+        `INSERT INTO requirement_bindings (project_id, automation_id, env, req_key, connection_id)
+         VALUES ($1,$2,$3,$4,$5)
+         ON CONFLICT (project_id, automation_id, env, req_key) DO UPDATE SET connection_id = EXCLUDED.connection_id`,
+        [opts.projectId, opts.automationId, opts.env, opts.reqKey, conn.id],
+      );
+    }
+    return conn;
+  }
+
+  // ---- OAuth apps (BYO per workspace, ADR-0005; env fallback for dev) ----
+
+  async setOAuthApp(workspaceId: string, provider: string, clientId: string, clientSecret: string): Promise<void> {
+    const cipher = encrypt(await this.dataKey(workspaceId), clientSecret);
+    await this.db.query(
+      `INSERT INTO oauth_apps (workspace_id, provider, client_id, client_secret_cipher)
+       VALUES ($1,$2,$3,$4)
+       ON CONFLICT (workspace_id, provider) DO UPDATE SET client_id=EXCLUDED.client_id, client_secret_cipher=EXCLUDED.client_secret_cipher`,
+      [workspaceId, provider, clientId, cipher],
+    );
+    this.masker.add(clientSecret, `oauthapp.${provider}`);
+  }
+
+  async getOAuthApp(
+    workspaceId: string,
+    provider: string,
+  ): Promise<{ clientId: string; clientSecret: string } | null> {
+    const { rows } = await this.db.query<{ client_id: string; client_secret_cipher: string }>(
+      `SELECT client_id, client_secret_cipher FROM oauth_apps WHERE workspace_id=$1 AND provider=$2`,
+      [workspaceId, provider],
+    );
+    if (rows[0]) {
+      const clientSecret = decrypt(await this.dataKey(workspaceId), rows[0].client_secret_cipher).toString("utf8");
+      this.masker.add(clientSecret, `oauthapp.${provider}`);
+      return { clientId: rows[0].client_id, clientSecret };
+    }
+    const envKey = provider.toUpperCase().replace(/[^A-Z0-9]/g, "_");
+    const clientId = process.env[`TESSER_OAUTH_${envKey}_CLIENT_ID`];
+    const clientSecret = process.env[`TESSER_OAUTH_${envKey}_CLIENT_SECRET`];
+    if (clientId && clientSecret) return { clientId, clientSecret };
+    return null;
+  }
+
+  // ---- token freshness (refresh-once, single-flight per connection) ----
+
+  /** Returns true when a refresh happened (caller should re-read the credential). */
+  async refreshConnection(connectionId: string, facts: OAuth2ProviderFacts): Promise<boolean> {
+    const inFlight = this.refreshing.get(connectionId);
+    if (inFlight) return inFlight;
+    const p = (async (): Promise<boolean> => {
+      const row = await this.getConnection(connectionId);
+      if (!row) return false;
+      const { fields, meta } = await this.getCredential(connectionId);
+      const rt = fields["refresh_token"];
+      if (rt === undefined) return false;
+      const app = await this.getOAuthApp(row.workspace_id, row.provider ?? row.connector_id);
+      if (!app) return false;
+      const tokens = await refreshToken({
+        facts,
+        clientId: app.clientId,
+        clientSecret: app.clientSecret,
+        refreshToken: rt,
+        fetchImpl: this.fetchImpl,
+      });
+      const nextFields: Record<string, string> = {
+        ...fields,
+        access_token: tokens.accessToken,
+        ...(tokens.refreshToken !== undefined ? { refresh_token: tokens.refreshToken } : {}),
+      };
+      await this.setConnectionCredential(connectionId, nextFields, {
+        ...meta,
+        ...(tokens.expiresAt !== undefined ? { expiresAt: tokens.expiresAt } : {}),
+      });
+      return true;
+    })().finally(() => this.refreshing.delete(connectionId));
+    this.refreshing.set(connectionId, p);
+    return p;
+  }
+
+  /** Workspace-keyed encryption for values that live outside the secrets table
+   *  (deploy keys, webhook signing secrets). */
+  async encryptValue(workspaceId: string, value: string, maskLabel?: string): Promise<string> {
+    if (maskLabel !== undefined) this.masker.add(value, maskLabel);
+    return encrypt(await this.dataKey(workspaceId), value);
+  }
+
+  async decryptValue(workspaceId: string, cipher: string, maskLabel?: string): Promise<string> {
+    const value = decrypt(await this.dataKey(workspaceId), cipher).toString("utf8");
+    if (maskLabel !== undefined) this.masker.add(value, maskLabel);
+    return value;
+  }
+
+  /** Ensure a fresh access token (60s slack) before injecting. */
+  async freshCredential(connectionId: string, facts: OAuth2ProviderFacts | undefined): Promise<CredentialBundle> {
+    let bundle = await this.getCredential(connectionId);
+    const expiresAt = bundle.meta.expiresAt;
+    if (
+      facts !== undefined &&
+      typeof expiresAt === "number" &&
+      expiresAt < Date.now() + 60_000 &&
+      bundle.fields["refresh_token"] !== undefined
+    ) {
+      const refreshed = await this.refreshConnection(connectionId, facts);
+      if (refreshed) bundle = await this.getCredential(connectionId);
+    }
+    return bundle;
+  }
+}

package/src/broker/connect.ts

@@ -0,0 +1,224 @@
+// The credential handoff (ADR-0005): deploy halts on missing requirements; the server
+// mints a short-lived single-use connect link; a human completes OAuth / pastes values
+// in their browser; the agent only ever polls a status.
+
+import { randomBytes } from "node:crypto";
+import type { ConnectorManifest } from "@devosurf/tesser-sdk/internal";
+import type { ProviderFacts } from "@devosurf/tesser-sdk/connector";
+import type { Db } from "../db/db.js";
+import type { Broker } from "./broker.js";
+
+export interface ConnectionRequirement {
+  type: "connection";
+  key: string;
+  connector: string;
+  scope: "workspace" | "per_user";
+  /** Auth modes the human can choose between (from the connector manifest). */
+  modes: Array<{
+    name: string;
+    kind: "oauth2" | "apiKey" | "basic" | "custom";
+    describe?: string;
+    /** Paste-field names for non-OAuth modes. */
+    fields: string[];
+    scopes?: string[];
+  }>;
+  provider?: string;
+  providerFacts?: ProviderFacts;
+  automations: string[];
+}
+
+export interface SecretRequirement {
+  type: "secret";
+  name: string;
+  describe?: string;
+  automations: string[];
+}
+
+export interface ManualWebhookRequirement {
+  type: "webhook-manual";
+  registrationId: string;
+  connector: string;
+  trigger: string;
+  automation: string;
+  instructions: string;
+  url: string;
+}
+
+export type Requirement = ConnectionRequirement | SecretRequirement | ManualWebhookRequirement;
+
+export interface AutomationRequirementSource {
+  automationId: string;
+  connections: Record<string, { connector: string; scope: "workspace" | "per_user" }>;
+  secrets: Record<string, { describe?: string }>;
+}
+
+function fieldsFor(kind: string, declared?: string[]): string[] {
+  switch (kind) {
+    case "apiKey":
+      return ["api_key"];
+    case "basic":
+      return ["username", "password"];
+    case "custom":
+      return declared ?? [];
+    default:
+      return [];
+  }
+}
+
+/** Compute what is still missing for a set of automations (deploy-halt gate). */
+export async function computeMissingRequirements(opts: {
+  db: Db;
+  broker: Broker;
+  workspaceId: string;
+  projectId: string;
+  env: string;
+  automations: AutomationRequirementSource[];
+  connectorManifests: Record<string, ConnectorManifest & { providerFacts?: ProviderFacts }>;
+}): Promise<Requirement[]> {
+  const connReqs = new Map<string, ConnectionRequirement>();
+  const secretReqs = new Map<string, SecretRequirement>();
+
+  for (const auto of opts.automations) {
+    for (const [key, decl] of Object.entries(auto.connections)) {
+      let satisfied = false;
+      if (decl.scope === "per_user") {
+        // Deploy-time validation cannot know every future end user. For per-user
+        // requirements, the production gate only proves that this Instance has at
+        // least one non-null end-user Connection for the Connector; runtime still
+        // resolves the exact endUserId and fails closed for unknown users.
+        const { rows } = await opts.db.query(
+          `SELECT 1 FROM connections
+           WHERE workspace_id=$1 AND connector_id=$2 AND status='ready' AND scope='per_user' AND end_user_id IS NOT NULL
+           LIMIT 1`,
+          [opts.workspaceId, decl.connector],
+        );
+        satisfied = rows.length > 0;
+      } else {
+        const resolved = await opts.broker.resolveBinding({
+          workspaceId: opts.workspaceId,
+          projectId: opts.projectId,
+          automationId: auto.automationId,
+          env: opts.env,
+          reqKey: key,
+          connectorId: decl.connector,
+          scope: decl.scope,
+        });
+        satisfied = resolved !== null;
+      }
+      if (satisfied) continue;
+      const manifest = opts.connectorManifests[decl.connector];
+      const id = `${decl.connector}:${decl.scope}`;
+      const existing = connReqs.get(id);
+      if (existing) {
+        if (!existing.automations.includes(auto.automationId)) existing.automations.push(auto.automationId);
+        continue;
+      }
+      const modes = Object.entries(manifest?.auth ?? { default: { kind: "apiKey" as const, in: "header", name: "Authorization" } }).map(
+        ([name, decl2]) => ({
+          name,
+          kind: decl2.kind as ConnectionRequirement["modes"][number]["kind"],
+          fields: fieldsFor(decl2.kind, (decl2 as { fields?: string[] }).fields),
+          ...("describe" in decl2 && decl2.describe !== undefined ? { describe: decl2.describe } : {}),
+          ...(decl2.kind === "oauth2" && "scopes" in decl2 ? { scopes: decl2.scopes } : {}),
+        }),
+      );
+      connReqs.set(id, {
+        type: "connection",
+        key,
+        connector: decl.connector,
+        scope: decl.scope,
+        modes,
+        ...(manifest?.provider !== undefined ? { provider: manifest.provider } : {}),
+        ...(manifest?.providerFacts !== undefined ? { providerFacts: manifest.providerFacts } : {}),
+        automations: [auto.automationId],
+      });
+    }
+    for (const [name, decl] of Object.entries(auto.secrets)) {
+      const value = await opts.broker.getSecretValue(opts.workspaceId, name);
+      if (value !== null) continue;
+      const existing = secretReqs.get(name);
+      if (existing) {
+        if (!existing.automations.includes(auto.automationId)) existing.automations.push(auto.automationId);
+        continue;
+      }
+      secretReqs.set(name, {
+        type: "secret",
+        name,
+        ...(decl.describe !== undefined ? { describe: decl.describe } : {}),
+        automations: [auto.automationId],
+      });
+    }
+  }
+  return [...connReqs.values(), ...secretReqs.values()];
+}
+
+export async function mintConnectLink(opts: {
+  db: Db;
+  workspaceId: string;
+  projectId?: string | undefined;
+  requirements: Requirement[];
+  ttlMs?: number;
+}): Promise<string> {
+  const token = `cl_${randomBytes(18).toString("hex")}`;
+  await opts.db.query(
+    `INSERT INTO connect_links (token, workspace_id, project_id, requirements, expires_at)
+     VALUES ($1,$2,$3,$4::jsonb, now() + ($5 || ' milliseconds')::interval)`,
+    [token, opts.workspaceId, opts.projectId ?? null, JSON.stringify(opts.requirements), String(opts.ttlMs ?? 24 * 3600 * 1000)],
+  );
+  return token;
+}
+
+export interface ConnectLinkRow {
+  token: string;
+  workspace_id: string;
+  project_id: string | null;
+  requirements: Requirement[];
+  status: string;
+  expires_at: string;
+}
+
+export async function getConnectLink(db: Db, token: string): Promise<ConnectLinkRow | null> {
+  const { rows } = await db.query<ConnectLinkRow>(`SELECT * FROM connect_links WHERE token=$1`, [token]);
+  const link = rows[0];
+  if (!link) return null;
+  if (link.status === "pending" && new Date(String(link.expires_at)).getTime() < Date.now()) {
+    await db.query(`UPDATE connect_links SET status='expired' WHERE token=$1`, [token]);
+    link.status = "expired";
+  }
+  return link;
+}
+
+/** Per-requirement satisfaction + link completion. */
+export async function connectLinkStatus(
+  db: Db,
+  broker: Broker,
+  link: ConnectLinkRow,
+): Promise<{ status: string; requirements: Array<{ requirement: Requirement; satisfied: boolean }> }> {
+  const detail: Array<{ requirement: Requirement; satisfied: boolean }> = [];
+  for (const req of link.requirements) {
+    let satisfied = false;
+    if (req.type === "connection") {
+      const scopeFilter = req.scope === "per_user" ? `AND scope='per_user' AND end_user_id IS NOT NULL` : `AND scope='workspace'`;
+      const { rows } = await db.query(
+        `SELECT 1 FROM connections WHERE workspace_id=$1 AND connector_id=$2 AND status='ready' ${scopeFilter} LIMIT 1`,
+        [link.workspace_id, req.connector],
+      );
+      satisfied = rows.length > 0;
+    } else if (req.type === "secret") {
+      satisfied = (await broker.getSecretValue(link.workspace_id, req.name)) !== null;
+    } else {
+      const { rows } = await db.query<{ status: string }>(
+        `SELECT status FROM webhook_registrations WHERE id=$1`,
+        [req.registrationId],
+      );
+      satisfied = rows[0]?.status === "registered";
+    }
+    detail.push({ requirement: req, satisfied });
+  }
+  const allSatisfied = detail.every((d) => d.satisfied);
+  if (allSatisfied && link.status === "pending") {
+    await db.query(`UPDATE connect_links SET status='completed', completed_at=now() WHERE token=$1`, [link.token]);
+    link.status = "completed";
+  }
+  return { status: link.status, requirements: detail };
+}