@sanoma-ai/workflows 0.10.0 → 0.10.1

package/dist/steps.d.ts

@@ -1,5 +1,6 @@
 import type { LedgerRecord } from "./ledger.ts";
 import type { Op } from "./op.ts";
+import type { ConnectionRef } from "./connection.ts";
 /** Any operation, whatever its input and output. */
 type AnyOp<I = any, O = any> = Op<string, string, string, I, O>;
 /**
@@ -14,9 +15,11 @@ export type Seed = {
     op: AnyOp;
     input: Record<string, unknown>;
     as?: string;
+    connection?: ConnectionRef;
 } | {
     op: AnyOp;
     fault: "failNext" | "rateLimit" | "loseReply";
+    connection?: ConnectionRef;
 };
 /** A call through an operation: what it was given, and what it returned. */
 export interface Call<I, O> {

package/dist/steps.js.map

@@ -1 +1 @@
-{"version":3,"file":"steps.js","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAgEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,MAGU;IAEV,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,MAAM,CAAC;QACL,KAAK,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QAC7E,wFAAwF;QACxF,+CAA+C;QAC/C,IAAI,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;KAC5E,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC"}
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../src/steps.ts"],"names":[],"mappings":"AAiEA;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,WAAW,CACzB,KAAa,EACb,MAGU;IAEV,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,MAAM,CAAC;QACL,KAAK,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;QAC7E,wFAAwF;QACxF,+CAA+C;QAC/C,IAAI,EAAE,CAAC,UAAU,EAAE,EAAE,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,CAAC;KAC5E,CAAC,CAAC;IACH,OAAO,MAAM,CAAC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;AAC/D,CAAC"}

package/oxlint.json

@@ -94,6 +94,7 @@
                   "@sanoma-ai/connector-*/fake",
                   "@sanoma-ai/connector-*/driver",
                   "@sanoma-ai/connector-*/remote",
+                  "@sanoma-ai/connector-*/vault",
                   "@sanoma-ai/workflows/describe",
                   "@sanoma-ai/workflows/fake",
                   "@sanoma-ai/workflows/plugin",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sanoma-ai/workflows",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Business processes as TypeScript functions, run durably on DBOS",
   "keywords": [
     "approvals",
@@ -24,6 +24,7 @@
     "!src/AGENTS.md",
     "oxlint.json",
     "README.md",
+    "SECRET-SUPPORT.md",
     "LICENSE"
   ],
   "type": "module",

package/src/apps.ts

@@ -7,7 +7,7 @@ import { exportsOf, type Loaded, loadModules } from "./load.ts";
 import { stringValue } from "./outline.ts";
 import { APPS_DIR, filesUnder, inside, isDirectory, RELATIVE, relPath } from "./paths.ts";
 import type { ResourceProblem } from "./resources.ts";
-import { APP_NAME } from "./shared.ts";
+import { APP_NAME, problemLine } from "./shared.ts";
 
 // A company's apps: each folder of `apps/` holds the kinds the root does (workflows, resources,
 // policies, scenarios, sites), merged from a source repository whose URL its `app.ts` names, or
@@ -65,6 +65,22 @@ export function appsAt(root: string | undefined): { apps: AppEntry[]; problems:
   return { apps, problems };
 }
 
+/**
+ * The source URL the app `folder` under `root` is taken from, as its `app.ts` names it; an error
+ * saying why there is none: no such app, its `app.ts` does not load or is not `defineApp({ source })`
+ * (what is wrong, where), or it names none (the company's own app).
+ */
+export function appSourceOf(root: string, folder: string): string {
+  if (!APP_NAME.test(folder) || !isDirectory(join(root, APPS_DIR, folder)))
+    throw new Error(`There is no app ${APPS_DIR}/${folder}/`);
+  const file = `${APPS_DIR}/${folder}/app.ts`;
+  const path = join(root, file);
+  const read = existsSync(path) ? appDefinitionOf(file, loadModules(root, [path], [])) : { problems: [] };
+  if (read.problems.length) throw new Error(read.problems.map(problemLine).join("; "));
+  if (read.source === undefined) throw new Error(`${file} names no source: the app is the company's own`);
+  return read.source;
+}
+
 /** What `app.ts`'s default export, `defineApp({ … })`, may say. */
 const AppDefinitionSchema = z.strictObject({ source: z.string().optional() });
 

package/src/authentication.ts

@@ -1,6 +1,95 @@
 import type { z } from "zod";
+import type { CallContext } from "./op.ts";
 import { SecretStoreError, type SecretStoreCapabilities } from "./secret-store.ts";
 
+/** Facts verified with the provider, not account claims supplied by the caller. */
+export interface AuthenticationIdentity {
+  account: string;
+  scopes: readonly string[];
+  /** Unix time in milliseconds. Missing means the provider gives no expiry. */
+  expiresAt?: number;
+}
+
+export type AuthenticationProblem =
+  | "missing"
+  | "expired"
+  | "revoked"
+  | "rejected"
+  | "wrong_account"
+  | "scope_changed"
+  | "uncertain"
+  | "unavailable"
+  | "unsupported";
+
+/** Safe lifecycle information only: never a provider response, cause or credential. */
+export class AuthenticationError extends Error {
+  readonly code = "authentication_failed";
+  readonly retryable: boolean;
+  readonly problem: AuthenticationProblem;
+  constructor(problem: AuthenticationProblem) {
+    super(`Authentication: ${problem}`);
+    this.problem = problem;
+    this.name = "AuthenticationError";
+    this.retryable = problem === "unavailable";
+  }
+}
+
+const authenticationProblems = new Set<AuthenticationProblem>([
+  "missing",
+  "expired",
+  "revoked",
+  "rejected",
+  "wrong_account",
+  "scope_changed",
+  "uncertain",
+  "unavailable",
+  "unsupported",
+]);
+
+export function authenticationProblem(error: unknown): AuthenticationProblem | undefined {
+  const failure = error as Partial<AuthenticationError> | null;
+  return failure?.name === "AuthenticationError" && authenticationProblems.has(failure.problem!)
+    ? failure.problem
+    : undefined;
+}
+
+/** Shared by credential intake and execution; unknown provider failures never imply revocation. */
+export async function verifyAuthentication(
+  method: Authentication,
+  credentials?: unknown,
+): Promise<AuthenticationIdentity> {
+  if (!method.verify) throw new AuthenticationError("unsupported");
+  try {
+    const identity = await method.verify(credentials);
+    if (
+      typeof identity?.account !== "string" ||
+      !identity.account.trim() ||
+      !Array.isArray(identity.scopes) ||
+      identity.scopes.some((scope) => typeof scope !== "string") ||
+      (identity.expiresAt !== undefined && !Number.isFinite(identity.expiresAt))
+    )
+      throw new AuthenticationError("unavailable");
+    if (identity.expiresAt !== undefined && identity.expiresAt <= Date.now()) throw new AuthenticationError("expired");
+    return {
+      account: identity.account,
+      scopes: [...new Set(identity.scopes)].toSorted(),
+      ...(identity.expiresAt !== undefined && { expiresAt: identity.expiresAt }),
+    };
+  } catch (error) {
+    // Structural recognition works across installed copies. Rebuild even recognized errors so
+    // an SDK message, stack or cause attached by a verifier cannot cross this boundary.
+    throw new AuthenticationError(authenticationProblem(error) ?? "unavailable");
+  }
+}
+
+/** Ephemeral material for one authorized driver invocation; never checkpoint this object. */
+export interface CallAuthentication {
+  method: string;
+  kind: Authentication["kind"];
+  credentialVersion?: string;
+  credentials?: unknown;
+}
+
 /** Credential schemas and lifecycle are owned by authentication, never by the store provider. */
 export type Authentication<S extends z.ZodType = z.ZodType> =
   | {
@@ -8,14 +97,23 @@ export type Authentication<S extends z.ZodType = z.ZodType> =
       version: number;
       schema: S;
       storage: { writable: boolean; maxBytes: number; conditionalWrites: boolean };
+      verify?(credentials: z.output<S>): Promise<AuthenticationIdentity>;
     }
-  | { kind: "workload-identity"; storage?: never; version?: never; schema?: never };
+  | {
+      kind: "workload-identity";
+      storage?: never;
+      version?: never;
+      schema?: never;
+      verify?(): Promise<AuthenticationIdentity>;
+    };
 
 export function defineAuthentication<S extends z.ZodType>(definition: Authentication<S>): Authentication<S> {
+  if (definition.verify !== undefined && typeof definition.verify !== "function")
+    throw new SecretStoreError("invalid_configuration");
   if (definition.kind === "workload-identity") {
     if (definition.storage !== undefined || definition.schema !== undefined || definition.version !== undefined)
       throw new SecretStoreError("invalid_configuration");
-    return Object.freeze({ kind: "workload-identity" });
+    return Object.freeze({ ...definition });
   }
   if (
     !["api-key", "fields", "oauth2", "signed"].includes(definition.kind) ||
@@ -33,6 +131,25 @@ export function defineAuthentication<S extends z.ZodType>(definition: Authentica
   return Object.freeze({ ...definition, storage: Object.freeze({ ...definition.storage }) });
 }
 
+/** Typed access inside a driver. A missing or different method never falls back to the environment. */
+export function authenticationCredentials<S extends z.ZodType>(
+  method: string,
+  definition: Authentication<S>,
+  call: CallContext,
+): z.output<S> {
+  if (
+    definition.kind === "workload-identity" ||
+    call.authentication?.method !== method ||
+    call.authentication.kind !== definition.kind
+  )
+    throw new SecretStoreError("unsupported");
+  try {
+    return definition.schema.parse(call.authentication.credentials);
+  } catch {
+    throw new SecretStoreError("invalid_value");
+  }
+}
+
 /** Compatibility check before consent, including externally renewed (read-only) OAuth bundles. */
 export function checkAuthenticationStore(
   auth: Authentication,

package/src/call.ts

@@ -458,9 +458,8 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?:
   const connection = await DBOS.runStep(
     async () => {
       if (run.sandbox !== undefined) {
-        if (ref)
-          throw new SanomaError("invalid_input", "Named sandbox connections require explicit fake account state");
-        return undefined;
+        if (!run.fakeConnection) throw new SanomaError("invalid_input", "Sandbox account state is unavailable");
+        return run.fakeConnection(op.vendor, ref);
       }
       return run.state.connections?.select(op.vendor, ref, run.actor.id);
     },
@@ -469,7 +468,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?:
   const decideStep = () =>
     DBOS.runStep(
       async () => {
-        await run.state.connections?.assertCurrent(connection, run.actor.id);
+        if (run.sandbox === undefined) await run.state.connections?.assertCurrent(connection, run.actor.id);
         return decide(run, op, parsed, connection);
       },
       { name: `policy:${op.id}` },
@@ -527,7 +526,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?:
       async () => {
         const at = Date.now();
         attempt = DBOS.stepStatus?.currentAttempt ?? 1;
-        await run.state.connections?.assertCurrent(connection, run.actor.id);
+        if (run.sandbox === undefined) await run.state.connections?.assertCurrent(connection, run.actor.id);
         const secrets = secretsOf(run);
         const context: CallContext = {
           idempotencyKey: `${run.id}:${seq}`,

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,224 @@ 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),
+    );
+    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),
+    );
+    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/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) => {