@open-everywhere/adapters 0.1.0

package/agent/model/gateway.ts

@@ -0,0 +1,85 @@
+// The Vercel AI Gateway model backend — the reference `ModelBackend`. Provider SELECTION is not pinned here:
+// that is a gateway-operator concern, and `ModelRoute.providers` is only an optional per-route preference.
+
+import { gateway, createGateway } from "ai";
+import {
+  type ModelRoute,
+  type BindableContext,
+  type ModelBackend,
+  type RoutedCallOptions,
+  liveIdentity,
+  resolvePrimaryModel,
+} from "@open-everywhere/core/agent/adapter-api.js";
+
+type GatewayModel = ReturnType<typeof gateway>;
+
+/**
+ * THE GATEWAY TARGET — `OE_AI_GATEWAY_URL`, read once at module load: a target that changed mid-process would
+ * send two calls in one turn to two providers. Unset ⇒ the plain `gateway` export, byte-identical.
+ */
+const GATEWAY_BASE_URL = process.env.OE_AI_GATEWAY_URL?.trim();
+
+/** The gateway provider this backend resolves model ids through — retargeted only when
+ *  {@link GATEWAY_BASE_URL} names a different host. */
+const provider = GATEWAY_BASE_URL ? createGateway({ baseURL: GATEWAY_BASE_URL }) : gateway;
+
+/** Static defaults for one routed slot — mirrors what a plain string config said. */
+export interface GatewayRoutedDefaults {
+  /** Default gateway model id (what unrouted channels use), e.g. "zai/glm-5.2". */
+  readonly id: string;
+  /**
+   * Gateway providerOptions applied when the CALL carries none — a floor, since turn calls carry their own.
+   * Any gateway option is forwarded verbatim; this mapping has no allow-list of keys.
+   */
+  readonly gateway?: Record<string, unknown>;
+}
+
+/** Gateway pin keys a route replaces — a pin belongs to the id it was set with. */
+const PIN_KEYS = ["only", "order"] as const;
+
+/**
+ * Map a route's provider hints onto one call's gateway options. Pure. A MODEL CHANGE strips the pin keys — a
+ * pin set for one model is broken for another — and a route's `providers` becomes `order`, never `only`.
+ */
+export function applyGatewayOptions(
+  route: ModelRoute,
+  options: RoutedCallOptions,
+  ids: { readonly id: string; readonly defaultId: string },
+  defaults?: Record<string, unknown>,
+): RoutedCallOptions {
+  const base = (options.providerOptions?.gateway ?? defaults) as Record<string, unknown> | undefined;
+  let gatewayOpts = base;
+  if (ids.id !== ids.defaultId && base !== undefined) {
+    gatewayOpts = { ...base };
+    for (const k of PIN_KEYS) delete gatewayOpts[k];
+  }
+  if (route.providers !== undefined) {
+    gatewayOpts = { ...(gatewayOpts ?? {}), order: [...route.providers] };
+    delete gatewayOpts["only"];
+  }
+  if (gatewayOpts === undefined) return options;
+  return { ...options, providerOptions: { ...options.providerOptions, gateway: gatewayOpts } };
+}
+
+/** The gateway ModelBackend (see core ModelBackend). */
+export function gatewayModelBackend(defaults?: Record<string, unknown>): ModelBackend<GatewayModel> {
+  return {
+    model: (id) => provider(id),
+    applyOptions: (route, options, ids) => applyGatewayOptions(route, options, ids, defaults),
+  };
+}
+
+/**
+ * A `step.started` dynamic-model resolver. It MUST be `step.started`: eve discards a model INSTANCE at turn
+ * scope. It ALWAYS returns a model, never null, and `event` carries the turn id this ctx does not.
+ */
+export function gatewayModelResolver(primary: GatewayRoutedDefaults): (event: unknown, ctx: unknown) => Promise<GatewayModel> {
+  const deps = { ...liveIdentity, backend: gatewayModelBackend(primary.gateway) };
+  return (event, ctx) => resolvePrimaryModel(ctx as BindableContext, { primary: { id: primary.id } }, deps, event);
+}
+
+// There is deliberately NO exported compaction model here. eve 0.38.3 cannot run an authored
+// `compaction.model` under a dynamic agent model — it resolves the slot's reference through the
+// AGENT-LEVEL `model` field and throws (OPE-670; the full chain is on `agent/agent.ts`'s
+// `compaction` block). Compaction runs on the live turn model instead, which this file already
+// serves through `gatewayModelResolver`.

package/agent/oe-oauth/config.ts

@@ -0,0 +1,246 @@
+// The `oe-oauth` master flag and provider config, env-sourced. 🔴 The client SECRET is a REF — a literal in
+// the JSON is REFUSED. ⚠️ A map key must equal the credential home's ref, or the click dies late, at DCR.
+
+/** The master arming flag env var — one string this module's readers share. */
+const OE_OAUTH_ENABLED_ENV = "OE_OAUTH_ENABLED";
+/** The JSON provider-config block env var. */
+export const OE_OAUTH_CONFIG_ENV = "OE_OAUTH_CONFIG";
+/** Convenience: a `notion` provider's resource (mcp.notion.com), without hand-writing the JSON. */
+const OE_OAUTH_NOTION_RESOURCE_ENV = "OE_OAUTH_NOTION_RESOURCE";
+
+/** The discovery + DCR + PKCE public-client dialect — the original and default mode. */
+export const OE_OAUTH_MODE_DISCOVERY = "discovery-dcr-pkce";
+/** The static confidential-client dialect (OPE-1086) — no discovery, no registration, HTTP Basic. */
+export const OE_OAUTH_MODE_STATIC = "static-confidential";
+
+/** How a static provider encodes its token-request body. Declared, never inferred: Notion's REST
+ *  token endpoint takes JSON, the RFC 6749 default is form-encoded, and sending the wrong one reads
+ *  as an authentication failure rather than as a shape error. */
+export type OeOauthBodyEncoding = "json" | "form";
+
+/** Fields every provider entry carries, whatever its mode. */
+interface OeOauthProviderConfigBase {
+  /** The opaque connector id (the connection's providerRef, and this map's key). */
+  readonly ref: string;
+  /** Requested scopes (space-joined onto the authorization + token requests when present). */
+  readonly scopes?: readonly string[];
+}
+
+/** A provider whose authorization server publishes RFC 8414 metadata and an RFC 7591 registration
+ *  endpoint — the hosted-MCP shape the adapter was built for. */
+export interface OeOauthDiscoveryProviderConfig extends OeOauthProviderConfigBase {
+  readonly mode: typeof OE_OAUTH_MODE_DISCOVERY;
+  /** The hosted-MCP server URL — discovery base + RFC 8707 resource indicator. */
+  readonly resource: string;
+  /** The `client_name` sent at Dynamic Client Registration (default "Open Everywhere"). */
+  readonly clientName?: string;
+}
+
+/**
+ * A provider whose client is created BY A HUMAN in the vendor's developer portal, and authenticated
+ * as a CONFIDENTIAL client with a secret (OPE-1086). Nothing here is discovered at runtime.
+ */
+export interface OeOauthStaticProviderConfig extends OeOauthProviderConfigBase {
+  readonly mode: typeof OE_OAUTH_MODE_STATIC;
+  /** Where the human is sent to consent. HTTPS only. */
+  readonly authorizationEndpoint: string;
+  /** Where the code is exchanged and the refresh happens. HTTPS only. */
+  readonly tokenEndpoint: string;
+  /** RFC 7009 revocation, when the vendor offers one. ABSENT ⇒ a purge is local-only, exactly as it
+   *  is for a discovered server that publishes no `revocation_endpoint`. Notion documents none. */
+  readonly revocationEndpoint?: string;
+  /** The client id from the vendor's developer portal. Not a secret — it rides the authorize URL. */
+  readonly clientId: string;
+  /** The credential-store REF of the client secret. NEVER the value. */
+  readonly clientSecretRef: string;
+  /** The broker the ref resolves through. Default "db" — the encrypted credential store. */
+  readonly clientSecretBroker: string;
+  /** Extra authorize-URL query parameters the vendor requires (Notion needs `owner=user`). The
+   *  parameters this adapter sets itself are RESERVED and cannot be overridden here. */
+  readonly authorizeParams?: Readonly<Record<string, string>>;
+  /** Extra token-request headers the vendor requires (Notion needs `Notion-Version`). `authorization`
+   *  is RESERVED — config may not replace the Basic credential. */
+  readonly tokenHeaders?: Readonly<Record<string, string>>;
+  /** How the token-request body is encoded. */
+  readonly bodyEncoding: OeOauthBodyEncoding;
+}
+
+/** One provider's OAuth target, in one of the two declared modes. */
+export type OeOauthProviderConfig = OeOauthDiscoveryProviderConfig | OeOauthStaticProviderConfig;
+
+/** Narrow a provider config to the static confidential-client mode. Reads the DECLARED `mode` and
+ *  nothing else — never the presence of a field. */
+export function isStaticConfidential(cfg: OeOauthProviderConfig): cfg is OeOauthStaticProviderConfig {
+  return cfg.mode === OE_OAUTH_MODE_STATIC;
+}
+
+/** Truthiness for the master flag — same off-spellings as the connector flags (default OFF). */
+export function oeOauthEnabled(): boolean {
+  const raw = process.env[OE_OAUTH_ENABLED_ENV];
+  if (raw === undefined) return false;
+  const v = raw.trim().toLowerCase();
+  return v !== "" && v !== "0" && v !== "false" && v !== "off" && v !== "no";
+}
+
+/** Authorize-URL parameters this adapter composes itself. A config entry that named one of these
+ *  could point the consent at another client id or another redirect target, so the parser refuses
+ *  them instead of letting the last writer win. */
+const RESERVED_AUTHORIZE_PARAMS = new Set(["response_type", "client_id", "redirect_uri", "state", "scope", "code_challenge", "code_challenge_method"]);
+
+function requireString(v: unknown, where: string): string {
+  if (typeof v !== "string" || v.trim() === "") throw new Error(`${where} must be a non-empty string.`);
+  return v.trim();
+}
+
+/** An endpoint must be an absolute HTTPS URL. A client secret rides these requests in an
+ *  `Authorization` header, so `http:` would put it on the wire in the clear, and a relative value
+ *  would resolve against whatever base the runtime happened to have. */
+function requireHttpsUrl(v: unknown, where: string): string {
+  const raw = requireString(v, where);
+  let parsed: URL;
+  try {
+    parsed = new URL(raw);
+  } catch {
+    throw new Error(`${where} must be an absolute URL (got ${JSON.stringify(raw)}).`);
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(`${where} must use https — a confidential client presents its secret on this request, so ${JSON.stringify(parsed.protocol)} is refused.`);
+  }
+  return raw;
+}
+
+function optionalStringMap(v: unknown, where: string): Record<string, string> | undefined {
+  if (v === undefined) return undefined;
+  if (typeof v !== "object" || v === null || Array.isArray(v)) throw new Error(`${where} must be a JSON object of string values.`);
+  const out: Record<string, string> = {};
+  for (const [k, raw] of Object.entries(v as Record<string, unknown>)) {
+    if (typeof raw !== "string") throw new Error(`${where}["${k}"] must be a string.`);
+    out[k] = raw;
+  }
+  return Object.keys(out).length > 0 ? out : undefined;
+}
+
+function parseScopes(v: unknown): readonly string[] | undefined {
+  const scopes = Array.isArray(v) ? v.filter((s): s is string => typeof s === "string") : undefined;
+  return scopes && scopes.length ? scopes : undefined;
+}
+
+/** Parse ONE `static-confidential` entry, with every refusal stated. */
+function parseStaticProvider(ref: string, rec: Record<string, unknown>): OeOauthStaticProviderConfig {
+  const where = `${OE_OAUTH_CONFIG_ENV}["${ref}"]`;
+  // 🔴 A LITERAL SECRET IS REFUSED, NOT ACCEPTED. See the module header: this block is an env var.
+  if ("clientSecret" in rec) {
+    throw new Error(
+      `${where} carries a literal "clientSecret". The client secret must NEVER live in this config block — ` +
+        `store it in the credential store and name it with "clientSecretRef" (for example "db:notion:rest-client-secret").`,
+    );
+  }
+  const authorizeParams = optionalStringMap(rec.authorizeParams, `${where}.authorizeParams`);
+  for (const name of Object.keys(authorizeParams ?? {})) {
+    if (RESERVED_AUTHORIZE_PARAMS.has(name.toLowerCase())) {
+      throw new Error(`${where}.authorizeParams may not set "${name}" — the adapter composes that parameter itself.`);
+    }
+  }
+  const tokenHeaders = optionalStringMap(rec.tokenHeaders, `${where}.tokenHeaders`);
+  for (const name of Object.keys(tokenHeaders ?? {})) {
+    if (name.toLowerCase() === "authorization") {
+      throw new Error(`${where}.tokenHeaders may not set "${name}" — that header carries the confidential client's Basic credential.`);
+    }
+  }
+  const bodyEncoding = requireString(rec.bodyEncoding, `${where}.bodyEncoding`);
+  if (bodyEncoding !== "json" && bodyEncoding !== "form") {
+    throw new Error(`${where}.bodyEncoding must be "json" or "form" — the dialect is declared, not guessed.`);
+  }
+  const revocationEndpoint = rec.revocationEndpoint === undefined ? undefined : requireHttpsUrl(rec.revocationEndpoint, `${where}.revocationEndpoint`);
+  const scopes = parseScopes(rec.scopes);
+  return {
+    mode: OE_OAUTH_MODE_STATIC,
+    ref,
+    authorizationEndpoint: requireHttpsUrl(rec.authorizationEndpoint, `${where}.authorizationEndpoint`),
+    tokenEndpoint: requireHttpsUrl(rec.tokenEndpoint, `${where}.tokenEndpoint`),
+    ...(revocationEndpoint ? { revocationEndpoint } : {}),
+    clientId: requireString(rec.clientId, `${where}.clientId`),
+    clientSecretRef: requireString(rec.clientSecretRef, `${where}.clientSecretRef`),
+    clientSecretBroker: rec.clientSecretBroker === undefined ? "db" : requireString(rec.clientSecretBroker, `${where}.clientSecretBroker`),
+    ...(authorizeParams ? { authorizeParams } : {}),
+    ...(tokenHeaders ? { tokenHeaders } : {}),
+    bodyEncoding,
+  };
+}
+
+/** Parse ONE `discovery-dcr-pkce` entry. */
+function parseDiscoveryProvider(ref: string, rec: Record<string, unknown>): OeOauthDiscoveryProviderConfig {
+  const where = `${OE_OAUTH_CONFIG_ENV}["${ref}"]`;
+  const resource = typeof rec.resource === "string" ? rec.resource.trim() : "";
+  if (!resource) throw new Error(`${where} is missing a string "resource".`);
+  const scopes = parseScopes(rec.scopes);
+  return {
+    mode: OE_OAUTH_MODE_DISCOVERY,
+    ref,
+    resource,
+    ...(scopes ? { scopes } : {}),
+    ...(typeof rec.clientName === "string" && rec.clientName.trim() ? { clientName: rec.clientName.trim() } : {}),
+  };
+}
+
+function parseJsonConfig(raw: string): Map<string, OeOauthProviderConfig> {
+  const out = new Map<string, OeOauthProviderConfig>();
+  let obj: unknown;
+  try {
+    obj = JSON.parse(raw);
+  } catch {
+    throw new Error(`${OE_OAUTH_CONFIG_ENV} is not valid JSON — expected {"<ref>":{"resource":"..."}}.`);
+  }
+  if (typeof obj !== "object" || obj === null || Array.isArray(obj)) {
+    throw new Error(`${OE_OAUTH_CONFIG_ENV} must be a JSON object mapping provider ref → one provider entry.`);
+  }
+  for (const [ref, v] of Object.entries(obj as Record<string, unknown>)) {
+    if (typeof v !== "object" || v === null) continue;
+    const rec = v as Record<string, unknown>;
+    // The MODE decides how the rest is read. An absent `mode` is the discovery dialect, which is
+    // what every entry authored before OPE-1086 means. An unknown one is refused rather than
+    // defaulted: silently reading a mistyped mode as the public-client flow would drop the client
+    // secret and the Basic authentication without saying so.
+    const mode = rec.mode === undefined ? OE_OAUTH_MODE_DISCOVERY : rec.mode;
+    if (mode === OE_OAUTH_MODE_STATIC) {
+      out.set(ref, parseStaticProvider(ref, rec));
+      continue;
+    }
+    if (mode !== OE_OAUTH_MODE_DISCOVERY) {
+      throw new Error(
+        `${OE_OAUTH_CONFIG_ENV}["${ref}"].mode ${JSON.stringify(mode)} is not a known oe-oauth mode — use "${OE_OAUTH_MODE_DISCOVERY}" or "${OE_OAUTH_MODE_STATIC}".`,
+      );
+    }
+    const parsed = parseDiscoveryProvider(ref, rec);
+    // A discovery entry that also carries confidential-client fields is a MIS-DECLARED entry, not a
+    // static one. Refusing it here is the whole "declared, not sniffed" rule in one place: the
+    // adapter will not promote an entry to the confidential mode because it looks like one.
+    for (const field of ["clientId", "clientSecretRef", "clientSecret", "tokenEndpoint", "authorizationEndpoint"]) {
+      if (field in rec) {
+        throw new Error(
+          `${OE_OAUTH_CONFIG_ENV}["${ref}"] carries "${field}" but declares no mode, so it reads as "${OE_OAUTH_MODE_DISCOVERY}" ` +
+            `(discovery + dynamic registration + PKCE), which ignores that field. Add "mode": "${OE_OAUTH_MODE_STATIC}" if that is what you meant.`,
+        );
+      }
+    }
+    out.set(ref, parsed);
+  }
+  return out;
+}
+
+/**
+ * Load the provider config map from env, or `undefined` when no provider is configured (the
+ * "config-absent" path — combined with {@link oeOauthEnabled}, both must be truthy for the own-rolled
+ * OAuth layer to register). Explicit OE_OAUTH_CONFIG entries win over the notion shortcut.
+ */
+export function loadOeOauthConfig(): Map<string, OeOauthProviderConfig> | undefined {
+  const providers = new Map<string, OeOauthProviderConfig>();
+
+  const notionResource = process.env[OE_OAUTH_NOTION_RESOURCE_ENV]?.trim();
+  if (notionResource) providers.set("notion", { mode: OE_OAUTH_MODE_DISCOVERY, ref: "notion", resource: notionResource });
+
+  const rawJson = process.env[OE_OAUTH_CONFIG_ENV]?.trim();
+  if (rawJson) for (const [ref, cfg] of parseJsonConfig(rawJson)) providers.set(ref, cfg);
+
+  return providers.size > 0 ? providers : undefined;
+}

package/agent/oe-oauth/errors.ts

@@ -0,0 +1,77 @@
+// Typed errors for the own-rolled OAuth adapter. Each carries a stable `code`, so classification is
+// DUCK-TYPED across processes. SECURITY: no error here carries a token, a code, or a PKCE verifier.
+
+/** The subject an error is about, as a log-safe label (never an opaque token). */
+export function subjectLabel(subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }): string {
+  return subject.type === "app" ? "app" : `user:${subject.id}`;
+}
+
+/** The human has NEVER authorized this (provider, subject) — no token is stored. The connector plane
+ *  turns this into a fresh consent link. */
+export class OeOauthNeedsConsentError extends Error {
+  readonly code = "oe_oauth_needs_consent";
+  constructor(providerRef: string, subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }) {
+    super(`connection "${providerRef}": ${subjectLabel(subject)} has not authorized this account — user authorization required.`);
+    this.name = "OeOauthNeedsConsentError";
+  }
+}
+
+/** A previously-working authorization is dead (refresh token rejected / rotated away) — the human
+ *  must RE-authorize. Distinct from needs-consent so the audit trail can tell a first connect from a
+ *  lapsed one, but both classify as "user authorization required". */
+export class OeOauthNeedsReconsentError extends Error {
+  readonly code = "oe_oauth_needs_reconsent";
+  constructor(providerRef: string, subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }, why: string) {
+    super(`connection "${providerRef}": ${subjectLabel(subject)} must re-authorize — ${why}.`);
+    this.name = "OeOauthNeedsReconsentError";
+  }
+}
+
+/** The cross-process single-flight LOSER timed out (OPE-91): another instance holds the refresh claim
+ *  and did not release a rotated token within this caller's wait budget. TRANSIENT and RETRYABLE — a
+ *  fresh request may win the claim or find the rotated token — so it is DELIBERATELY not classified as
+ *  user-auth-required (the human need do nothing; nothing is re-consented). Carries no secret material,
+ *  only the provider ref + subject label. */
+export class OeOauthRefreshContendedError extends Error {
+  readonly code = "oe_oauth_refresh_contended";
+  constructor(providerRef: string, subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" }) {
+    super(`connection "${providerRef}": ${subjectLabel(subject)} token refresh is in progress on another instance and did not complete in time — retry.`);
+    this.name = "OeOauthRefreshContendedError";
+  }
+}
+
+/** A generic upstream OAuth failure (token endpoint / discovery / DCR returned an error). `oauthError`
+ *  is the RFC 6749 `error` code when the body carried one (e.g. "invalid_grant", "invalid_client") —
+ *  a fixed-vocabulary string, never a secret. */
+export class OeOauthError extends Error {
+  readonly code = "oe_oauth_error";
+  readonly oauthError?: string;
+  readonly httpStatus?: number;
+  constructor(message: string, opts: { readonly oauthError?: string; readonly httpStatus?: number } = {}) {
+    super(message);
+    this.name = "OeOauthError";
+    if (opts.oauthError) this.oauthError = opts.oauthError;
+    if (opts.httpStatus !== undefined) this.httpStatus = opts.httpStatus;
+  }
+}
+
+/** True iff `e` is an upstream OAuth failure whose `error` code is `invalid_grant` (the refresh token
+ *  was rejected — consumed by a rotation, revoked, or expired). Duck-typed for cross-process safety. */
+export function isInvalidGrant(e: unknown): boolean {
+  if (!(e instanceof Error)) return false;
+  const oauthError = (e as { oauthError?: unknown }).oauthError;
+  return typeof oauthError === "string" && oauthError.toLowerCase() === "invalid_grant";
+}
+
+/** The connector-plane classifier (used by UserAuthFlowProvider.isUserAuthRequired). Duck-typed on
+ *  the stable `code` strings so a cross-process instance still matches. */
+export function isUserAuthRequiredError(e: unknown): boolean {
+  if (!(e instanceof Error)) return false;
+  const code = (e as { code?: unknown }).code;
+  return (
+    (typeof code === "string" && (code === "oe_oauth_needs_consent" || code === "oe_oauth_needs_reconsent")) ||
+    e.name === "OeOauthNeedsConsentError" ||
+    e.name === "OeOauthNeedsReconsentError" ||
+    /user[_ ]?authorization[_ ]?required/i.test(e.message)
+  );
+}