@keemakr/operator-sdk 0.1.0 → 0.3.0

package/package.json

@@ -1,12 +1,15 @@
 {
   "name": "@keemakr/operator-sdk",
-  "version": "0.1.0",
-  "description": "The keemakr connector contract: defineProvider + ConnectionProvider/ConnectionOperation types, shared by keemakr-core's built-in adapters and external connector repos. One shape, two consumers.",
+  "version": "0.3.0",
+  "description": "The keemakr connector contract: defineProvider + ConnectionProvider/ConnectionOperation types + OperationContext (governed fetch) + the connector manifest schema, shared by keemakr-core's built-in adapters and external connector repos. One shape, two consumers.",
   "type": "module",
   "license": "MIT",
   "types": "./src/index.ts",
   "exports": {
-    ".": "./src/index.ts"
+    ".": "./src/index.ts",
+    "./manifest": "./src/manifest.ts",
+    "./conformance": "./src/conformance/index.ts",
+    "./conformance/runner": "./src/conformance/runner.ts"
   },
   "files": [
     "src"

package/src/conformance/index.ts

@@ -0,0 +1,180 @@
+// The golden conformance suite — ONE source of truth, two runners.
+//
+// keemakr-core's publish gate (validation queue, gate G4) and the
+// kee-connector CLI's `certify` command both execute exactly these checks, so
+// an author's local green can never disagree with the server's. The suite
+// receives an ALREADY-IMPORTED provider module (the runners own how it was
+// loaded/sandboxed) plus the parsed manifest, and returns a structured report.
+//
+// Check #1 (import-without-throwing) belongs to the RUNNER: defineProvider's
+// invariants fire at import, before this suite ever sees the module.
+
+import type { ConnectorManifest } from '../manifest';
+import type { ConnectionProvider, OperationContext } from '../index';
+
+export interface ConformanceCheck {
+  id: string;
+  title: string;
+  ok: boolean;
+  detail?: string;
+}
+
+export interface ConformanceReport {
+  ok: boolean;
+  checks: ConformanceCheck[];
+}
+
+const TEST_TIMEOUT_MS = 5_000;
+
+// A ctx whose fetch always answers 401 — test() must SETTLE against it (a clean
+// {ok:false} or a typed throw), never hang and never crash the runner.
+function stubCtx(): OperationContext {
+  return {
+    fetch: (async () =>
+      new Response(JSON.stringify({ error: 'unauthorized' }), { status: 401 })) as typeof fetch,
+    signal: AbortSignal.timeout(TEST_TIMEOUT_MS),
+  };
+}
+
+export async function runConformance(
+  provider: ConnectionProvider,
+  manifest: ConnectorManifest,
+): Promise<ConformanceReport> {
+  const checks: ConformanceCheck[] = [];
+  const add = (id: string, title: string, ok: boolean, detail?: string) =>
+    checks.push({ id, title, ok, ...(detail ? { detail } : {}) });
+
+  // 2 — the export is provider-shaped.
+  const shaped =
+    !!provider && typeof provider === 'object' && typeof provider.provider === 'string';
+  add('export-shape', 'export is a ConnectionProvider', shaped);
+  if (!shaped) return { ok: false, checks };
+
+  // 3/4/5 — identity matches the manifest.
+  add(
+    'provider-key',
+    'provider key matches the manifest',
+    provider.provider === manifest.provider,
+    `code '${provider.provider}' vs manifest '${manifest.provider}'`,
+  );
+  add(
+    'publisher',
+    'publisher matches the manifest (when set in code)',
+    !provider.publisher || provider.publisher === manifest.publisher,
+  );
+  add(
+    'auth-kind',
+    'auth kind matches the manifest declaration (when declared)',
+    !manifest.auth_kind || provider.authKind === manifest.auth_kind,
+    `code '${provider.authKind}' vs manifest '${manifest.auth_kind ?? '—'}'`,
+  );
+
+  // 6 — code may not claim MORE network than the reviewed manifest.
+  const undeclared = (provider.allowedDomains ?? []).filter(
+    (d) => !manifest.allowed_domains.includes(d),
+  );
+  add(
+    'domains-subset',
+    'code allowedDomains ⊆ manifest allowed_domains',
+    undeclared.length === 0,
+    undeclared.length ? `undeclared: ${undeclared.join(', ')}` : undefined,
+  );
+
+  // 7/8 — operation inventory matches, both directions.
+  const codeOps = Object.keys(provider.operations ?? {});
+  const manifestOps = manifest.operations.map((o) => o.name);
+  const missing = manifestOps.filter((o) => !codeOps.includes(o));
+  const phantom = codeOps.filter((o) => !manifestOps.includes(o));
+  add(
+    'ops-declared-exist',
+    'every manifest operation exists in code',
+    missing.length === 0,
+    missing.length ? `missing: ${missing.join(', ')}` : undefined,
+  );
+  add(
+    'ops-no-phantoms',
+    'every code operation is declared in the manifest',
+    phantom.length === 0,
+    phantom.length ? `undeclared: ${phantom.join(', ')}` : undefined,
+  );
+
+  // 9/10 — per-op access + idempotency match the reviewed declarations.
+  const accessMismatch: string[] = [];
+  const idemMismatch: string[] = [];
+  for (const decl of manifest.operations) {
+    const op = provider.operations?.[decl.name];
+    if (!op) continue;
+    if ((op.access ?? 'write') !== decl.readWrite) accessMismatch.push(decl.name);
+    if ((op.idempotent ?? false) !== decl.idempotent) idemMismatch.push(decl.name);
+  }
+  add(
+    'ops-access',
+    'op access classes match the manifest',
+    accessMismatch.length === 0,
+    accessMismatch.length ? accessMismatch.join(', ') : undefined,
+  );
+  add(
+    'ops-idempotent',
+    'op idempotency flags match the manifest',
+    idemMismatch.length === 0,
+    idemMismatch.length ? idemMismatch.join(', ') : undefined,
+  );
+
+  // 11/12 — schemas parse safely; call signatures accept (cred, args).
+  const badSchema: string[] = [];
+  const badArity: string[] = [];
+  for (const [name, op] of Object.entries(provider.operations ?? {})) {
+    try {
+      const r = op.inputSchema?.safeParse({});
+      if (!r || typeof r.success !== 'boolean') badSchema.push(name);
+    } catch {
+      badSchema.push(name);
+    }
+    if (typeof op.call !== 'function' || op.call.length < 2) badArity.push(name);
+  }
+  add(
+    'schemas-safe',
+    'every inputSchema.safeParse({}) returns without throwing',
+    badSchema.length === 0,
+    badSchema.length ? badSchema.join(', ') : undefined,
+  );
+  add(
+    'call-arity',
+    'every call accepts (cred, args)',
+    badArity.length === 0,
+    badArity.length ? badArity.join(', ') : undefined,
+  );
+
+  // 13 — test() settles cleanly against garbage credentials.
+  let testOk = false;
+  let testDetail: string | undefined;
+  try {
+    const result = await Promise.race([
+      provider.test({ accessToken: 'conformance-garbage-credential', meta: {} }, stubCtx()),
+      new Promise<never>((_, reject) =>
+        setTimeout(() => reject(new Error('test() did not settle within 5s')), TEST_TIMEOUT_MS),
+      ),
+    ]);
+    // A clean negative ({ok:false}) is the CORRECT answer to garbage creds; a
+    // positive is suspicious but not fatal (some stubs accept anything in dev).
+    testOk = typeof result === 'object' && result !== null && typeof result.ok === 'boolean';
+    if (result && (result as { ok?: boolean }).ok === true) {
+      testDetail = 'test() accepted garbage credentials — verify it actually validates';
+    }
+  } catch (e) {
+    // A THROW is acceptable only if it's a typed, message-bearing error.
+    testOk = e instanceof Error && e.message !== '' && !/did not settle/.test(e.message);
+    testDetail = e instanceof Error ? e.message : String(e);
+  }
+  add('test-settles', 'test() settles cleanly against bad credentials', testOk, testDetail);
+
+  // 14 — auth-shape completeness (re-asserting defineProvider's rules against
+  // the RUNTIME object, in case the module bypassed defineProvider).
+  const authShapeOk =
+    provider.authKind === 'oauth2'
+      ? typeof provider.buildAuthUrl === 'function' && typeof provider.exchangeCode === 'function'
+      : (provider.connectFields?.length ?? 0) > 0;
+  add('auth-shape', 'auth lifecycle / connect form is complete for the auth kind', authShapeOk);
+
+  return { ok: checks.every((c) => c.ok), checks };
+}

package/src/conformance/runner.ts

@@ -0,0 +1,87 @@
+// Standalone conformance runner — the entrypoint the publish gate bundles
+// (esbuild, self-contained) and spawns as a sandboxed child:
+//
+//   node --permission --allow-fs-read=<dir> runner.mjs <artifact.mjs> <manifest.json>
+//
+// with an EMPTY environment. Check #1 (the import itself — defineProvider's
+// invariants fire here) happens in this process; everything after delegates to
+// the shared suite. The report is printed as one JSON line on stdout; exit 0
+// on pass, 1 on fail, 2 on harness error.
+
+import { readFileSync } from 'node:fs';
+import { pathToFileURL } from 'node:url';
+import { runConformance, type ConformanceReport } from './index';
+import { connectorManifestSchema } from '../manifest';
+
+async function main(): Promise<number> {
+  const [artifactPath, manifestPath, exportName = 'provider'] = process.argv.slice(2);
+  if (!artifactPath || !manifestPath) {
+    console.error('usage: runner <artifact.mjs> <manifest.json> [exportName]');
+    return 2;
+  }
+
+  const manifest = connectorManifestSchema.parse(JSON.parse(readFileSync(manifestPath, 'utf8')));
+
+  let report: ConformanceReport;
+  let mod: Record<string, unknown>;
+  try {
+    mod = (await import(pathToFileURL(artifactPath).href)) as Record<string, unknown>;
+  } catch (e) {
+    report = {
+      ok: false,
+      checks: [
+        {
+          id: 'imports',
+          title: 'artifact imports without throwing (defineProvider invariants)',
+          ok: false,
+          detail: e instanceof Error ? e.message : String(e),
+        },
+      ],
+    };
+    console.log(JSON.stringify(report));
+    return 1;
+  }
+
+  const provider = (mod[exportName] ?? (mod.default as Record<string, unknown>)?.[exportName]) as
+    | Parameters<typeof runConformance>[0]
+    | undefined;
+  if (!provider) {
+    report = {
+      ok: false,
+      checks: [
+        {
+          id: 'export-exists',
+          title: `named export '${exportName}' exists`,
+          ok: false,
+          detail: `exports found: ${Object.keys(mod).join(', ') || '(none)'}`,
+        },
+      ],
+    };
+    console.log(JSON.stringify(report));
+    return 1;
+  }
+
+  const suite = await runConformance(provider, manifest);
+  report = {
+    ok: suite.ok,
+    checks: [
+      {
+        id: 'imports',
+        title: 'artifact imports without throwing (defineProvider invariants)',
+        ok: true,
+      },
+      { id: 'export-exists', title: `named export '${exportName}' exists`, ok: true },
+      ...suite.checks,
+    ],
+  };
+  console.log(JSON.stringify(report));
+  return report.ok ? 0 : 1;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (e) => {
+    console.error(e instanceof Error ? e.message : String(e));
+    process.exit(2);
+  },
+);

package/src/index.ts

@@ -22,6 +22,23 @@ export type AuthKind = 'oauth2' | 'api_key' | 'app_password';
 // to 'ready'), so legacy adapters stay connectable until told otherwise.
 export type Maturity = 'ready' | 'coming_soon';
 
+// Who a connector is FOR — the audience axis the end-user client uses to decide
+// whether to surface it, and how. Classify EVERY connector (defineProvider will
+// enforce this) so the client catalog never conflates the three kinds:
+//   'user-account' → the tenant's OWN account; connect/disconnect is the point.
+//                    Shown in the end-user connections hub (Gmail, Slack, Stripe,
+//                    HubSpot, social channels).
+//   'agent-tool'   → infrastructure an AGENT uses to do a task, not a personal
+//                    account. The platform may hold a shared key; a tenant may
+//                    override with their own. NEVER a standalone hub card — it
+//                    surfaces only via the install card of an agent that declares
+//                    it (Apollo, Hunter, Clearbit — enrichment/analytics/scraping).
+//   'internal'     → platform plumbing, or a dormant connector with no operations
+//                    and no consumer. Never shown to end users (e.g. agent-sessions;
+//                    op-less stubs — also keep those at maturity:'coming_soon').
+// See docs/architecture/05 + 15 and the AGENTS.md "Connectors" convention.
+export type ConnectorSurface = 'user-account' | 'agent-tool' | 'internal';
+
 export interface TokenSet {
   accessToken: string;
   refreshToken?: string | null;
@@ -35,6 +52,37 @@ export interface TestResult {
   detail?: string;
 }
 
+// ─── Execution context ───────────────────────────────────────────────────────
+//
+// Handed to an operation (and test()) by the platform at call time. Marketplace
+// connectors MUST route all network egress through ctx.fetch — it enforces the
+// manifest's allowed_domains at the egress layer (private/link-local IPs blocked,
+// redirects re-validated, response size + wall-clock capped). Built-in adapters
+// are grandfathered on ambient fetch and migrate opportunistically.
+export interface OperationContext {
+  // Governed HTTP client: domain-allowlisted, SSRF-guarded, size/time-capped.
+  fetch: typeof fetch;
+  // One wall-clock budget for the whole operation call; combine with your own
+  // per-request signals via AbortSignal.any if needed.
+  signal: AbortSignal;
+  // Connector-level config resolved by the platform (e.g. an OAuth client id
+  // from the encrypted config store). Never tenant credentials — those arrive
+  // as `cred`.
+  config?: Record<string, string>;
+  // Trace-correlated logger. Never log credentials or response payloads.
+  log?: (msg: string) => void;
+}
+
+// Slim context for the OAuth lifecycle hooks (buildAuthUrl/exchangeCode/refresh):
+// connector-level config, plus the governed fetch for the token exchange —
+// marketplace connector code may not touch ambient fetch ANYWHERE (the publish
+// scan bans it), so the lifecycle's egress rides the same fenced client as
+// operations. There is no tenant credential yet at these steps.
+export interface LifecycleContext {
+  config?: Record<string, string>;
+  fetch?: typeof fetch;
+}
+
 // A single field in an inline connect form (api_key / app_password adapters).
 // The UI renders these generically; the adapter owns the spec so the form and
 // the route's expectations never drift. `target` says where the value goes in
@@ -64,6 +112,24 @@ export interface ConnectionProvider {
   // Connect-path maturity. Omitted ⇒ 'ready'. See Maturity above.
   maturity?: Maturity;
 
+  // Audience classification — see ConnectorSurface. Drives whether the end-user
+  // client surfaces this connector and how. Optional in the type for now so
+  // existing/external adapters compile through the SDK bump; defineProvider warns
+  // when omitted and this tightens to required once every built-in declares it.
+  surface?: ConnectorSurface;
+
+  // Egress allowlist: the ONLY hosts this connector's operations/test may reach
+  // through ctx.fetch. Bare hostname for an exact match ('api.acme.com') or a
+  // wildcard for subdomains ('*.acme.com' — does NOT match the apex; list it
+  // separately). For marketplace connectors the authoritative copy lives in the
+  // reviewed manifest and is enforced from the platform's registry row — this
+  // field documents intent and powers the local dev harness.
+  allowedDomains?: string[];
+
+  // Publisher handle (lowercase-kebab) for marketplace connectors. Built-ins
+  // omit it (first-party).
+  publisher?: string;
+
   // Inline connect-form spec for api_key / app_password shapes. Omitted by pure
   // oauth2 adapters (they render a Connect button instead). For a dual-mode
   // provider (WordPress), this describes the NON-oauth fallback form; the UI
@@ -81,13 +147,29 @@ export interface ConnectionProvider {
   // meta.mode='<fallbackMode>' so the route/adapter know which branch to take.
   dualMode?: { fallbackMode: string; oauthLabel?: string; formLabel?: string };
 
-  // OAuth-only lifecycle. Omitted by api_key / app_password adapters.
-  buildAuthUrl?(args: { tenantId: string; state: string; callbackUrl: string }): string;
-  exchangeCode?(args: { code: string; callbackUrl: string }): Promise<TokenSet>;
-  refresh?(args: { refreshToken: string }): Promise<TokenSet>;
+  // OAuth-only lifecycle. Omitted by api_key / app_password adapters. The
+  // optional trailing ctx carries connector-level config (encrypted config
+  // store) so client ids/secrets need not live in process.env.
+  buildAuthUrl?(
+    args: { tenantId: string; state: string; callbackUrl: string },
+    ctx?: LifecycleContext,
+  ): string;
+  exchangeCode?(
+    args: { code: string; callbackUrl: string },
+    ctx?: LifecycleContext,
+  ): Promise<TokenSet>;
+  refresh?(args: { refreshToken: string }, ctx?: LifecycleContext): Promise<TokenSet>;
 
-  // All kinds — validate a credential at save time.
-  test(args: { accessToken: string; meta: Record<string, unknown> }): Promise<TestResult>;
+  // Best-effort revocation at the provider, called when a tenant disconnects
+  // (or an install is removed). Optional; failures are audited, never fatal.
+  revoke?(tokenSet: { accessToken: string; refreshToken?: string | null }): Promise<void>;
+
+  // All kinds — validate a credential at save time. ctx is passed by the
+  // platform (optional in the type so existing adapters compile unchanged).
+  test(
+    args: { accessToken: string; meta: Record<string, unknown> },
+    ctx?: OperationContext,
+  ): Promise<TestResult>;
 
   // Derive a human-readable account_label + durable handle
   // (stripe_user_id, store url, ...) to persist alongside the token.
@@ -111,6 +193,13 @@ export interface ConnectionProvider {
 // sees it. Keep `call` pure-ish: do the request, return JSON-serializable data.
 export interface ConnectionOperation {
   description?: string;
+  // Access class, for grant scoping + install consent. Omitted ⇒ 'write' (the
+  // most restrictive assumption: unlabeled ops require the write scope and are
+  // listed as writes on the consent screen).
+  access?: 'read' | 'write';
+  // Safe-to-retry marker. Omitted ⇒ false. The platform NEVER auto-retries a
+  // non-idempotent operation; callers (agents) read this to know what is safe.
+  idempotent?: boolean;
   // A Standard Schema (zod/valibot/…) validating the agent-supplied args. Typed
   // loosely here so the connector contract doesn't hard-depend on zod; adapters
   // pass a zod schema and the route validates with `.parse`/`.safeParse`.
@@ -120,17 +209,49 @@ export interface ConnectionOperation {
   call(
     cred: { accessToken: string; meta: Record<string, unknown> },
     args: Record<string, unknown>,
+    ctx?: OperationContext,
   ): Promise<unknown>;
 }
 
+// Machine-readable failure classes. The capability proxy maps these to HTTP
+// codes + health-machine outcomes; a provider outage must never read as a
+// broken connector, and an auth failure must revoke, not retry.
+//   provider_unavailable → the upstream API is down/5xx/timing out
+//   connector_error      → the connector's own fault (bug, bad normalization)
+//   auth_revoked         → the credential is dead (401-class, invalid_grant)
+//   egress_blocked       → the governed fetch refused a non-allowlisted host
+//   rate_limited         → upstream 429 (platform applies backoff)
+export type OperationErrorCode =
+  | 'provider_unavailable'
+  | 'connector_error'
+  | 'auth_revoked'
+  | 'egress_blocked'
+  | 'rate_limited';
+
 // Throw from a ConnectionOperation.call to surface a typed, agent-safe failure
 // (maps to a 4xx with a clean message — never leaks the credential).
 export class OperationError extends Error {
   status: number;
-  constructor(message: string, status = 400) {
+  code?: OperationErrorCode;
+  constructor(message: string, status = 400, code?: OperationErrorCode) {
     super(message);
     this.name = 'OperationError';
     this.status = status;
+    this.code = code;
+  }
+}
+
+// Thrown by the governed fetch when an operation tries to reach a host outside
+// its allowlist (or a private/link-local address). Carries the offending host
+// so audit + the author's dev harness can say exactly what was refused.
+export class EgressViolationError extends OperationError {
+  host: string;
+  reason: string;
+  constructor(host: string, reason: string) {
+    super(`egress blocked: ${reason} (${host})`, 502, 'egress_blocked');
+    this.name = 'EgressViolationError';
+    this.host = host;
+    this.reason = reason;
   }
 }
 
@@ -169,5 +290,24 @@ export function defineProvider(p: ConnectionProvider): ConnectionProvider {
   if (typeof p.test !== 'function') {
     throw new Error(`connections: provider '${p.provider}' must implement test()`);
   }
+  if (!p.surface) {
+    // Nudge, not throw (yet): the built-ins all declare `surface`, but external/marketplace
+    // connectors (separate repos) haven't adopted it. Tightening to a hard throw + a required
+    // field is gated on adding `surface` to the connector manifest schema.
+    console.warn(
+      `connections: provider '${p.provider}' does not declare surface ` +
+        `('user-account' | 'agent-tool' | 'internal') — classify it so the client catalog knows ` +
+        `whether and how to show it. See the AGENTS.md "Connectors" convention.`,
+    );
+  }
+  if (p.operations && Object.keys(p.operations).length > 0 && !p.allowedDomains?.length) {
+    // Warn, don't throw: built-ins are grandfathered on ambient fetch. The
+    // marketplace publish gate REQUIRES allowed_domains in the manifest, so
+    // third-party connectors can't ship without one.
+    console.warn(
+      `connections: provider '${p.provider}' declares operations but no allowedDomains — ` +
+        `its egress cannot be fenced. Declare the hosts its operations reach.`,
+    );
+  }
   return p;
 }

package/src/manifest.ts

@@ -0,0 +1,171 @@
+// @keemakr/operator-sdk/manifest — the connector entry.json schema.
+//
+// One schema, two consumers: keemakr-core's marketplace upload validation and
+// the kee-connector CLI's `lint` both parse the author's entry.json with this.
+// The manifest is the DECLARED, reviewable half of a connector (identity,
+// egress allowlist, operation inventory); the code half (connectFields, the
+// auth lifecycle, the operation bodies) lives in the adapter itself.
+//
+// Notable rule: `allowed_domains` here is what reviewers approve and what the
+// platform persists to its registry at publish — the runtime enforces THAT
+// copy, never what the code claims.
+
+import { z } from 'zod';
+
+// Same shape defineProvider enforces for provider keys — and reused for
+// publisher handles. Must be a valid URL path segment (it is one, in
+// /api/capability/conn/[provider]/[op]) and a valid scope-string atom.
+const kebab = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+// 'api.acme.com' (exact), '*.acme.com' (subdomains only — the apex must be
+// listed separately), optional ':port' pin (443 implied otherwise).
+const domainPattern =
+  /^(\*\.)?[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:\d{1,5})?$/i;
+
+// Operation names follow the adapter's key convention: lowercase, dot-scoped
+// ('contacts.search', 'weather.current'), hyphens allowed within a segment.
+const opName = /^[a-z0-9]+(?:[.-][a-z0-9]+)*$/;
+
+export const connectorOperationDeclaration = z.object({
+  name: z.string().regex(opName, 'operation names are lowercase, dot/hyphen-scoped'),
+  readWrite: z.enum(['read', 'write']),
+  idempotent: z.boolean(),
+  description: z.string().max(500).optional(),
+});
+
+export const connectorManifestSchema = z
+  .object({
+    kind: z.literal('connection'),
+    publisher: z.string().regex(kebab, 'publisher handle must be lowercase-kebab'),
+    provider: z.string().regex(kebab, 'provider key must be lowercase-kebab'),
+    display_name: z.string().min(1).max(120),
+    description: z.string().max(2000).optional(),
+    category: z.string().regex(kebab, 'category must be lowercase-kebab'),
+    icon: z.string().max(2000).optional(),
+    // Declared auth kind — cross-checked against the compiled adapter at the
+    // publish gate. Optional (the adapter is authoritative); declaring it lets
+    // the upload preview show it before any code runs.
+    auth_kind: z.enum(['oauth2', 'api_key', 'app_password']).optional(),
+    // The operator-sdk contract version the connector targets (semver).
+    sdk_version: z.string().regex(/^\d+\.\d+\.\d+$/, 'sdk_version must be exact semver'),
+    // Module (relative path inside the bundle) whose named export is the
+    // defineProvider(...) result. Lane A (vendored) connectors require it; a
+    // pure Lane B (remote) connector may omit it and declare runtime_url instead.
+    entrypoint: z.string().min(1).max(300).optional(),
+    export: z.string().min(1).max(100).default('provider'),
+    // Lane B: the author-hosted service implementing the wire protocol
+    // (POST {runtime_url}/connector/v1/{op|test|auth-url|exchange|refresh|revoke}).
+    // https only; core forwards calls with a short-TTL signed grant and the
+    // tenant's credential — which is why remote connectors require explicit
+    // per-connection consent before any call.
+    runtime_url: z.string().url().max(500).optional(),
+    // Lane 'mcp': the author points at a remote Model Context Protocol server
+    // instead of writing operation bodies. Each declared operation forwards to
+    // that server's `tools/call` over Streamable HTTP, driven through the same
+    // governed fetch as Lane B. `url` is https-only and author-declared (never
+    // tenant-supplied); `auth` is 'injected' only in v1 — core vaults the
+    // tenant's credential and rides it on a transport header, never in the tool
+    // args. ('server_managed', where the MCP server holds its own upstream
+    // OAuth, is reserved for a later, higher-tier release.)
+    mcp: z
+      .object({
+        url: z.string().url().max(500),
+        auth: z.enum(['injected']),
+      })
+      .optional(),
+    // Remote connectors have no adapter code in core, so their connect form is
+    // declared HERE (vendored connectors keep connectFields in code — the
+    // adapter stays the single source of truth for Lane A). MCP connectors are
+    // the same: no adapter code, so the form lives here too.
+    connect_fields: z
+      .array(
+        z.object({
+          target: z.string().min(1),
+          label: z.string().min(1),
+          secret: z.boolean().optional(),
+          optional: z.boolean().optional(),
+          help: z.string().max(500).optional(),
+        }),
+      )
+      .optional(),
+    // The reviewable egress allowlist — the ONLY hosts ctx.fetch may reach.
+    allowed_domains: z
+      .array(z.string().regex(domainPattern, 'each entry is a bare host or *.host, optional :port'))
+      .min(1, 'declare at least one allowed domain'),
+    // Connector-level config keys the platform must supply (resolved from the
+    // encrypted config store — values are set by staff at publish, never bundled).
+    env: z
+      .array(z.string().regex(/^[A-Z][A-Z0-9_]*$/, 'config keys are SCREAMING_SNAKE'))
+      .default([]),
+    // Human-readable data-handling summary, surfaced on connect/install consent.
+    data_handling: z.string().min(1).max(2000),
+    // Static operation inventory — cross-checked against the compiled adapter at
+    // the publish gate (both directions: no undeclared ops, no phantom ops). For
+    // remote connectors this list IS the contract core builds the forwarder from.
+    operations: z.array(connectorOperationDeclaration).min(1),
+    changelog: z.string().max(5000).optional(),
+  })
+  .superRefine((m, ctx) => {
+    const lanes = [m.entrypoint, m.runtime_url, m.mcp].filter((v) => v != null).length;
+    if (lanes === 0) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'declare exactly one lane: an entrypoint (vendored, Lane A), a runtime_url (remote, Lane B), or an mcp endpoint (remote MCP)',
+      });
+    }
+    if (lanes > 1) {
+      ctx.addIssue({
+        code: 'custom',
+        message:
+          'declare exactly one lane — entrypoint, runtime_url, and mcp are mutually exclusive',
+      });
+    }
+    if (m.runtime_url && !m.runtime_url.startsWith('https://')) {
+      ctx.addIssue({ code: 'custom', path: ['runtime_url'], message: 'runtime_url must be https' });
+    }
+    if (m.runtime_url && m.auth_kind === 'oauth2') {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['auth_kind'],
+        message:
+          'remote (Lane B) connectors are api_key/app_password only — core will not broker an author-owned OAuth dance',
+      });
+    }
+    if (m.runtime_url && (!m.connect_fields || m.connect_fields.length === 0)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['connect_fields'],
+        message:
+          'remote connectors must declare connect_fields (there is no adapter code to own the form)',
+      });
+    }
+    if (m.mcp && !m.mcp.url.startsWith('https://')) {
+      ctx.addIssue({ code: 'custom', path: ['mcp', 'url'], message: 'mcp.url must be https' });
+    }
+    if (m.mcp && m.auth_kind === 'oauth2') {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['auth_kind'],
+        message:
+          'mcp connectors are api_key/app_password only — core injects the vaulted credential on a transport header, it does not broker an author-owned OAuth dance',
+      });
+    }
+    if (m.mcp && (!m.connect_fields || m.connect_fields.length === 0)) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['connect_fields'],
+        message:
+          'mcp connectors must declare connect_fields (there is no adapter code to own the form)',
+      });
+    }
+  });
+
+export type ConnectorOperationDeclaration = z.infer<typeof connectorOperationDeclaration>;
+export type ConnectorManifest = z.infer<typeof connectorManifestSchema>;
+
+// Parse + normalize an entry.json object. Throws ZodError on invalid input;
+// callers wanting a report use connectorManifestSchema.safeParse directly.
+export function parseConnectorManifest(raw: unknown): ConnectorManifest {
+  return connectorManifestSchema.parse(raw);
+}