@zackbart/connecta 0.1.0

package/src/auth/downstream-oauth.ts

@@ -0,0 +1,202 @@
+import type { OAuthClientProvider } from "@modelcontextprotocol/sdk/client/auth.js";
+import type {
+  OAuthClientInformationMixed,
+  OAuthClientMetadata,
+  OAuthTokens,
+} from "@modelcontextprotocol/sdk/shared/auth.js";
+import type { KVStorage } from "../types.js";
+
+/** A 256-bit random opaque value, hex-encoded — used for the OAuth `state`. */
+function randomState(): string {
+  const bytes = new Uint8Array(32);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** Length-safe, constant-time string compare (no early-exit on first mismatch). */
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+
+/**
+ * OAuthClientProvider implemented over KVStorage for a single downstream
+ * connector. Keys live in the connector's namespace as `oauth:<field>`.
+ *
+ * Headless twist: redirectToAuthorization() cannot navigate a user agent, so it
+ * STORES the authorization URL; the registry surfaces it as status
+ * "auth_required" and the operator opens it. The /oauth/callback/<id> route then
+ * drives transport.finishAuth(code).
+ */
+export class KvOAuthProvider implements OAuthClientProvider {
+  /**
+   * The force-reauth generation this provider's flow started under, captured by
+   * the connector before it drives a connect. `null` until stamped — a provider
+   * used outside a connect flow (or in isolation) writes unconditionally.
+   */
+  private capturedGeneration: number | null = null;
+
+  constructor(
+    private readonly connectorId: string,
+    private readonly storage: KVStorage,
+    private readonly redirectUri: string,
+  ) {}
+
+  /**
+   * Stamp the force-reauth generation the current connect flow started under.
+   * Subsequent saveTokens/saveClientInformation writes are dropped if KV's
+   * generation has since advanced (a concurrent force wiped credentials) — see
+   * isStale(). Called by the connector once per connect, before c.connect().
+   */
+  captureGeneration(gen: number): void {
+    this.capturedGeneration = gen;
+  }
+
+  /**
+   * Whether a concurrent force re-auth advanced the KV generation past the one
+   * this flow captured. When true, this isolate's SDK is mid-flight against
+   * credentials that were just wiped — persisting them would resurrect the
+   * wiped-and-reauthorized connector for later isolates. Fails open (writes)
+   * when no generation was captured.
+   */
+  private async isStale(): Promise<boolean> {
+    if (this.capturedGeneration === null) return false;
+    return (await this.generation()) > this.capturedGeneration;
+  }
+
+  get redirectUrl(): string {
+    return this.redirectUri;
+  }
+
+  get clientMetadata(): OAuthClientMetadata {
+    return {
+      redirect_uris: [this.redirectUri],
+      client_name: "connecta",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    };
+  }
+
+  async clientInformation(): Promise<OAuthClientInformationMixed | undefined> {
+    const raw = await this.storage.get("oauth:client");
+    return raw ? (JSON.parse(raw) as OAuthClientInformationMixed) : undefined;
+  }
+
+  async saveClientInformation(
+    info: OAuthClientInformationMixed,
+  ): Promise<void> {
+    // A concurrent force wiped credentials and bumped the generation while this
+    // flow ran — skip rather than re-register a client under revoked state. The
+    // in-memory SDK keeps this info for the current (doomed) connect, which the
+    // connector's post-connect fence then discards.
+    if (await this.isStale()) return;
+    await this.storage.set("oauth:client", JSON.stringify(info));
+  }
+
+  async tokens(): Promise<OAuthTokens | undefined> {
+    const raw = await this.storage.get("oauth:tokens");
+    return raw ? (JSON.parse(raw) as OAuthTokens) : undefined;
+  }
+
+  async saveTokens(tokens: OAuthTokens): Promise<void> {
+    // Generation-guarded write. The dangerous case: an isolate mid-connect (or
+    // mid-refresh) whose SDK just minted fresh tokens against a still-valid
+    // grant, racing a force re-auth that wiped KV and bumped the generation.
+    // Persisting here would resurrect those tokens for later isolates to read.
+    // A silent skip (not a throw) is deliberate: throwing propagates out of the
+    // SDK's auth() and fails the in-flight request/connect noisily, whereas
+    // skipping lets the in-memory client finish its current operation while
+    // leaving KV wiped — the connector's generation check drops that client on
+    // its next call. Fails open when no generation was captured, so ordinary
+    // token refresh (no force) still persists.
+    if (await this.isStale()) return;
+    await this.storage.set("oauth:tokens", JSON.stringify(tokens));
+  }
+
+  /**
+   * OAuth `state`. The SDK calls this (when present) and appends the value to
+   * the authorization URL. We generate a fresh random value and persist it so
+   * the public /oauth/callback route can prove the callback belongs to a flow
+   * WE started. Without it, anyone holding a pending authorization URL could
+   * complete consent with their own account (login CSRF) — PKCE does not help,
+   * since the verifier belongs to connecta, not the attacker. Cleared in
+   * clearPending() once the flow completes.
+   */
+  async state(): Promise<string> {
+    const value = randomState();
+    await this.storage.set("oauth:state", value);
+    return value;
+  }
+
+  /**
+   * Constant-time check of a callback's `state` against the stored one-shot
+   * value. Absent stored state or absent candidate → false (fail closed).
+   */
+  async verifyState(candidate: string | null): Promise<boolean> {
+    const expected = await this.storage.get("oauth:state");
+    if (!expected || candidate === null) return false;
+    return timingSafeEqual(candidate, expected);
+  }
+
+  async saveCodeVerifier(verifier: string): Promise<void> {
+    await this.storage.set("oauth:verifier", verifier);
+  }
+
+  async codeVerifier(): Promise<string> {
+    const raw = await this.storage.get("oauth:verifier");
+    if (!raw) throw new Error(`No PKCE code verifier for "${this.connectorId}"`);
+    return raw;
+  }
+
+  async redirectToAuthorization(authorizationUrl: URL): Promise<void> {
+    await this.storage.set("oauth:pending", authorizationUrl.toString());
+  }
+
+  /** The stored authorization URL, if a flow is pending. */
+  async pendingAuthorizationUrl(): Promise<string | undefined> {
+    return (await this.storage.get("oauth:pending")) ?? undefined;
+  }
+
+  /** Clear one-shot flow state after the callback completes. */
+  async clearPending(): Promise<void> {
+    await this.storage.delete("oauth:pending");
+    await this.storage.delete("oauth:verifier");
+    await this.storage.delete("oauth:state");
+  }
+
+  /**
+   * Force-reauth generation. Monotonic counter shared across isolates via KV;
+   * NOT cleared by clearPending/invalidateCredentials — its whole job is to
+   * keep advancing so an isolate holding a client from a prior generation can
+   * notice it went stale. Defaults to 0 when never bumped.
+   */
+  async generation(): Promise<number> {
+    const raw = await this.storage.get("oauth:generation");
+    const n = raw ? Number(raw) : 0;
+    return Number.isFinite(n) ? n : 0;
+  }
+
+  /** Advance the generation (on force re-auth) and return the new value. */
+  async bumpGeneration(): Promise<number> {
+    const next = (await this.generation()) + 1;
+    await this.storage.set("oauth:generation", String(next));
+    return next;
+  }
+
+  async invalidateCredentials(
+    scope: "all" | "client" | "tokens" | "verifier" | "discovery",
+  ): Promise<void> {
+    if (scope === "all" || scope === "client") {
+      await this.storage.delete("oauth:client");
+    }
+    if (scope === "all" || scope === "tokens") {
+      await this.storage.delete("oauth:tokens");
+    }
+    if (scope === "all" || scope === "verifier") {
+      await this.storage.delete("oauth:verifier");
+    }
+  }
+}

package/src/catalog.ts

@@ -0,0 +1,166 @@
+import type { JsonSchema, ToolDef } from "./types.js";
+
+const DEFAULT_DESCRIPTION_LENGTH = 240;
+
+export function summarizeDescription(
+  text: string | undefined,
+  full: boolean,
+): string | undefined {
+  if (!text) return undefined;
+  if (full) return text;
+  const compact = text.replace(/\s+/g, " ").trim();
+  if (compact.length <= DEFAULT_DESCRIPTION_LENGTH) return compact;
+  return `${compact.slice(0, DEFAULT_DESCRIPTION_LENGTH - 1).trimEnd()}…`;
+}
+
+function normalized(text: string): string {
+  return text.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+}
+
+interface SearchDocument {
+  tool: ToolDef;
+  name: string;
+  description: string;
+}
+
+const searchDocuments = new WeakMap<ToolDef[], SearchDocument[]>();
+
+function documentsFor(tools: ToolDef[]): SearchDocument[] {
+  let docs = searchDocuments.get(tools);
+  if (!docs) {
+    docs = tools.map((tool) => ({
+      tool,
+      name: normalized(tool.name),
+      description: normalized(tool.description ?? ""),
+    }));
+    searchDocuments.set(tools, docs);
+  }
+  return docs;
+}
+
+function scoreDocument(
+  doc: SearchDocument,
+  phrase: string,
+  terms: string[],
+): number | null {
+  if (!phrase) return 0;
+  const haystack = `${doc.name} ${doc.description}`;
+  if (!terms.every((term) => haystack.includes(term))) return null;
+
+  let score = 0;
+  if (doc.name === phrase) score += 1_000;
+  else if (doc.name.startsWith(phrase)) score += 800;
+  else if (doc.name.includes(phrase)) score += 600;
+  for (const term of terms) {
+    if (doc.name === term) score += 200;
+    else if (doc.name.startsWith(term)) score += 120;
+    else if (doc.name.includes(term)) score += 80;
+    if (doc.description.includes(term)) score += 10;
+  }
+  return score;
+}
+
+/** Rank a connector's tools while caching its normalized plain-data index. */
+export function rankTools(
+  tools: ToolDef[],
+  query: string,
+): Array<{ tool: ToolDef; score: number; order: number }> {
+  const phrase = normalized(query);
+  const terms = phrase.split(/\s+/).filter(Boolean);
+  const ranked: Array<{ tool: ToolDef; score: number; order: number }> = [];
+  documentsFor(tools).forEach((doc, order) => {
+    const score = scoreDocument(doc, phrase, terms);
+    if (score !== null) ranked.push({ tool: doc.tool, score, order });
+  });
+  return ranked;
+}
+
+function refName(ref: string): string {
+  return ref.split("/").pop() ?? ref;
+}
+
+function renderSchema(
+  schema: unknown,
+  defs: Record<string, unknown>,
+  seen: Set<string>,
+  depth: number,
+): string {
+  if (depth > 4) return "…";
+  if (schema === null || typeof schema !== "object") {
+    return JSON.stringify(schema);
+  }
+  const s = schema as Record<string, unknown>;
+
+  if (typeof s.$ref === "string") {
+    const name = refName(s.$ref);
+    if (seen.has(name)) return name;
+    const target = defs[name];
+    if (target === undefined) return name;
+    seen.add(name);
+    const rendered = renderSchema(target, defs, seen, depth);
+    seen.delete(name);
+    return rendered;
+  }
+
+  const union = (s.oneOf ?? s.anyOf) as unknown[] | undefined;
+  if (Array.isArray(union)) {
+    return (
+      union.map((u) => renderSchema(u, defs, seen, depth + 1)).join(" | ") ||
+      "unknown"
+    );
+  }
+  if (Array.isArray(s.enum)) {
+    return s.enum.map((value) => JSON.stringify(value)).join(" | ");
+  }
+
+  const type = s.type;
+  if (type === "array" || s.items) {
+    const items = s.items
+      ? renderSchema(s.items, defs, seen, depth + 1)
+      : "unknown";
+    return `${items}[]`;
+  }
+  if (type === "object" || s.properties) {
+    const props = (s.properties ?? {}) as Record<string, unknown>;
+    const required = new Set(
+      (Array.isArray(s.required) ? s.required : []) as string[],
+    );
+    const keys = Object.keys(props);
+    if (keys.length === 0) return "{}";
+    return `{ ${keys
+      .map((key) => {
+        const optional = required.has(key) ? "" : "?";
+        const rendered = renderSchema(props[key], defs, seen, depth + 1);
+        const description = (
+          props[key] as Record<string, unknown> | null
+        )?.description;
+        const comment =
+          typeof description === "string" ? ` // ${description}` : "";
+        return `${key}${optional}: ${rendered}${comment}`;
+      })
+      .join(", ")} }`;
+  }
+  if (typeof type === "string") return type;
+  if (Array.isArray(type)) return type.join(" | ");
+  return JSON.stringify(schema);
+}
+
+const compactSchemas = new WeakMap<JsonSchema, string>();
+
+/** Render and cache a compact TypeScript-like representation of JSON Schema. */
+export function compactSchema(schema: JsonSchema): string {
+  const cached = compactSchemas.get(schema);
+  if (cached) return cached;
+  const defs = {
+    ...((schema.$defs as Record<string, unknown>) ?? {}),
+    ...((schema.definitions as Record<string, unknown>) ?? {}),
+  };
+  let rendered: string;
+  try {
+    rendered = renderSchema(schema, defs, new Set(), 0);
+  } catch {
+    rendered = JSON.stringify(schema);
+  }
+  compactSchemas.set(schema, rendered);
+  return rendered;
+}

package/src/connectors/api.ts

@@ -0,0 +1,80 @@
+import type {
+  Connector,
+  ConnectorCredentialConfig,
+  ConnectorCredentialValues,
+  ConnectorContext,
+  CredentialTestResult,
+  JsonSchema,
+  ToolAnnotations,
+  ToolDef,
+} from "../types.js";
+
+export interface ApiTool {
+  name: string;
+  description?: string;
+  /** A plain JSON Schema object describing the tool input. */
+  inputSchema?: JsonSchema;
+  /** A plain JSON Schema object describing the tool's structured output. */
+  outputSchema?: JsonSchema;
+  /**
+   * Standard MCP-style behavior hints. Only an explicit readOnlyHint: true
+   * admits the tool to call_tool, batch_call, and execute_code.
+   */
+  annotations?: ToolAnnotations;
+  handler: (args: any, ctx: ConnectorContext) => Promise<unknown> | unknown;
+}
+
+export interface ApiOptions {
+  /** Human-readable display name; the connector id remains the address prefix. */
+  title?: string;
+  description?: string;
+  /** Optional operator-managed credential exposed through ctx.credential and /ui. */
+  credential?: ConnectorCredentialConfig;
+  /** Optional validation behind /ui's Test action. */
+  testCredential?: (
+    value: string,
+    ctx: ConnectorContext,
+  ) => Promise<CredentialTestResult>;
+  /** Optional validation for named multi-field credentials. */
+  testCredentials?: (
+    values: ConnectorCredentialValues,
+    ctx: ConnectorContext,
+  ) => Promise<CredentialTestResult>;
+  tools: ApiTool[];
+}
+
+/**
+ * A connector defined entirely in code: static tool defs + fetch handlers.
+ * Tool inputs are plain JSON Schema objects (bring your own zod-to-json-schema
+ * conversion if you prefer zod). call_tool JSON-wraps the handler's return.
+ */
+export function api(id: string, opts: ApiOptions): Connector {
+  const defs: ToolDef[] = opts.tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    inputSchema: t.inputSchema,
+    outputSchema: t.outputSchema,
+    annotations: t.annotations,
+  }));
+  const byName = new Map(opts.tools.map((t) => [t.name, t]));
+  return {
+    id,
+    title: opts.title,
+    kind: "api",
+    description: opts.description,
+    credential: opts.credential,
+    testCredential: opts.testCredential,
+    testCredentials: opts.testCredentials,
+    staticTools: defs,
+    async listTools() {
+      return defs;
+    },
+    async callTool(name, args, ctx) {
+      const tool = byName.get(name);
+      if (!tool) {
+        throw new Error(`Unknown tool "${name}" on connector "${id}"`);
+      }
+      return tool.handler(args ?? {}, ctx);
+    },
+  };
+}