@sanoma-ai/workflows 0.10.0 → 0.10.2

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}`;

package/src/sites.ts

@@ -7,6 +7,7 @@ import type { ConfigDescription, SiteCall, SiteEntry, SitePage } from "./descrip
 import { stringValue, unwrap } from "./outline.ts";
 import { exportsOf, loadModules } from "./load.ts";
 import { APPS_DIR, appFolders, filesUnder, isDirectory, relPath, SITE_ENTRIES } from "./paths.ts";
+import { isObject } from "./resource.ts";
 import type { ResourceProblem } from "./resources.ts";
 import { START } from "./schema.ts";
 import {
@@ -428,6 +429,9 @@ const SiteDefinitionSchema = z.strictObject({
   locales: z.array(z.string()).optional(),
 });
 
+/** What `site.ts` says of who may see a site: read together or not at all. */
+const ACCESS = ["public", "login", "locales"];
+
 /**
  * What the site in `dir` (relative to `root`) says of itself in its `site.ts`, loaded
  * (`loadModules`, `defineSite` served from `sanoma/site`), and what is wrong there: its default
@@ -452,13 +456,25 @@ function siteDefinitionOf(
   const value = loaded.exports.find(([name]) => name === "default")?.[1];
   if (value === undefined) return { problems: [] };
   const problem = (message: string) => ({ file, export: "default", message });
-  const parsed = SiteDefinitionSchema.safeParse(value);
+  const problems: (ResourceProblem & { file: string })[] = [];
+  let parsed = SiteDefinitionSchema.safeParse(value);
   if (!parsed.success) {
     const why = z.prettifyError(parsed.error).replaceAll(/\s*\n\s*/g, " ");
-    return { problems: [problem(`its default export is \`defineSite({ … })\` from "sanoma/site": ${why}`)] };
+    problems.push(problem(`its default export is \`defineSite({ … })\` from "sanoma/site": ${why}`));
+    // The fields it names wrongly (and the keys it does not know) left out, the rest still read:
+    // a bad icon keeps a site's `public`, `login` and `locales`. Those three say who may see it,
+    // so a wrong one leaves out all three: never a site read as public without its login.
+    const wrong = new Set(
+      parsed.error.issues.flatMap((i) => (i.code === "unrecognized_keys" ? i.keys : i.path.slice(0, 1))),
+    );
+    if (ACCESS.some((key) => wrong.has(key))) for (const key of ACCESS) wrong.add(key);
+    if (!isObject(value) || !wrong.size) return { problems };
+    parsed = SiteDefinitionSchema.safeParse(
+      Object.fromEntries(Object.entries(value).filter(([key]) => !wrong.has(key))),
+    );
+    if (!parsed.success) return { problems };
   }
   const { title, icon, public: isPublic, login, locales } = parsed.data;
-  const problems: (ResourceProblem & { file: string })[] = [];
   const loginProblem = (): string | undefined => {
     if (!isPublic) return "a login is for a public site: add `public: true`, or remove `login`";
     if (!connectors.vendors.has(login!)) return `login names "${login}", which is not a connector in sanoma.config.ts`;

package/src/steps.ts

@@ -1,5 +1,6 @@
 import type { LedgerRecord } from "./ledger.ts";
 import type { Op } from "./op.ts";
+import type { ConnectionRef } from "./connection.ts";
 
 /*
  * Steps a connector (or a company) ships for its Gherkin tests, as plain data: expressions and
@@ -19,8 +20,8 @@ type AnyOp<I = any, O = any> = Op<string, string, string, I, O>;
  * seed's name (else the type's) as the export.
  */
 export type Seed =
-  | { op: AnyOp; input: Record<string, unknown>; as?: string }
-  | { op: AnyOp; fault: "failNext" | "rateLimit" | "loseReply" };
+  | { op: AnyOp; input: Record<string, unknown>; as?: string; connection?: ConnectionRef }
+  | { op: AnyOp; fault: "failNext" | "rateLimit" | "loseReply"; connection?: ConnectionRef };
 
 /** A call through an operation: what it was given, and what it returned. */
 export interface Call<I, O> {