@open-everywhere/adapters 0.3.0 → 0.5.0

package/README.md

@@ -9,7 +9,6 @@ It implements core's host seams against concrete services:
 
 - **AI Gateway** — model routing and the pricing the spend reports read
 - **Sandbox** — the isolated workspace a turn runs its commands in
-- **Blob** — file storage
 - **Neon** — Postgres for the operational and memory stores
 - **OpenTelemetry** — the traces and the telemetry export
 - **AWS** and **Okta** — the directory and credential integrations

package/agent/aws/config.ts

@@ -1,8 +1,11 @@
 // The `aws` access master arming flag and config block. Flag-off ⇒ NOTHING registers and core's AWS paths
-// fail closed, with no fallback. Config is env-sourced at the adapter boundary, like DATABASE_URL.
+// fail closed, with no fallback. The two CHOICES are settings since OPE-2411 — `aws.enabled` (was
+// OE_AWS_ENABLED) and `aws.ssoScopes` (was OE_AWS_SSO_SCOPES) — because arming the plane and widening
+// what it asks for are policy. The WIRING (regions, the public OIDC client id) stays env-sourced at the
+// adapter boundary, like DATABASE_URL.
+
+import { getSettings } from "@open-everywhere/core/agent/adapter-api.js";
 
-/** The master arming flag env var — one string this module's readers share. */
-const OE_AWS_ENABLED_ENV = "OE_AWS_ENABLED";
 /** Optional default region for STS + the CLI when a grant names none. */
 const OE_AWS_REGION_ENV = "OE_AWS_REGION";
 
@@ -14,16 +17,11 @@ const OE_AWS_REGION_ENV = "OE_AWS_REGION";
 const OE_AWS_SSO_REGION_ENV = "OE_AWS_SSO_REGION";
 /** The pre-registered PUBLIC OIDC client id for the Identity Center auth-code + PKCE link flow. */
 const OE_AWS_SSO_CLIENT_ID_ENV = "OE_AWS_SSO_CLIENT_ID";
-/** Optional space-separated OAuth scopes for the link (default "sso:account:access"). */
-const OE_AWS_SSO_SCOPES_ENV = "OE_AWS_SSO_SCOPES";
-
-/** Truthiness for the master flag — same off-spellings as the other connector-plane flags (default
- *  OFF: off is the inert posture; arming is a deliberate operator act). */
+/** The master flag: the `aws.enabled` setting (default OFF: off is the inert posture; arming is a
+ *  deliberate, reviewed commit). Read from the registered settings, so it is called at boot AFTER
+ *  `registerSettings` (register-defaults.ts runs from the app's register-adapters, after register-config). */
 export function awsAccessEnabled(): boolean {
-  const raw = process.env[OE_AWS_ENABLED_ENV];
-  if (raw === undefined) return false;
-  const v = raw.trim().toLowerCase();
-  return v !== "" && v !== "0" && v !== "false" && v !== "off" && v !== "no";
+  return getSettings().aws.enabled;
 }
 
 /** The AWS-access config block (env-sourced). Only a default region today; the identity/executor DI
@@ -53,16 +51,15 @@ export interface AwsSsoConfig {
   readonly scopes?: readonly string[];
 }
 
-/** Load the Identity Center SSO link config from env. Region falls back to the general AWS default. */
+/** Load the Identity Center SSO link config: the region and client id from env, the scopes from the
+ *  `aws.ssoScopes` setting (empty ⇒ the minter's default). Region falls back to the general AWS default. */
 export function loadAwsSsoConfig(): AwsSsoConfig {
   const region =
     process.env[OE_AWS_SSO_REGION_ENV]?.trim() ||
     process.env[OE_AWS_REGION_ENV]?.trim() ||
     process.env.AWS_REGION?.trim();
   const clientId = process.env[OE_AWS_SSO_CLIENT_ID_ENV]?.trim();
-  const scopes = process.env[OE_AWS_SSO_SCOPES_ENV]?.trim()
-    ? process.env[OE_AWS_SSO_SCOPES_ENV]!.trim().split(/\s+/u).filter(Boolean)
-    : undefined;
+  const scopes = getSettings().aws.ssoScopes;
   return {
     ...(region ? { region } : {}),
     ...(clientId ? { clientId } : {}),

package/agent/aws/register.ts

@@ -1,4 +1,4 @@
-// Register the AWS-access layer, called only when the OE_AWS_ENABLED master flag is armed. Flag-off ⇒
+// Register the AWS-access layer, called only when the `aws.enabled` master flag is armed. Flag-off ⇒
 // nothing registers and core's AWS mint, exec and link paths fail closed; rollback is not arming the flag.
 
 import {
@@ -53,7 +53,7 @@ export function registerAwsAccess(opts: RegisterAwsAccessOptions = {}): {
   });
 
   // Wire the `GET OE_AWS_SSO_CALLBACK_PATH` route to the SSO minter's code→token exchange, mirroring the
-  // own-rolled OAuth adapter's registerOeOauthCallbackCompleter. Fires under the OE_AWS_ENABLED boot
+  // own-rolled OAuth adapter's registerOeOauthCallbackCompleter. Fires under the `aws.enabled` boot
   // guard; flag-off ⇒ the completer is never registered and the route fails closed (generic error page).
   registerAwsSsoCallbackCompleter({ complete: ({ state, code }) => sso.completeLink(state, code) });
 

package/agent/aws/sso.ts

@@ -25,7 +25,7 @@ export { OE_AWS_SSO_CALLBACK_PATH };
  *  what makes the token response carry an id-token, and the id-token's `sub` is the only statement of
  *  WHO completed the sign-in the callback can observe. Without it {@link AwsSsoMinter.completeLink}
  *  refuses every completion, because it cannot name the signer (OPE-1955). An operator who overrides
- *  `OE_AWS_SSO_SCOPES` must keep `openid` in the list. */
+ *  the `aws.ssoScopes` setting must keep `openid` in the list. */
 const DEFAULT_SSO_SCOPES = ["sso:account:access", "openid"] as const;
 /** Consent window for a pending link (15 min, matching the own-rolled OAuth pending TTL). */
 const DEFAULT_PENDING_TTL_MS = 15 * 60 * 1000;
@@ -281,7 +281,7 @@ export function makeAwsSsoMinter(opts: AwsSsoMinterOptions = {}): AwsSsoMinter {
   function requireOpenIdScope(): void {
     if (scopes.includes("openid")) return;
     throw new Error(
-      "AWS SSO link: the configured scopes omit \"openid\" (OE_AWS_SSO_SCOPES). Without it the Identity " +
+      "AWS SSO link: the configured scopes omit \"openid\" (the aws.ssoScopes setting). Without it the Identity " +
         "Center token response carries no id-token, so the account that signs in cannot be named and the " +
         "link can never complete. Fail-closed: no link was started.",
     );

package/agent/browser/register.ts

@@ -12,8 +12,18 @@ interface BoundBrowserConfig {
   readonly autoInstall: boolean;
   readonly contentBoundaries: boolean;
   readonly inlineScreenshots: boolean;
+  readonly session?: string;
 }
 
+/**
+ * The agent-browser session name every tool call passes as `--session`. 🔴 IT MUST BE BOUND. Without
+ * it the vendor derives the name from `sandbox.id`, and eve 0.69.0+ hands the tool a `SandboxSession`
+ * that has no `id`: `sanitizeSessionPart(undefined).trim()` then throws on EVERY browser call
+ * ("Cannot read properties of undefined (reading 'trim')", F-ART leg 4, 2026-10-09). One sandbox runs
+ * one agent-browser daemon, so a fixed name is per-sandbox — the same isolation the vendor default gave.
+ */
+export const BROWSER_SESSION_NAME = "oe-browser";
+
 /**
  * Arm the toolkit for a validated config. Returns false, LOUDLY, when the extension-config binding did not
  * take: unbound tools would run auto-install on and UNCONTAINED, so they are not registered at all.
@@ -24,6 +34,7 @@ export function registerAgentBrowser(cfg: AgentBrowserConfig): boolean {
     autoInstall: false,
     contentBoundaries: true,
     inlineScreenshots: false,
+    session: BROWSER_SESSION_NAME,
   });
 
   const bound = browserExtension.config as unknown as BoundBrowserConfig;
@@ -31,7 +42,7 @@ export function registerAgentBrowser(cfg: AgentBrowserConfig): boolean {
     Array.isArray(bound.allowedDomains) &&
     bound.allowedDomains.length === cfg.domains.length &&
     cfg.domains.every((d, i) => bound.allowedDomains![i] === d);
-  if (bound.autoInstall !== false || !domainsBound) {
+  if (bound.autoInstall !== false || !domainsBound || bound.session !== BROWSER_SESSION_NAME) {
     console.error(
       "[open-everywhere:agent-browser] extension config binding FAILED (namespace patch missing? see patches/@agent-browser+eve+*.patch) — " +
         "REFUSING to arm the browser toolkit: unbound tools would run with vendor defaults (auto-install on, no domain containment).",

package/agent/directory/config.ts

@@ -1,6 +1,8 @@
 // The directory-adapter SELECTION and Okta config. Selector-off or config-absent ⇒ NOTHING registers, with no
 // partial arming. 🔴 The API token is a `secretRef` through a broker (default `db`), never a raw env read.
 
+import { SETTINGS, getSettings, type OktaAppSetting } from "@open-everywhere/core/agent/adapter-api.js";
+
 /** Which directory adapter to arm ("okta"). Unset ⇒ the directory plane stays off. */
 const OE_DIRECTORY_PROVIDER_ENV = "OE_DIRECTORY_PROVIDER";
 /** The Okta org URL, e.g. `https://acme.okta.com` (or an `*.oktapreview.com` sandbox). MUST be
@@ -11,8 +13,8 @@ const OE_DIRECTORY_OKTA_ORG_URL_ENV = "OE_DIRECTORY_OKTA_ORG_URL";
 const OE_DIRECTORY_OKTA_TOKEN_REF_ENV = "OE_DIRECTORY_OKTA_TOKEN_REF";
 /** Which broker holds that ref. Default "db" (the encrypted credential store — OPE-408 step 2). */
 const OE_DIRECTORY_OKTA_TOKEN_BROKER_ENV = "OE_DIRECTORY_OKTA_TOKEN_BROKER";
-/** App map: `"<platform>[/<tenant>]:<oktaAppId>[:<field>], …"` — see {@link parseOktaAppMap}. */
-const OE_DIRECTORY_OKTA_APPS_ENV = "OE_DIRECTORY_OKTA_APPS";
+// The APP MAP is not env (OPE-2411): it is the `directory.oktaApps` setting, because its `field`
+// half decides which mappings `directory.autoConfirm` may confirm — see {@link oktaAppMappings}.
 
 /** Which app-assignment field carries the app-side identity for one mapped app. */
 export type OktaAppIdField = "externalId" | "userName";
@@ -49,49 +51,20 @@ export function oktaDirectoryEnabled(env: NodeJS.ProcessEnv = process.env): bool
 }
 
 /**
- * Parse the app map: `<platform>[/<tenant>]:<oktaAppId>[:<field>]`, comma-separated. The workspace rung uses
- * `/`, matching the principal-key grammar. FAIL-LOUD on a malformed entry — a dropped entry is a silent gap.
+ * Normalise the `directory.oktaApps` setting into the adapter's mappings: the default `field` is
+ * `externalId`. FAIL-LOUD on a malformed table — a dropped entry is a silent gap. The rules are the
+ * setting's own validator (`SETTINGS.directory.oktaApps.validate`), so settings load and this adapter
+ * refuse the same tables; it runs here too because a test can register an unvalidated value.
  */
-export function parseOktaAppMap(raw: string | undefined): readonly OktaAppMapping[] {
-  const out: OktaAppMapping[] = [];
-  const seen = new Set<string>();
-  for (const entry of (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean)) {
-    const parts = entry.split(":").map((s) => s.trim());
-    const [head, appId, field] = parts;
-    if (parts.length < 2 || parts.length > 3 || !head || !appId) {
-      throw new Error(
-        `${OE_DIRECTORY_OKTA_APPS_ENV} entry "${entry}" is malformed — expected "<platform>[/<tenant>]:<oktaAppId>" ` +
-          `with an optional ":externalId"/":userName" suffix, e.g. "slack:0oa1a2b3c4d5" or "slack/T0AB1CD2E:0oa1a2b3c4d5".`,
-      );
-    }
-    if (field !== undefined && field !== "externalId" && field !== "userName") {
-      throw new Error(`${OE_DIRECTORY_OKTA_APPS_ENV} entry "${entry}" names field "${field}" — only "externalId" (default) or "userName" are valid.`);
-    }
-    const slash = head.indexOf("/");
-    const platform = (slash < 0 ? head : head.slice(0, slash)).toLowerCase();
-    const tenant = slash < 0 ? undefined : head.slice(slash + 1).trim();
-    if (!platform || (tenant !== undefined && (tenant.length === 0 || tenant.includes("/")))) {
-      throw new Error(
-        `${OE_DIRECTORY_OKTA_APPS_ENV} entry "${entry}" has an unusable platform/workspace half ("${head}") — write "<platform>" ` +
-          `or "<platform>/<workspace-id>" with exactly one slash, e.g. "slack/T0AB1CD2E".`,
-      );
-    }
-    // Two apps mapped to the SAME (platform, workspace) is a genuine misconfiguration rather than a
-    // widening: the two would write suggestions that are indistinguishable downstream, and whichever
-    // ran second would silently redefine the first's ids. Refused here, where the operator can see
-    // both entries, rather than as a mystery in a sync warning.
-    const key = `${platform}/${tenant ?? ""}`;
-    if (seen.has(key)) {
-      throw new Error(
-        `${OE_DIRECTORY_OKTA_APPS_ENV} maps two apps to the same target "${key.replace(/\/$/u, "")}" — an app map entry names WHERE ` +
-          "the ids land, so two entries for one place cannot both be right. Give each workspace its own rung " +
-          '("slack/T0AB1CD2E:…,slack/T9ZYX8W7V:…"), or remove the duplicate.',
-      );
-    }
-    seen.add(key);
-    out.push({ platform, ...(tenant !== undefined ? { tenant } : {}), appId, field: field ?? "externalId" });
-  }
-  return out;
+export function oktaAppMappings(entries: readonly OktaAppSetting[]): readonly OktaAppMapping[] {
+  const problem = SETTINGS.directory.oktaApps.validate(entries);
+  if (problem !== undefined) throw new Error(`directory.oktaApps: ${problem}`);
+  return entries.map((a) => ({
+    platform: a.platform,
+    ...(a.tenant !== undefined ? { tenant: a.tenant } : {}),
+    appId: a.appId,
+    field: a.field ?? "externalId",
+  }));
 }
 
 /**
@@ -118,7 +91,10 @@ function requireHttpsOrgUrl(raw: string): void {
  * Load the Okta config block. FAIL-LOUD when the selector is armed but a required field is missing. An unset
  * SELECTOR stays silent — that is a deployment with no IdP, not a broken one.
  */
-export function loadOktaDirectoryConfig(env: NodeJS.ProcessEnv = process.env): OktaDirectoryConfig {
+export function loadOktaDirectoryConfig(
+  env: NodeJS.ProcessEnv = process.env,
+  apps: readonly OktaAppSetting[] = getSettings().directory.oktaApps,
+): OktaDirectoryConfig {
   const orgUrl = env[OE_DIRECTORY_OKTA_ORG_URL_ENV]?.trim();
   const tokenRef = env[OE_DIRECTORY_OKTA_TOKEN_REF_ENV]?.trim();
   const missing: string[] = [];
@@ -128,11 +104,10 @@ export function loadOktaDirectoryConfig(env: NodeJS.ProcessEnv = process.env): O
     throw new Error(`${OE_DIRECTORY_PROVIDER_ENV}="okta" but ${missing.join(" and ")} ${missing.length > 1 ? "are" : "is"} not set — directory sync cannot be armed.`);
   }
   requireHttpsOrgUrl(orgUrl!);
-  const apps = parseOktaAppMap(env[OE_DIRECTORY_OKTA_APPS_ENV]);
   return {
     orgUrl: orgUrl!.replace(/\/+$/u, ""),
     tokenRef: tokenRef!,
     tokenBroker: env[OE_DIRECTORY_OKTA_TOKEN_BROKER_ENV]?.trim() || "db",
-    apps,
+    apps: oktaAppMappings(apps),
   };
 }

package/agent/model/gateway.ts

@@ -7,6 +7,7 @@ import {
   type BindableContext,
   type ModelBackend,
   type RoutedCallOptions,
+  hostPlaneFetch,
   liveIdentity,
   resolvePrimaryModel,
 } from "@open-everywhere/core/agent/adapter-api.js";
@@ -19,9 +20,33 @@ type GatewayModel = ReturnType<typeof gateway>;
  */
 const GATEWAY_BASE_URL = process.env.OE_AI_GATEWAY_URL?.trim();
 
+/** The gateway's own host when {@link GATEWAY_BASE_URL} is unset. It must match the `ai` package's default base URL. */
+export const DEFAULT_GATEWAY_HOST = "ai-gateway.vercel.sh";
+
+/** The one host the model call reaches: the retarget's host, else the default. An unparseable retarget falls back to the default host. */
+export function gatewayHost(baseUrl: string | undefined): string {
+  if (!baseUrl) return DEFAULT_GATEWAY_HOST;
+  try {
+    return new URL(baseUrl).hostname;
+  } catch {
+    return DEFAULT_GATEWAY_HOST;
+  }
+}
+
+/**
+ * THE MODEL CALL'S TRANSPORT ON THE SELF-HOST PROXY TIER (OPE-2406). With an egress proxy wired, the model call goes out
+ * on the app's HOST PLANE: the proxy decides it against the gateway host alone, never against a session's policy. That is
+ * what lets a turn reach its model while the session stays default-deny. Off that tier it is `undefined` and the provider
+ * keeps its default fetch, byte-identical to before.
+ */
+const HOST_PLANE_FETCH = hostPlaneFetch([gatewayHost(GATEWAY_BASE_URL)]);
+
 /** 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;
+const provider =
+  GATEWAY_BASE_URL || HOST_PLANE_FETCH
+    ? createGateway({ ...(GATEWAY_BASE_URL ? { baseURL: GATEWAY_BASE_URL } : {}), ...(HOST_PLANE_FETCH ? { fetch: HOST_PLANE_FETCH } : {}) })
+    : gateway;
 
 /** Static defaults for one routed slot — mirrors what a plain string config said. */
 export interface GatewayRoutedDefaults {

package/agent/oe-oauth/config.ts

@@ -1,12 +1,13 @@
-// 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 `oe-oauth` provider config: each connector's SIGN-IN, declared in its own connection module next to its
+// URL (core connections/connection-sign-in.ts) and validated here. 🔴 The client SECRET is a REF — a literal
+// in a declaration is REFUSED. ⚠️ A declaration's key must equal the credential home's ref, or no mint reaches it.
+//
+// OPE-2411 deleted the env path: `OE_OAUTH_CONFIG` (the JSON map), `OE_OAUTH_NOTION_RESOURCE` (its Notion
+// shortcut) and the `OE_OAUTH_ENABLED` master flag. A scope list reaches the authorize URL, so a dashboard
+// could widen what the agent asks for with no diff. There is no master flag any more: a connector that
+// declares a sign-in offers "Connect my account" to whoever a bundle grants its `user-oauth` credential.
 
-/** 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";
+import { declaredConnectionSignIns } from "@open-everywhere/core/agent/adapter-api.js";
 
 /** The discovery + DCR + PKCE public-client dialect — the original and default mode. */
 export const OE_OAUTH_MODE_DISCOVERY = "discovery-dcr-pkce";
@@ -74,14 +75,6 @@ export function isStaticConfidential(cfg: OeOauthProviderConfig): cfg is OeOauth
   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. */
@@ -127,11 +120,11 @@ function parseScopes(v: unknown): readonly string[] | 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.
+  const where = `sign-in "${ref}"`;
+  // 🔴 A LITERAL SECRET IS REFUSED, NOT ACCEPTED. See the module header: a declaration is committed source.
   if ("clientSecret" in rec) {
     throw new Error(
-      `${where} carries a literal "clientSecret". The client secret must NEVER live in this config block — ` +
+      `${where} carries a literal "clientSecret". The client secret must NEVER live in a sign-in declaration — ` +
         `store it in the credential store and name it with "clientSecretRef" (for example "db:notion:rest-client-secret").`,
     );
   }
@@ -165,12 +158,13 @@ function parseStaticProvider(ref: string, rec: Record<string, unknown>): OeOauth
     ...(authorizeParams ? { authorizeParams } : {}),
     ...(tokenHeaders ? { tokenHeaders } : {}),
     bodyEncoding,
+    ...(scopes ? { scopes } : {}),
   };
 }
 
 /** Parse ONE `discovery-dcr-pkce` entry. */
 function parseDiscoveryProvider(ref: string, rec: Record<string, unknown>): OeOauthDiscoveryProviderConfig {
-  const where = `${OE_OAUTH_CONFIG_ENV}["${ref}"]`;
+  const where = `sign-in "${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);
@@ -183,18 +177,10 @@ function parseDiscoveryProvider(ref: string, rec: Record<string, unknown>): OeOa
   };
 }
 
-function parseJsonConfig(raw: string): Map<string, OeOauthProviderConfig> {
+/** Parse the declared sign-ins into provider configs. Every refusal names the declaration's home ref. */
+function parseDeclarations(declared: ReadonlyMap<string, unknown>): 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>)) {
+  for (const [ref, v] of declared) {
     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
@@ -208,7 +194,7 @@ function parseJsonConfig(raw: string): Map<string, OeOauthProviderConfig> {
     }
     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}".`,
+        `sign-in "${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);
@@ -218,7 +204,7 @@ function parseJsonConfig(raw: string): Map<string, OeOauthProviderConfig> {
     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}" ` +
+          `sign-in "${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.`,
         );
       }
@@ -229,18 +215,12 @@ function parseJsonConfig(raw: string): Map<string, OeOauthProviderConfig> {
 }
 
 /**
- * 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.
+ * The provider config map from the DECLARED sign-ins, or `undefined` when no connector declares one.
+ * Read PER CALL by the vault (see register.ts): a connection module declares at its own load, which
+ * eve's module map runs at server start, and a per-call read never depends on that order. A malformed
+ * declaration throws here, naming the field, so the mint that reaches it fails loudly.
  */
-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);
-
+export function loadOeOauthConfig(declared: ReadonlyMap<string, unknown> = declaredConnectionSignIns()): Map<string, OeOauthProviderConfig> | undefined {
+  const providers = parseDeclarations(declared);
   return providers.size > 0 ? providers : undefined;
 }

package/agent/oe-oauth/register.ts

@@ -1,27 +1,29 @@
 // Register the own-rolled OAuth adapter: the user-auth flow, the callback completer and the credential-purge
-// hook, from one shared vault. Flag-off ⇒ none registers and the callback route fails closed with a 404.
+// hook, from one shared vault. Since OPE-2411 there is no master flag: the flow ALWAYS registers, and each
+// mint reads the declared sign-ins PER CALL (core connections/connection-sign-in.ts). An OAuth home no
+// connector declares fails its mint closed with a message naming the fix, unless the vault already
+// holds a client record or an unexpired token for it (that row keeps serving). The off switch is the bundle's
+// `user-oauth` grant: with no grant, no mint reaches this flow.
 
 import { registerUserAuthFlow, registerOeOauthCallbackCompleter, registerCredentialPurgeHook } from "@open-everywhere/core/agent/adapter-api.js";
-import { loadOeOauthConfig, type OeOauthProviderConfig } from "./config.js";
+import { loadOeOauthConfig } from "./config.js";
 import { makeOeOauth } from "./user-auth-flow.js";
-import type { OeOauthVaultDeps } from "./token-vault.js";
+import type { OeOauthProviderSource, OeOauthVaultDeps } from "./token-vault.js";
 
-/** Registration input. `providers` defaults to {@link loadOeOauthConfig}; `deps` is a test/DI seam. */
+/** Registration input. `providers` defaults to the declared sign-ins, read per call; `deps` is a test/DI seam. */
 export interface RegisterOeOauthOptions {
-  readonly providers?: ReadonlyMap<string, OeOauthProviderConfig>;
+  readonly providers?: OeOauthProviderSource;
   readonly deps?: OeOauthVaultDeps;
 }
 
+/** The deployed provider source: the declared sign-ins, parsed per call. */
+const declaredProviders = () => loadOeOauthConfig() ?? new Map();
+
 /**
- * Construct the own-rolled OAuth provider and callback completer and register both. Throws when no provider
- * config is available — the caller invokes this only once it has decided to arm.
+ * Construct the own-rolled OAuth provider and callback completer and register both.
  */
 export function registerOeOauth(opts: RegisterOeOauthOptions = {}) {
-  const providers = opts.providers ?? loadOeOauthConfig();
-  if (!providers || providers.size === 0) {
-    throw new Error("registerOeOauth: no oe-oauth provider config (set OE_OAUTH_CONFIG / OE_OAUTH_NOTION_RESOURCE).");
-  }
-  const { flow, completer, purge } = makeOeOauth(providers, opts.deps ?? {});
+  const { flow, completer, purge } = makeOeOauth(opts.providers ?? declaredProviders, opts.deps ?? {});
   registerUserAuthFlow(flow);
   registerOeOauthCallbackCompleter(completer);
   // (OPE-287) The purge hook registers ALONGSIDE the mint flow, in the same call, deliberately: a

package/agent/oe-oauth/token-vault.ts

@@ -169,11 +169,16 @@ function defaultRedirectUri(): string | undefined {
   return `${withScheme}${OE_OAUTH_CALLBACK_PATH}`;
 }
 
+/** The provider set a vault reads: a fixed map (a test), or a function read PER CALL (the deployed
+ *  path, over the declared sign-ins — see oe-oauth/config.ts `loadOeOauthConfig`). */
+export type OeOauthProviderSource = ReadonlyMap<string, OeOauthProviderConfig> | (() => ReadonlyMap<string, OeOauthProviderConfig>);
+
 /**
  * Construct a token vault over the configured providers. One instance is built at registration and
  * shared, so the in-process single-flight lock (core withLock) coordinates all callers in the process.
  */
-export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProviderConfig>, deps: OeOauthVaultDeps = {}) {
+export function makeOeOauthTokenVault(source: OeOauthProviderSource, deps: OeOauthVaultDeps = {}) {
+  const providersNow = typeof source === "function" ? source : () => source;
   const vault = deps.vault ?? encryptedKvVault();
   const doFetch = deps.fetch ?? ((input: string, init?: RequestInit) => fetch(input, init));
   const now = deps.now ?? Date.now;
@@ -192,8 +197,12 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
   const tokRef = (providerRef: string, subject: OeOauthSubject) => `oe-oauth:tok:${providerRef}:${subjectKey(subject)}`;
 
   function providerConfig(providerRef: string): OeOauthProviderConfig {
-    const cfg = providers.get(providerRef);
-    if (!cfg) throw new Error(`connection "${providerRef}": no oe-oauth provider config (set OE_OAUTH_CONFIG / OE_OAUTH_NOTION_RESOURCE).`);
+    const cfg = providersNow().get(providerRef);
+    if (!cfg) {
+      throw new Error(
+        `connection "${providerRef}": no sign-in is declared for this OAuth home — the connector's connection module declares one with declareConnectionSignIn (core connections/connection-sign-in.ts).`,
+      );
+    }
     return cfg;
   }
 
@@ -288,7 +297,7 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
    * `ensureDcrClient`, so it never discovers, registers or writes a DCR row — the two share no network path.
    */
   async function ensureClient(providerRef: string): Promise<ClientRecord> {
-    const cfg = providers.get(providerRef);
+    const cfg = providersNow().get(providerRef);
     return cfg !== undefined && isStaticConfidential(cfg) ? staticClient(cfg) : ensureDcrClient(providerRef);
   }
 
@@ -323,7 +332,7 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
     // `providers.get`, not providerConfig: the discovery path never read the config here before this
     // mode existed, and it must not start failing on a config-absent ref now. The drift check below
     // therefore runs only when there IS a config to compare against.
-    const cfg = providers.get(pending.providerRef);
+    const cfg = providersNow().get(pending.providerRef);
     const startedStatic = pending.mode === OE_OAUTH_MODE_STATIC;
     if (cfg !== undefined && isStaticConfidential(cfg) !== startedStatic) {
       throw new Error(
@@ -371,7 +380,7 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
         // from config — which is a read, not a registration, so the "never registers" rule above
         // holds on both paths. `providers.get` rather than `providerConfig`: a purge must still
         // destroy the row for a provider whose config an operator has already removed.
-        const cfg = providers.get(providerRef);
+        const cfg = providersNow().get(providerRef);
         const client: ClientRecord | null = cfg && isStaticConfidential(cfg) ? staticClient(cfg) : await readJson<DcrClientRecord>(dcrRef(providerRef));
         // Prefer the REFRESH token: revoking it kills the whole grant family (RFC 7009 §2.1),
         // whereas revoking an access token kills only that one.
@@ -451,7 +460,8 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
       let purged = 0;
       let failures = 0;
       let lastError: unknown;
-      for (const providerRef of providers.keys()) {
+      const all = providersNow();
+      for (const providerRef of all.keys()) {
         try {
           if (await forget(providerRef, subject)) purged++;
         } catch (e) {
@@ -459,7 +469,7 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
           lastError = e;
         }
       }
-      if (failures > 0 && purged === 0 && failures === providers.size) throw lastError;
+      if (failures > 0 && purged === 0 && failures === all.size) throw lastError;
       return purged;
     },
 
@@ -597,7 +607,7 @@ export function makeOeOauthTokenVault(providers: ReadonlyMap<string, OeOauthProv
           try {
             // `providers.get`, not providerConfig — see {@link ensureClient}: a discovery refresh
             // must still resolve from a complete DCR record when the config entry is absent.
-            const cfg = providers.get(providerRef);
+            const cfg = providersNow().get(providerRef);
             let tok: OAuthTokenResponse;
             try {
               // The dialect decides the refresh call and nothing else about this block. A static

package/agent/oe-oauth/user-auth-flow.ts

@@ -3,8 +3,7 @@
 
 import type { TokenResult } from "eve/connections";
 import type { UserAuthFlowProvider, UserAuthSubject, UserTokenMintParams, OeOauthCallbackCompleter, CredentialPurgeHook } from "@open-everywhere/core/agent/adapter-api.js";
-import type { OeOauthProviderConfig } from "./config.js";
-import { makeOeOauthTokenVault, type OeOauthVaultDeps, type OeOauthSubject } from "./token-vault.js";
+import { makeOeOauthTokenVault, type OeOauthProviderSource, type OeOauthVaultDeps, type OeOauthSubject } from "./token-vault.js";
 import { isUserAuthRequiredError } from "./errors.js";
 
 /** Normalise the port's UserAuthSubject into the vault's subject shape. */
@@ -14,7 +13,7 @@ function toVaultSubject(subject: UserAuthSubject): OeOauthSubject {
 
 /** Build the own-rolled provider plus the callback completer, sharing one token vault. `deps` is the DI seam. */
 export function makeOeOauth(
-  providers: ReadonlyMap<string, OeOauthProviderConfig>,
+  providers: OeOauthProviderSource,
   deps: OeOauthVaultDeps = {},
 ): { readonly flow: UserAuthFlowProvider; readonly completer: OeOauthCallbackCompleter; readonly purge: CredentialPurgeHook } {
   const vault = makeOeOauthTokenVault(providers, deps);