@sanoma-ai/workflows 0.9.1 → 0.10.0

package/src/apply.ts

@@ -1,3 +1,4 @@
+import type { ConnectionRef } from "./connection.ts";
 import { z } from "zod";
 import { type Approver, defineWorkflow, type WorkflowDefinition } from "./define.ts";
 import {
@@ -63,7 +64,7 @@ export type ApplyInput = z.infer<typeof ApplyInput>;
  * object its identity `found` or the input `given`, ask about a `gone` object or an `orphan`ed
  * binding (unless `answer`ed), or `none`.
  */
-export type PlanStep = { id: string; vendor: string; type: string } & (
+export type PlanStep = { id: string; vendor: string; type: string; connection?: ConnectionRef } & (
   | { action: "create"; planned: Record<string, unknown>; unknown: string[] }
   | { action: "update" | "replace"; binding: string; fields: DriftField[]; replace: string[] }
   | { action: "bind"; binding: string; source: "found" | "given" }
@@ -114,6 +115,7 @@ export interface ApplyDeclared extends DriftDeclared {
 export interface PlannedCall {
   op: string;
   input: unknown;
+  connection?: ConnectionRef;
 }
 
 /** What apply does that is no vendor call, each a step of its own (`apply-steps.ts`). */
@@ -155,7 +157,7 @@ type DeleteOp = Op<string, string, "delete", { id: string }, { id: string; gone:
 type ApplyUse = ImportOp | PlanOp | CreateOp | UpdateOp | DeleteOp | ResolveOp | "approval" | "sleep";
 
 /** An operation as `ctx` gives it, called by its id. */
-type Call = (input: unknown) => Promise<unknown>;
+type Call = (input: unknown, options?: { connection?: ConnectionRef }) => Promise<unknown>;
 
 /** What a step's resource is called in a problem: its file, and its export. */
 const problemOf = (id: string, message: string): ResourceProblem => ({
@@ -369,13 +371,24 @@ function writesOf(
       const made = { id: `new:${at}`, export: exportOf(keyOf(step)) };
       const after = (types.get(at)?.afterCreate ?? [])
         .filter((hook) => ops.get(hook.op)?.effect === "write")
-        .map((hook) => ({ op: hook.op, input: hook.input(made) }));
-      return [{ op: `${at}.create`, input: { desired: desired.get(step.id) } }, ...after];
+        .map((hook) => ({
+          op: hook.op,
+          input: hook.input(made),
+          ...(hook.op.startsWith(`${step.vendor}.`) && step.connection && { connection: step.connection }),
+        }));
+      return [{ op: `${at}.create`, connection: step.connection, input: { desired: desired.get(step.id) } }, ...after];
     }
-    if (run === "delete" && "binding" in step) return [{ op: `${at}.delete`, input: { id: step.binding } }];
+    if (run === "delete" && "binding" in step)
+      return [{ op: `${at}.delete`, connection: step.connection, input: { id: step.binding } }];
     if (run !== "update" || (step.action !== "update" && step.action !== "replace")) return [];
     const expect = { action: step.action, replace: step.replace };
-    return [{ op: `${at}.update`, input: { id: step.binding, desired: desired.get(step.id), expect } }];
+    return [
+      {
+        op: `${at}.update`,
+        connection: step.connection,
+        input: { id: step.binding, desired: desired.get(step.id), expect },
+      },
+    ];
   });
 }
 
@@ -474,7 +487,12 @@ export function applyWorkflow(
         if (!("id" in by)) found.set(resource.id, by);
         else {
           try {
-            found.set(resource.id, observed(await ctx[resource.vendor]![resource.type]!.import({ id: by.id })));
+            found.set(
+              resource.id,
+              observed(
+                await ctx[resource.vendor]![resource.type]!.import({ id: by.id }, { connection: resource.connection }),
+              ),
+            );
           } catch (err) {
             if (isRunControlError(err)) throw err;
             found.set(resource.id, { error: errorMessage(err) });
@@ -529,7 +547,11 @@ export function applyWorkflow(
             : decide(resource, result, found.get(resource.id)!, input, desired.get(resource.id)!, types, usable);
         if (next.ask !== undefined) {
           try {
-            const answer = fromPlan(resource, result, await ctx[resource.vendor]![resource.type]!.plan(next.ask));
+            const answer = fromPlan(
+              resource,
+              result,
+              await ctx[resource.vendor]![resource.type]!.plan(next.ask, { connection: resource.connection }),
+            );
             if (answer.step) planned.push(answer.step);
             if (answer.problem) problems.push(answer.problem);
           } catch (err) {
@@ -547,6 +569,8 @@ export function applyWorkflow(
         steps: [...planned, ...orphaned.steps],
       };
 
+      for (const step of plan.steps)
+        step.connection = declarations.get(step.id)?.connection ?? locked[keyOf(step)]?.connection;
       const writes = writesOf(plan, desired, types, ops);
       const approver = writes.length ? await steps.holds(writes) : undefined;
       if (approver !== undefined) {
@@ -569,24 +593,31 @@ export function applyWorkflow(
         let state: State | undefined;
         try {
           if (todo === "create") {
-            const made = await ctx[step.vendor]![step.type]!.create({
-              desired: desiredOf(declared!, types, bindings, hosts, urls),
-            });
-            bindings[key] = { type, id: made.id };
+            const made = await ctx[step.vendor]![step.type]!.create(
+              {
+                desired: desiredOf(declared!, types, bindings, hosts, urls),
+              },
+              { connection: step.connection },
+            );
+            bindings[key] = { type, id: made.id, ...(step.connection && { connection: step.connection }) };
             state = made.state;
           } else if (todo === "update" && (step.action === "update" || step.action === "replace")) {
             const expect = { action: step.action, replace: step.replace };
-            const changed = await ctx[step.vendor]![step.type]!.update({
-              id: binding,
-              desired: desiredOf(declared!, types, bindings, hosts, urls),
-              expect,
-            });
-            bindings[key] = { type, id: changed.id };
+            const changed = await ctx[step.vendor]![step.type]!.update(
+              {
+                id: binding,
+                desired: desiredOf(declared!, types, bindings, hosts, urls),
+                expect,
+              },
+              { connection: step.connection },
+            );
+            bindings[key] = { type, id: changed.id, ...(step.connection && { connection: step.connection }) };
             state = changed.state;
           } else if (todo === "delete") {
-            await ctx[step.vendor]![step.type]!.delete({ id: binding });
+            await ctx[step.vendor]![step.type]!.delete({ id: binding }, { connection: step.connection });
             delete bindings[key];
-          } else if (todo === "bind") bindings[key] = { type, id: binding };
+          } else if (todo === "bind")
+            bindings[key] = { type, id: binding, ...(step.connection && { connection: step.connection }) };
           else if (todo === "forget") delete bindings[key];
           if (state && declared) answersAt(declared, state);
           const after = bindings[key];
@@ -615,7 +646,9 @@ export function applyWorkflow(
               ) {
                 if (call > 0) await ctx.sleep({ seconds: AFTER_CREATE_SECONDS });
                 try {
-                  output = await (ctx[vendor]![group] as unknown as Record<string, Call>)[name]!(given);
+                  output = await (ctx[vendor]![group] as unknown as Record<string, Call>)[name]!(given, {
+                    connection: vendor === step.vendor ? step.connection : undefined,
+                  });
                   failed = undefined;
                 } catch (err) {
                   if (isRunControlError(err) || !hook.until) throw err;

package/src/approvals.ts

@@ -82,6 +82,7 @@ export interface HeldCall {
   op: string;
   seq?: number;
   input: unknown;
+  connection?: string;
   reasons?: string[] | undefined;
 }
 
@@ -109,7 +110,12 @@ export async function awaitApproval(
     ...(req.details === undefined ? {} : { details: req.details }),
     requestedBy: held ? "policy" : "workflow",
     covers,
-    ...(held && { op: held.op, ...heldOf(held), input: held.input }),
+    ...(held && {
+      op: held.op,
+      ...heldOf(held),
+      input: held.input,
+      ...(held.connection && { connection: held.connection }),
+    }),
     status: "pending",
     requestedAt: 0,
     refused: [],

package/src/apps.ts

@@ -1,9 +1,12 @@
 import { existsSync, readdirSync } from "node:fs";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { childrenOf, type LintProblem, type Node, readSource } from "./ast.ts";
-import { keyName } from "./datafile.ts";
-import { stringValue, unwrap } from "./outline.ts";
-import { APPS_DIR, filesUnder, inside, isDirectory, RELATIVE } from "./paths.ts";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+import { childrenOf, type Node, readSource } from "./ast.ts";
+import type { AppEntry } from "./description.ts";
+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";
 
 // A company's apps: each folder of `apps/` holds the kinds the root does (workflows, resources,
@@ -11,108 +14,74 @@ import { APP_NAME } from "./shared.ts";
 // made here. What a folder declares is named with the folder (`qualified`): never written, read
 // from where the declaration's file is (`appOfFile`).
 
-/** An app: a folder of `apps/`, by its name, and the source repository its `app.ts` names. */
-export interface AppEntry {
-  /** The folder's name, which prefixes what it declares (`crm.contacts`) and is the app's title. */
-  name: string;
-  /** The folder, relative to the root, with `/`: `apps/crm`. */
-  dir: string;
-  /** `defineApp({ source })` in its `app.ts`: the repository it was taken from; absent for the company's own app. */
-  source?: string;
-}
-
-/** What `app.ts` declares: the source repository's URL, when the app was taken from one. */
-export interface AppDefinition {
-  source?: string;
-}
-
-/**
- * Declares an app in its folder's `app.ts`, read without running it: `defineApp({ source:
- * "https://github.com/acme/crm" })`, the repository it was taken from; `defineApp({})` for an app
- * the company made itself.
- */
-export function defineApp(definition: AppDefinition): AppDefinition {
-  return Object.freeze({ ...definition });
-}
+export type { AppEntry };
 
 /** What is wrong with a company's apps, at a file relative to the root. */
-export type AppProblem = LintProblem & { file: string };
+export type AppProblem = ResourceProblem & { file: string };
 
 /** The apps under `root` (`appsAt`), without what is wrong with them. */
 export const readApps = (root: string | undefined): AppEntry[] => appsAt(root).apps;
 
 /**
  * The apps under `root`: each folder of `apps/` whose name is an `APP_NAME`, sorted, with what is
- * wrong in its `app.ts` and each folder refused for its name as `problems`. `app.ts` is read
- * with oxc, never run: its default export must be `defineApp({ … })`, from `sanoma`, written out,
- * and `source` a string.
+ * wrong in its `app.ts` and each folder refused for its name as `problems`. Each `app.ts` is
+ * loaded (`loadModules`, `defineApp` served from `sanoma`): its default export is
+ * `defineApp({ source })`, `source` a string when given.
  */
 export function appsAt(root: string | undefined): { apps: AppEntry[]; problems: AppProblem[] } {
-  const dir = root === undefined ? undefined : join(root, APPS_DIR);
-  if (dir === undefined || !isDirectory(dir)) return { apps: [], problems: [] };
+  if (root === undefined) return { apps: [], problems: [] };
+  const dir = join(root, APPS_DIR);
+  if (!isDirectory(dir)) return { apps: [], problems: [] };
   const apps: AppEntry[] = [];
   const problems: AppProblem[] = [];
   const folders = readdirSync(dir, { withFileTypes: true })
     .filter((d) => d.isDirectory())
     .map((d) => d.name)
     .toSorted();
-  for (const name of folders) {
+  const named = folders.filter((folder) => APP_NAME.test(folder));
+  for (const name of folders.filter((folder) => !APP_NAME.test(folder))) {
     const at = `${APPS_DIR}/${name}`;
-    if (!APP_NAME.test(name)) {
-      problems.push({
-        file: at,
-        line: 1,
-        column: 1,
-        message: `${at} is not an app: an app's folder name is a lowercase letter, then lowercase letters and digits`,
-      });
-      continue;
-    }
-    const read = appOptionsOf(join(dir, name, "app.ts"));
-    problems.push(...read.problems.map((p) => ({ file: `${at}/app.ts`, ...p })));
-    apps.push({ name, dir: at, ...(read.source !== undefined && { source: read.source }) });
+    problems.push({
+      file: at,
+      line: 1,
+      column: 1,
+      message: `${at} is not an app: an app's folder name is a lowercase letter, then lowercase letters and digits`,
+    });
+  }
+  const files = named.map((name) => join(dir, name, "app.ts")).filter((path) => existsSync(path));
+  const loaded = files.length ? loadModules(root, files, []) : new Map<string, Loaded>();
+  for (const name of named) {
+    const file = `${APPS_DIR}/${name}/app.ts`;
+    const read = appDefinitionOf(file, loaded);
+    problems.push(...read.problems);
+    apps.push({
+      name,
+      dir: `${APPS_DIR}/${name}`,
+      ...(read.source !== undefined && { source: read.source }),
+      ...(loaded.has(file) && { at: { file, export: "default" } }),
+    });
   }
+  problems.sort((a, b) => a.file.localeCompare(b.file));
   return { apps, problems };
 }
 
-/** Where `defineApp` comes from in `app.ts`. */
-const APP_SOURCES: ReadonlySet<string> = new Set(["sanoma", "@sanoma-ai/workflows"]);
+/** What `app.ts`'s default export, `defineApp({ … })`, may say. */
+const AppDefinitionSchema = z.strictObject({ source: z.string().optional() });
 
-/** `app.ts`'s `source`, read without running it, and what is wrong there; nothing for no file. */
-function appOptionsOf(path: string): { source?: string; problems: LintProblem[] } {
-  if (!existsSync(path)) return { problems: [] };
-  const file = readSource(path);
-  if (typeof file === "string") return { problems: [{ line: 1, column: 1, message: file }] };
-  const problems: LintProblem[] = [...file.problems];
-  const problem = (at: Node, message: string) => problems.push({ ...file.at(at.start), message });
-  const unread =
-    'app.ts is read without running it: its default export is `defineApp({ source })` from "sanoma", written out';
-  const exported = file.program.body.find((s: Node) => s.type === "ExportDefaultDeclaration");
-  const call = unwrap(exported?.declaration);
-  const callee = unwrap(call?.callee);
-  const options = unwrap(call?.arguments?.[0]);
-  const defineApps = new Set<string>();
-  for (const statement of file.program.body) {
-    if (statement.type !== "ImportDeclaration" || !APP_SOURCES.has(statement.source.value)) continue;
-    for (const s of statement.specifiers) {
-      if (s.type === "ImportSpecifier" && keyName(s.imported) === "defineApp") defineApps.add(s.local.name);
-    }
-  }
-  const written =
-    call?.type === "CallExpression" &&
-    callee?.type === "Identifier" &&
-    defineApps.has(callee.name) &&
-    (options === undefined || options.type === "ObjectExpression");
-  if (!written) {
-    problem(exported ?? file.program, unread);
-    return { problems };
+/** `app.ts`'s `source`, as loading it gave, and what is wrong there; nothing for no file. */
+function appDefinitionOf(file: string, answer: Map<string, Loaded>): { source?: string; problems: AppProblem[] } {
+  // A helper it imports threw: said at the helper.
+  const loaded = exportsOf(answer, file);
+  if (loaded === undefined) return { problems: [] };
+  if ("problem" in loaded) return { problems: [loaded.problem] };
+  const value = loaded.exports.find(([name]) => name === "default")?.[1];
+  const parsed = AppDefinitionSchema.safeParse(value);
+  if (!parsed.success) {
+    const why = z.prettifyError(parsed.error).replaceAll(/\s*\n\s*/g, " ");
+    const message = `its default export is \`defineApp({ source })\` from "sanoma", \`source\` a string: ${why}`;
+    return { problems: [{ file, export: "default", message }] };
   }
-  const property = options?.properties.findLast(
-    (p: Node) => p.type === "Property" && !p.computed && keyName(p.key) === "source",
-  );
-  const source = property && stringValue(property.value);
-  if (property && source === undefined)
-    problem(property, "`source` is read without running app.ts: write it as a string");
-  return { ...(source !== undefined && { source }), problems };
+  return { ...(parsed.data.source !== undefined && { source: parsed.data.source }), problems: [] };
 }
 
 /** A source file under an app: `.ts` or `.tsx`, but a declaration. */
@@ -131,7 +100,7 @@ export function crossAppImports(root: string | undefined, apps: readonly AppEntr
     for (const path of filesUnder(own, isSource)) {
       const file = readSource(path);
       if (typeof file === "string") continue;
-      const rel = relative(root, path).split(sep).join("/");
+      const rel = relPath(root, path);
       const visit = (node: Node) => {
         if (!node) return;
         const specifier =

package/src/ast.ts

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { parseSync, visitorKeys } from "oxc-parser";
+import type { LintProblem } from "./description.ts";
 import { errorMessage } from "./shared.ts";
 
 // What the lints, the outline and the data-file reader share: one way to parse a file, walk it
@@ -30,6 +31,10 @@ const CODE_KEYS = new Map(
   Object.entries(visitorKeys).map(([type, keys]) => [type, keys.filter((key) => !TYPE_KEYS.has(key))]),
 );
 
+/** A property's name: an identifier's, or a literal's as a string; undefined for any other key. */
+export const keyName = (key: Node): string | undefined =>
+  key.type === "Identifier" ? key.name : key.type === "Literal" ? String(key.value) : undefined;
+
 /** A node's children in source order, by oxc-parser's `visitorKeys`, without its types. A hole in a list is `null`. */
 export const childrenOf = (node: Node): Node[] => (CODE_KEYS.get(node.type) ?? []).flatMap((key) => node[key] ?? []);
 
@@ -68,12 +73,7 @@ export function offsetOf(lineStarts: readonly number[], line: number, column: nu
   return offset < next - 1 ? offset : undefined;
 }
 
-/** Something wrong in a file, at a line and column from 1. */
-export interface LintProblem {
-  line: number;
-  column: number;
-  message: string;
-}
+export type { LintProblem };
 
 /** A file parsed, its syntax errors as problems, and offsets as lines and columns from 1. */
 export function parsed(source: string, filename: string) {

package/src/authentication.ts

@@ -0,0 +1,74 @@
+import type { z } from "zod";
+import { SecretStoreError, type SecretStoreCapabilities } from "./secret-store.ts";
+
+/** Credential schemas and lifecycle are owned by authentication, never by the store provider. */
+export type Authentication<S extends z.ZodType = z.ZodType> =
+  | {
+      kind: "api-key" | "fields" | "oauth2" | "signed";
+      version: number;
+      schema: S;
+      storage: { writable: boolean; maxBytes: number; conditionalWrites: boolean };
+    }
+  | { kind: "workload-identity"; storage?: never; version?: never; schema?: never };
+
+export function defineAuthentication<S extends z.ZodType>(definition: Authentication<S>): Authentication<S> {
+  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" });
+  }
+  if (
+    !["api-key", "fields", "oauth2", "signed"].includes(definition.kind) ||
+    !Number.isSafeInteger(definition.version) ||
+    definition.version < 1 ||
+    typeof definition.schema?.safeParse !== "function" ||
+    !definition.storage ||
+    !Number.isSafeInteger(definition.storage.maxBytes) ||
+    definition.storage.maxBytes < 1 ||
+    typeof definition.storage.writable !== "boolean" ||
+    typeof definition.storage.conditionalWrites !== "boolean"
+  ) {
+    throw new SecretStoreError("invalid_configuration");
+  }
+  return Object.freeze({ ...definition, storage: Object.freeze({ ...definition.storage }) });
+}
+
+/** Compatibility check before consent, including externally renewed (read-only) OAuth bundles. */
+export function checkAuthenticationStore(
+  auth: Authentication,
+  store: SecretStoreCapabilities,
+  management: "sanoma" | "external",
+): void {
+  if (auth.kind === "workload-identity") return;
+  if (auth.storage.maxBytes > store.maxBytes) throw new SecretStoreError("too_large");
+  if (auth.storage.writable && (management === "external" || !store.writable)) throw new SecretStoreError("read_only");
+  if (auth.storage.conditionalWrites && store.conditionalWrites === "none") throw new SecretStoreError("unsupported");
+}
+
+/** Serialized only at the trusted store boundary, never returned by an operation to a workflow. */
+export function encodeCredentials<S extends z.ZodType>(auth: Authentication<S>, value: z.input<S>): string {
+  if (auth.kind === "workload-identity") throw new SecretStoreError("unsupported");
+  try {
+    const parsed = auth.schema.safeParse(value);
+    if (!parsed.success) throw new SecretStoreError("invalid_value");
+    const encoded = JSON.stringify({ version: auth.version, value: parsed.data });
+    if (Buffer.byteLength(encoded) > auth.storage.maxBytes) throw new SecretStoreError("too_large");
+    return encoded;
+  } catch (error) {
+    if (error instanceof SecretStoreError) throw new SecretStoreError(error.code);
+    throw new SecretStoreError("invalid_value");
+  }
+}
+
+export function decodeCredentials<S extends z.ZodType>(auth: Authentication<S>, encoded: string): z.output<S> {
+  if (auth.kind === "workload-identity") throw new SecretStoreError("unsupported");
+  try {
+    if (Buffer.byteLength(encoded) > auth.storage.maxBytes) throw new SecretStoreError("too_large");
+    const bundle = JSON.parse(encoded);
+    if (bundle?.version !== auth.version) throw new SecretStoreError("invalid_value");
+    return auth.schema.parse(bundle.value);
+  } catch (error) {
+    if (error instanceof SecretStoreError) throw new SecretStoreError(error.code);
+    throw new SecretStoreError("invalid_value");
+  }
+}

package/src/call-workflow.ts

@@ -1,3 +1,4 @@
+import { connectionRefSchema, type ConnectionRef } from "./connection.ts";
 import { z } from "zod";
 import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
 import { isDirect } from "./direct.ts";
@@ -12,10 +13,10 @@ export { CALL_WORKFLOW } from "./shared.ts";
 // held to the same lint: the call goes through `ctx`, under the policy, in the ledger.
 
 /** An operation on `ctx`. */
-type OpCall = (input: unknown) => Promise<unknown>;
+type OpCall = (input: unknown, options?: { connection?: ConnectionRef }) => Promise<unknown>;
 
 /** The call workflow's input: the operation's id, and its input. */
-export const CallInput = z.object({ op: z.string(), input: z.unknown() });
+export const CallInput = z.object({ op: z.string(), input: z.unknown(), connection: connectionRefSchema.optional() });
 
 /**
  * The call workflow for a config: it `uses` every operation that may be called directly and has
@@ -43,10 +44,10 @@ export function callWorkflow(
       // Four segments for an app's collection: `data.<app>.<collection>.<op>`.
       const [vendor = "", a = "", b = "", c] = input.op.split(".");
       return c === undefined
-        ? ctx[vendor]![a]![b]!(input.input)
+        ? ctx[vendor]![a]![b]!(input.input, { connection: input.connection })
         : (ctx as unknown as Record<string, Record<string, Record<string, Record<string, OpCall>>>>)[vendor]![a]![b]![
             c
-          ]!(input.input);
+          ]!(input.input, { connection: input.connection });
     },
   });
 }

package/src/call.ts

@@ -1,3 +1,4 @@
+import type { ConnectionRef, ConnectionSnapshot } from "./connection.ts";
 import { DBOS, DBOSWorkflowConflictError, Error as DBOSErrors } from "@dbos-inc/dbos-sdk";
 import { awaitApproval, type CheckedApproval } from "./approvals.ts";
 import { offsetOf } from "./ast.ts";
@@ -161,8 +162,10 @@ export function buildCtx(wf: WorkflowDefinition<any, any>, run: Run): any {
       .split(".")
       .slice(0, -1)
       .reduce<Record<string, any>>((at, key) => (at[key] ??= {}), members);
-    group[op.name] = placed(op.id, (node, input) =>
-      serial(run, () => callOp(run, op.id, input, { node: node.path, name: named(node) ?? op.id })),
+    group[op.name] = placed(op.id, (node, input, options?: { connection?: ConnectionRef }) =>
+      serial(run, () =>
+        callOp(run, op.id, input, { node: node.path, name: named(node) ?? op.id }, options?.connection),
+      ),
     );
   }
   members.runId = run.id;
@@ -284,8 +287,19 @@ function targetOf(op: Op, input: unknown): { target?: string } {
  * the running instance's people): while it holds or denies, the company's policy is not asked.
  * Runs inside a step, so it must have no side effects of its own.
  */
-export async function decide(run: Run, op: Op, input: unknown): Promise<RecordedDecision> {
-  const seen = { id: run.id, workflow: run.workflow, approvals: structuredClone(run.approvals) };
+export async function decide(
+  run: Run,
+  op: Op,
+  input: unknown,
+  connection?: ConnectionSnapshot,
+): Promise<RecordedDecision> {
+  const seen = {
+    id: run.id,
+    workflow: run.workflow,
+    approvals: structuredClone(run.approvals).filter(
+      (a) => a.requestedBy !== "policy" || a.connection === connection?.revision,
+    ),
+  };
   // Only a merge is the rule's: no other call reads the people's files.
   const held =
     op.id === CHANGE_MERGE ? runtimeHold(op.id, input, seen.approvals, readPeople(run.state.root).people) : undefined;
@@ -298,7 +312,7 @@ export async function decide(run: Run, op: Op, input: unknown): Promise<Recorded
       { idempotencyKey: `${run.id}:${run.seq}:before`, runId: run.id, opId: get, attempt: 1, secrets: secretsOf(run) },
     ),
   );
-  const call = { ...callOf(op, input, run.actor, seen), ...before };
+  const call = { ...callOf(op, input, run.actor, seen), ...before, ...(connection && { connection }) };
   return ask(policy, op.id, () => policy(call), run.state);
 }
 
@@ -357,7 +371,7 @@ export function decideCall(
   input: unknown,
   actor: Principal,
   run: PolicyCall["run"],
-  before: Pick<PolicyCall, "before"> = {},
+  before: Pick<PolicyCall, "before" | "connection"> = {},
 ): RecordedDecision {
   const call = { ...callOf(op, input, actor, run), ...before };
   return ask(policy, op.id, () => policy(call));
@@ -411,7 +425,7 @@ function ask(
   return policy.version === undefined ? decision : { ...decision, policyVersion: policy.version };
 }
 
-async function callOp(run: Run, id: string, input: unknown, place: Placed) {
+async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?: ConnectionRef) {
   // The worker's declaration, never the workflow's: its effect, schemas and retry setting.
   const op = run.state.ops.get(id);
   // A sandbox run calls its own fakes, never a vendor.
@@ -441,10 +455,36 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
   // The decision is recorded as a step, so a replay reuses it instead of asking a policy
   // that may have changed since. The policy must still be deterministic: a run that fails
   // before the step is recorded asks again.
-  const decideStep = () => DBOS.runStep(() => decide(run, op, parsed), { name: `policy:${op.id}` });
+  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;
+      }
+      return run.state.connections?.select(op.vendor, ref, run.actor.id);
+    },
+    { name: `connection:${op.id}` },
+  );
+  const decideStep = () =>
+    DBOS.runStep(
+      async () => {
+        await run.state.connections?.assertCurrent(connection, run.actor.id);
+        return decide(run, op, parsed, connection);
+      },
+      { name: `policy:${op.id}` },
+    );
   let decision = await decideStep();
   const logged = recorded(op, parsed);
-  const call = { type: "op.called", op: op.id, ...place, effect: op.effect, input: logged, decision } as const;
+  const call = {
+    type: "op.called",
+    op: op.id,
+    ...place,
+    effect: op.effect,
+    input: logged,
+    decision,
+    ...(connection && { connection }),
+  } as const;
 
   // Each hold is lifted in turn: once one is approved, the policy is asked again, with it.
   for (;;) {
@@ -462,6 +502,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
         seq,
         input: logged,
         reasons: decision.reasons,
+        connection: connection?.revision,
       });
     } catch (err) {
       // A rejection or a withdrawal stops the call: it is recorded as failed, naming the approval.
@@ -486,6 +527,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       async () => {
         const at = Date.now();
         attempt = DBOS.stepStatus?.currentAttempt ?? 1;
+        await run.state.connections?.assertCurrent(connection, run.actor.id);
         const secrets = secretsOf(run);
         const context: CallContext = {
           idempotencyKey: `${run.id}:${seq}`,
@@ -493,6 +535,8 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
           opId: op.id,
           attempt,
           secrets,
+          principal: run.actor,
+          ...(connection && { connection }),
           // A call run is the person's direct call held for an approval: made as them, as it would have been.
           by: run.workflow === CALL_WORKFLOW ? run.actor.id : `run:${run.id}`,
         };

package/src/cedar.ts

@@ -403,7 +403,20 @@ export function cedarPolicy(
       call.actor,
       call.op.id,
       call.target,
-      { input: call.input, ...(call.before !== undefined && { before: call.before }) },
+      {
+        input: call.input,
+        ...(call.before !== undefined && { before: call.before }),
+        ...(call.connection && {
+          connection: {
+            id: call.connection.id,
+            vendor: call.connection.vendor,
+            method: call.connection.method,
+            account: call.connection.account,
+            revision: call.connection.revision,
+            scopes: call.connection.scopes,
+          },
+        }),
+      },
       call.run.approvals,
       call.run.workflow === CALL_WORKFLOW,
       call.entity,