@sanoma-ai/workflows 0.9.1 → 0.10.1

package/src/run.ts

@@ -1,3 +1,4 @@
+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";
@@ -38,6 +39,7 @@ export interface StartHold {
  * from a stopped worker never reads a newer worker's drivers or policy.
  */
 export interface WorkerState {
+  connections?: ConnectionRegistry;
   /** The config's `appName`, recorded on every ledger record. */
   app: string;
   /** The operations as the config's connectors declare them, by id. */
@@ -96,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

@@ -1,8 +1,10 @@
 import { DBOS } from "@dbos-inc/dbos-sdk";
 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";
@@ -19,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
@@ -88,7 +114,7 @@ export function seedResource(
  * run whose seeding is replayed from it has none, and fails, since a sandbox run does not
  * survive a worker restart.
  */
-export async function seedSandbox(run: Run, name: string): Promise<void> {
+export async function seedSandbox(run: Run, name: string, input: unknown): Promise<void> {
   const { state } = run;
   let copies: Map<string, DriverFn> | undefined;
   // The run's secrets, in memory as its fakes are: seeding and its calls share them.
@@ -109,12 +135,23 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
         });
       }
       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 },
       );
-      const uses = opIdsOf(state.workflows.get(run.workflow)!);
+      // The built-in call workflow selects exactly one operation. Other direct operations
+      // (including live connection mutations) need no fake unless this scenario calls them.
+      const uses =
+        run.workflow === CALL_WORKFLOW ? [CallInput.parse(input).op] : opIdsOf(state.workflows.get(run.workflow)!);
       const seeding = scenario.given.flatMap((g) => ("op" in g ? [g.op] : []));
       const missing = [...new Set([...uses, ...seeding])].filter((id) => !drivers.has(id));
       if (missing.length) {
@@ -130,16 +167,33 @@ export async function seedSandbox(run: Run, name: string): Promise<void> {
       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/scenarios.ts

@@ -5,6 +5,7 @@ import { type LedgerRecord, memoryLedger } from "./ledger.ts";
 import { type Check, check, drive, loadScenarios, type Scenario, type Scope } from "./scenario.ts";
 import { errorMessage } from "./shared.ts";
 import { startWorker } from "./worker.ts";
+import { memorySecretStore } from "./secret-store.ts";
 
 /*
  * `@sanoma-ai/workflows/scenarios`: runs a config's scenarios as sandbox runs, with no test
@@ -77,7 +78,12 @@ export async function runScenarios(
   config: SanomaConfig,
   { databaseUrl, startedBy, timeoutMs, log }: RunScenariosOptions,
 ): Promise<{ passed: string[]; failed: ScenarioFailure[] }> {
-  const shared: SanomaConfig = { ...config, databaseUrl, ledger: memoryLedger() };
+  const shared: SanomaConfig = {
+    ...config,
+    databaseUrl,
+    ledger: memoryLedger(),
+    secrets: { store: memorySecretStore(), namespace: "scenarios" },
+  };
   const resolved = resolveConfig(shared);
   const { scenarios, errors } = await loadScenarios(resolved);
   const failed: ScenarioFailure[] = errors.map(({ file, message }) => ({

package/src/schema.ts

@@ -104,6 +104,16 @@ function buildSchema(
       memberOf: [{ id: `effect:${op.effect}` }],
       appliesTo: applies(op.id === CHANGE_MERGE ? CHANGE : "Target", {
         ...input(op.input),
+        connection: optional(
+          record({
+            id: STRING,
+            vendor: STRING,
+            method: STRING,
+            account: STRING,
+            revision: STRING,
+            scopes: { type: "Set", element: STRING },
+          }),
+        ),
         ...(before && { before: optional(before) }),
       }),
     };

package/src/secret-store-check.ts

@@ -0,0 +1,93 @@
+import { SecretAccess, SecretStoreError, type SecretStore } from "./secret-store.ts";
+
+const assert = (condition: unknown) => {
+  if (!condition) throw new Error("Conformance failure");
+};
+
+const rejects = async (run: () => Promise<unknown>, code: string) => {
+  try {
+    await run();
+  } catch (error) {
+    assert(error instanceof SecretStoreError && error.code === code);
+    return;
+  }
+  throw new Error("Expected refusal");
+};
+
+export interface SecretStoreCheck {
+  name: string;
+  ok: boolean;
+}
+
+/**
+ * Destructive conformance checks on a fresh, disposable namespace. Never use a production
+ * namespace. The caller supplies a store scoped to test credentials and cleans up retained
+ * versions/namespaces according to the provider's retention rules. No result contains values.
+ */
+export async function checkSecretStore(store: SecretStore, namespace: string): Promise<SecretStoreCheck[]> {
+  const access = new SecretAccess({ store, namespace }, store);
+  const other = new SecretAccess({ store, namespace: `${namespace}-other` }, store);
+  const results: SecretStoreCheck[] = [];
+  const check = async (name: string, run: () => Promise<void>) => {
+    try {
+      await run();
+      results.push({ name, ok: true });
+    } catch {
+      results.push({ name, ok: false });
+    }
+  };
+  await check("validate and missing read", async () => {
+    await access.validate();
+    assert((await access.read("ABSENT")) === undefined);
+  });
+  await check("external ownership", async () => {
+    const external = new SecretAccess(
+      { store, namespace, bindings: { EXISTING: { path: "existing", management: "external" } } },
+      store,
+    );
+    await rejects(() => external.write("EXISTING", "value", { expectedVersion: null, by: "check" }), "read_only");
+    await rejects(() => external.delete("EXISTING", { expectedVersion: "v1", by: "check" }), "read_only");
+  });
+  if (!store.capabilities.writable) {
+    await check("read-only provider", () =>
+      rejects(() => access.write("VALUE", "value", { expectedVersion: null, by: "check" }), "read_only"),
+    );
+    return results;
+  }
+  if (store.capabilities.conditionalWrites === "none") {
+    await check("unsupported conditional writes", () =>
+      rejects(() => access.ensure("VALUE", () => "value"), "unsupported"),
+    );
+    return results;
+  }
+  await check("concurrent create and namespace separation", async () => {
+    const values = await Promise.all(Array.from({ length: 8 }, (_, i) => access.ensure("RACE", () => String(i))));
+    assert(new Set(values).size === 1);
+    assert((await other.get("RACE")) === undefined);
+  });
+  await check("replace rejects stale versions", async () => {
+    const one = await access.write("REPLACE", "one", { expectedVersion: null, by: "check" });
+    const two = await access.write("REPLACE", "two", { expectedVersion: one.version, by: "check" });
+    assert(one.version !== two.version);
+    await rejects(() => access.write("REPLACE", "stale", { expectedVersion: one.version, by: "check" }), "conflict");
+    assert((await access.get("REPLACE")) === "two");
+  });
+  await check("UTF-8 size rejection", () =>
+    rejects(
+      () =>
+        access.write("OVERSIZE", "x".repeat(store.capabilities.maxBytes + 1), { expectedVersion: null, by: "check" }),
+      "too_large",
+    ),
+  );
+  await check("deletion semantics", async () => {
+    const one = await access.write("DELETE", "one", { expectedVersion: null, by: "check" });
+    if (store.capabilities.deletion === "unsupported") {
+      await rejects(() => access.delete("DELETE", { expectedVersion: one.version, by: "check" }), "unsupported");
+      return;
+    }
+    await rejects(() => access.delete("DELETE", { expectedVersion: "incorrect", by: "check" }), "conflict");
+    await access.delete("DELETE", { expectedVersion: one.version, by: "check" });
+    assert((await access.read("DELETE")) === undefined);
+  });
+  return results;
+}

package/src/secret-store.ts

@@ -0,0 +1,314 @@
+import { deploymentKey } from "./deployment-key.ts";
+/** Opaque values belong only in trusted runtime code, never workflow history or descriptions. */
+export interface SecretValue {
+  value: string;
+  version: string;
+  updatedBy?: string;
+  updatedAt?: string;
+}
+
+/** A store instance already authenticates as one deployment. A namespace is not tenant authorization. */
+export interface SecretAddress {
+  namespace: string;
+  path: string;
+}
+
+export interface SecretStoreCapabilities {
+  writable: boolean;
+  /** UTF-8 bytes, including any serialized credential bundle. */
+  maxBytes: number;
+  /** `coordinated` covers cooperating Sanoma writers only; `none` cannot ensure or replace safely. */
+  conditionalWrites: "atomic" | "coordinated" | "none";
+  deletion: "destroy" | "soft-delete" | "unsupported";
+  changeDetection: "read" | "watch";
+}
+
+export type SecretStoreErrorCode =
+  | "invalid_configuration"
+  | "unavailable"
+  | "denied"
+  | "conflict"
+  | "read_only"
+  | "unsupported"
+  | "too_large"
+  | "invalid_value";
+
+/** Intentionally carries no provider message, cause, path or value. */
+export class SecretStoreError extends Error {
+  readonly code: SecretStoreErrorCode;
+  readonly retryable: boolean;
+  constructor(code: SecretStoreErrorCode) {
+    super(`Secret store: ${code}`);
+    this.name = "SecretStoreError";
+    this.code = code;
+    this.retryable = code === "unavailable";
+  }
+}
+
+export interface SecretStore {
+  /** Non-secret adapter identifier, e.g. `postgres` or `aws-secrets-manager`. */
+  readonly id: string;
+  readonly capabilities: Readonly<SecretStoreCapabilities>;
+  /** Check scoped access without listing an account or returning secret material. */
+  validate(namespace: string): Promise<void>;
+  read(address: SecretAddress): Promise<SecretValue | undefined>;
+  /** null means create only. A string means replace only that exact current version. */
+  write(
+    address: SecretAddress,
+    value: string,
+    options: { expectedVersion: string | null; by: string },
+  ): Promise<SecretValue>;
+  /** Delete only the exact version; report the retention behavior advertised in capabilities. */
+  delete(address: SecretAddress, options: { expectedVersion: string; by: string }): Promise<void>;
+}
+
+export type SecretBinding =
+  | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never }
+  | { env: string; management?: "external"; path?: never; bootstrap?: never }
+  | { bootstrap: "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY"; management?: "external"; env?: never; path?: never };
+
+export interface SecretConfiguration {
+  /** Omitted: built-in encrypted Postgres, supplied by the runtime. */
+  store?: SecretStore;
+  /** Defaults to `default`. Choose a distinct namespace and identity for each deployment. */
+  namespace?: string;
+  /** Names without a binding resolve to the same name in this namespace. */
+  bindings?: Readonly<Record<string, SecretBinding>>;
+}
+
+export interface SecretLocation {
+  store: string;
+  namespace: string;
+  path: string;
+  management: "sanoma" | "external";
+}
+
+const errorCodes = new Set<string>([
+  "invalid_configuration",
+  "unavailable",
+  "denied",
+  "conflict",
+  "read_only",
+  "unsupported",
+  "too_large",
+  "invalid_value",
+]);
+const storeError = (error: unknown): error is SecretStoreError =>
+  typeof error === "object" &&
+  error !== null &&
+  (error as SecretStoreError).name === "SecretStoreError" &&
+  errorCodes.has((error as SecretStoreError).code);
+
+/** Provider failures are sanitized even when an SDK throws a credential-bearing response. */
+export async function secretStoreCall<T>(run: () => Promise<T>): Promise<T> {
+  try {
+    return await run();
+  } catch (error) {
+    if (storeError(error)) throw new SecretStoreError(error.code);
+    throw new SecretStoreError("unavailable");
+  }
+}
+
+const namePattern = /^[A-Z][A-Z0-9_]*$/;
+const environmentPattern = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const nonempty = (value: unknown): value is string =>
+  typeof value === "string" && value.trim().length > 0 && !value.includes("\0");
+
+/** Structural validation only: no secret reads, provider calls or environment access. */
+const invalid = () => {
+  throw new SecretStoreError("invalid_configuration");
+};
+export function checkSecretConfiguration(config: SecretConfiguration): void {
+  if (!config || typeof config !== "object" || Array.isArray(config)) invalid();
+  if (config.namespace !== undefined && !nonempty(config.namespace)) invalid();
+  if (config.store !== undefined) {
+    const s = config.store;
+    const c = s?.capabilities;
+    if (
+      !nonempty(s?.id) ||
+      !/^[a-z][a-z0-9-]{0,63}$/.test(s.id) ||
+      !c ||
+      typeof c.writable !== "boolean" ||
+      !Number.isSafeInteger(c.maxBytes) ||
+      c.maxBytes < 1 ||
+      !["atomic", "coordinated", "none"].includes(c.conditionalWrites) ||
+      !["destroy", "soft-delete", "unsupported"].includes(c.deletion) ||
+      !["read", "watch"].includes(c.changeDetection) ||
+      [s.validate, s.read, s.write, s.delete].some((fn) => typeof fn !== "function")
+    )
+      invalid();
+  }
+  if (
+    config.bindings !== undefined &&
+    (!config.bindings || typeof config.bindings !== "object" || Array.isArray(config.bindings))
+  )
+    invalid();
+  for (const [name, b] of Object.entries(config.bindings ?? {})) {
+    if (!namePattern.test(name) || !b || typeof b !== "object") invalid();
+    if (["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
+    if ("bootstrap" in b) {
+      if (
+        !["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(b.bootstrap!) ||
+        b.path !== undefined ||
+        b.env !== undefined ||
+        (b.management !== undefined && b.management !== "external")
+      )
+        invalid();
+    } else if ("env" in b) {
+      if (
+        typeof b.env !== "string" ||
+        !environmentPattern.test(b.env) ||
+        b.path !== undefined ||
+        (b.management !== undefined && b.management !== "external")
+      )
+        invalid();
+    } else if (!nonempty(b.path) || !["sanoma", "external"].includes(b.management)) invalid();
+  }
+}
+
+/** Enforces binding ownership before calling a provider; preserves the drivers' get/ensure interface. */
+export class SecretAccess {
+  readonly store: SecretStore;
+  readonly namespace: string;
+  private readonly bindings: Readonly<Record<string, SecretBinding>>;
+
+  private readonly env: (name: string) => string | undefined;
+
+  constructor(
+    config: SecretConfiguration,
+    defaultStore: SecretStore,
+    env: (name: string) => string | undefined = (name) => process.env[name],
+  ) {
+    this.env = env;
+    checkSecretConfiguration(config);
+    this.store = config.store ?? defaultStore;
+    checkSecretConfiguration({ store: this.store });
+    this.namespace = config.namespace ?? "default";
+    this.bindings = Object.fromEntries(
+      Object.entries(config.bindings ?? {}).map(([name, binding]) => [name, { ...binding }]),
+    );
+  }
+
+  location(name: string): SecretLocation {
+    if (!namePattern.test(name)) throw new SecretStoreError("invalid_configuration");
+    const binding = Object.hasOwn(this.bindings, name) ? this.bindings[name] : undefined;
+    if (binding?.bootstrap !== undefined)
+      return { store: "bootstrap", namespace: "", path: binding.bootstrap, management: "external" };
+    if (["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(name) && !binding)
+      throw new SecretStoreError("invalid_configuration");
+    if (binding?.env !== undefined)
+      return { store: "environment", namespace: "", path: binding.env, management: "external" };
+    return {
+      store: this.store.id,
+      namespace: this.namespace,
+      path: binding?.path ?? name,
+      management: binding?.management ?? "sanoma",
+    };
+  }
+
+  async validate(): Promise<void> {
+    await secretStoreCall(() => this.store.validate(this.namespace));
+  }
+
+  async read(name: string): Promise<SecretValue | undefined> {
+    const location = this.location(name);
+    if (location.store === "bootstrap" && location.namespace === "") {
+      const value = deploymentKey(location.path as "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY").toString("base64");
+      return { value, version: "bootstrap" };
+    }
+    if (location.store === "environment" && location.namespace === "") {
+      const value = this.env(location.path);
+      // No content-derived version (which would expose a hash of a low-entropy password).
+      return value === undefined ? undefined : { value, version: "environment" };
+    }
+    return secretStoreCall(() => this.store.read(location));
+  }
+
+  async get(name: string): Promise<string | undefined> {
+    return (await this.read(name))?.value;
+  }
+
+  async write(
+    name: string,
+    value: string,
+    options: { expectedVersion: string | null; by: string },
+  ): Promise<SecretValue> {
+    const location = this.writable(name);
+    if (Buffer.byteLength(value, "utf8") > this.store.capabilities.maxBytes) throw new SecretStoreError("too_large");
+    return secretStoreCall(() => this.store.write(location, value, options));
+  }
+
+  async delete(name: string, options: { expectedVersion: string; by: string }): Promise<void> {
+    const location = this.writable(name);
+    if (this.store.capabilities.deletion === "unsupported") throw new SecretStoreError("unsupported");
+    await secretStoreCall(() => this.store.delete(location, options));
+  }
+
+  async ensure(name: string, make: () => string): Promise<string> {
+    const stored = await this.read(name);
+    if (stored) return stored.value;
+    this.writable(name);
+    try {
+      return (await this.write(name, make(), { expectedVersion: null, by: "sanoma" })).value;
+    } catch (error) {
+      if (!storeError(error) || error.code !== "conflict") throw error;
+      const winner = await this.read(name);
+      if (winner) return winner.value;
+      throw error;
+    }
+  }
+
+  private writable(name: string): SecretLocation {
+    const location = this.location(name);
+    if (location.management === "external" || !this.store.capabilities.writable)
+      throw new SecretStoreError("read_only");
+    if (this.store.capabilities.conditionalWrites === "none") throw new SecretStoreError("unsupported");
+    return location;
+  }
+}
+
+/** Reference provider for tests. `atomic` is scoped to this shared in-process instance only. */
+const key = (a: SecretAddress) => JSON.stringify([a.namespace, a.path]);
+export function memorySecretStore(
+  options: { maxBytes?: number; writable?: boolean; deletion?: "destroy" | "soft-delete" } = {},
+): SecretStore {
+  const values = new Map<string, SecretValue>();
+  const retained = new Map<string, SecretValue>();
+  let generation = 0;
+  const capabilities: SecretStoreCapabilities = {
+    writable: options.writable ?? true,
+    maxBytes: options.maxBytes ?? 65_536,
+    conditionalWrites: "atomic",
+    deletion: options.deletion ?? "destroy",
+    changeDetection: "read",
+  };
+  const mutable = () => {
+    if (!capabilities.writable) throw new SecretStoreError("read_only");
+  };
+  return {
+    id: "memory",
+    capabilities: Object.freeze(capabilities),
+    async validate(namespace) {
+      if (!nonempty(namespace)) throw new SecretStoreError("invalid_configuration");
+    },
+    async read(address) {
+      const value = values.get(key(address));
+      return value && { ...value };
+    },
+    async write(address, value, { expectedVersion, by }) {
+      mutable();
+      if (Buffer.byteLength(value, "utf8") > capabilities.maxBytes) throw new SecretStoreError("too_large");
+      const current = values.get(key(address));
+      if ((current?.version ?? null) !== expectedVersion) throw new SecretStoreError("conflict");
+      const stored = { value, version: String(++generation), updatedBy: by, updatedAt: new Date().toISOString() };
+      values.set(key(address), stored);
+      return { ...stored };
+    },
+    async delete(address, { expectedVersion }) {
+      mutable();
+      if (values.get(key(address))?.version !== expectedVersion) throw new SecretStoreError("conflict");
+      if (capabilities.deletion === "soft-delete") retained.set(expectedVersion, values.get(key(address))!);
+      values.delete(key(address));
+    },
+  };
+}

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