@stigmer/server 3.14.0-dev.20260910084630

package/src/domain/mcpserver/disconnect-oauth.ts

@@ -0,0 +1,106 @@
+/**
+ * disconnectOAuth — ports
+ * pkg/domain/mcpserver/controller/disconnect_oauth.go: tear down a user's
+ * OAuth connection for an MCP server. Deletes the OAuthGrant record and
+ * its associated managed environment (which holds the access and refresh
+ * tokens); the MCP server definition is unchanged.
+ *
+ * Idempotent: no grant for the (caller, resource_id, org) tuple returns
+ * disconnected=false without error — race conditions, retries after
+ * partial failures, and desired-state semantics all rely on it.
+ *
+ * Delete order: managed environment first (eliminates secrets), then
+ * grant record (metadata only). If grant deletion fails after environment
+ * deletion, the orphaned grant is harmless metadata pointing to a deleted
+ * environment.
+ *
+ * Proven by mcpserver-oauth.conformance.test.ts (guards + no-grant
+ * idempotence, CONFORMANCE_TARGET=local) and
+ * mcpserver-connect.conformance.test.ts (teardown,
+ * CONFORMANCE_TARGET=local-execution).
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type {
+  DisconnectOAuthInput,
+  DisconnectOAuthOutput,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { DisconnectOAuthOutputSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import { authorizeDirect } from "../../pipeline/steps/authorize.js";
+import type { McpServerConnectDeps } from "./connect.js";
+
+export async function disconnectOAuth(
+  deps: McpServerConnectDeps,
+  input: DisconnectOAuthInput,
+  identity: CallerIdentity,
+): Promise<DisconnectOAuthOutput> {
+  const resourceId = input.resourceId;
+  if (resourceId === "") {
+    throw invalidArgumentError("resource_id is required");
+  }
+  const org = input.org;
+  if (org === "") {
+    throw invalidArgumentError("org is required");
+  }
+  // The annotation's can_connect check (validate → authorize, the Java
+  // McpServerDisconnectOAuthHandler order — no load step; on the
+  // multi-tenant edition an unresolvable id answers through the
+  // authorizer's ruled uniform posture). C2 Stage 4.
+  await authorizeDirect(
+    McpServerCommandController.method.disconnectOAuth,
+    deps.authorizer,
+    identity,
+    input,
+  );
+
+  // OSS mode: single user, empty identity_account_id.
+  let grant;
+  try {
+    grant = await deps.oauthGrants.find("", resourceId, org);
+  } catch (error) {
+    throw internalError(error, "failed to look up OAuth grant");
+  }
+
+  if (grant === undefined) {
+    deps.logger.debug("No OAuth grant to disconnect", {
+      resource_id: resourceId,
+      org,
+    });
+    return create(DisconnectOAuthOutputSchema, { disconnected: false });
+  }
+
+  const envId = grant.environmentId;
+  if (envId !== "") {
+    try {
+      await deps.managedEnv.deleteManagedEnvironment(envId);
+    } catch (error) {
+      deps.logger.warn(
+        "Failed to delete managed environment — may already be deleted",
+        {
+          resource_id: resourceId,
+          environment_id: envId,
+          error: error instanceof Error ? error.message : String(error),
+        },
+      );
+    }
+  }
+
+  try {
+    await deps.oauthGrants.delete("", resourceId, org);
+  } catch (error) {
+    throw internalError(error, "failed to delete OAuth grant");
+  }
+
+  deps.logger.info("OAuth connection disconnected", {
+    resource_id: resourceId,
+    org,
+    env_deleted: envId !== "",
+  });
+
+  return create(DisconnectOAuthOutputSchema, { disconnected: true });
+}

package/src/domain/mcpserver/enabledtools/__tests__/enabledtools.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Pins the enabled-tools classification (enabledtools.ts, ports
+ * pkg/domain/mcpserver/enabledtools): discovered tools pass, discovered
+ * resource-template names are classified SEPARATELY from plainly unknown
+ * names (the two get different error copy at the call sites, #402), and
+ * both partitions preserve the requested order so error messages are
+ * deterministic.
+ */
+import { create } from "@bufbuild/protobuf";
+import { describe, expect, it } from "vitest";
+
+import { DiscoveredCapabilitiesSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+
+import {
+  classify,
+  isValidClassification,
+  quoteJoin,
+  toolNames,
+} from "../enabledtools.js";
+
+const caps = create(DiscoveredCapabilitiesSchema, {
+  tools: [{ name: "search_docs" }, { name: "create_ticket" }],
+  resourceTemplates: [{ name: "customer-record" }, { name: "invoice" }],
+});
+
+describe("classify", () => {
+  it("passes names that resolve to discovered tools", () => {
+    const c = classify(caps, ["search_docs", "create_ticket"]);
+    expect(c.unknown).toEqual([]);
+    expect(c.resourceTemplates).toEqual([]);
+    expect(isValidClassification(c)).toBe(true);
+  });
+
+  it("classifies resource-template names separately from unknown names", () => {
+    const c = classify(caps, ["customer-record"]);
+    expect(c.resourceTemplates).toEqual(["customer-record"]);
+    expect(c.unknown).toEqual([]);
+    expect(isValidClassification(c)).toBe(false);
+  });
+
+  it("collects plainly unknown names", () => {
+    const c = classify(caps, ["serach_docs"]);
+    expect(c.unknown).toEqual(["serach_docs"]);
+    expect(c.resourceTemplates).toEqual([]);
+    expect(isValidClassification(c)).toBe(false);
+  });
+
+  it("preserves the requested order within each partition", () => {
+    const c = classify(caps, [
+      "zzz-unknown",
+      "invoice",
+      "search_docs",
+      "aaa-unknown",
+      "customer-record",
+    ]);
+    expect(c.unknown).toEqual(["zzz-unknown", "aaa-unknown"]);
+    expect(c.resourceTemplates).toEqual(["invoice", "customer-record"]);
+  });
+
+  it("matching is exact and case-sensitive", () => {
+    const c = classify(caps, ["Search_Docs"]);
+    expect(c.unknown).toEqual(["Search_Docs"]);
+  });
+});
+
+describe("error-message helpers", () => {
+  it("toolNames returns discovered tool names in discovery order", () => {
+    expect(toolNames(caps)).toEqual(["search_docs", "create_ticket"]);
+  });
+
+  it("quoteJoin renders 'a', 'b', 'c'", () => {
+    expect(quoteJoin(["a", "b", "c"])).toBe("'a', 'b', 'c'");
+    expect(quoteJoin([])).toBe("");
+  });
+});

package/src/domain/mcpserver/enabledtools/enabledtools.ts

@@ -0,0 +1,93 @@
+/**
+ * Enabled-tools classification — ports
+ * pkg/domain/mcpserver/enabledtools/enabledtools.go: classifies
+ * enabled-tools selections against an MCP server's discovered capabilities.
+ *
+ * It is the shared core of the apply-time validation added for issue #402:
+ * the agent controller checks McpServerUsage.enabled_tools and the
+ * mcpserver controller (arriving with sub-project #9 — this module is its
+ * first resident, placed here so the tree keeps corresponding to Go's)
+ * checks McpServerSpec.default_enabled_tools, and both must agree on what
+ * counts as a valid tool name. Keeping the classification here — in the
+ * domain that owns capability semantics — prevents the two error paths
+ * from drifting.
+ *
+ * The classification deliberately distinguishes resource templates from
+ * plainly unknown names: a resource-template name in an enabled-tools list
+ * is a specific, documented mistake (templates are read-only data
+ * endpoints, not callable tools — see DiscoveredCapabilities in
+ * mcpserver/v1/status.proto), and the error message should say so instead
+ * of implying a typo.
+ */
+import type { DiscoveredCapabilities } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/status_pb";
+
+/**
+ * Partitions the requested-but-invalid names of an enabled-tools list.
+ * Names present in the server's discovered tools appear in neither array.
+ * Order follows the requested list (stable, deterministic error messages).
+ */
+export interface Classification {
+  /**
+   * Names the server exposes neither as a tool nor as a resource template
+   * — almost always typos or stale entries.
+   */
+  readonly unknown: string[];
+  /**
+   * Names that match a discovered resource template: real names on the
+   * server, but never callable as tools.
+   */
+  readonly resourceTemplates: string[];
+}
+
+/** Whether every requested name resolved to a discovered tool. */
+export function isValidClassification(c: Classification): boolean {
+  return c.unknown.length === 0 && c.resourceTemplates.length === 0;
+}
+
+/**
+ * Checks each requested name against the discovered capabilities. Matching
+ * is exact and case-sensitive — tool names must match what the server
+ * reports via tools/list (see McpServerUsage.enabled_tools docs).
+ *
+ * Callers are expected to skip validation entirely when capabilities are
+ * absent (server not yet connected); classifying against absent
+ * capabilities would mark every name unknown, which is not a statement the
+ * platform can honestly make before the first discovery.
+ */
+export function classify(
+  caps: DiscoveredCapabilities,
+  requested: readonly string[],
+): Classification {
+  const tools = new Set(caps.tools.map((tool) => tool.name));
+  const templates = new Set(caps.resourceTemplates.map((tmpl) => tmpl.name));
+
+  const unknown: string[] = [];
+  const resourceTemplates: string[] = [];
+  for (const name of requested) {
+    if (tools.has(name)) {
+      continue;
+    }
+    if (templates.has(name)) {
+      resourceTemplates.push(name);
+      continue;
+    }
+    unknown.push(name);
+  }
+  return { unknown, resourceTemplates };
+}
+
+/**
+ * The discovered tool names in discovery order, for error messages that
+ * tell the operator what IS valid.
+ */
+export function toolNames(caps: DiscoveredCapabilities): string[] {
+  return caps.tools.map((tool) => tool.name);
+}
+
+/**
+ * Renders a name list as 'a', 'b', 'c' for error messages — shared so the
+ * agent and mcpserver error texts quote tool names identically.
+ */
+export function quoteJoin(names: readonly string[]): string {
+  return names.map((n) => `'${n}'`).join(", ");
+}

package/src/domain/mcpserver/engine.ts

@@ -0,0 +1,176 @@
+/**
+ * McpServer connect-engine seam — the domain's view of the Temporal client
+ * operations the connect lanes need (Go holds these as optional fields on
+ * McpServerController, set by SetConnectDependencies; here availability is
+ * the modeled engine state, the same idiom as agentexecution's engine.ts
+ * and workflowexecution's engine.ts — guidelines §4).
+ *
+ * The engine does NOT run a worker: the connect workflow
+ * (stigmer/mcp-server/connect) is the RUNNER's — this server only starts,
+ * attaches to, and awaits runs of it. The temporal-side implementation
+ * lands in src/temporal/mcpserver/engine-client.ts; tests fake this
+ * interface directly.
+ *
+ * Failure classification (ConnectRunFailure) mirrors the error taxonomy
+ * Go's awaitConnectWorkflow switches on (connect.go:661-694). The engine
+ * classifies; the DOMAIN owns the gRPC codes and user-facing copy the
+ * classes map to — the split keeps Temporal error types out of handler
+ * code.
+ */
+
+/**
+ * The connect workflow's input — matches the runner's
+ * ConnectMcpServerWorkflowInput (Go connectWorkflowInput). Snake_case keys
+ * are the Temporal JSON payload wire contract; ids-only except
+ * execution_context_token, the ONE deliberate exception (oss#535): the EC
+ * read RPC redacts secrets unless the caller presents an execution-scoped
+ * runner token, and the discovery activity has no execution of its own to
+ * exchange for one — the capability travels with the work item. It is a
+ * decrypt-lane discriminator, not a secret value: short-TTL, bound to
+ * this connect flow's ephemeral EC (deleted when the handler returns),
+ * and useless once either expires.
+ */
+export interface ConnectWorkflowInput {
+  readonly mcp_server_id: string;
+  readonly execution_context_id?: string;
+  readonly execution_context_token?: string;
+}
+
+/**
+ * The connect workflow's result — mirrors the runner's
+ * ConnectMcpServerWorkflowOutput (Go connectWorkflowOutput). Every field
+ * the runner emits must have a home here: a missing field is silently
+ * dropped during JSON deserialization, which is exactly how
+ * tool_approvals used to be lost.
+ */
+export interface ConnectWorkflowOutput {
+  readonly tools?: DiscoveredToolResult[];
+  readonly resource_templates?: DiscoveredResourceTemplateResult[];
+  /**
+   * Per-tool approval policies produced by the connect-time classifier —
+   * layer 1 of the approval policy chain. The classifier returns only the
+   * gated tools, but each entry still carries requires_approval so a
+   * future runner that emits non-gated entries is handled defensively at
+   * conversion time.
+   */
+  readonly tool_approvals?: ToolApprovalResult[];
+}
+
+export interface DiscoveredToolResult {
+  readonly name?: string;
+  readonly description?: string;
+  readonly input_schema?: Record<string, unknown>;
+}
+
+export interface DiscoveredResourceTemplateResult {
+  readonly uri_template?: string;
+  readonly name?: string;
+  readonly description?: string;
+  readonly mime_type?: string;
+}
+
+export interface ToolApprovalResult {
+  readonly tool_name?: string;
+  readonly requires_approval?: boolean;
+  readonly message?: string;
+  /**
+   * True when the connect-time tightener force-gated this tool from its
+   * destructiveHint annotation (not the classifier) — persisted to
+   * ToolApprovalPolicy.from_destructive_hint so the runner attributes the
+   * gate to the annotation rather than the classifier default.
+   */
+  readonly from_destructive_hint?: boolean;
+}
+
+/**
+ * How a connect run failed, in Go awaitConnectWorkflow's taxonomy:
+ * - "application": the workflow itself failed with the runner's crafted,
+ *   user-facing message (Go temporal.ApplicationError).
+ * - "timeout": the WorkflowRunTimeout elapsed (Go temporal.TimeoutError).
+ * - "service-not-found": Temporal no longer knows the run (Go
+ *   serviceerror.NotFound).
+ * - "other": everything else; message carries the error's own text (Go's
+ *   default arm, err.Error()).
+ */
+export type ConnectRunFailure =
+  | { readonly kind: "application"; readonly message: string }
+  | { readonly kind: "timeout" }
+  | { readonly kind: "service-not-found" }
+  | { readonly kind: "other"; readonly message: string };
+
+export type ConnectRunOutcome =
+  | { readonly ok: true; readonly output: ConnectWorkflowOutput }
+  | { readonly ok: false; readonly failure: ConnectRunFailure };
+
+/** A started-or-attached connect run (Go client.WorkflowRun). */
+export interface ConnectRun {
+  readonly workflowId: string;
+  /**
+   * True when the deterministic workflow ID reported an in-flight run and
+   * this handle attached to it instead of starting a new one — the lanes
+   * skip the CONNECTING write in that case so the starting lane's
+   * started_at survives.
+   */
+  readonly attached: boolean;
+  /**
+   * Blocks until the run settles and classifies the outcome. The
+   * workflow's own WorkflowRunTimeout is the deadline that should fire
+   * first; raceTimeoutMs (budget + a small buffer on the background
+   * lanes) is only a backstop so a settle task can never hang if Temporal
+   * becomes unreachable — Go's bounded background contexts.
+   */
+  result(raceTimeoutMs?: number): Promise<ConnectRunOutcome>;
+}
+
+/** The Temporal client operations the connect lanes consume. */
+export interface McpServerConnectEngine {
+  /**
+   * Starts the connect workflow on the runner queue, or attaches to the
+   * in-flight run when the deterministic workflow ID reports one already
+   * running (Go startOrAttachConnectWorkflow). Throws on any other start
+   * failure — the lanes map that to Internal "failed to start connect
+   * workflow".
+   */
+  startOrAttachConnect(
+    mcpServerId: string,
+    input: ConnectWorkflowInput,
+    runTimeoutMs: number,
+  ): Promise<ConnectRun>;
+
+  /**
+   * Whether the recorded connect workflow is still running (Go
+   * isConnectRunRunning). Errors — including a run Temporal no longer
+   * knows — report false: the caller falls through to a fresh start,
+   * where the AlreadyStarted refusal is the authoritative answer.
+   */
+  isConnectRunRunning(workflowId: string): Promise<boolean>;
+
+  /**
+   * Whether any worker is polling the runner task queue (Go
+   * runnerQueueWarning's DescribeTaskQueue probe). `undefined` when the
+   * question cannot be answered — an unreachable Temporal should not cry
+   * wolf on an operation that is about to fail loudly anyway.
+   */
+  hasRunnerQueuePollers(): Promise<boolean | undefined>;
+}
+
+/** Engine availability as an explicit modeled state (guidelines §4). */
+export type McpServerEngineState =
+  | { readonly connected: true; readonly engine: McpServerConnectEngine }
+  | { readonly connected: false };
+
+/**
+ * The disconnected state: no Temporal behind this server (never
+ * connected since boot). Connect/startConnect refuse with Go's
+ * byte-pinned FailedPrecondition; the OAuth RPCs work fully — the
+ * ratified DB-1 split (sub-project 20260825.02).
+ */
+export const MCP_SERVER_ENGINE_DISCONNECTED: McpServerEngineState =
+  Object.freeze({ connected: false });
+
+/**
+ * A provider rather than a value: consumers observe the CURRENT state at
+ * request time, never a boot-time snapshot — reconnects propagate
+ * automatically (the #18 engine-state idiom).
+ */
+export type McpServerEngineStateProvider = () => McpServerEngineState;

package/src/domain/mcpserver/get-oauth-grant-status.ts

@@ -0,0 +1,105 @@
+/**
+ * getOAuthGrantStatus — ports
+ * pkg/domain/mcpserver/controller/get_oauth_grant_status.go: whether the
+ * authenticated user has an active OAuth grant for the specified MCP
+ * server in the given org. Returns grant metadata (connected status,
+ * token expiry, auth method, connection health) without exposing secret
+ * token values; the frontend renders the OAuth state in the MCP server
+ * detail page and session composer from it. In OSS mode the
+ * identity_account_id is always empty (single-user).
+ *
+ * Proven by mcpserver-oauth.conformance.test.ts
+ * (CONFORMANCE_TARGET=local) and
+ * __tests__/get-oauth-grant-status.test.ts.
+ */
+import { create } from "@bufbuild/protobuf";
+
+import type {
+  GetOAuthGrantStatusInput,
+  GetOAuthGrantStatusOutput,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import {
+  GetOAuthGrantStatusOutputSchema,
+  OAuthConnectionHealth,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+
+import type { CallerIdentity } from "../../extensions/identity.js";
+import { internalError, invalidArgumentError } from "../../pipeline/errors.js";
+import { authorizeDirect } from "../../pipeline/steps/authorize.js";
+import type { OAuthGrant } from "../../store/interface.js";
+import type { McpServerConnectDeps } from "./connect.js";
+import { REFRESH_EXPIRY_BUFFER_SECONDS } from "./oauth/refresh.js";
+
+export async function getOAuthGrantStatus(
+  deps: McpServerConnectDeps,
+  input: GetOAuthGrantStatusInput,
+  identity: CallerIdentity,
+): Promise<GetOAuthGrantStatusOutput> {
+  if (input.resourceId === "") {
+    throw invalidArgumentError("resource_id is required");
+  }
+  if (input.org === "") {
+    throw invalidArgumentError("org is required");
+  }
+  // The annotation's can_view check (validate → authorize, the Java
+  // McpServerGetOAuthGrantStatusHandler order — no load step). C2 Stage 4.
+  await authorizeDirect(
+    McpServerQueryController.method.getOAuthGrantStatus,
+    deps.authorizer,
+    identity,
+    input,
+  );
+
+  let grant: OAuthGrant | undefined;
+  try {
+    grant = await deps.oauthGrants.find("", input.resourceId, input.org);
+  } catch (error) {
+    throw internalError(error, "failed to look up OAuth grant");
+  }
+
+  if (grant === undefined) {
+    return create(GetOAuthGrantStatusOutputSchema, {
+      connected: false,
+      connectionHealth: OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_NO_GRANT,
+    });
+  }
+
+  return create(GetOAuthGrantStatusOutputSchema, {
+    connected: true,
+    accessTokenExpiresAt: BigInt(grant.accessTokenExpiresAt),
+    targetEnvVar: grant.accessTokenEnvVar,
+    authMethod: grant.authMethod,
+    connectionHealth: evaluateHealth(grant),
+  });
+}
+
+/**
+ * Determines the health of an OAuth connection from locally available
+ * grant metadata (Go evaluateHealth). Uses the same 60-second expiry
+ * buffer as oauth/refresh.ts so the UX signal matches execution behavior.
+ *
+ * Ported bug, as-is (oss#863): "refreshable" keys off
+ * refreshTokenEnvVar != "" — but completeOAuthConnect sets that field
+ * unconditionally, so TOKEN_EXPIRED is unreachable through the real flow
+ * and an expired grant always claims refreshable even when no refresh
+ * token was ever issued. The conformance suite pins this behavior;
+ * fixing it is a both-editions change tracked on the issue.
+ */
+export function evaluateHealth(grant: OAuthGrant): OAuthConnectionHealth {
+  if (grant.accessTokenExpiresAt === 0) {
+    return OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_HEALTHY;
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (now < grant.accessTokenExpiresAt - REFRESH_EXPIRY_BUFFER_SECONDS) {
+    return OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_HEALTHY;
+  }
+
+  if (grant.refreshTokenEnvVar !== "") {
+    return OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_TOKEN_EXPIRED_REFRESHABLE;
+  }
+
+  return OAuthConnectionHealth.OAUTH_CONNECTION_HEALTH_TOKEN_EXPIRED;
+}