@sanoma-ai/workflows 0.1.0 → 0.4.0

package/src/schema.ts

@@ -0,0 +1,261 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import type {
+  DetailedError,
+  EntityType,
+  RecordType,
+  SchemaJson,
+  Type,
+  TypeOfAttribute,
+} from "@cedar-policy/cedar-wasm/nodejs";
+import { recordSchemaOf } from "./collection.ts";
+import type { ResolvedConfig } from "./config.ts";
+import { jsonSchemaOf } from "./define.ts";
+import { isObject } from "./resource.ts";
+import { DATA_VENDOR, EFFECTS, groupNamesOf, type PeopleResource, WORKFLOW_ACTION } from "./shared.ts";
+
+// The Cedar schema a company's policies are validated and decided against: made from the
+// resolved config and the people, in memory for the evaluator, and written as text to
+// `.sanoma/schema.cedarschema` for the policies' author.
+
+const require = createRequire(import.meta.url);
+let wasm: typeof import("@cedar-policy/cedar-wasm/nodejs") | undefined;
+
+/** `@cedar-policy/cedar-wasm`'s Node build, loaded (synchronously, once) on first use, so a process that never decides with Cedar never loads it. */
+export const cedarWasm = () => (wasm ??= require("@cedar-policy/cedar-wasm/nodejs") as typeof wasm)!;
+
+/** The schema as Cedar's JSON format has it. */
+export type CedarSchemaJson = SchemaJson<string>;
+
+/** Where the schema's text is written, under a company's root. */
+export const SCHEMA_FILE = join(".sanoma", "schema.cedarschema");
+
+/** The schema's namespace: policies name `Sanoma::Group::"finance"`, `Sanoma::Action::"effect:money"`. */
+export const NAMESPACE = "Sanoma";
+
+/** The action group every workflow start (`workflow:<name>`) is in. */
+export const START = "start";
+
+const STRING = { type: "EntityOrCommon", name: "String" } as const;
+const LONG = { type: "EntityOrCommon", name: "Long" } as const;
+const BOOL = { type: "EntityOrCommon", name: "Bool" } as const;
+const entity = (name: string) => ({ type: "Entity", name }) as const;
+const record = (attributes: Record<string, TypeOfAttribute<string>>): RecordType<string> & { type: "Record" } => ({
+  type: "Record",
+  attributes,
+});
+const optional = (type: Type<string>): TypeOfAttribute<string> => ({ ...type, required: false });
+
+/**
+ * The Cedar type of a zod schema's parsed value (`io: "output"`: what the policy is given, defaults
+ * filled and transforms applied), through its JSON Schema; undefined when it has none.
+ */
+const typeOf = (schema: Parameters<typeof jsonSchemaOf>[0]) => {
+  const json = jsonSchemaOf(schema, "output");
+  return cedarType(json, { root: json, seen: new Set() });
+};
+
+/** A context's `input`, typed from a zod schema: none when it has no Cedar type. */
+const input = (schema: Parameters<typeof jsonSchemaOf>[0]): Record<string, TypeOfAttribute<string>> => {
+  const type = typeOf(schema);
+  return type ? { input: type } : {};
+};
+
+/** A collection's operations that change a record, whose context has the record as it was (`before`). */
+const WRITES = new Set(["save", "delete"]);
+
+/**
+ * The Cedar schema for a resolved config and its people, namespace `Sanoma`:
+ *
+ * - `entity Group enum [...]`, the declared groups and `agents`, so a policy naming another fails
+ *   validation; `entity Principal in [Group] { onBehalfOf?: Principal }`; `Collection`;
+ *   `Target in [Collection]`; `Workflow`;
+ * - an action per operation id, in its effect's group (`effect:money`), on a `Target`, with
+ *   `context` `{ input, before? }`: `input` from the operation's input schema, `before` the record
+ *   as it was for a collection's `save` and `delete`;
+ * - `workflow:<name>` per workflow, in the group `start`, on a `Workflow`, with its `input`.
+ *
+ * Zod to Cedar, through the JSON Schema of the parsed value: string and enum `String`, integer `Long`, boolean `Bool`,
+ * object a record (its optional and nullable fields optional), array a `Set`; a decimal number
+ * is a `String`; a field with no Cedar type (a union of types, a map, a recursive type) is left
+ * out, so a policy naming it fails validation. Pure: the same config and people give the same schema.
+ */
+function buildSchema(
+  resolved: Pick<ResolvedConfig, "ops" | "workflows" | "collections">,
+  people: readonly PeopleResource[],
+): CedarSchemaJson {
+  const applies = (resource: string, context: Record<string, TypeOfAttribute<string>>) => ({
+    principalTypes: ["Principal"],
+    resourceTypes: [resource],
+    context: record(context),
+  });
+  const actions: CedarSchemaJson[string]["actions"] = { [START]: {} };
+  for (const effect of EFFECTS) actions[`effect:${effect}`] = {};
+  for (const op of [...resolved.ops.values()].toSorted((a, b) => a.id.localeCompare(b.id))) {
+    const collection =
+      op.vendor === DATA_VENDOR && WRITES.has(op.name) ? resolved.collections.get(op.resource) : undefined;
+    const before = collection && typeOf(recordSchemaOf(collection));
+    actions[op.id] = {
+      memberOf: [{ id: `effect:${op.effect}` }],
+      appliesTo: applies("Target", { ...input(op.input), ...(before && { before: optional(before) }) }),
+    };
+  }
+  for (const name of [...resolved.workflows.keys()].toSorted()) {
+    actions[`${WORKFLOW_ACTION}${name}`] = {
+      memberOf: [{ id: START }],
+      appliesTo: applies("Workflow", input(resolved.workflows.get(name)!.input)),
+    };
+  }
+  const entityTypes: Record<string, EntityType<string>> = {
+    Group: { enum: groupNamesOf(people) },
+    Principal: { memberOfTypes: ["Group"], shape: record({ onBehalfOf: optional(entity("Principal")) }) },
+    Collection: {},
+    Target: { memberOfTypes: ["Collection"] },
+    Workflow: {},
+  };
+  return { [NAMESPACE]: { entityTypes, actions } };
+}
+
+const schemas = new WeakMap<object, WeakMap<readonly PeopleResource[], CedarSchemaJson>>();
+
+/**
+ * The Cedar schema for a resolved config and its people (`buildSchema`), made once for each pair:
+ * validating, deciding and writing it share one.
+ */
+export function schemaOf(
+  resolved: Pick<ResolvedConfig, "ops" | "workflows" | "collections">,
+  people: readonly PeopleResource[],
+): CedarSchemaJson {
+  let byPeople = schemas.get(resolved.ops);
+  if (!byPeople) schemas.set(resolved.ops, (byPeople = new WeakMap()));
+  let schema = byPeople.get(people);
+  if (!schema) byPeople.set(people, (schema = buildSchema(resolved, people)));
+  return schema;
+}
+
+/** The schema as Cedar's text, through the package's own `schemaToText`: what `.sanoma/schema.cedarschema` holds. */
+export function schemaText(schema: CedarSchemaJson): string {
+  const answer = cedarWasm().schemaToText(schema);
+  if (answer.type === "failure") {
+    throw new Error(`The Cedar schema does not print: ${answer.errors.map(messageOf).join("; ")}`);
+  }
+  return answer.text;
+}
+
+interface Typing {
+  root: Record<string, unknown>;
+  /** The schemas being typed, to leave a recursive one out. */
+  seen: Set<unknown>;
+}
+
+/** The Cedar type of a JSON Schema (`jsonSchemaOf`'s, draft 2020-12), or undefined when it has none. */
+function cedarType(schema: unknown, typing: Typing): Type<string> | undefined {
+  if (!isObject(schema) || typing.seen.has(schema)) return undefined;
+  if (typeof schema.$ref === "string") {
+    const defs = typing.root.$defs as Record<string, unknown> | undefined;
+    const target = schema.$ref.startsWith("#/$defs/") ? defs?.[schema.$ref.slice("#/$defs/".length)] : undefined;
+    return within(schema, typing, () => cedarType(target, typing));
+  }
+  const variants = schema.anyOf ?? schema.oneOf;
+  if (Array.isArray(variants)) {
+    const each = within(schema, typing, () => variants.filter((v) => !isNull(v)).map((v) => cedarType(v, typing)));
+    const first = each[0];
+    return first && each.every((t) => t && JSON.stringify(t) === JSON.stringify(first)) ? first : undefined;
+  }
+  const values = Array.isArray(schema.enum) ? schema.enum : "const" in schema ? [schema.const] : undefined;
+  if (values) {
+    if (values.every((v) => typeof v === "string")) return STRING;
+    if (values.every((v) => Number.isSafeInteger(v))) return LONG;
+    return values.every((v) => typeof v === "boolean") ? BOOL : undefined;
+  }
+  const types = Array.isArray(schema.type) ? schema.type.filter((t) => t !== "null") : [schema.type];
+  if (types.length !== 1) return undefined;
+  switch (types[0]) {
+    case "string":
+    case "number":
+      // Cedar has no decimal number: one is compared as text.
+      return STRING;
+    case "integer":
+      return LONG;
+    case "boolean":
+      return BOOL;
+    case "array": {
+      const element = within(schema, typing, () => cedarType(schema.items, typing));
+      return element && { type: "Set", element };
+    }
+    case "object": {
+      // A map's keys are not known: it has no Cedar type.
+      if (!isObject(schema.properties)) return schema.additionalProperties ? undefined : record({});
+      const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+      const attributes: Record<string, TypeOfAttribute<string>> = {};
+      for (const [name, property] of Object.entries(schema.properties)) {
+        const type = within(schema, typing, () => cedarType(property, typing));
+        if (type) attributes[name] = required.has(name) && !allowsNull(property) ? type : optional(type);
+      }
+      return record(attributes);
+    }
+    default:
+      return undefined;
+  }
+}
+
+/** `type()` with `schema` marked as being typed, so a reference back to it is not followed. */
+function within<T>(schema: unknown, typing: Typing, type: () => T): T {
+  typing.seen.add(schema);
+  try {
+    return type();
+  } finally {
+    typing.seen.delete(schema);
+  }
+}
+
+const isNull = (schema: unknown) => isObject(schema) && schema.type === "null";
+
+/** True when a JSON Schema accepts `null`: its value is then optional in Cedar, which has no null. */
+const allowsNull = (schema: unknown): boolean =>
+  isObject(schema) &&
+  (isNull(schema) ||
+    (Array.isArray(schema.type) && schema.type.includes("null")) ||
+    [schema.anyOf, schema.oneOf].some((v) => Array.isArray(v) && v.some(isNull)));
+
+/** Cedar's message, with its help when it has one. */
+export const messageOf = (e: DetailedError) => (e.help ? `${e.message} (${e.help})` : e.message);
+
+/** An action's context type in the schema: a record, when the action is there. */
+export const contextTypeOf = (schema: CedarSchemaJson, action: string) =>
+  schema[NAMESPACE]?.actions[action]?.appliesTo?.context as (RecordType<string> & { type: "Record" }) | undefined;
+
+/**
+ * A value as Cedar takes it for a type `schemaOf` wrote (`cedarType`'s other side): a record's
+ * fields it declares only, a set's elements, a number where it is a `String` as text. An unknown
+ * (`{ __extn: unknown }`) passes as it is; what does not fit is left out (undefined), as `null` is.
+ */
+export function cedarValue(value: unknown, type: Type<string>): unknown {
+  if (value === null || value === undefined) return undefined;
+  if (isObject(value) && "__extn" in value) return value;
+  const t = type as { type: string; name?: string; element?: Type<string>; attributes?: Record<string, Type<string>> };
+  if (t.attributes) {
+    if (!isObject(value)) return undefined;
+    return Object.fromEntries(
+      Object.entries(t.attributes).flatMap(([name, field]) => {
+        const shaped = cedarValue(value[name], field);
+        return shaped === undefined ? [] : [[name, shaped]];
+      }),
+    );
+  }
+  if (t.type === "Set") {
+    return Array.isArray(value)
+      ? value.map((v) => cedarValue(v, t.element!)).filter((v) => v !== undefined)
+      : undefined;
+  }
+  switch (t.name) {
+    case STRING.name:
+      return typeof value === "string" ? value : typeof value === "number" ? String(value) : undefined;
+    case LONG.name:
+      return Number.isSafeInteger(value) ? value : undefined;
+    case BOOL.name:
+      return typeof value === "boolean" ? value : undefined;
+    default:
+      return undefined;
+  }
+}

package/src/sdk.ts

@@ -0,0 +1,211 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import type { CollectionEntry, ConfigDescription, OpEntry, WorkflowEntry } from "./describe.ts";
+import { isObject } from "./resource.ts";
+import { type CedarSchemaJson, SCHEMA_FILE, schemaText } from "./schema.ts";
+import { apiNameOf, DATA_VENDOR, problemLine } from "./shared.ts";
+
+// A company's generated SDK, `.sanoma/api.ts`: the types of a site's `api` from `sanoma/site`,
+// written from `describeConfig` (types and JSDoc only: `api` itself is one generic client). It
+// augments `sanoma/site`'s `Register`, so it is type-checked only through the sites' generated
+// tsconfig, never the company's root one (Node, no DOM).
+
+/** Where `writeApi` writes, under a company's root. */
+export const API_FILE = join(".sanoma", "api.ts");
+
+const API_NAME_PROBLEM = "A site calls this workflow api.";
+
+/** `describeConfig`'s problem on a workflow whose api name is taken: `taken` says by what. */
+export const apiNameProblem = (api: string, taken: string) => `${API_NAME_PROBLEM}${api}, ${taken}: rename it`;
+
+type Schema = Record<string, unknown>;
+
+/**
+ * `.sanoma/api.ts` for a description: one record type per collection, and `CompanyApi` (not `Api`,
+ * which inside `declare module "sanoma/site"` is the module's own), one member per
+ * workflow (`apiNameOf`), per vendor of the operations a person may call directly (`OpEntry.direct`,
+ * by resource) and `data` for the collections, each with its JSDoc; then `Register`'s
+ * augmentation. Pure: the same description gives the same text. A workflow whose api name another
+ * has, `describeConfig`'s problem on its entry, is left out, and its problem is in `problems`.
+ */
+export function generateApi(description: ConfigDescription): { source: string; problems: string[] } {
+  const problems: string[] = [];
+  const members: string[] = [];
+  for (const wf of description.workflows) {
+    const taken = wf.problems.filter((p) => p.message.startsWith(API_NAME_PROBLEM));
+    if (taken.length) problems.push(...taken.map((p) => problemLine({ file: wf.file, ...p })));
+    else members.push(workflowMember(wf));
+  }
+  // The ops are sorted by id, so by vendor and then resource.
+  const direct = description.ops.filter((op) => op.direct && op.vendor !== DATA_VENDOR);
+  for (const [vendor, ops] of Map.groupBy(direct, (op) => op.vendor)) {
+    const title = description.vendors[vendor]?.title ?? vendor;
+    const resources = [...Map.groupBy(ops, (op) => op.resource)].map(([resource, own]) =>
+      member(undefined, resource, block(own.map(opMember))),
+    );
+    members.push(member(`${title}: the operations a person may call directly.`, vendor, block(resources)));
+  }
+  if (description.collections.length) {
+    const data = description.collections.map((c) =>
+      member(collectionDoc(c), c.name, `CollectionApi<${recordName(c)}>`),
+    );
+    members.push(member("The company's collections.", DATA_VENDOR, block(data)));
+  }
+  const source = [
+    "// Generated by sanoma from sanoma.config.ts and the connectors it names; do not edit.",
+    "// The types of `api` from sanoma/site: what a site may call, as the person on the page.",
+    'import type { CollectionApi, OpFn, WorkflowFn } from "sanoma/site";',
+    ...description.collections.map(
+      (c) => `\n${jsdoc(`A record of ${c.title ?? c.name}.`)}type ${recordName(c)} = ${typeOf(c.record)};`,
+    ),
+    "",
+    `interface CompanyApi ${block(members)}`,
+    "",
+    'declare module "sanoma/site" {',
+    "  interface Register {",
+    "    api: CompanyApi;",
+    "  }",
+    "}",
+    "",
+    "export {};",
+    "",
+  ].join("\n");
+  return { source, problems };
+}
+
+/**
+ * Writes `<root>/.sanoma/api.ts` (`generateApi`) when its text differs from the file's, so an
+ * editor or a dev server sees no change when there is none; `wrote` says whether it did.
+ */
+export async function writeApi(
+  root: string,
+  description: ConfigDescription,
+): Promise<{ wrote: boolean; file: string }> {
+  const file = join(root, API_FILE);
+  return { wrote: await writeChanged(file, generateApi(description).source), file };
+}
+
+/**
+ * The generated files, each written when its text changed: `.sanoma/api.ts` (`writeApi`) and the
+ * Cedar schema's text, `.sanoma/schema.cedarschema` (`schemaText` of `schemaOf`). `wrote` lists
+ * those written, relative to the root.
+ */
+export async function writeGenerated(
+  root: string,
+  description: ConfigDescription,
+  schema: CedarSchemaJson,
+): Promise<{ wrote: string[] }> {
+  const [api, cedar] = await Promise.all([
+    writeApi(root, description),
+    writeChanged(join(root, SCHEMA_FILE), schemaText(schema)),
+  ]);
+  return { wrote: [...(api.wrote ? [API_FILE] : []), ...(cedar ? [SCHEMA_FILE] : [])] };
+}
+
+/** Writes `text` to `file` unless the file holds it already; true when it wrote. */
+async function writeChanged(file: string, text: string): Promise<boolean> {
+  if ((await readFile(file, "utf8").catch(() => undefined)) === text) return false;
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, text);
+  return true;
+}
+
+const workflowMember = (wf: WorkflowEntry) =>
+  member(
+    `${wf.title ?? wf.name}: the workflow \`${wf.name}\`${wf.builtin ? ", built in" : ""}.`,
+    apiNameOf(wf.name),
+    `WorkflowFn<${typeOf(wf.input)}, unknown>`,
+  );
+
+const opMember = (op: OpEntry) =>
+  member(
+    `${op.description ? `${op.description}\n\n` : ""}\`${op.id}\`, a ${op.effect}.`,
+    op.name,
+    `OpFn<${typeOf(op.input)}, unknown>`,
+  );
+
+const collectionDoc = (c: CollectionEntry) =>
+  `${c.title ?? c.name}: the collection \`${c.name}\`, keyed by \`${c.key}\`.`;
+
+/** A collection's record type's name: `outbound` gives `OutboundRecord`, never `CompanyApi` nor an imported type's. */
+const recordName = (c: CollectionEntry) => `${c.name[0]!.toUpperCase()}${c.name.slice(1)}Record`;
+
+/**
+ * A JSON Schema as a TypeScript type, for the kinds a start form draws (`fieldsOf` in the app):
+ * strings (a date-time among them), numbers, integers, booleans, enums and constants, objects and
+ * arrays, each property with its description, and unions of those, `null` among them (a
+ * collection's date, a date or a date-time; a nullable field); anything else is `unknown`.
+ */
+const typeOf = (schema: unknown): string => union(alternatives(schema));
+
+/** One type of several: `unknown` when any is. */
+function union(types: string[]): string {
+  const distinct = new Set(types);
+  return distinct.has("unknown") ? "unknown" : [...distinct].join(" | ");
+}
+
+/** The types a schema allows, one per alternative. */
+function alternatives(schema: unknown): string[] {
+  if (!isObject(schema)) return ["unknown"];
+  if ("const" in schema && !isObject(schema.const) && !Array.isArray(schema.const)) {
+    return [JSON.stringify(schema.const)];
+  }
+  if (Array.isArray(schema.enum) && schema.enum.length && schema.enum.every((v) => v === null || !isObject(v))) {
+    return schema.enum.map((v) => JSON.stringify(v));
+  }
+  if (Array.isArray(schema.anyOf) && schema.anyOf.length) return schema.anyOf.flatMap(alternatives);
+  if (Array.isArray(schema.type) && schema.type.length) {
+    return schema.type.flatMap((type) => alternatives({ ...schema, type }));
+  }
+  switch (schema.type) {
+    case "string":
+      return ["string"];
+    case "number":
+    case "integer":
+      return ["number"];
+    case "boolean":
+      return ["boolean"];
+    case "null":
+      return ["null"];
+    case "array": {
+      const item = typeOf(schema.items);
+      return [new Set(alternatives(schema.items)).size > 1 && item !== "unknown" ? `(${item})[]` : `${item}[]`];
+    }
+    case "object":
+      return [isObject(schema.properties) ? objectType(schema) : "Record<string, unknown>"];
+    default:
+      return ["unknown"];
+  }
+}
+
+function objectType(schema: Schema): string {
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const lines = Object.entries(schema.properties as Schema).map(([name, prop]) => {
+    const doc = isObject(prop) && typeof prop.description === "string" ? jsdoc(prop.description) : "";
+    return `${doc}${key(name)}${required.has(name) ? "" : "?"}: ${typeOf(prop)};`;
+  });
+  // An object that takes other keys too.
+  if (schema.additionalProperties !== undefined && schema.additionalProperties !== false) {
+    lines.push("[key: string]: unknown;");
+  }
+  return block(lines);
+}
+
+/** A property's name, quoted when it is not an identifier. */
+const key = (name: string) => (/^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name));
+
+/** A member, under its JSDoc when there is one. */
+const member = (doc: string | undefined, name: string, type: string) =>
+  `${doc ? jsdoc(doc) : ""}${key(name)}: ${type};`;
+
+/** `{ … }` around lines, each indented a level (a nested block's lines with it); `{}` for none. */
+const block = (lines: string[]) =>
+  lines.length ? `{\n${lines.map((l) => l.replace(/^(?=.)/gm, "  ")).join("\n")}\n}` : "{}";
+
+/** A JSDoc comment and the line break after it; `*\/` in the text cannot end it. */
+function jsdoc(text: string): string {
+  const lines = text.replaceAll("*/", "*\\/").split("\n");
+  return lines.length === 1
+    ? `/** ${lines[0]} */\n`
+    : `/**\n${lines.map((l) => ` *${l ? ` ${l}` : ""}`).join("\n")}\n */\n`;
+}

package/src/secret.ts

@@ -0,0 +1,92 @@
+import { randomBytes } from "node:crypto";
+import { DriverError } from "./op.ts";
+
+// Secrets are named, never written: `secret("NAME")` in a data file is a marker for a value in
+// the company's secrets store (the credentials table), allowed only at a write-only field. The
+// marker is what declarations, checkpoints and the ledger hold; a driver resolves it
+// (`resolveSecrets`) just before the vendor call. The `./resources` entry, which data files import
+// `secret` from (`sanoma/resources` re-exports it).
+
+/** What `secret()` makes: a plain object, so it reads the same as JSON and across copies of this package. */
+export interface Secret {
+  readonly $secret: string;
+  /** When none is stored, apply makes the value (`generateSecret`) and stores it before the vendor call. */
+  readonly generate?: true;
+}
+
+/** A secret's name: an environment variable's, upper case. */
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/;
+
+/**
+ * True for one of sanoma's own secrets (`SANOMA_…`, its key and database URLs among them): only a
+ * host, which runs the company, is given them, at its `secrets` input (`HostSpec`); never a vendor.
+ */
+export const isSanomaSecret = (name: string) => name.startsWith("SANOMA_");
+
+/**
+ * Names a stored secret for a write-only field of a data file: `secret("SUPABASE_DB_PASSWORD",
+ * { generate: true })`. With `generate`, apply makes the value when none is stored.
+ */
+export function secret(name: string, options?: { generate: true }): Secret {
+  if (!SECRET_NAME.test(name)) {
+    throw new Error(`secret("${name}"): a secret's name is an environment variable's, upper case: A-Z, 0-9 and _`);
+  }
+  return Object.freeze(options?.generate ? { $secret: name, generate: true as const } : { $secret: name });
+}
+
+/** True for a secret marker, `{ $secret: "NAME" }`. */
+export const isSecret = (value: unknown): value is Secret =>
+  typeof value === "object" && value !== null && typeof (value as { $secret?: unknown }).$secret === "string";
+
+/** The secrets store, as a driver sees it (`CallContext.secrets`). */
+export interface Secrets {
+  /** The stored value, or undefined when there is none. */
+  get(name: string): Promise<string | undefined>;
+  /** The stored value; when there is none, `make()`'s, stored first. */
+  ensure(name: string, make: () => string): Promise<string>;
+}
+
+/** A value for a secret with `generate`: 32 random bytes, base64url. */
+export const generateSecret = (): string => randomBytes(32).toString("base64url");
+
+/** `T` with each secret marker's place holding its value: what `resolveSecrets` returns. */
+export type Resolved<T> = T extends Secret
+  ? string
+  : T extends readonly (infer I)[]
+    ? Resolved<I>[]
+    : T extends object
+      ? { [K in keyof T]: Resolved<T[K]> }
+      : T;
+
+/**
+ * `value` with each secret marker in it replaced by the stored value: generated and stored first
+ * for one with `generate` and none stored. A marker naming nothing stored fails the call, for good.
+ */
+export async function resolveSecrets<T>(value: T, secrets: Secrets): Promise<Resolved<T>> {
+  const resolve = async (v: unknown): Promise<unknown> => {
+    if (isSecret(v)) {
+      const stored = v.generate ? await secrets.ensure(v.$secret, generateSecret) : await secrets.get(v.$secret);
+      if (stored === undefined) {
+        throw new DriverError(`The secret ${v.$secret} is not set: store it before applying`, { retryable: false });
+      }
+      return stored;
+    }
+    if (Array.isArray(v)) return Promise.all(v.map(resolve));
+    if (typeof v !== "object" || v === null) return v;
+    const entries = await Promise.all(Object.entries(v).map(async ([k, item]) => [k, await resolve(item)] as const));
+    return Object.fromEntries(entries);
+  };
+  return (await resolve(value)) as Resolved<T>;
+}
+
+/** A secrets store in memory, for fakes, sandbox runs and tests. */
+export function memorySecrets(initial: Record<string, string> = {}): Secrets {
+  const values = new Map(Object.entries(initial));
+  return {
+    get: async (name) => values.get(name),
+    async ensure(name, make) {
+      if (!values.has(name)) values.set(name, make());
+      return values.get(name)!;
+    },
+  };
+}