@sanoma-ai/workflows 0.9.1 → 0.10.1

package/src/apps.ts

@@ -1,118 +1,103 @@
 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 { APP_NAME } from "./shared.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, 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
 // 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"]);
+/**
+ * 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;
+}
 
-/** `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 };
+/** What `app.ts`'s default export, `defineApp({ … })`, may say. */
+const AppDefinitionSchema = z.strictObject({ source: z.string().optional() });
+
+/** `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 +116,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,191 @@
+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> =
+  | {
+      kind: "api-key" | "fields" | "oauth2" | "signed";
+      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;
+      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({ ...definition });
+  }
+  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 }) });
+}
+
+/** 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,
+  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,35 @@ 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 (!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);
+    },
+    { name: `connection:${op.id}` },
+  );
+  const decideStep = () =>
+    DBOS.runStep(
+      async () => {
+        if (run.sandbox === undefined) 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 +501,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 +526,7 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed) {
       async () => {
         const at = Date.now();
         attempt = DBOS.stepStatus?.currentAttempt ?? 1;
+        if (run.sandbox === undefined) await run.state.connections?.assertCurrent(connection, run.actor.id);
         const secrets = secretsOf(run);
         const context: CallContext = {
           idempotencyKey: `${run.id}:${seq}`,
@@ -493,6 +534,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,

package/src/change-steps.ts

@@ -15,6 +15,7 @@ import {
   followBase,
   repositoryOf,
   isRules,
+  mayDeclarePeople,
   sourceOfRun,
   touchesOf,
 } from "./change.ts";
@@ -23,7 +24,7 @@ import type { DriftReport } from "./drift.ts";
 import { isRunControlError } from "./errors.ts";
 import { warn } from "./log.ts";
 import { inside } from "./paths.ts";
-import { DECLARES_PEOPLE } from "./resources.ts";
+import { peopleSources } from "./resources.ts";
 import { currentRun, type Run } from "./run.ts";
 import {
   AGENTS,
@@ -48,8 +49,8 @@ const runNow = (): Run => {
   return run;
 };
 
-/** True when the file at `path` is a people file (`DECLARES_PEOPLE`), one `readPeople` would read; false when there is none. */
-const fileDeclaresPeople = async (path: string) => DECLARES_PEOPLE.test(await readFile(path, "utf8").catch(() => ""));
+/** True when the file at `path` is a people file (`mayDeclarePeople`), one `readPeople` would load; false when there is none. */
+const fileDeclaresPeople = async (path: string) => mayDeclarePeople(await readFile(path, "utf8").catch(() => ""));
 
 /** Which events win when several wait: one that ends the change over one that plans it again. */
 const WEIGHT: Record<ChangeEvent["kind"], number> = { commits: 0, close: 1, closed: 2, merged: 3 };
@@ -188,12 +189,14 @@ export function changeSteps({ remotes, hosts }: ChangeStepsOptions): ChangeSteps
               .filter((file) => file.startsWith("resources/"))
               .flatMap((file) => [join(source.root, file), join(draft.root, file)].map(fileDeclaresPeople)),
           );
+          const sources = peopleSources(source.root);
           return {
             touches,
             strandedRuns: stranded.length,
             stranded,
             checksOk: check.ok,
-            rules: people.includes(true) || touches.some(isRules),
+            // Or a file main's people are read from: a helper a people file imports.
+            rules: people.includes(true) || touches.some(isRules) || files.some((file) => sources.has(file)),
           };
         },
         { name: "change:plan" },