@sanoma-ai/workflows 0.10.0 → 0.10.2

package/src/fake.ts

@@ -11,6 +11,7 @@ import {
 import { fail, type Instance, UNREGISTERED, type WakeupApi, wakeupCalls } from "./wakeup-driver.ts";
 import { INSTANCE_TOKEN, instanceUrl } from "./wakeup-service.ts";
 import { wakeupOps } from "./wakeup-type.ts";
+import type { ConnectionRef } from "./connection.ts";
 
 /*
  * Fake vendors for tests, at `@sanoma-ai/workflows/fake`. Kept off the main entry so the
@@ -25,6 +26,76 @@ export interface FakeCall {
   at: string;
   idempotencyKey: string;
   attempt: number;
+  connection?: string;
+}
+
+/** A factory per named account: state, faults and idempotent replies never cross connections. */
+export function connectionFakes<F extends Fake<unknown>>(make: () => F) {
+  const seen = new WeakSet<object>();
+  const fresh = () => {
+    const fake = make();
+    const parts = [
+      fake,
+      fake.driver,
+      fake.driver.ops,
+      ...(fake.state && typeof fake.state === "object" ? [fake.state] : []),
+    ];
+    if (parts.some((part) => seen.has(part)))
+      throw new Error("A named fake factory must create separate state for each connection");
+    for (const part of parts) seen.add(part);
+    return fake;
+  };
+  const first = fresh();
+  const { vendor } = first.driver;
+  let unused: F | undefined = first;
+  const accounts = new Map<string, { fake: F; identity?: string }>();
+  const calls: FakeCall[] = [];
+  const account = (ref: ConnectionRef): F => {
+    if (ref.vendor !== vendor || !ref.$connection.startsWith(`${vendor}/`))
+      throw new Error(`fake ${vendor}: select a connection of this connector`);
+    let entry = accounts.get(ref.$connection);
+    if (!entry) {
+      entry = { fake: unused ?? fresh() };
+      unused = undefined;
+      accounts.set(ref.$connection, entry);
+    }
+    return entry.fake;
+  };
+  const ops: Record<string, DriverFn> = {};
+  for (const key of Object.keys(first.driver.ops)) {
+    ops[key] = async (input, call) => {
+      const selected = call.connection;
+      if (!selected || selected.vendor !== vendor)
+        throw new DriverError(`fake ${vendor}: select a named connection`, { retryable: false });
+      const ref = { vendor, $connection: selected.id };
+      account(ref);
+      let entry = accounts.get(selected.id)!;
+      // Rebinding to another vendor account gets fresh state. Rotation within an account does not.
+      if (entry.identity !== undefined && entry.identity !== selected.account) {
+        entry = { fake: fresh() };
+        accounts.set(selected.id, entry);
+      }
+      entry.identity = selected.account;
+      calls.push({
+        op: `${vendor}.${key}`,
+        input: structuredClone(input),
+        at: new Date().toISOString(),
+        idempotencyKey: call.idempotencyKey,
+        attempt: call.attempt,
+        connection: selected.id,
+      });
+      return entry.fake.driver.ops[key]!(input, call);
+    };
+  }
+  return {
+    driver: { vendor, ops } satisfies Driver,
+    account,
+    calls,
+    reset() {
+      for (const entry of accounts.values()) entry.fake.reset();
+      calls.length = 0;
+    },
+  };
 }
 
 export interface FakeOptions {

package/src/index.ts

@@ -62,7 +62,7 @@ export {
   type SanomaConfig,
 } from "./config.ts";
 // An app's `app.ts` (`defineApp`), and where the launcher finds an app's workflows and data file.
-export { type AppEntry, readApps } from "./apps.ts";
+export { type AppEntry, appSourceOf, readApps } from "./apps.ts";
 export { type AppDefinition, defineApp } from "./definitions.ts";
 export { appFolders, APPS_DIR, filesUnder, kindDirs } from "./paths.ts";
 // `sanoma` itself (the people types' constructors) is at `@sanoma-ai/workflows/resources`, for data files.
@@ -214,6 +214,7 @@ export {
   type ChangesFilter,
   type ChangeView,
   type ClientOptions,
+  type ConnectionReview,
   SanomaClient,
   type RunsFilter,
   type RunSummary,
@@ -285,7 +286,14 @@ export {
   checkAuthenticationStore,
   encodeCredentials,
   decodeCredentials,
+  authenticationCredentials,
+  verifyAuthentication,
+  AuthenticationError,
+  type AuthenticationProblem,
   type Authentication,
+  type AuthenticationIdentity,
+  type AuthenticationContext,
+  type CallAuthentication,
 } from "./authentication.ts";
 export { checkSecretStore, type SecretStoreCheck } from "./secret-store-check.ts";
 
@@ -301,4 +309,8 @@ export {
   type ConnectionDefinition,
   type ConnectionRule,
   type ConnectionSnapshot,
+  type ConnectionCard,
+  type ConnectionHealth,
+  type ConnectionTarget,
+  type ConnectionSetup,
 } from "./connection.ts";

package/src/kms-secrets.ts

@@ -0,0 +1,271 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
+import type { protos } from "@google-cloud/kms";
+import crc32c from "crc-32/crc32c.js";
+import type { Db } from "./db.ts";
+import { SecretStoreError, type SecretAddress, type SecretStore, type SecretValue } from "./secret-store.ts";
+
+/** Install with a privileged connection; runtime needs only SELECT/INSERT/UPDATE/DELETE on its company database. */
+export const KMS_SECRETS_SQL = `
+CREATE SCHEMA IF NOT EXISTS sanoma_kms;
+REVOKE ALL ON SCHEMA sanoma_kms FROM PUBLIC;
+CREATE TABLE IF NOT EXISTS sanoma_kms.secrets (
+  company text NOT NULL, namespace text NOT NULL, path text NOT NULL,
+  version uuid NOT NULL, envelope jsonb NOT NULL,
+  updated_by text NOT NULL, updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (company, namespace, path)
+);
+REVOKE ALL ON sanoma_kms.secrets FROM PUBLIC;
+DO $revoke$
+DECLARE api_role text;
+BEGIN
+  FOREACH api_role IN ARRAY ARRAY['anon', 'authenticated', 'service_role'] LOOP
+    IF EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = api_role) THEN
+      EXECUTE format('REVOKE ALL ON SCHEMA sanoma_kms FROM %I', api_role);
+      EXECUTE format('REVOKE ALL ON sanoma_kms.secrets FROM %I', api_role);
+    END IF;
+  END LOOP;
+END;
+$revoke$;
+`;
+
+/** Promise interface implemented by Google's KeyManagementServiceClient. */
+export interface GcpKmsClient {
+  encrypt(
+    request: protos.google.cloud.kms.v1.IEncryptRequest,
+  ): Promise<[protos.google.cloud.kms.v1.IEncryptResponse, ...unknown[]]>;
+  decrypt(
+    request: protos.google.cloud.kms.v1.IDecryptRequest,
+  ): Promise<[protos.google.cloud.kms.v1.IDecryptResponse, ...unknown[]]>;
+}
+
+export interface KmsPostgresOptions {
+  /** Fixed by trusted deployment bootstrap. IAM must independently restrict the runtime to this company’s CryptoKeys. */
+  company: string;
+  /** Full GCP CryptoKey resource name for new writes, using its primary version. */
+  keyName: string;
+  /** Retained CryptoKey names allowed for reads during key replacement/backup recovery. */
+  decryptKeyNames?: readonly string[];
+  /** Explicit client under a company-scoped IAM identity, never fleet credentials. Caller owns its lifecycle. */
+  kms: GcpKmsClient;
+  /** Company-scoped database access. Caller owns connection lifecycle; never shared admin authority. */
+  database: () => Promise<Db>;
+}
+
+interface Envelope {
+  format: "sanoma-gcp-kms-v1";
+  key: string;
+  keyVersion: string;
+  wrapped: string;
+  nonce: string;
+  ciphertext: string;
+  tag: string;
+}
+interface Row {
+  version: string;
+  envelope: Envelope;
+  updated_by: string;
+  updated_at: Date;
+}
+const FORMAT = "sanoma-gcp-kms-v1";
+const MAX_BYTES = 65_536;
+const keyName =
+  /^projects\/[a-zA-Z0-9-]+\/locations\/[a-z0-9-]+\/keyRings\/[a-zA-Z0-9_-]+\/cryptoKeys\/[a-zA-Z0-9_-]+$/;
+const nonempty = (v: string) =>
+  typeof v === "string" && v.length > 0 && Buffer.byteLength(v, "utf8") <= 1024 && !v.includes("\0");
+const failed = (error: unknown): never => {
+  if (error instanceof SecretStoreError) throw error;
+  const code = (error as { code?: string | number } | null)?.code;
+  throw new SecretStoreError(
+    code === 7 || code === 16 || code === "42501"
+      ? "denied"
+      : code === 3
+        ? "invalid_value"
+        : code === 5 || code === 9 || code === "42P01"
+          ? "invalid_configuration"
+          : "unavailable",
+  );
+};
+const safe = async <T>(run: () => Promise<T>): Promise<T> => {
+  try {
+    return await run();
+  } catch (e) {
+    return failed(e);
+  }
+};
+const bytes = (v: string, length?: number, max = MAX_BYTES): Buffer => {
+  if (
+    typeof v !== "string" ||
+    v.length > Math.ceil((length ?? max) / 3) * 4 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(v)
+  )
+    throw new SecretStoreError("invalid_value");
+  const b = Buffer.from(v, "base64");
+  if (length !== undefined && b.length !== length) throw new SecretStoreError("invalid_value");
+  return b;
+};
+
+const versionOf = (name: unknown, key: string): name is string =>
+  typeof name === "string" &&
+  name.startsWith(`${key}/cryptoKeyVersions/`) &&
+  /^[1-9][0-9]{0,19}$/.test(name.slice(`${key}/cryptoKeyVersions/`.length));
+const checksum = (value: Uint8Array) => crc32c.buf(value) >>> 0;
+
+/** Versioned envelope encryption; no plaintext/data-key cache, no SANOMA_SECRETS_KEY and no Secrets Manager. */
+export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore {
+  const { company, keyName: writeKey, kms, database } = options;
+  const keys = new Set([writeKey, ...(options.decryptKeyNames ?? [])]);
+  if (!nonempty(company) || [...keys].some((k) => !nonempty(k) || !keyName.test(k)))
+    throw new SecretStoreError("invalid_configuration");
+  const context = (address: SecretAddress, version: string) => {
+    if (!nonempty(address.namespace) || !nonempty(address.path)) throw new SecretStoreError("invalid_configuration");
+    return { company, namespace: address.namespace, path: address.path, version, format: FORMAT };
+  };
+  const seal = async (address: SecretAddress, value: string, version: string): Promise<Envelope> => {
+    const bound = context(address, version);
+    const aad = Buffer.from(JSON.stringify(bound));
+    const dataKey = randomBytes(32);
+    try {
+      const [encrypted] = await kms.encrypt({
+        name: writeKey,
+        plaintext: dataKey,
+        plaintextCrc32c: { value: checksum(dataKey) },
+        additionalAuthenticatedData: aad,
+        additionalAuthenticatedDataCrc32c: { value: checksum(aad) },
+      });
+      const wrapped =
+        typeof encrypted.ciphertext === "string" ? bytes(encrypted.ciphertext, undefined, 6144) : encrypted.ciphertext;
+      if (
+        !versionOf(encrypted.name, writeKey) ||
+        !wrapped?.length ||
+        wrapped.length > 6144 ||
+        !encrypted.verifiedPlaintextCrc32c ||
+        !encrypted.verifiedAdditionalAuthenticatedDataCrc32c ||
+        Number(encrypted.ciphertextCrc32c?.value ?? NaN) !== checksum(wrapped)
+      )
+        throw new SecretStoreError("invalid_value");
+      const nonce = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", dataKey, nonce).setAAD(
+        Buffer.from(JSON.stringify({ ...bound, keyVersion: encrypted.name })),
+      );
+      const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+      return {
+        format: FORMAT,
+        key: writeKey,
+        keyVersion: encrypted.name,
+        wrapped: Buffer.from(wrapped).toString("base64"),
+        nonce: nonce.toString("base64"),
+        ciphertext: ciphertext.toString("base64"),
+        tag: cipher.getAuthTag().toString("base64"),
+      };
+    } finally {
+      dataKey.fill(0);
+    }
+  };
+  const open = async (address: SecretAddress, row: Row): Promise<SecretValue> => {
+    const e = row.envelope;
+    if (!e || e.format !== FORMAT || !keys.has(e.key) || !versionOf(e.keyVersion, e.key))
+      throw new SecretStoreError("invalid_value");
+    const nonce = bytes(e.nonce, 12),
+      tag = bytes(e.tag, 16),
+      ciphertext = bytes(e.ciphertext),
+      wrapped = bytes(e.wrapped, undefined, 6144);
+    if (ciphertext.length > MAX_BYTES || !wrapped.length || wrapped.length > 6144)
+      throw new SecretStoreError("invalid_value");
+    const bound = context(address, row.version);
+    const aad = Buffer.from(JSON.stringify(bound));
+    const [decrypted] = await kms.decrypt({
+      name: e.key,
+      ciphertext: wrapped,
+      ciphertextCrc32c: { value: checksum(wrapped) },
+      additionalAuthenticatedData: aad,
+      additionalAuthenticatedDataCrc32c: { value: checksum(aad) },
+    });
+    const dataKey = typeof decrypted.plaintext === "string" ? bytes(decrypted.plaintext, 32) : decrypted.plaintext;
+    try {
+      if (dataKey?.length !== 32 || Number(decrypted.plaintextCrc32c?.value ?? NaN) !== checksum(dataKey))
+        throw new SecretStoreError("invalid_value");
+      const decipher = createDecipheriv("aes-256-gcm", dataKey, nonce)
+        .setAAD(Buffer.from(JSON.stringify({ ...bound, keyVersion: e.keyVersion })))
+        .setAuthTag(tag);
+      let plaintext: Buffer;
+      try {
+        plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+      } catch {
+        throw new SecretStoreError("invalid_value");
+      }
+      try {
+        return {
+          value: plaintext.toString("utf8"),
+          version: row.version,
+          updatedBy: row.updated_by,
+          updatedAt: row.updated_at.toISOString(),
+        };
+      } finally {
+        plaintext.fill(0);
+      }
+    } finally {
+      dataKey?.fill(0);
+    }
+  };
+  return {
+    id: "kms-postgres",
+    capabilities: Object.freeze({
+      writable: true,
+      maxBytes: MAX_BYTES,
+      conditionalWrites: "atomic",
+      deletion: "destroy",
+      changeDetection: "read",
+    }),
+    validate: (namespace) =>
+      safe(async () => {
+        const address = { namespace, path: "__validation__" },
+          version = randomUUID();
+        const envelope = await seal(address, "validation", version);
+        await open(address, { envelope, version, updated_by: "validation", updated_at: new Date() });
+        await (await database()).query("SELECT version FROM sanoma_kms.secrets WHERE company=$1 LIMIT 0", [company]);
+        // Own-key usability only. Cross-company authorization requires live IAM proof with another existing key.
+      }),
+    read: (address) =>
+      safe(async () => {
+        context(address, "read");
+        const { rows } = await (
+          await database()
+        ).query<Row>(
+          "SELECT version,envelope,updated_by,updated_at FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3",
+          [company, address.namespace, address.path],
+        );
+        return rows[0] && open(address, rows[0]);
+      }),
+    write: (address, value, { expectedVersion, by }) =>
+      safe(async () => {
+        if (Buffer.byteLength(value, "utf8") > MAX_BYTES) throw new SecretStoreError("too_large");
+        if (!nonempty(by)) throw new SecretStoreError("invalid_value");
+        const version = randomUUID(),
+          envelope = await seal(address, value, version);
+        const args = [company, address.namespace, address.path, version, JSON.stringify(envelope), by];
+        const sql =
+          expectedVersion === null
+            ? "INSERT INTO sanoma_kms.secrets(company,namespace,path,version,envelope,updated_by) VALUES($1,$2,$3,$4,$5,$6) ON CONFLICT(company,namespace,path) DO NOTHING RETURNING version,envelope,updated_by,updated_at"
+            : "UPDATE sanoma_kms.secrets SET version=$4,envelope=$5,updated_by=$6,updated_at=now() WHERE company=$1 AND namespace=$2 AND path=$3 AND version::text=$7 RETURNING version,envelope,updated_by,updated_at";
+        const { rows } = await (
+          await database()
+        ).query<Row>(sql, expectedVersion === null ? args : [...args, expectedVersion]);
+        if (!rows[0]) throw new SecretStoreError("conflict");
+        // Return the caller's value, never make a second decrypt after a successful commit.
+        return { value, version, updatedBy: by, updatedAt: rows[0].updated_at.toISOString() };
+      }),
+    delete: (address, { expectedVersion }) =>
+      safe(async () => {
+        context(address, expectedVersion);
+        const { rowCount } = await (
+          await database()
+        ).query("DELETE FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version::text=$4", [
+          company,
+          address.namespace,
+          address.path,
+          expectedVersion,
+        ]);
+        if (!rowCount) throw new SecretStoreError("conflict");
+      }),
+  };
+}

package/src/lint.ts

@@ -28,7 +28,7 @@ const ALLOWED_PACKAGE = new RegExp(`^(${[...AUTHOR_PACKAGES, "@sanoma-ai/connect
 const REFUSED_PACKAGES: [RegExp, string][] = [
   [/^@sanoma-ai\/testing(\/|$)/, `fakes and test helpers belong in tests; ${THROUGH_CTX}`],
   [/^@sanoma-ai\/app(\/|$)/, "the app starts runs and decides approvals, so a workflow could approve itself"],
-  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver|remote)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
+  [/^@sanoma-ai\/connector-[^/]+\/(fake|driver|remote|vault)(\/|$)/, `${THROUGH_CTX}; import the connector itself`],
   [/^sanoma\//, "`sanoma` has no entry points for a workflow: import its names from `sanoma` itself"],
 ];
 

package/src/load.ts

@@ -1,4 +1,4 @@
-import { readFileSync, realpathSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { createRequire, registerHooks } from "node:module";
 import { dirname, isAbsolute, join, relative, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
@@ -254,20 +254,47 @@ function placeOf(gen: Generation, error: unknown): { file: string; line?: number
   return undefined;
 }
 
+/**
+ * Each company file under `root` a load has read, and each one's folder, with its stamp
+ * (`stampOf`) as it was before the file was read: the latest generation's for a file several
+ * read. Taken after a load, it still says what the load read, so a file changed while it read is
+ * found changed after.
+ */
+export function stampsOf(root: string): Map<string, string> {
+  const stamps = new Map<string, string>();
+  if (!existsSync(root)) return stamps;
+  const real = realpathSync(root);
+  // In the order made: a later generation's stamp is the newer.
+  for (const gen of registry.generations.values()) {
+    if (gen.root === real) for (const [path, stamp] of gen.stamps) stamps.set(path, stamp);
+  }
+  return stamps;
+}
+
 const byOrder = <T extends string | number>(a: T, b: T) => (a < b ? -1 : a > b ? 1 : 0);
 
-/** A file's size and modification time, or that it is gone. */
-function stampOf(path: string): string {
+/** A file's size and modification time, or that it is gone: what a generation keeps of each file it read. */
+export function stampOf(path: string): string {
   const stat = statSync(path, { bigint: true, throwIfNoEntry: false });
   return stat ? `${stat.size} ${stat.mtimeNs}` : "gone";
 }
 
+/** True while each path's stamp (`stampOf`) is still the one kept. */
+export function fresh(stamps: ReadonlyMap<string, string>): boolean {
+  for (const [path, stamp] of stamps) if (stampOf(path) !== stamp) return false;
+  return true;
+}
+
 /** Records a file of the generation, and its directory, as they are now: before it is read, so an edit after is seen. */
 function touch(gen: Generation, file: string) {
   for (const path of [file, dirname(file)]) if (!gen.stamps.has(path)) gen.stamps.set(path, stampOf(path));
 }
 
-/** The generation of `root` and these constructors: the current one while nothing it stamped changed, else a new one. */
+/**
+ * The generation of `root` and these constructors: the current one while nothing it stamped
+ * changed, else a new one. A generation of `root` whose files changed goes, whatever its
+ * constructors, so `stampsOf` never keeps the stamps of one no load will make again.
+ */
 function generationOf(
   root: string,
   connectors: readonly Connector<any, any>[],
@@ -278,11 +305,13 @@ function generationOf(
     return info?.package ? [`${info.package}/resources`, id] : [];
   });
   const typesKey = [...packages, ...[...types.values()].map(idOf)].join(" ");
+  let current: Generation | undefined;
   for (const gen of registry.generations.values()) {
-    if (gen.root !== root || gen.typesKey !== typesKey) continue;
-    if ([...gen.stamps].every(([path, stamp]) => stampOf(path) === stamp)) return gen;
-    registry.generations.delete(gen.id);
+    if (gen.root !== root) continue;
+    if (!fresh(gen.stamps)) registry.generations.delete(gen.id);
+    else if (gen.typesKey === typesKey) current = gen;
   }
+  if (current !== undefined) return current;
   const gen: Generation = {
     id: String(++registry.seq),
     root,

package/src/op.ts

@@ -1,5 +1,5 @@
 import type { Principal } from "./define.ts";
-import type { Authentication } from "./authentication.ts";
+import type { Authentication, CallAuthentication } from "./authentication.ts";
 import type { ConnectionSnapshot } from "./connection.ts";
 import type { ProviderV4 } from "@ai-sdk/provider";
 import type { z } from "zod";
@@ -41,6 +41,8 @@ export interface OpSpec<I extends z.ZodType = z.ZodType, O extends z.ZodType = z
    * (a resource type's `handle`): the ledger records each as `"<name>"`, never its value.
    */
   opaque?: readonly string[];
+  /** Logical destinations this operation may create with Secrets.ensure, derived from its authorized input. */
+  createsSecrets?: (input: any) => readonly string[];
 }
 
 /** One vendor operation, such as `ghost.post.publish`. Declares the contract only; drivers implement it. */
@@ -59,6 +61,7 @@ export interface Op<V extends string = string, R extends string = string, N exte
   readonly phrases?: { readonly given?: string; readonly expect?: string };
   /** From the spec: fields the ledger records by name only. */
   readonly opaque?: readonly string[];
+  readonly createsSecrets?: (input: any) => readonly string[];
   readonly input: z.ZodType<any, I>;
   readonly output: z.ZodType<O>;
 }
@@ -111,7 +114,7 @@ export type Connector<V extends string, S extends Specs> = {
  * and `resolveConfig` reads only a record of its own shape (`checkConnector`): change it with
  * the record, so a build refuses a connector another build made in another shape.
  */
-export const CONNECTOR_FORMAT = 2;
+export const CONNECTOR_FORMAT = 3;
 
 /**
  * A connector's vendor: its id, who it is (`defineConnector`'s third argument, for a UI), its
@@ -212,6 +215,7 @@ export function defineConnector<const V extends string, const S extends Specs>(
         target: spec.target,
         phrases: spec.phrases,
         ...(spec.opaque?.length ? { opaque: spec.opaque } : {}),
+        ...(spec.createsSecrets && { createsSecrets: spec.createsSecrets }),
         input: spec.input,
         output: spec.output,
       } satisfies Op);
@@ -243,6 +247,8 @@ export interface CallContext {
   principal?: Principal;
   /** Authorized account metadata. Credential material stays inside the driver boundary. */
   connection?: ConnectionSnapshot;
+  /** Resolved after policy, for this call alone. Never return it from a driver. */
+  authentication?: CallAuthentication;
   idempotencyKey: string;
   runId: string;
   opId: string;
@@ -302,13 +308,15 @@ export function retryableStatus(status: number): boolean {
 export type DriverEnv = z.ZodObject<Record<string, z.ZodType<string | undefined, string | undefined>>>;
 
 /**
- * Implements a vendor's operations, keyed `"resource.name"`. A driver reads its credentials
- * from the environment when it is called, never from the config file; `env` declares them.
+ * Implements a vendor's operations, keyed `"resource.name"`. Named authentication is supplied
+ * in the call context. `env` describes a driver that has not added named-account support.
  */
 export interface Driver {
   readonly vendor: string;
   readonly ops: Readonly<Record<string, DriverFn>>;
   readonly env?: DriverEnv;
+  /** Methods this driver consumes from CallContext.authentication. Others fail closed. */
+  readonly authentication?: readonly string[];
 }
 
 /**
@@ -322,7 +330,7 @@ export interface Driver {
 export interface ConnectorSetup {
   /** Auth methods available to named connections; login identity is separate. */
   authentication?: Readonly<Record<string, Authentication>>;
-  /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
+  /** Makes the live driver once per resolved config; credentials belong to each invocation. */
   driver?: () => Driver;
   /** Makes a fake of the vendor (`defineFake`): once per sandbox run, its own. */
   fake?: () => Fake<any, any>;
@@ -466,8 +474,8 @@ export type OpIdOf<V extends string, S extends Specs> = {
  */
 export function defineDriver<V extends string, S extends Specs>(
   connector: Connector<V, S>,
-  impl: DriverImpl<S>,
-  options: { env?: DriverEnv } = {},
+  impl: DriverImpl<S> | ((call: CallContext) => DriverImpl<S>),
+  options: { env?: DriverEnv; authentication?: readonly string[] } = {},
 ): Driver {
   const declared = new Map<string, Op>();
   for (const resource of Object.values(connector as Record<string, Record<string, unknown>>)) {
@@ -475,6 +483,18 @@ export function defineDriver<V extends string, S extends Specs>(
   }
   const vendor = connector[VENDOR].id;
   const ops: Record<string, DriverFn> = {};
+  if (typeof impl === "function") {
+    // Build clients only once the runtime has authorized and authenticated this invocation.
+    for (const key of declared.keys()) {
+      ops[key] = async (input, call) => defineDriver(connector, impl(call), options).ops[key]!(input, call);
+    }
+    return Object.freeze({
+      vendor,
+      ops: Object.freeze(ops),
+      ...(options.env && { env: options.env }),
+      ...(options.authentication && { authentication: Object.freeze([...options.authentication]) }),
+    });
+  }
   const extra: string[] = [];
   for (const [resource, fns] of Object.entries(impl as Record<string, Record<string, unknown>>)) {
     for (const [name, fn] of Object.entries(fns ?? {})) {
@@ -489,5 +509,10 @@ export function defineDriver<V extends string, S extends Specs>(
     ...(extra.length ? [`it implements ${extra.join(", ")}, which the connector does not declare`] : []),
   ];
   if (problems.length) throw new Error(`defineDriver("${vendor}"): ${problems.join("; ")}`);
-  return Object.freeze({ vendor, ops: Object.freeze(ops), ...(options.env && { env: options.env }) });
+  return Object.freeze({
+    vendor,
+    ops: Object.freeze(ops),
+    ...(options.env && { env: options.env }),
+    ...(options.authentication && { authentication: Object.freeze([...options.authentication]) }),
+  });
 }

package/src/outline.ts

@@ -44,7 +44,7 @@ export type OutlineNode = { path: string; span: Span } &
    */
   /** `name`: the one the call gives (`ctx.x.y.z(input, { name: "…" })`), else the id when no segment is computed. */
   (
-    | { kind: "op"; id: string; ops?: string[]; name?: string }
+    | { kind: "op"; id: string; ops?: string[]; name?: string; connection?: { id: string } | { dynamic: true } }
     /**
      * `ctx.approval(...)`, with its title, and the title as its `name`, when the first argument is
      * a string literal or a top-level `const` holding one.
@@ -417,6 +417,31 @@ export function outlineBody(
     return undefined;
   };
 
+  // Dependency information only. Execution still resolves and authorizes the actual reference.
+  // An imported/computed reference stays unknown rather than being guessed from its variable name.
+  const connectionIn = (options: Node | undefined): { id: string } | { dynamic: true } | undefined => {
+    if (!options) return undefined;
+    const object = options && unwrap(options);
+    if (object?.type !== "ObjectExpression") return { dynamic: true };
+    if (object.properties.some((p: Node) => p.type !== "Property" || p.computed)) return { dynamic: true };
+    const property =
+      object?.type === "ObjectExpression" &&
+      object.properties.findLast(
+        (p: Node) => p.type === "Property" && !p.computed && (p.key.name ?? p.key.value) === "connection",
+      );
+    if (!property) return undefined;
+    const ref = unwrap(property.value);
+    if (ref?.type !== "ObjectExpression") return { dynamic: true };
+    if (ref.properties.some((p: Node) => p.type !== "Property" || p.computed)) return { dynamic: true };
+    const key =
+      ref?.type === "ObjectExpression" &&
+      ref.properties.findLast(
+        (p: Node) => p.type === "Property" && !p.computed && (p.key.name ?? p.key.value) === "$connection",
+      );
+    const id = key && literalOf(key.value, consts);
+    return typeof id === "string" ? { id } : { dynamic: true };
+  };
+
   // The arguments are evaluated before the call is made, so their calls come first.
   const call = (node: Node, at: Where): OutlineNode[] => {
     const args: Node[] = node.arguments;
@@ -442,9 +467,17 @@ export function outlineBody(
           if (isOpPath(members)) {
             // A computed id's own name is the operation it calls, known only in a run.
             const name = nameIn(args[1], true) ?? (id.includes("*") ? undefined : id);
+            const connection = connectionIn(args[1]);
             return [
               ...walk(args, at),
-              { kind: "op", path, id, span: span(node), ...(name === undefined ? {} : { name }) },
+              {
+                kind: "op",
+                path,
+                id,
+                span: span(node),
+                ...(name === undefined ? {} : { name }),
+                ...(connection && { connection }),
+              },
             ];
           }
           return READS.has(id) ? walk(args, at) : [...walk(args, at), ...problem(node, CTX_CALL(id))];