@sanoma-ai/workflows 0.10.0 → 0.10.1

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,13 @@ export {
   checkAuthenticationStore,
   encodeCredentials,
   decodeCredentials,
+  authenticationCredentials,
+  verifyAuthentication,
+  AuthenticationError,
+  type AuthenticationProblem,
   type Authentication,
+  type AuthenticationIdentity,
+  type CallAuthentication,
 } from "./authentication.ts";
 export { checkSecretStore, type SecretStoreCheck } from "./secret-store-check.ts";
 
@@ -301,4 +308,8 @@ export {
   type ConnectionDefinition,
   type ConnectionRule,
   type ConnectionSnapshot,
+  type ConnectionCard,
+  type ConnectionHealth,
+  type ConnectionTarget,
+  type ConnectionSetup,
 } from "./connection.ts";

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))];

package/src/paths.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
-import { APP_NAME } from "./shared.ts";
+import { APP_NAME, APPS_DIR, appOfPath } from "./shared.ts";
 
 // Where an import may reach, as the lints and the data-file reader all decide it, the one walk up
 // the directories and the one walk down (`filesUnder`). Node's `path` and `fs` only, no parser:
@@ -65,8 +65,7 @@ export function filesUnder(dir: string, keep: (name: string) => boolean): string
     .toSorted();
 }
 
-/** Where a company's apps are, under its root: `apps/<app>/`. */
-export const APPS_DIR = "apps";
+export { APPS_DIR, appOfPath };
 
 /** Each directory's company root (the nearest one with a `sanoma.config.ts`, short of a `node_modules`), once found. */
 const roots = new Map<string, string>();
@@ -98,12 +97,6 @@ export function appOfFile(file: string | undefined): string | undefined {
   return root === null ? undefined : appOfPath(relPath(root, file));
 }
 
-/** The app a path relative to a company's root is in: `<app>` under `apps/<app>/`; undefined for any other. */
-export function appOfPath(rel: string): string | undefined {
-  const [top, app, ...rest] = rel.split("/");
-  return top === APPS_DIR && app !== undefined && rest.length && APP_NAME.test(app) ? app : undefined;
-}
-
 /** The apps' folders under `root` whose names are an `APP_NAME`, sorted: `apps/<app>/`, absolute. */
 export function appFolders(root: string): string[] {
   const dir = join(root, APPS_DIR);

package/src/run.ts

@@ -1,4 +1,4 @@
-import type { ConnectionRegistry } from "./connection.ts";
+import type { ConnectionRef, ConnectionRegistry, ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Collection } from "./collection.ts";
 import type { DeadlineRegistry } from "./deadlines.ts";
@@ -98,6 +98,8 @@ export interface Run {
   fakeDrivers?: Map<string, DriverFn>;
   /** A sandbox run's own secrets, in memory, from `seedSandbox`; unset for a live run. */
   fakeSecrets?: Secrets;
+  /** Synthetic, run-local identities; this resolver never reads production connection records. */
+  fakeConnection?: (vendor: string, ref?: ConnectionRef) => ConnectionSnapshot | undefined;
   approvals: ApprovalState[];
   /** The next ledger `seq`. Advanced only outside steps, so a replay counts the same way. */
   seq: number;

package/src/sandbox.ts

@@ -3,7 +3,8 @@ import { indexDrivers, sandboxDrivers } from "./config.ts";
 import { CALL_WORKFLOW, CallInput } from "./call-workflow.ts";
 import { opIdsOf } from "./define.ts";
 import { SanomaError } from "./errors.ts";
-import type { Fake, ResourceFake } from "./fake.ts";
+import { connectionFakes, type Fake, type ResourceFake } from "./fake.ts";
+import type { ConnectionCatalog, ConnectionRef, ConnectionSnapshot } from "./connection.ts";
 import { entry, type LedgerRecord, write } from "./ledger.ts";
 import type { DriverFn } from "./op.ts";
 import type { Run } from "./run.ts";
@@ -20,6 +21,30 @@ import { errorMessage } from "./shared.ts";
 const holdsResources = (fake: Fake<unknown>): fake is Fake<unknown> & ResourceFake =>
   "override" in fake && "put" in fake && "remove" in fake;
 
+/** Declared accounts get synthetic identities in each run; no production metadata or secrets are read. */
+export function sandboxConnection(catalog: ConnectionCatalog, runId: string) {
+  return (vendor: string, ref?: ConnectionRef): ConnectionSnapshot | undefined => {
+    const definitions = [...catalog.definitions.values()].filter((d) => d.vendor === vendor);
+    const selected = ref ?? definitions.find((d) => d.default);
+    if (!selected && !Object.keys(catalog.methods.get(vendor) ?? {}).length) return undefined;
+    const definition = selected && catalog.definitions.get(selected.$connection);
+    if (!definition || selected?.vendor !== vendor || definition.vendor !== vendor)
+      throw new SanomaError("invalid_input", "Select an explicitly declared sandbox connection");
+    const revision = `sandbox:${runId}:${definition.$connection}`;
+    if (selected.revision !== undefined && selected.revision !== revision)
+      throw new SanomaError("invalid_input", "A sandbox cannot use a production connection revision");
+    return {
+      id: definition.$connection,
+      vendor,
+      method: definition.method,
+      account: definition.account ?? `fake:${definition.$connection}`,
+      scopes: [...definition.scopes],
+      revision,
+      definition: revision,
+    };
+  };
+}
+
 /**
  * The error a sandbox run of the scenario fails with when it seeds a resource of a vendor whose
  * fake (one of `fakes`, by vendor) holds none, or whose connector attaches no fake; undefined
@@ -110,10 +135,18 @@ export async function seedSandbox(run: Run, name: string, input: unknown): Promi
         });
       }
       const fakes = new Map([...state.fakes].map(([vendor, make]) => [vendor, make()]));
+      const named = new Map(
+        [...state.fakes]
+          .filter(([vendor]) => Object.keys(state.connections!.catalog.methods.get(vendor) ?? {}).length)
+          .map(([vendor, make]) => [vendor, connectionFakes(make)]),
+      );
+      const select = sandboxConnection(state.connections!.catalog, run.id);
+      run.fakeConnection = select;
       // The built-ins first, so a connector's fake that implements one of their operations wins.
       const drivers = indexDrivers(
-        [...sandboxDrivers(state.ops), ...Array.from(fakes.values(), (f) => f.driver)],
+        [...sandboxDrivers(state.ops), ...Array.from(fakes, ([vendor, f]) => named.get(vendor)?.driver ?? f.driver)],
         state.ops,
+        { sandbox: true },
       );
       // The built-in call workflow selects exactly one operation. Other direct operations
       // (including live connection mutations) need no fake unless this scenario calls them.
@@ -134,16 +167,33 @@ export async function seedSandbox(run: Run, name: string, input: unknown): Promi
       for (const [i, given] of scenario.given.entries()) {
         if ("fault" in given) continue;
         if ("op" in given) {
-          const call = { idempotencyKey: `${run.id}:seed:${i}`, runId: run.id, opId: given.op, attempt: 1, secrets };
+          const connection = select(state.ops.get(given.op)!.vendor, given.connection);
+          const call = {
+            idempotencyKey: `${run.id}:seed:${i}`,
+            runId: run.id,
+            opId: given.op,
+            attempt: 1,
+            secrets,
+            connection,
+          };
           const output = await drivers.get(given.op)!(given.input, call);
           seeded.push({ op: given.op, input: given.input, output });
           continue;
         }
         // Checked above: the vendor's fake holds resources.
-        seeded.push(seedResource(name, fakes.get(given.vendor) as Fake<unknown> & ResourceFake, given));
+        const selected = select(given.vendor, given.connection);
+        const fake = selected
+          ? named.get(given.vendor)!.account({ vendor: given.vendor, $connection: selected.id })
+          : fakes.get(given.vendor)!;
+        seeded.push(seedResource(name, fake as Fake<unknown> & ResourceFake, given));
       }
       for (const given of scenario.given) {
-        if ("fault" in given) fakes.get(state.ops.get(given.op)!.vendor)![given.fault](given.op);
+        if ("fault" in given) {
+          const vendor = state.ops.get(given.op)!.vendor;
+          const selected = select(vendor, given.connection);
+          const fake = selected ? named.get(vendor)!.account({ vendor, $connection: selected.id }) : fakes.get(vendor)!;
+          fake[given.fault](given.op);
+        }
       }
       copies = drivers;
       return { seeds: seeded };

package/src/scenario.ts

@@ -29,6 +29,7 @@ import {
 import { errorCode, errorInfo, SanomaError } from "./errors.ts";
 import { type CallRecord, contains, type CoreExpectation, detailOf, isCall } from "./expectations.ts";
 import type { Fake } from "./fake.ts";
+import type { ConnectionRef } from "./connection.ts";
 import { fill, isBug, objectUnder, restOf, seedFrom, shapeOf } from "./fill.ts";
 import type { LedgerRecord } from "./ledger.ts";
 import type { Driver, Op } from "./op.ts";
@@ -92,10 +93,26 @@ export interface ScenarioStep {
  * its import id, with `fields` to set on it (put, when the vendor has none) or `gone` to remove it.
  */
 export type Given =
-  | { step: string; op: string; input: unknown; as?: string }
-  | { step: string; op: string; fault: Fault }
-  | { step: string; resource: string; vendor: string; type: string; name: string; fields: Record<string, unknown> }
-  | { step: string; resource: string; vendor: string; type: string; name: string; gone: true };
+  | { step: string; op: string; input: unknown; as?: string; connection?: ConnectionRef }
+  | { step: string; op: string; fault: Fault; connection?: ConnectionRef }
+  | {
+      step: string;
+      resource: string;
+      vendor: string;
+      type: string;
+      name: string;
+      fields: Record<string, unknown>;
+      connection?: ConnectionRef;
+    }
+  | {
+      step: string;
+      resource: string;
+      vendor: string;
+      type: string;
+      name: string;
+      gone: true;
+      connection?: ConnectionRef;
+    };
 
 /** How one approval is decided; `approval` is its title or its id. */
 export interface Decision {
@@ -671,7 +688,8 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
           read: (values) => {
             const seed = def.fn(...values);
             const op = opNamed(seed.op);
-            if ("fault" in seed) return [{ op, fault: seed.fault }];
+            const connection = seed.connection && { connection: seed.connection };
+            if ("fault" in seed) return [{ op, fault: seed.fault, ...connection }];
             let input: unknown;
             try {
               input = fill(opOf(op).input, seed.input);
@@ -681,7 +699,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
                 cause: err,
               });
             }
-            return [{ op, input, ...(seed.as === undefined ? {} : { as: seed.as }) }];
+            return [{ op, input, ...(seed.as === undefined ? {} : { as: seed.as }), ...connection }];
           },
         });
         continue;

package/src/secret.ts

@@ -46,6 +46,35 @@ export interface Secrets {
   ensure(name: string, make: () => string): Promise<string>;
 }
 
+/** A named call can resolve only the auxiliary secret markers present in its authorized input. */
+export function secretsForInput(input: unknown, secrets: Secrets, creates: readonly string[] = []): Secrets {
+  const allowed = new Map<string, boolean>();
+  for (const name of creates) {
+    if (!SECRET_NAME.test(name)) throw new DriverError("Invalid operation secret destination", { retryable: false });
+    allowed.set(name, true);
+  }
+  const visit = (value: unknown) => {
+    if (isSecret(value)) allowed.set(value.$secret, allowed.get(value.$secret) === true || value.generate === true);
+    else if (Array.isArray(value)) value.forEach(visit);
+    else if (value && typeof value === "object") Object.values(value).forEach(visit);
+  };
+  visit(input);
+  const check = (name: string, generate: boolean) => {
+    if (!allowed.has(name) || (generate && !allowed.get(name)))
+      throw new DriverError("The call does not authorize this secret access", { retryable: false });
+  };
+  return {
+    async get(name) {
+      check(name, false);
+      return secrets.get(name);
+    },
+    async ensure(name, make) {
+      check(name, true);
+      return secrets.ensure(name, make);
+    },
+  };
+}
+
 /** A value for a secret with `generate`: 32 random bytes, base64url. */
 export const generateSecret = (): string => randomBytes(32).toString("base64url");
 

package/src/shared.ts

@@ -89,6 +89,15 @@ export const SITE_NAME = /^[a-z][a-z0-9-]*$/;
  */
 export const APP_NAME = /^[a-z][a-z0-9]*$/;
 
+/** Where a company's apps are, under its root: `apps/<app>/`. */
+export const APPS_DIR = "apps";
+
+/** The app a path relative to a company's root is in: `<app>` under `apps/<app>/`; undefined for any other. */
+export function appOfPath(rel: string): string | undefined {
+  const [top, app, ...rest] = rel.split("/");
+  return top === APPS_DIR && app !== undefined && rest.length && APP_NAME.test(app) ? app : undefined;
+}
+
 /** A name declared under `apps/<app>/` as the runtime has it, `<app>.<name>`; one declared at the root as it is. */
 export const qualified = (app: string | undefined, name: string): string =>
   app === undefined ? name : `${app}.${name}`;