@sanoma-ai/workflows 0.10.0 → 0.10.2

package/src/client.ts

@@ -1,5 +1,16 @@
-import { connectionDriver, type ConnectionRef, type ConnectionSnapshot } from "./connection.ts";
-import { randomUUID } from "node:crypto";
+import {
+  connectionDriver,
+  connectionTargetSchema,
+  type ConnectionRef,
+  type ConnectionSnapshot,
+  type ConnectionTarget,
+  type ConnectionSetup,
+  type ConnectionCard,
+  type ConnectionRule,
+} from "./connection.ts";
+import { encodeCredentials, decodeCredentials, verifyAuthentication, AuthenticationError } from "./authentication.ts";
+
+import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { type DBOSClient, Error as DBOSErrors, type WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
@@ -53,7 +64,7 @@ import type { CallContext, Driver, Op } from "./op.ts";
 import { allowAll, type RecordedDecision } from "./policy.ts";
 import { admit, readPeople } from "./resources.ts";
 import type { RunArgs, StartHold } from "./run.ts";
-import type { SecretAccess, SecretLocation } from "./secret-store.ts";
+import { SecretStoreError, type SecretAccess, type SecretLocation } from "./secret-store.ts";
 import {
   BUILT_IN_WORKFLOWS,
   CALL_WORKFLOW,
@@ -220,6 +231,15 @@ export interface CallOptions {
   id?: string;
 }
 
+/** A credential-free review shown before the user saves a connection. */
+export interface ConnectionReview extends ConnectionSetup {
+  authorization: string;
+  requestId: string;
+  account: string;
+  scopes: string[];
+  credentialVersion: string | null;
+  expiresAt?: number;
+}
 /** What `SanomaClient.connect` is given besides the config. */
 export interface ClientOptions {
   /**
@@ -1148,10 +1168,226 @@ export class SanomaClient {
     if (current) await this.storedSecrets.delete(name, { expectedVersion: current.version, by });
   }
 
+  private connectionAuthorization(): string {
+    return createHash("sha256")
+      .update(
+        JSON.stringify({
+          version: this.config.version,
+          policies: this.config.policies,
+          problems: this.config.policyProblems,
+        }),
+      )
+      .digest("hex");
+  }
+
+  /** Safe account cards, scoped to the admitted principal. No provider or secret reads. */
+  async connections(options: { actor: Principal | string }): Promise<ConnectionCard[]> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    return this.config.connections.cards(actor.id);
+  }
+
+  /** Creation choices are scoped by code to the admitted person's current groups. */
+  async connectionRules(options: { actor: Principal | string }): Promise<{ id: string; rule: ConnectionRule }[]> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    return [...this.config.connections.catalog.rules]
+      .filter(([, rule]) =>
+        rule.createBy.some((by) => (typeof by === "string" ? by === actor.id : actor.groups?.includes(by.group))),
+      )
+      .map(([id, rule]) => ({ id, rule }));
+  }
+
+  /** Readiness only, without reading or listing any credential. The adapter's bootstrap
+   * authority is checked by validate; provider details never escape this boundary. */
+  async secretStoreStatus(options: { actor: Principal | string }) {
+    await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    const { store, namespace } = this.storedSecrets;
+    let problem: string | undefined;
+    try {
+      await this.storedSecrets.validate();
+    } catch (error) {
+      problem = (error as SecretStoreError).code;
+    }
+    return {
+      store: store.id,
+      namespace,
+      capabilities: { ...store.capabilities },
+      ready: !problem,
+      ...(problem && { problem }),
+    };
+  }
+
+  /** Secure intake endpoint, never a workflow operation. Only its metadata-only prepare gate
+   * enters policy/approval history; callers keep the value in a password form while reviewing. */
+  async previewConnection(
+    target: ConnectionTarget,
+    credentials: unknown,
+    options: { actor: Principal | string; id: string },
+  ): Promise<ConnectionReview> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    const id = parseOrThrow(z.string().min(1).max(200), options.id, "Name the setup request");
+    target = parseOrThrow(connectionTargetSchema, target, "Select a declared connection or creation rule");
+    const setup = await this.config.connections.setup(target, actor, id);
+    const authorized = (await this.call(
+      "sanoma.connection.prepare",
+      {
+        target,
+        requestId: id,
+        definition: setup.definition,
+        authorization: this.connectionAuthorization(),
+      },
+      { actor, id: `connection-prepare:${id}` },
+    )) as ConnectionSetup;
+    if (!isDeepStrictEqual(authorized, setup))
+      throw new SanomaError("invalid_input", "The connection changed; start a new review");
+    const method = this.config.connections.catalog.methods.get(setup.vendor)![setup.method]!;
+    const external =
+      method.kind !== "workload-identity" &&
+      (setup.location?.management === "external" || !this.storedSecrets.store.capabilities.writable);
+    if (
+      !external &&
+      method.kind !== "workload-identity" &&
+      this.storedSecrets.store.capabilities.conditionalWrites === "none"
+    )
+      throw new SecretStoreError("unsupported");
+    if (credentials !== undefined && (external || method.kind === "workload-identity"))
+      throw new SecretStoreError("read_only");
+    const existing = setup.credential ? await this.storedSecrets.read(setup.credential) : undefined;
+    if (external && !existing) throw new SecretStoreError("unavailable");
+    const encoded =
+      method.kind === "workload-identity"
+        ? undefined
+        : external
+          ? existing!.value
+          : encodeCredentials(method, credentials);
+    const identity = await verifyAuthentication(
+      method,
+      encoded === undefined ? undefined : decodeCredentials(method, encoded),
+      { connectionId: setup.id, vendor: setup.vendor },
+    );
+    if (setup.expectedAccount && setup.expectedAccount !== identity.account)
+      throw new AuthenticationError("wrong_account");
+    if (setup.requiredScopes.some((scope) => !identity.scopes.includes(scope)))
+      throw new AuthenticationError("scope_changed");
+    return {
+      ...setup,
+      requestId: id,
+      authorization: this.connectionAuthorization(),
+      account: identity.account,
+      scopes: [...identity.scopes],
+      credentialVersion: existing?.version ?? null,
+      ...(identity.expiresAt !== undefined && { expiresAt: identity.expiresAt }),
+    };
+  }
+
+  /** Reverify the reviewed authority, reserve its metadata under policy, then write the bundle
+   * outside durable execution. Activation has its own policy gate and verifies what was saved. */
+  async connectConnection(
+    review: ConnectionReview,
+    credentials: unknown,
+    options: { actor: Principal | string },
+  ): Promise<ConnectionSnapshot> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    if (review.authorization !== this.connectionAuthorization())
+      throw new SanomaError("invalid_input", "The policy changed; start a new connection review");
+    const setup = await this.config.connections.setup(review.target, actor, review.requestId);
+    for (const field of ["id", "vendor", "method", "definition", "credential", "location"] as const) {
+      if (!isDeepStrictEqual(setup[field], review[field]))
+        throw new SanomaError("invalid_input", "The destination changed; review it again before saving");
+    }
+    // Reuse only the metadata gate, never a cached credential or verification result.
+    await this.call(
+      "sanoma.connection.prepare",
+      {
+        target: review.target,
+        requestId: review.requestId,
+        definition: setup.definition,
+        authorization: review.authorization,
+      },
+      { actor, id: `connection-prepare:${review.requestId}` },
+    );
+    const method = this.config.connections.catalog.methods.get(setup.vendor)![setup.method]!;
+    const external =
+      method.kind !== "workload-identity" &&
+      (setup.location?.management === "external" || !this.storedSecrets.store.capabilities.writable);
+    if (
+      !external &&
+      method.kind !== "workload-identity" &&
+      this.storedSecrets.store.capabilities.conditionalWrites === "none"
+    )
+      throw new SecretStoreError("unsupported");
+    if (credentials !== undefined && (external || method.kind === "workload-identity"))
+      throw new SecretStoreError("read_only");
+    const existing = setup.credential ? await this.storedSecrets.read(setup.credential) : undefined;
+    if (external && (!existing || existing.version !== review.credentialVersion))
+      throw new SecretStoreError("conflict");
+    if (setup.expectedRevision === review.expectedRevision && (existing?.version ?? null) !== review.credentialVersion)
+      throw new SecretStoreError("conflict");
+    const encoded =
+      method.kind === "workload-identity"
+        ? undefined
+        : external
+          ? existing!.value
+          : encodeCredentials(method, credentials);
+    const identity = await verifyAuthentication(
+      method,
+      encoded === undefined ? undefined : decodeCredentials(method, encoded),
+      { connectionId: setup.id, vendor: setup.vendor },
+    );
+    if (identity.account !== review.account) throw new AuthenticationError("wrong_account");
+    if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(review.scopes)].toSorted()))
+      throw new AuthenticationError("scope_changed");
+    const selected = (await this.call(
+      "sanoma.connection.configure",
+      {
+        target: review.target,
+        requestId: review.requestId,
+        expectedRevision: review.expectedRevision,
+        definition: review.definition,
+        account: identity.account,
+        scopes: [...identity.scopes],
+      },
+      { actor, id: `connection-configure:${review.requestId}` },
+    )) as ConnectionSnapshot;
+    const ref = { vendor: selected.vendor, $connection: selected.id };
+    if (
+      (await this.config.connections.setupState(selected, actor)) === "pending" &&
+      !external &&
+      encoded !== undefined
+    ) {
+      let written = false;
+      try {
+        const receipt = await this.config.connections.storedVersion(selected.id, selected.revision);
+        if (receipt) {
+          if (existing?.version !== receipt || existing.value !== encoded) throw new SecretStoreError("conflict");
+        } else {
+          const stored = await this.storedSecrets.write(setup.credential!, encoded, {
+            expectedVersion: review.credentialVersion,
+            by: actor.id,
+          });
+          written = true;
+          await this.config.connections.recordStoredVersion(selected.id, selected.revision, stored.version);
+        }
+      } catch (error) {
+        if (written || (error as { code?: string })?.code === "unavailable")
+          await this.config.connections.uncertain(ref, selected.revision, actor.id);
+        throw error;
+      }
+    }
+    const connected = (await this.call(
+      "sanoma.connection.activate",
+      {
+        connection: ref,
+        expectedRevision: selected.revision,
+      },
+      { actor, id: `connection-activate:${review.requestId}` },
+    )) as ConnectionSnapshot;
+    await this.config.connections.assertCurrent(connected, actor.id);
+    return connected;
+  }
+
   /**
-   * The values of these secrets, as a driver's `secrets.get` reads them: this process's
-   * environment, which wins, else the stored value, with who set it and when. A name with neither
-   * is left out. For server code: a page is told whether one is set, never its value.
+   * Values resolved through the selected store and explicit bindings, with version and change
+   * metadata. Missing names are left out. Server code only; pages receive status, never values.
    */
   async secrets(names: readonly string[]): Promise<Map<string, StoredSecret>> {
     const found = new Map<string, StoredSecret>();

package/src/cloud-identity.ts

@@ -0,0 +1,266 @@
+import { createHash, randomBytes } from "node:crypto";
+import { Compute, OAuth2Client } from "google-auth-library";
+import type { Db } from "./db.ts";
+
+const LIFETIME = 600_000;
+const SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const CREDENTIAL = /^[A-Za-z0-9_-]{43}$/;
+const ACCOUNT = /^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/;
+
+/** A safe error boundary: no HTTP response, credentials, SDK cause or request options. */
+export class CloudIdentityError extends Error {
+  constructor() {
+    super("Cloud identity unavailable");
+    this.name = "CloudIdentityError";
+  }
+}
+
+/** Provisioning only. Deliver the value once through deployment secrets; persist only its hash. */
+export function createDeploymentCredential(): { credential: string; hash: string } {
+  const credential = randomBytes(32).toString("base64url");
+  return { credential, hash: credentialHash(credential) };
+}
+const credentialHash = (credential: string) => createHash("sha256").update(credential).digest("hex");
+
+export interface IdentityEnrollment {
+  deployment: string;
+  company: string;
+  environment: string;
+  serviceAccount: string;
+  generation: number;
+}
+export interface IdentityEnrollments {
+  /** Return an enrollment only while this hash/generation and deployment are active. Never cache. */
+  active(hash: string): Promise<IdentityEnrollment | undefined>;
+}
+
+/** Install in the broker's own database using provisioning authority, never a company database. */
+export const CLOUD_IDENTITY_SQL = `
+CREATE SCHEMA IF NOT EXISTS sanoma_identity;
+REVOKE ALL ON SCHEMA sanoma_identity FROM PUBLIC;
+CREATE TABLE IF NOT EXISTS sanoma_identity.deployments (
+  id text PRIMARY KEY, company text NOT NULL, environment text NOT NULL,
+  service_account text NOT NULL, enabled boolean NOT NULL DEFAULT true
+);
+CREATE TABLE IF NOT EXISTS sanoma_identity.credentials (
+  hash text PRIMARY KEY CHECK (hash ~ '^[0-9a-f]{64}$'),
+  deployment text NOT NULL REFERENCES sanoma_identity.deployments(id),
+  generation bigint NOT NULL CHECK (generation > 0),
+  valid_from timestamptz NOT NULL DEFAULT now(), valid_until timestamptz NOT NULL,
+  revoked boolean NOT NULL DEFAULT false,
+  UNIQUE (deployment, generation), CHECK (valid_until > valid_from),
+  CHECK (isfinite(valid_from) AND isfinite(valid_until))
+);
+REVOKE ALL ON ALL TABLES IN SCHEMA sanoma_identity FROM PUBLIC;
+`;
+
+/** Give the broker SELECT only; enrollment, rotation and revocation use a separate database role. */
+export function postgresIdentityEnrollments(database: () => Promise<Db>): IdentityEnrollments {
+  return {
+    async active(hash) {
+      const { rows } = await (
+        await database()
+      ).query<{
+        deployment: string;
+        company: string;
+        environment: string;
+        service_account: string;
+        generation: string;
+      }>(
+        `SELECT d.id AS deployment, d.company, d.environment, d.service_account, c.generation
+          FROM sanoma_identity.credentials c JOIN sanoma_identity.deployments d ON d.id = c.deployment
+          WHERE c.hash = $1 AND NOT c.revoked AND d.enabled
+            AND c.valid_from <= clock_timestamp() AND c.valid_until > clock_timestamp()`,
+        [hash],
+      );
+      const row = rows[0];
+      return (
+        row && {
+          deployment: row.deployment,
+          company: row.company,
+          environment: row.environment,
+          serviceAccount: row.service_account,
+          generation: Number(row.generation),
+        }
+      );
+    },
+  };
+}
+
+export interface CloudAccessToken {
+  accessToken: string;
+  expiresAt: number;
+}
+export interface IdentityAudit {
+  result: "issued" | "denied" | "unavailable";
+  enrollment?: IdentityEnrollment;
+  expiresAt?: number;
+}
+export interface IdentityBrokerOptions {
+  enrollments: IdentityEnrollments;
+  /** Trusted issuer with attached platform authority; target comes exclusively from enrollment. */
+  issue(serviceAccount: string): Promise<CloudAccessToken>;
+  /** Must durably record the decision without token values. A failure prevents delivery. */
+  audit(event: IdentityAudit): Promise<void>;
+}
+const validEnrollment = (e: IdentityEnrollment | undefined): e is IdentityEnrollment =>
+  !!e &&
+  [e.deployment, e.company, e.environment].every((v) => typeof v === "string" && v.length > 0 && v.length <= 256) &&
+  ACCOUNT.test(e.serviceAccount) &&
+  Number.isSafeInteger(e.generation) &&
+  e.generation > 0;
+const validToken = (token: CloudAccessToken, now: number) =>
+  typeof token?.accessToken === "string" &&
+  token.accessToken.length > 0 &&
+  token.accessToken.length <= 8192 &&
+  !/[\s\r\n]/.test(token.accessToken) &&
+  Number.isFinite(token.expiresAt) &&
+  token.expiresAt > now &&
+  token.expiresAt <= now + LIFETIME + 30_000;
+const reply = (status: number, body: unknown) =>
+  Response.json(body, {
+    status,
+    headers: { "Cache-Control": "no-store", Pragma: "no-cache" },
+  });
+
+// Node/edge adapters can represent an empty POST as a stream. Reject actual bytes,
+// without buffering attacker-controlled input or waiting indefinitely for its end.
+async function hasBody(request: Request): Promise<boolean> {
+  if (!request.body) return false;
+  const reader = request.body.getReader();
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const first = await Promise.race([
+      reader.read(),
+      new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new CloudIdentityError()), 5_000);
+      }),
+    ]);
+    return !first.done;
+  } finally {
+    clearTimeout(timeout);
+    void reader.cancel().catch(() => {});
+  }
+}
+
+/** POST /token with a deployment bearer credential and no query or body. No enrollment endpoint. */
+export function identityBroker(options: IdentityBrokerOptions): (request: Request) => Promise<Response> {
+  return async (request) => {
+    let enrollment: IdentityEnrollment | undefined;
+    try {
+      const url = new URL(request.url);
+      if (url.pathname !== "/token" || request.method !== "POST") return reply(404, { error: "not_found" });
+      if (url.search || (await hasBody(request))) return reply(400, { error: "invalid_request" });
+      const authorization = request.headers.get("authorization") ?? "";
+      const credential = authorization.startsWith("Bearer ") ? authorization.slice(7) : "";
+      const hash = CREDENTIAL.test(credential) ? credentialHash(credential) : undefined;
+      enrollment = hash ? await options.enrollments.active(hash) : undefined;
+      if (!validEnrollment(enrollment)) {
+        await options.audit({ result: "denied" });
+        return reply(401, { error: "unauthorized" });
+      }
+      // Copy authoritative values before any awaits; caller fields never select a target or lifetime.
+      enrollment = {
+        deployment: enrollment.deployment,
+        company: enrollment.company,
+        environment: enrollment.environment,
+        serviceAccount: enrollment.serviceAccount,
+        generation: enrollment.generation,
+      };
+      const token = await options.issue(enrollment.serviceAccount);
+      if (!validToken(token, Date.now())) throw new CloudIdentityError();
+      const current = await options.enrollments.active(hash!);
+      if (
+        !current ||
+        (Object.keys(enrollment) as (keyof IdentityEnrollment)[]).some((key) => current[key] !== enrollment![key])
+      ) {
+        await options.audit({ result: "denied", enrollment });
+        return reply(401, { error: "unauthorized" });
+      }
+      await options.audit({ result: "issued", enrollment, expiresAt: token.expiresAt });
+      return reply(200, { accessToken: token.accessToken, expiresAt: token.expiresAt });
+    } catch {
+      try {
+        await options.audit({ result: "unavailable", ...(enrollment && { enrollment }) });
+      } catch {
+        /* fail closed */
+      }
+      return reply(503, { error: "unavailable" });
+    }
+  };
+}
+
+/** Cloud Run attached identity only: no ADC environment file or service-account private key fallback. */
+export function attachedGoogleTokenIssuer(): IdentityBrokerOptions["issue"] {
+  const auth = new Compute({ scopes: [SCOPE] });
+  return async (serviceAccount) => {
+    if (!ACCOUNT.test(serviceAccount)) throw new CloudIdentityError();
+    try {
+      const response = await auth.request<{ accessToken: string; expireTime: string }>({
+        url: `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${serviceAccount}:generateAccessToken`,
+        method: "POST",
+        data: { scope: [SCOPE], lifetime: "600s" },
+        timeout: 10_000,
+      });
+      const token = { accessToken: response.data.accessToken, expiresAt: Date.parse(response.data.expireTime) };
+      if (!validToken(token, Date.now())) throw new CloudIdentityError();
+      return token;
+    } catch {
+      throw new CloudIdentityError();
+    }
+  };
+}
+
+/** A per-runtime Google SDK auth client. Short-lived access tokens are kept only in this instance's memory. */
+export function cloudIdentityAuth(options: {
+  endpoint: string;
+  /** Read the current deployment credential from protected bootstrap; called again on renewal. */
+  credential(): Promise<string>;
+}): OAuth2Client {
+  let endpoint: URL;
+  try {
+    endpoint = new URL(options.endpoint);
+  } catch {
+    throw new CloudIdentityError();
+  }
+  if (
+    endpoint.protocol !== "https:" ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    endpoint.pathname !== "/token"
+  )
+    throw new CloudIdentityError();
+  const client = new OAuth2Client({ eagerRefreshThresholdMillis: 60_000 });
+  let pending: Promise<{ access_token: string; expiry_date: number }> | undefined;
+  client.refreshHandler = () => {
+    if (pending) return pending;
+    pending = (async () => {
+      try {
+        const credential = await options.credential();
+        if (!CREDENTIAL.test(credential)) throw new CloudIdentityError();
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${credential}` },
+          cache: "no-store",
+          redirect: "error",
+          signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) throw new CloudIdentityError();
+        const raw = await response.text();
+        if (raw.length > 16_384) throw new CloudIdentityError();
+        const token = JSON.parse(raw) as CloudAccessToken;
+        const now = Date.now();
+        if (!validToken(token, now) || token.expiresAt <= now + 60_000) throw new CloudIdentityError();
+        return { access_token: token.accessToken, expiry_date: token.expiresAt };
+      } catch {
+        throw new CloudIdentityError();
+      } finally {
+        pending = undefined;
+      }
+    })();
+    return pending;
+  };
+  return client;
+}

package/src/config.ts

@@ -1,4 +1,6 @@
 import { configuredSecrets } from "./credentials.ts";
+import { secretsForInput } from "./secret.ts";
+import { isRunControlError } from "./errors.ts";
 import { currentRun } from "./run.ts";
 import {
   connectionCatalog,
@@ -331,6 +333,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
     ops,
+    { connections },
   );
   const fakes = makersOf(running, "fake");
   if (dataStore) fakes.set(DATA_VENDOR, () => collectionsFake(declared));
@@ -617,11 +620,15 @@ function indexConnectors(list: Connector<any, any>[]) {
 }
 
 /**
- * The drivers' functions by operation id, refusing one no connector declares. A driver that
- * declares an `env` has each function guarded by it (`guarded`); a fake declares none, so a
- * sandbox run's calls are not.
+ * The drivers' functions by operation id, refusing one no connector declares. Named live
+ * calls resolve authentication here, after policy, inside the driver's execution boundary.
+ * Drivers without named authentication retain their declared environment guard.
  */
-export function indexDrivers(list: Driver[], ops: Map<string, Op>) {
+export function indexDrivers(
+  list: Driver[],
+  ops: Map<string, Op>,
+  options: { connections?: ConnectionRegistry; sandbox?: boolean } = {},
+) {
   const map = new Map<string, DriverFn>();
   for (const d of list) {
     for (const [key, fn] of Object.entries(d.ops)) {
@@ -629,7 +636,36 @@ export function indexDrivers(list: Driver[], ops: Map<string, Op>) {
       if (!ops.has(id)) {
         throw new Error(`Driver "${d.vendor}" implements ${id}, which no connector in \`connectors\` declares`);
       }
-      map.set(id, d.env ? guarded(d.vendor, d.env, fn) : fn);
+      const unselected = d.env ? guarded(d.vendor, d.env, fn) : fn;
+      map.set(id, async (input, call) => {
+        if (options.sandbox) return fn(input, call);
+        if (!call.connection) {
+          if (d.authentication?.length)
+            throw new DriverError("Select a named connection for this driver", { retryable: false });
+          return unselected(input, call);
+        }
+        if (!options.connections || !call.principal || !d.authentication?.includes(call.connection.method))
+          throw new DriverError("This driver does not support the selected connection", { retryable: false });
+        const authentication = await options.connections.authenticate(call.connection, call.principal.id);
+        try {
+          return await fn(input, {
+            ...call,
+            connection: structuredClone(call.connection),
+            authentication,
+            secrets: secretsForInput(input, call.secrets, ops.get(id)!.createsSecrets?.(input)),
+          });
+        } catch (error) {
+          if (isRunControlError(error)) throw error;
+          // SDK exceptions can contain the complete request, including authorization headers.
+          // Drivers may come from another installed copy of this package.
+          const failure = error as { code?: unknown; retryable?: unknown; status?: unknown } | null;
+          const status = failure?.code === "driver_failed" ? failure.status : undefined;
+          throw new DriverError(`${d.vendor} operation failed`, {
+            retryable: failure?.code === "driver_failed" && failure.retryable === true,
+            ...(typeof status === "number" && Number.isInteger(status) && status >= 100 && status <= 599 && { status }),
+          });
+        }
+      });
     }
   }
   return map;
@@ -637,12 +673,10 @@ export function indexDrivers(list: Driver[], ops: Map<string, Op>) {
 
 /**
  * `fn`, refused while the environment leaves a variable `env` declares missing or invalid. The
- * worker started without it (`startWorker` only warns), and stored credentials load into the
- * environment as they are set, so the check is made when the function is called, inside the
- * driver step, and nowhere earlier: not at start, and not before the policy's decision or an
- * approval hold, so a credential set on the connector page while a call waits for approval is
- * used when the approver approves. The refusal is the call's own failure, final: recorded as
- * the call's, and never retried.
+ * worker started without it (`startWorker` only warns). This checks only explicitly supplied
+ * process environment; stored credentials are never copied there. The guard runs inside the
+ * driver step after policy and approval. Named connections never use this path. The refusal
+ * is the call's own failure, final: recorded as the call's, and never retried.
  */
 function guarded(vendor: string, env: DriverEnv, fn: DriverFn): DriverFn {
   return async (input, call) => {