@open-everywhere/core 0.1.0

package/agent/connections/connector-card.ts

@@ -0,0 +1,447 @@
+// The connector CARD and its host-side click plane: the consequential acts run when a human clicks, never in the
+// model. An OAuth URL is CAPABILITY-BEARING — ephemeral to the clicker on Slack, host-posted into the room on a
+// surface with no buttons, and never in a log, an audit detail, an error, or the model's own tool result.
+
+import { bridgeSlackForm } from "../channels/slack-bridge.js";
+import { appendAudit } from "../audit/audit.js";
+import { getConfig } from "../access/config.js";
+import { roleForBinding } from "../access/roles.js";
+import { deploymentOrg, type SurfaceBinding } from "../identity/binding.js";
+import { rawVaultSubject } from "../identity/oauth-vault-share.js";
+import type { Domain } from "../memory/domain.js";
+import type { ConnectorCredentials, ConnectorCredentialType } from "../access/connector-credentials.js";
+import { vercelConnectorOf } from "../access/connector-credentials.js";
+import {
+  AUTH_URL_TTL_MS,
+  defaultConnectorAuthStarter,
+  type ConnectorAuthorizationStarter,
+} from "./connector-auth.js";
+import { requestCredentialIntake, type CredentialIntakeDeps } from "../credentials/intake.js";
+import { deriveCredentialRef } from "../credentials/ref.js";
+import { offerableCredential, optionLabel, unqualifiedAppRowMintHome, type ConnectMode, type ConnectorOption } from "./connector-offer.js";
+
+/** Structural type of the Slack `chat.*` client — matches slackForm exactly (same as intake.ts). */
+type PostFn = (method: string, body: string) => Promise<Record<string, unknown> | undefined>;
+
+/** Button action_id prefix — `oe_connect:<connector>:<credentialType>`. The Slack front route classifies
+ *  a `block_actions` click as ours iff its action_id starts with this (like OE_SETKEY_ACTION_PREFIX). */
+export const OE_CONNECT_ACTION_PREFIX = "oe_connect:";
+
+/** The button label per option kind — an action, not a description. */
+function buttonText(o: ConnectorOption): string {
+  if (o.credentialType === "user-oauth") return "Connect my account";
+  if (o.credentialType === "service-oauth") return "Connect org account";
+  return "Set API key";
+}
+
+/**
+ * Build the Block Kit card for a set of resolved options. PURE. An actionable option becomes a button
+ * carrying `oe_connect:<connector>:<type>`; NO URL is ever placed in the card — links mint at the click.
+ */
+export function buildConnectCard(
+  connectorName: string,
+  options: readonly ConnectorOption[],
+  org: string,
+): { blocks: unknown[]; text: string } {
+  const header = {
+    type: "section",
+    text: { type: "mrkdwn", text: `🔌 Connect *${connectorName}* — choose how to authorize:` },
+  };
+  const buttons = options
+    .filter((o) => o.route.kind === "modal" || o.route.kind === "url")
+    .map((o) => ({
+      type: "button",
+      action_id: `${OE_CONNECT_ACTION_PREFIX}${connectorName}:${o.credentialType}`,
+      value: org, // the org, so the click handler can resolve the catalogue/intake (mirrors intake.ts)
+      ...(o.credentialType === "user-oauth" ? { style: "primary" } : {}),
+      text: { type: "plain_text", text: buttonText(o) },
+    }));
+  // `unavailable` is NOT rendered (tools/connector.ts filters it out and this guards defence-in-depth):
+  // its reason is operator prose, not end-user copy. Only text-degrade (a working path, degraded
+  // presentation) earns a context line.
+  const degraded = options.filter((o) => o.route.kind === "text-degrade");
+  const blocks: unknown[] = [header];
+  if (buttons.length > 0) blocks.push({ type: "actions", elements: buttons });
+  for (const o of degraded) {
+    blocks.push({
+      type: "context",
+      elements: [{ type: "mrkdwn", text: `*${optionLabel(o)}*: ${o.route.reason ?? "not available on this surface."}` }],
+    });
+  }
+  return { blocks, text: `Connect ${connectorName} — choose how to authorize.` };
+}
+
+// A surface with no interactive buttons gets the URL minted into a HOST-POSTED message: the model only ever
+// sees the factual summary, never the URL. A personal-oauth URL still only mints in a DM.
+
+/** Mint one OAuth authorization URL for a subject. Throws (LIVE-ONLY) if the vendor SDK is unbound. */
+async function mintOAuthUrl(
+  startAuth: ConnectorAuthorizationStarter,
+  vercelConnector: string,
+  subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" },
+): Promise<string> {
+  return (await startAuth(vercelConnector, { subject }, { expiresInMs: AUTH_URL_TTL_MS })).url;
+}
+
+/**
+ * Render the connect message for a NON-Slack surface. The URL lives only in the returned `text`, which the
+ * caller host-posts to the surface — never in the tool result.
+ */
+export async function renderNonSlackConnect(
+  connectorName: string,
+  options: readonly ConnectorOption[],
+  /** The caller's binding facts. `org` + `platform` are here for ONE reason: the personal-OAuth URL
+   *  minted below binds a human's third-party account to a VAULT SUBJECT, and that subject must be
+   *  composed exactly as the later token read composes it (OPE-286) — so both come from the same
+   *  binding rather than being re-derived here. */
+  ctx: { readonly mode: ConnectMode; readonly principalId?: string; readonly org: string; readonly platform: string; readonly workspace?: string },
+  startAuth: ConnectorAuthorizationStarter = defaultConnectorAuthStarter,
+  /**
+   * Mint a one-shot intake-PAGE link for a `page`-route api-key option; absent ⇒ the option degrades to honest
+   * text. The URL is CAPABILITY-BEARING and lives ONLY in the returned `text`, so it is not added to `issued`.
+   */
+  issuePageLink?: (o: ConnectorOption) => Promise<string | undefined>,
+): Promise<{ text: string; issued: ConnectorOption[] }> {
+  const lines: string[] = [`Connect *${connectorName}*:`];
+  const issued: ConnectorOption[] = [];
+  for (const o of options) {
+    // service-oauth takes ONE of two routes, and `dashboardUrl` is the selector (OPE-1914).
+    // A credential that declares one is completed on the Vercel dashboard by a team member — Connect's
+    // hosted flow rejects app subjects (live-proven 2026-07-20), so there is nothing to mint for it.
+    // A credential that declares NONE is homed at an authorization server this deployment drives
+    // itself (adapters/agent/oe-oauth), where `{type:"app"}` is an ordinary subject — so mint the org
+    // account's own authorization URL, exactly as the personal arm below mints the clicker's.
+    // 🔴 THE ADMIN GATE IS UPSTREAM. `resolveConnectorOptions` OMITS every app-principal option for a
+    // non-admin (connector-offer.ts omission gate 2), and every MINT-route option for a non-ORG-admin
+    // (gate 2b, OPE-1936), so an option of this type in `options` has already passed both. This function
+    // takes no standing of its own and must never be handed an unfiltered option list.
+    // 🔴 AND THE ADMIN GATE IS NOT ENOUGH ON ITS OWN HERE, WHICH IS WHY THE DM FENCE BELOW EXISTS.
+    // This function's text is HOST-POSTED INTO THE ROOM (tools/connector.ts), not delivered to the
+    // asker — the module header says so. `completeAuthorization` checks no principal, so whoever
+    // opens an authorization URL owns the row it writes — and `storeToken` writes that row
+    // unconditionally (oe-oauth/token-vault.ts), so the binding is LAST-write-wins, not first. An org
+    // URL posted into a shared channel would therefore let any reader bind THEIR Notion workspace as
+    // the credential every routine then spends, over the top of an admin's earlier consent. The
+    // completion now audits `connector.credential_bound` with `rebound: true` (OPE-1937), so the swap
+    // is at least witnessed — the ledger row is a record after the fact, never a gate.
+    // The admin gate bounds who ASKS; only the DM bounds who COMPLETES.
+    // The personal arm below carries the identical fence for the identical reason.
+    if (o.credentialType === "service-oauth") {
+      if (o.dashboardUrl) {
+        lines.push(`• *${optionLabel(o)}* — a Vercel team member authorizes the org account on the dashboard: ${o.dashboardUrl}`);
+        continue;
+      }
+      if (o.route.kind === "url" && o.vercelConnector && ctx.mode === "dm") {
+        try {
+          // The subject carries NO id: the token lands in the vault under the app row, which is keyed
+          // to no principal. That is what a routine may later spend without touching a person's row.
+          const url = await mintOAuthUrl(startAuth, o.vercelConnector, { type: "app" });
+          lines.push(`• *${optionLabel(o)}* — connect the org account (expires soon): ${url}`);
+          issued.push(o);
+        } catch {
+          lines.push(`• *${optionLabel(o)}* — couldn't start the org connect flow (the connector isn't fully provisioned; ask an operator).`);
+        }
+        continue;
+      }
+      if (o.route.kind === "url" && o.vercelConnector) {
+        lines.push(`• *${optionLabel(o)}* — message me directly and ask again: this surface has no buttons, so the link would be posted into the room, and whoever opened it first would bind the org account.`);
+        continue;
+      }
+      lines.push(`• *${optionLabel(o)}* — an operator authorizes the org account on the vendor's admin dashboard.`);
+      continue;
+    }
+    if (o.route.kind === "page") {
+      // api-key on a non-Slack surface: mint the one-shot secure page link (the requester opens it and
+      // enters the key on our own form — never in chat). Degrade honestly if the issuer/page is absent.
+      const url = issuePageLink ? await issuePageLink(o) : undefined;
+      lines.push(
+        url
+          ? `• *${optionLabel(o)}* — open this one-time secure page to enter the key (expires soon; it works once): ${url}`
+          : `• *${optionLabel(o)}* — secure key entry isn't available on this deployment right now; ask an operator to set it via the Vercel dashboard/CLI.`,
+      );
+      continue;
+    }
+    if (o.route.kind === "url" && o.vercelConnector && o.credentialType === "user-oauth") {
+      if (!(ctx.mode === "dm" && ctx.principalId)) continue; // omitted off-DM by the resolver already; guard the principal id
+      try {
+        // 🔴 The QUALIFIED vault subject, through the ONE composer (OPE-286) — the same string
+        // connector-auth's mint will later read this token back under. A bare `ctx.principalId` here
+        // (the pre-OPE-286 spelling) would now bind the human's account to a row nothing reads.
+        const url = await mintOAuthUrl(startAuth, o.vercelConnector, {
+          type: "user",
+          id: rawVaultSubject(ctx.org, ctx.platform, ctx.workspace, ctx.principalId),
+        });
+        lines.push(`• *${optionLabel(o)}* — connect your personal account (expires soon): ${url}`);
+        issued.push(o);
+      } catch {
+        lines.push(`• *${optionLabel(o)}* — couldn't start the connect flow (the connector isn't fully provisioned; ask an operator).`);
+      }
+    } else {
+      lines.push(`• *${optionLabel(o)}* — ${o.route.reason ?? "not available on this surface."}`);
+    }
+  }
+  return { text: lines.join("\n"), issued };
+}
+
+/** The subset of a Slack `block_actions` payload the click handler reads — untrusted-shape wire JSON. */
+interface ConnectClickPayload {
+  readonly actions?: readonly { readonly action_id?: unknown; readonly value?: unknown }[];
+  readonly user?: { readonly id?: unknown };
+  readonly team?: { readonly id?: unknown };
+  readonly channel?: { readonly id?: unknown };
+}
+
+export interface ConnectorCardDeps {
+  readonly post?: PostFn;
+  /** OAuth URL minter (subject-flexible) — injected in tests; live default hits the registered user-auth flow. */
+  readonly startAuth?: ConnectorAuthorizationStarter;
+  /** The api-key intake poster (defaults to the real credentials/intake.ts). */
+  readonly requestIntake?: (input: Parameters<typeof requestCredentialIntake>[0], deps?: CredentialIntakeDeps) => Promise<{ id: string }>;
+  readonly loadConnectorCredentials?: () => readonly ConnectorCredentials[];
+  readonly loadDomains?: () => readonly Domain[];
+  readonly now?: () => Date;
+}
+
+/** Post an ephemeral (clicker-only) notice. Best-effort; the delivery channel for a capability URL. */
+async function ephemeral(post: PostFn, channelId: string, userId: string, text: string): Promise<void> {
+  const body = new URLSearchParams();
+  body.set("channel", channelId);
+  body.set("user", userId);
+  body.set("text", text);
+  await post("chat.postEphemeral", body.toString());
+}
+
+function connectWhere(org: string, teamId: string | undefined, channelId: string): { org: string; platform: string; workspace: string; surface: string } {
+  return { org, platform: "slack", workspace: teamId || "unknown", surface: channelId };
+}
+
+/**
+ * Session mode from a bare Slack channel id — the `D` prefix marks a DM. A click payload carries no
+ * channel_type, so the bundle's type-aware arms cannot apply here; this is its id-prefix arm, kept local.
+ */
+function slackIdPrefixMode(channelId: string | undefined): "dm" | "channel" {
+  return channelId?.startsWith("D") ? "dm" : "channel";
+}
+
+/** Re-derive the clicker's admin standing host-side from the payload facts + the live domains config
+ *  (never from the card). A synthetic binding is enough — roleForBinding reads platform/workspace/
+ *  surface/principalId only. isDomainAdmin already folds in org-admin (org admins are admins everywhere). */
+function clickerRole(
+  org: string,
+  teamId: string | undefined,
+  channelId: string,
+  clickerId: string,
+  domains: readonly Domain[],
+): { isAdmin: boolean; isOrgAdmin: boolean; domain?: string } {
+  const binding: SurfaceBinding = {
+    org,
+    platform: "slack",
+    workspace: teamId ?? "unknown",
+    surface: channelId,
+    mode: slackIdPrefixMode(channelId),
+    visibility: "private",
+    trust: "internal",
+    principalId: clickerId,
+  };
+  const role = roleForBinding(binding, domains);
+  return { isAdmin: role.isDomainAdmin, isOrgAdmin: role.isOrgAdmin, ...(role.domain ? { domain: role.domain } : {}) };
+}
+
+/**
+ * Handle one `oe_connect:` click: `false` when it is not ours, else it OWNS the click and NEVER throws.
+ * Every branch re-verifies standing host-side — a DM for personal, admin for org — and no URL is audited.
+ */
+export async function handleConnectClick(payload: unknown, deps: ConnectorCardDeps = {}): Promise<boolean> {
+  const p = payload as ConnectClickPayload | null | undefined;
+  const action = p?.actions?.[0];
+  const actionId = typeof action?.action_id === "string" ? action.action_id : undefined;
+  if (actionId === undefined || !actionId.startsWith(OE_CONNECT_ACTION_PREFIX)) return false; // not ours
+
+  const post = deps.post ?? bridgeSlackForm;
+  try {
+    const rest = actionId.slice(OE_CONNECT_ACTION_PREFIX.length);
+    const sep = rest.lastIndexOf(":"); // connector names have no ':'; the type is the last segment
+    const connectorName = sep > 0 ? rest.slice(0, sep) : undefined;
+    const type = (sep > 0 ? rest.slice(sep + 1) : undefined) as ConnectorCredentialType | undefined;
+    const org = typeof action?.value === "string" ? action.value : undefined;
+    const clickerId = typeof p?.user?.id === "string" ? p.user.id : undefined;
+    const channelId = typeof p?.channel?.id === "string" ? p.channel.id : undefined;
+    const teamId = typeof p?.team?.id === "string" ? p.team.id : undefined;
+
+    if (!connectorName || !type || !org || !clickerId || !channelId) {
+      console.error(`[open-everywhere:connector] malformed oe_connect click "${actionId}" — missing connector/type/org/user/channel; ignoring`);
+      return true; // it WAS ours — fail soft, never forward a half-understood payload
+    }
+
+    const catalogues = deps.loadConnectorCredentials ? deps.loadConnectorCredentials() : (getConfig().loadConnectorCredentials?.() ?? []);
+    const catalogue = catalogues.find((c) => c.connector === connectorName);
+    // Select the OFFERABLE credential of this type via the SAME helper the offer resolver uses — so a
+    // forged click can never target an `intake: false` PLUMBING credential (e.g. notion `channel-key`);
+    // it resolves the intake-able one (team-key) or nothing. Never a bare first-of-type find.
+    const cred = catalogue ? offerableCredential(catalogue, type) : undefined;
+    if (!catalogue || !cred) {
+      await ephemeral(post, channelId, clickerId, "This connect option is no longer available.");
+      return true;
+    }
+
+    const domains = deps.loadDomains ? deps.loadDomains() : getConfig().loadDomains();
+    const startAuth = deps.startAuth ?? defaultConnectorAuthStarter;
+
+    if (type === "user-oauth") {
+      if (slackIdPrefixMode(channelId) !== "dm") {
+        await ephemeral(post, channelId, clickerId, "Connecting your *personal* account only works in a DM with me — message me directly and try again.");
+        return true;
+      }
+      const userConnector = vercelConnectorOf(cred);
+      if (!userConnector) {
+        await ephemeral(post, channelId, clickerId, "This connector isn't configured for personal OAuth (no OAuth connector id). Ask an operator.");
+        return true;
+      }
+      // 🔴 The subject is the QUALIFIED vault subject through the ONE composer — connector-auth's mint reads that
+      // row back. The org is `deploymentOrg()`, never the click payload: a credential address never comes from input.
+      return await mintAndDeliverOAuth(post, startAuth, {
+        org, teamId, channelId, clickerId, connectorName, vercelConnector: userConnector,
+        subject: { type: "user", id: rawVaultSubject(deploymentOrg(), "slack", teamId, clickerId) }, subjectLabel: "user",
+      });
+    }
+
+    // service-oauth is ADMIN-ONLY — and the MINT route below is ORG-ADMIN-ONLY (OPE-1936). Both standings
+    // are re-derived host-side from the payload facts plus the live domains config — never read off the
+    // card, which an attacker would control.
+    // It then takes ONE of two routes, selected by `dashboardUrl` (OPE-1914), mirroring renderNonSlackConnect:
+    // a credential that declares one is completed on the VERCEL DASHBOARD, because Connect's hosted page
+    // REJECTS app subjects (live-proven 2026-07-20) and there is nothing to mint; a credential that declares
+    // NONE is homed at an authorization server this deployment drives itself (adapters/agent/oe-oauth), where
+    // `{type:"app"}` is an ordinary subject beside `{type:"user",id}` — so the org account gets a real
+    // authorization URL. The token then lands in the vault under the org's app row, keyed to no principal,
+    // which is what an unattended routine may spend without borrowing anyone's DM credential.
+    if (type === "service-oauth") {
+      const orgRole = clickerRole(org, teamId, channelId, clickerId, domains);
+      if (!orgRole.isAdmin) {
+        await ephemeral(post, channelId, clickerId, "Connecting the *org* account is admin-only — your id isn't listed as an admin for this workspace/domain.");
+        return true;
+      }
+      const dash = cred.dashboardUrl;
+      const mintHome = unqualifiedAppRowMintHome(type, cred);
+      if (mintHome) {
+        // 🔴 THE MINT ROUTE IS ORG-ADMIN-ONLY (OPE-1936), and this is the same predicate omission gate 2b
+        // reads — so a domain admin never sees the button and cannot reach the mint by forging a click.
+        // The row this bind writes carries no domain component, so domain standing is too narrow for it.
+        if (!orgRole.isOrgAdmin) {
+          await ephemeral(
+            post,
+            channelId,
+            clickerId,
+            "Connecting the *org* account binds one credential for the whole deployment, so it takes an ORG admin — " +
+              "your id is listed as an admin for this domain only. Ask an org admin to click it.",
+          );
+          return true;
+        }
+        // No id in the subject — the app row is the org's, not a person's. The audit row this writes is
+        // `connector.oauth_url_issued` with subject `app`; the URL itself is ephemeral-only and never audited.
+        return await mintAndDeliverOAuth(post, startAuth, {
+          org, teamId, channelId, clickerId, connectorName, vercelConnector: mintHome,
+          subject: { type: "app" }, subjectLabel: "app",
+        });
+      }
+      await ephemeral(
+        post,
+        channelId,
+        clickerId,
+        dash
+          ? `Connecting the *org* ${connectorName} account is completed on the Vercel dashboard (needs a Vercel team member): ${dash} — authorize there, then ask me again.`
+          : `Connecting the *org* ${connectorName} account is done by an operator on the vendor's admin dashboard — no self-serve link is configured for it here.`,
+      );
+      await appendAudit({
+        ...connectWhere(org, teamId, channelId),
+        principalId: clickerId,
+        action: "connector.dashboard_link_issued",
+        detail: { connector: connectorName, configured: Boolean(dash) },
+      });
+      return true;
+    }
+
+    if (type === "api-key") {
+      const role = clickerRole(org, teamId, channelId, clickerId, domains);
+      if (!role.isAdmin) {
+        await ephemeral(post, channelId, clickerId, "Setting an *org* API key is admin-only — your id isn't listed as an admin for this workspace/domain.");
+        return true;
+      }
+      if (!cred.secretRef) {
+        await ephemeral(post, channelId, clickerId, "This connector's API-key credential has no configured storage ref. Ask an operator.");
+        return true;
+      }
+      const requestIntake = deps.requestIntake ?? requestCredentialIntake;
+      // The intake flow posts its OWN button and modal, and audits the request. The stored ref names the
+      // credential's HOME (credentials/ref.ts), so a pasted key lives in the db broker.
+      const ref = deriveCredentialRef({
+        connector: connectorName,
+        credentialId: cred.id,
+      });
+      if (!ref) {
+        await ephemeral(post, channelId, clickerId, "This connector's API-key credential has no resolvable storage home. Ask an operator.");
+        return true;
+      }
+      await requestIntake({
+        org,
+        connector: connectorName,
+        ...(role.domain ? { domain: role.domain } : {}),
+        ref,
+        requestedBy: clickerId,
+        channelId,
+        ...(teamId ? { teamId } : {}),
+      });
+      return true;
+    }
+
+    console.error(`[open-everywhere:connector] oe_connect click with unrecognised type "${String(type)}" — ignoring`);
+    return true;
+  } catch (err) {
+    console.error(`[open-everywhere:connector] handleConnectClick failed softly for "${actionId}": ${String(err)}`);
+    return true;
+  }
+}
+
+/** Mint an OAuth authorization URL for `subject` and deliver it EPHEMERALLY to the clicker. Audits
+ *  `connector.oauth_url_issued` (subject type + connector + who — NEVER the URL). On a mint failure,
+ *  an honest ephemeral notice (no URL, no capability). Always returns true (the click was ours). */
+async function mintAndDeliverOAuth(
+  post: PostFn,
+  startAuth: ConnectorAuthorizationStarter,
+  ctx: {
+    readonly org: string;
+    readonly teamId?: string;
+    readonly channelId: string;
+    readonly clickerId: string;
+    readonly connectorName: string;
+    readonly vercelConnector: string;
+    readonly subject: { readonly type: "user"; readonly id: string } | { readonly type: "app" };
+    readonly subjectLabel: "user" | "app";
+  },
+): Promise<boolean> {
+  let url: string | undefined;
+  try {
+    url = (await startAuth(ctx.vercelConnector, { subject: ctx.subject }, { expiresInMs: AUTH_URL_TTL_MS })).url;
+  } catch (err) {
+    // Never mask why with the URL; name the vendor requirement (LIVE-ONLY), never anything secret.
+    console.error(`[open-everywhere:connector] oauth mint failed for ${ctx.connectorName} (${ctx.subjectLabel}): ${String(err)}`);
+    await ephemeral(post, ctx.channelId, ctx.clickerId, "Couldn't start the connect flow just now — the connector isn't fully provisioned on this deployment. Ask an operator.");
+    return true;
+  }
+  const who = ctx.subjectLabel === "user" ? "your personal" : "the org service";
+  // CAPABILITY-BEARING: ephemeral-only, to the clicker alone. NEVER logged/audited below.
+  await ephemeral(
+    post,
+    ctx.channelId,
+    ctx.clickerId,
+    `Open this link to connect ${who} *${ctx.connectorName}* account (expires soon): ${url}`,
+  );
+  // Audit THAT a URL was issued — subject type + connector + who. NEVER the URL.
+  await appendAudit({
+    ...connectWhere(ctx.org, ctx.teamId, ctx.channelId),
+    principalId: ctx.clickerId,
+    action: "connector.oauth_url_issued",
+    detail: { connector: ctx.connectorName, subject: ctx.subjectLabel },
+  });
+  return true;
+}

package/agent/connections/connector-flags.ts

@@ -0,0 +1,44 @@
+// Arming flags for the connector plane. All default OFF, so an unarmed deployment behaves exactly as it did
+// before the flag; arming one is a reviewed diff in the deployment's own `agent/settings.ts`.
+
+import { getSettings } from "../settings/settings.js";
+
+/** True iff the per-user (Connect user-subject) credential path is armed. Off (default) ⇒
+ *  connections stay on the app-principal path and flag-off is byte-identical. */
+export function connectorUserPrincipalEnabled(): boolean {
+  return getSettings().connectors.userPrincipal;
+}
+
+/**
+ * True iff the C.3 shared user-OAuth vault is armed — a confirmed link-set member then keys the vault by the
+ * set's subject. Arming makes a confirmed membership credential-bearing, which the directory-sync guard reads.
+ */
+export function connectorLinkSetVaultEnabled(): boolean {
+  return getSettings().connectors.linkSetVault;
+}
+
+/**
+ * {@link connectorLinkSetVaultEnabled}, read FAIL-CLOSED: any throw resolves ARMED, because a false negative
+ * is a silent cross-person credential grant. Keyed on the VAULT flag alone, never on a conjunction.
+ */
+export function directoryLinkSetVaultArmed(): boolean {
+  try {
+    return connectorLinkSetVaultEnabled();
+  } catch {
+    return true;
+  }
+}
+
+/** True iff the per-op read/write approval gate is armed. Off (default) ⇒ connections keep
+ *  the blanket `once()` approval and flag-off is byte-identical. */
+export function connectorOpTieringEnabled(): boolean {
+  return getSettings().connectors.opTiering;
+}
+
+/**
+ * True iff the MEMBER PLANE is armed — a member's own connector credential resolving in a shared room their
+ * domain declared it for, reads only. Off ⇒ inert. This flag is the deployment's half of the answer only.
+ */
+export function connectorMemberPlaneEnabled(): boolean {
+  return getSettings().connectors.memberPlane;
+}