@sanoma-ai/workflows 0.9.1 → 0.10.1

package/src/change.ts

@@ -320,6 +320,16 @@ export const ADMIN = "admin";
  */
 export const isRules = (path: string) =>
   path === "policies/" || path === "resources/people.ts" || /^apps\/[^/]+\/policies\/$/.test(path);
+/**
+ * Whether a data file's text imports the runtime's constructors, `sanoma` (by any local name, or
+ * the whole entry, `* as`, from which it can reach them): a file that may declare a person, agent
+ * or group, which `readPeople` loads and a change to which is a change to the rules. Read from the
+ * text, so a draft's file is told without running it.
+ */
+export const mayDeclarePeople = (text: string): boolean =>
+  /(?:\{[^}]*\bsanoma\b[^}]*\}|\*(?:\s*as\s+[\w$]+)?)\s*from\s*["'](?:sanoma|@sanoma-ai\/workflows)\/resources["']/.test(
+    text,
+  );
 /** The runtime rule's id, as a hold's `reasons` name it. */
 const RULES_WAIT_FOR_ADMIN = "sanoma:rules-wait-for-admin";
 

package/src/client.ts

@@ -1,4 +1,16 @@
-import { randomUUID } from "node:crypto";
+import {
+  connectionDriver,
+  connectionTargetSchema,
+  type ConnectionRef,
+  type ConnectionSnapshot,
+  type ConnectionTarget,
+  type ConnectionSetup,
+  type ConnectionCard,
+  type ConnectionRule,
+} from "./connection.ts";
+import { encodeCredentials, decodeCredentials, verifyAuthentication, AuthenticationError } from "./authentication.ts";
+
+import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { type DBOSClient, Error as DBOSErrors, type WorkflowStatusString } from "@dbos-inc/dbos-sdk";
 import type { Pool } from "pg";
@@ -16,7 +28,7 @@ import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call
 import { type Chats, chatStore } from "./chats.ts";
 import { collectionsDriver } from "./collection.ts";
 import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
-import { deleteCredential, storeCredential, storedCredentials, storedSecrets } from "./credentials.ts";
+import { configuredSecrets } from "./credentials.ts";
 import { dbosClient, lazyPool, type LazyPool } from "./db.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
 import { type ApprovalState, Principal, type WorkflowDefinition } from "./define.ts";
@@ -52,7 +64,7 @@ import type { CallContext, Driver, Op } from "./op.ts";
 import { allowAll, type RecordedDecision } from "./policy.ts";
 import { admit, readPeople } from "./resources.ts";
 import type { RunArgs, StartHold } from "./run.ts";
-import type { Secrets } from "./secret.ts";
+import { SecretStoreError, type SecretAccess, type SecretLocation } from "./secret-store.ts";
 import {
   BUILT_IN_WORKFLOWS,
   CALL_WORKFLOW,
@@ -206,6 +218,7 @@ export interface ChangesFilter {
 
 /** What `SanomaClient.call` takes besides the operation's id and its input. */
 export interface CallOptions {
+  connection?: ConnectionRef;
   /**
    * Who calls, by id, admitted as `startedBy` is: the policy decides as them, a write's record
    * names them, and a save's `updatedBy` is their id.
@@ -218,6 +231,15 @@ export interface CallOptions {
   id?: string;
 }
 
+/** A credential-free review shown before the user saves a connection. */
+export interface ConnectionReview extends ConnectionSetup {
+  authorization: string;
+  requestId: string;
+  account: string;
+  scopes: string[];
+  credentialVersion: string | null;
+  expiresAt?: number;
+}
 /** What `SanomaClient.connect` is given besides the config. */
 export interface ClientOptions {
   /**
@@ -243,7 +265,7 @@ export class SanomaClient {
   /** On the config's database, for the runtime's tables (the credentials, the chats): opened on first use. */
   private readonly pool: LazyPool;
   /** What a direct call's driver reads secrets from, as a worker's live driver does. */
-  private readonly storedSecrets: Secrets;
+  private readonly storedSecrets: SecretAccess;
   /** The operator agent's chats: their rows and their transcripts, in the config's database. */
   readonly chats: Chats;
   private readonly options: ClientOptions;
@@ -260,7 +282,7 @@ export class SanomaClient {
     this.options = options;
     this.audit = ownedLedger(config);
     this.pool = lazyPool(config.databaseUrl, "client");
-    this.storedSecrets = storedSecrets(() => this.db(), "sanoma");
+    this.storedSecrets = configuredSecrets(config.secrets, () => this.db());
     this.chats = chatStore(() => this.db());
   }
 
@@ -272,7 +294,14 @@ export class SanomaClient {
   static async connect(config: SanomaConfig, options: ClientOptions = {}): Promise<SanomaClient> {
     const resolved = resolveConfig(config);
     const dbos = await dbosClient(resolved.databaseUrl, resolved.appName);
-    return new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
+    const client = new SanomaClient(dbos, resolved, resolved.driversByVendor, options);
+    try {
+      await client.storedSecrets.validate();
+      return client;
+    } catch (error) {
+      await client.close();
+      throw error;
+    }
   }
 
   /**
@@ -414,14 +443,21 @@ export class SanomaClient {
     const fn = drivers.get(op.id);
     if (!fn) throw new SanomaError("invalid_input", `${op.id} has no driver: the connector package must attach one`);
     const parsed = parseOrThrow(op.input, input, `The input to ${op.id} does not match its schema`, { op: op.id });
+    const connection = await this.config.connections.select(op.vendor, options.connection, actor.id);
+    const selected = connection && {
+      $connection: connection.id,
+      vendor: connection.vendor,
+      revision: connection.revision,
+    };
     const runId = `direct:${actor.id}:${id}`;
     const heldId = `call:${actor.id}:${id}`;
-    const held: RunArgs = { input: { op: op.id, input }, startedBy: actor };
+    const held: RunArgs = { input: { op: op.id, input, ...(selected && { connection: selected }) }, startedBy: actor };
     const logged = recorded(op, parsed);
     const write = op.effect !== "read";
     // Only an id the caller gave can have been used: a write made, or held, with it settles it.
     if (write && options.id !== undefined) {
-      const first = (await this.recordedCall(runId, op.id, logged)) ?? (await this.heldCall(op.id, heldId, held));
+      const first =
+        (await this.recordedCall(runId, op.id, logged, connection)) ?? (await this.heldCall(op.id, heldId, held));
       if (first) return first.output;
     }
     const before = await beforeOf(policy, op, parsed, this.config.collections, (get, key) =>
@@ -431,7 +467,7 @@ export class SanomaClient {
       ),
     );
     const run = { id: runId, workflow: CALL_WORKFLOW, approvals: [] };
-    const decision = decideCall(policy, op, parsed, actor, run, before);
+    const decision = decideCall(policy, op, parsed, actor, run, { ...before, ...(connection && { connection }) });
     if (decision.kind === "deny") throw new PolicyDeniedError(op.id, decision.reason);
     if (decision.kind === "approve") {
       await this.start(CALL_WORKFLOW, held.input, { startedBy: actor, runId: heldId });
@@ -445,7 +481,10 @@ export class SanomaClient {
       attempt: 1,
       secrets: this.storedSecrets,
       by: actor.id,
+      principal: actor,
+      ...(connection && { connection }),
     };
+    await this.config.connections.assertCurrent(connection, actor.id);
     if (!write) return outputOf(op, () => fn(parsed, context));
     return this.directWrite({ op, fn, parsed, logged, actor, decision, context });
   }
@@ -469,13 +508,22 @@ export class SanomaClient {
     const { op, parsed, logged, actor, decision, context } = call;
     const { runId } = context;
     const { dataStore, collections, ledger } = this.config;
-    const conn = op.vendor === DATA_VENDOR && !ledger && dataStore ? await (await dataStore.db()).connect() : undefined;
+    const connectionMutation = op.id.startsWith("sanoma.connection.");
+    const transactionStore = connectionMutation
+      ? this.config.connectionPool
+      : op.vendor === DATA_VENDOR
+        ? dataStore
+        : undefined;
+    const conn = !ledger && transactionStore ? await (await transactionStore.db()).connect() : undefined;
     let broken: Error | undefined;
     try {
       await conn?.query("BEGIN");
-      // On the transaction's connection, the collection's own driver: it has no `env` to guard.
+      // The metadata or collection driver shares the ledger transaction; neither has an env guard.
       const fn = conn
-        ? collectionsDriver([collections.get(op.resource)!], { db: async () => conn }).ops[`${op.resource}.${op.name}`]!
+        ? (connectionMutation
+            ? connectionDriver(this.config.connections.onDatabase(conn))
+            : collectionsDriver([collections.get(op.resource)!], { db: async () => conn })
+          ).ops[`${op.resource}.${op.name}`]!
         : call.fn;
       const at = Date.now();
       const record = (outcome: { output: unknown } | { error: ErrorInfo }): LedgerRecord => ({
@@ -492,6 +540,7 @@ export class SanomaClient {
         effect: op.effect,
         input: logged,
         decision,
+        ...(context.connection && { connection: context.connection }),
         ...outcome,
         durationMs: Date.now() - at,
       });
@@ -513,7 +562,7 @@ export class SanomaClient {
         return output;
       }
       await conn.query("ROLLBACK");
-      return (await this.recordedCall(runId, op.id, logged))!.output;
+      return (await this.recordedCall(runId, op.id, logged, context.connection))!.output;
     } catch (err) {
       await conn?.query("ROLLBACK").catch((e: Error) => (broken = e));
       throw err;
@@ -526,10 +575,19 @@ export class SanomaClient {
    * What the direct write recorded as `runId` returned, when one did: refused (`invalid_input`)
    * when it was of another operation or input, and its failure again (`driver_failed`) when it failed.
    */
-  private async recordedCall(runId: string, opId: string, input: unknown): Promise<{ output: unknown } | undefined> {
+  private async recordedCall(
+    runId: string,
+    opId: string,
+    input: unknown,
+    connection?: ConnectionSnapshot,
+  ): Promise<{ output: unknown } | undefined> {
     const first = (await this.audit.store.read(runId)).find((r) => r.type === "op.called");
     if (!first) return undefined;
-    const differs = [...(first.op === opId ? [] : ["op"]), ...(sameJson(first.input, input) ? [] : ["input"])];
+    const differs = [
+      ...(first.op === opId ? [] : ["op"]),
+      ...(sameJson(first.input, input) ? [] : ["input"]),
+      ...(sameJson(first.connection ?? null, connection ?? null) ? [] : ["connection"]),
+    ];
     if (differs.length) {
       throw new SanomaError(
         "invalid_input",
@@ -1061,7 +1119,8 @@ export class SanomaClient {
         issues: [{ path: ["value"], message: problem, code: "custom" }],
       });
     }
-    await storeCredential(await this.db(), { name, value, setBy });
+    const current = await this.storedSecrets.read(name);
+    await this.storedSecrets.write(name, value, { expectedVersion: current?.version ?? null, by: setBy });
   }
 
   /**
@@ -1072,7 +1131,8 @@ export class SanomaClient {
   async clearCredential(name: string, options: { by: string }): Promise<void> {
     await this.admittedBy(options);
     this.declared(name, () => undefined);
-    await deleteCredential(await this.db(), name);
+    const current = await this.storedSecrets.read(name);
+    if (current) await this.storedSecrets.delete(name, { expectedVersion: current.version, by: options.by });
   }
 
   /**
@@ -1091,49 +1151,288 @@ export class SanomaClient {
       const path = VARIABLE.test(name) ? "value" : "name";
       throw new SanomaError("invalid_input", problem, { issues: [{ path: [path], message: problem, code: "custom" }] });
     }
-    await storeCredential(await this.db(), { name, value, setBy });
+    const current = await this.storedSecrets.read(name);
+    await this.storedSecrets.write(name, value, { expectedVersion: current?.version ?? null, by: setBy });
+  }
+
+  /** Removes a logical secret from the selected store; external bindings remain read-only. */
+  async clearSecret(name: string, options: { by: string }): Promise<void> {
+    const by = await this.admittedBy(options);
+    if (!VARIABLE.test(name)) {
+      const message = "That is not a variable name";
+      throw new SanomaError("invalid_input", message, {
+        issues: [{ path: ["name"], message, code: "custom" }],
+      });
+    }
+    const current = await this.storedSecrets.read(name);
+    if (current) await this.storedSecrets.delete(name, { expectedVersion: current.version, by });
+  }
+
+  private connectionAuthorization(): string {
+    return createHash("sha256")
+      .update(
+        JSON.stringify({
+          version: this.config.version,
+          policies: this.config.policies,
+          problems: this.config.policyProblems,
+        }),
+      )
+      .digest("hex");
+  }
+
+  /** Safe account cards, scoped to the admitted principal. No provider or secret reads. */
+  async connections(options: { actor: Principal | string }): Promise<ConnectionCard[]> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    return this.config.connections.cards(actor.id);
+  }
+
+  /** Creation choices are scoped by code to the admitted person's current groups. */
+  async connectionRules(options: { actor: Principal | string }): Promise<{ id: string; rule: ConnectionRule }[]> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    return [...this.config.connections.catalog.rules]
+      .filter(([, rule]) =>
+        rule.createBy.some((by) => (typeof by === "string" ? by === actor.id : actor.groups?.includes(by.group))),
+      )
+      .map(([id, rule]) => ({ id, rule }));
+  }
+
+  /** Readiness only, without reading or listing any credential. The adapter's bootstrap
+   * authority is checked by validate; provider details never escape this boundary. */
+  async secretStoreStatus(options: { actor: Principal | string }) {
+    await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    const { store, namespace } = this.storedSecrets;
+    let problem: string | undefined;
+    try {
+      await this.storedSecrets.validate();
+    } catch (error) {
+      problem = (error as SecretStoreError).code;
+    }
+    return {
+      store: store.id,
+      namespace,
+      capabilities: { ...store.capabilities },
+      ready: !problem,
+      ...(problem && { problem }),
+    };
+  }
+
+  /** Secure intake endpoint, never a workflow operation. Only its metadata-only prepare gate
+   * enters policy/approval history; callers keep the value in a password form while reviewing. */
+  async previewConnection(
+    target: ConnectionTarget,
+    credentials: unknown,
+    options: { actor: Principal | string; id: string },
+  ): Promise<ConnectionReview> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    const id = parseOrThrow(z.string().min(1).max(200), options.id, "Name the setup request");
+    target = parseOrThrow(connectionTargetSchema, target, "Select a declared connection or creation rule");
+    const setup = await this.config.connections.setup(target, actor, id);
+    const authorized = (await this.call(
+      "sanoma.connection.prepare",
+      {
+        target,
+        requestId: id,
+        definition: setup.definition,
+        authorization: this.connectionAuthorization(),
+      },
+      { actor, id: `connection-prepare:${id}` },
+    )) as ConnectionSetup;
+    if (!isDeepStrictEqual(authorized, setup))
+      throw new SanomaError("invalid_input", "The connection changed; start a new review");
+    const method = this.config.connections.catalog.methods.get(setup.vendor)![setup.method]!;
+    const external =
+      method.kind !== "workload-identity" &&
+      (setup.location?.management === "external" || !this.storedSecrets.store.capabilities.writable);
+    if (
+      !external &&
+      method.kind !== "workload-identity" &&
+      this.storedSecrets.store.capabilities.conditionalWrites === "none"
+    )
+      throw new SecretStoreError("unsupported");
+    if (credentials !== undefined && (external || method.kind === "workload-identity"))
+      throw new SecretStoreError("read_only");
+    const existing = setup.credential ? await this.storedSecrets.read(setup.credential) : undefined;
+    if (external && !existing) throw new SecretStoreError("unavailable");
+    const encoded =
+      method.kind === "workload-identity"
+        ? undefined
+        : external
+          ? existing!.value
+          : encodeCredentials(method, credentials);
+    const identity = await verifyAuthentication(
+      method,
+      encoded === undefined ? undefined : decodeCredentials(method, encoded),
+    );
+    if (setup.expectedAccount && setup.expectedAccount !== identity.account)
+      throw new AuthenticationError("wrong_account");
+    if (setup.requiredScopes.some((scope) => !identity.scopes.includes(scope)))
+      throw new AuthenticationError("scope_changed");
+    return {
+      ...setup,
+      requestId: id,
+      authorization: this.connectionAuthorization(),
+      account: identity.account,
+      scopes: [...identity.scopes],
+      credentialVersion: existing?.version ?? null,
+      ...(identity.expiresAt !== undefined && { expiresAt: identity.expiresAt }),
+    };
+  }
+
+  /** Reverify the reviewed authority, reserve its metadata under policy, then write the bundle
+   * outside durable execution. Activation has its own policy gate and verifies what was saved. */
+  async connectConnection(
+    review: ConnectionReview,
+    credentials: unknown,
+    options: { actor: Principal | string },
+  ): Promise<ConnectionSnapshot> {
+    const actor = await this.admitted(parseOrThrow(PrincipalOrId, options.actor, "Name the principal"));
+    if (review.authorization !== this.connectionAuthorization())
+      throw new SanomaError("invalid_input", "The policy changed; start a new connection review");
+    const setup = await this.config.connections.setup(review.target, actor, review.requestId);
+    for (const field of ["id", "vendor", "method", "definition", "credential", "location"] as const) {
+      if (!isDeepStrictEqual(setup[field], review[field]))
+        throw new SanomaError("invalid_input", "The destination changed; review it again before saving");
+    }
+    // Reuse only the metadata gate, never a cached credential or verification result.
+    await this.call(
+      "sanoma.connection.prepare",
+      {
+        target: review.target,
+        requestId: review.requestId,
+        definition: setup.definition,
+        authorization: review.authorization,
+      },
+      { actor, id: `connection-prepare:${review.requestId}` },
+    );
+    const method = this.config.connections.catalog.methods.get(setup.vendor)![setup.method]!;
+    const external =
+      method.kind !== "workload-identity" &&
+      (setup.location?.management === "external" || !this.storedSecrets.store.capabilities.writable);
+    if (
+      !external &&
+      method.kind !== "workload-identity" &&
+      this.storedSecrets.store.capabilities.conditionalWrites === "none"
+    )
+      throw new SecretStoreError("unsupported");
+    if (credentials !== undefined && (external || method.kind === "workload-identity"))
+      throw new SecretStoreError("read_only");
+    const existing = setup.credential ? await this.storedSecrets.read(setup.credential) : undefined;
+    if (external && (!existing || existing.version !== review.credentialVersion))
+      throw new SecretStoreError("conflict");
+    if (setup.expectedRevision === review.expectedRevision && (existing?.version ?? null) !== review.credentialVersion)
+      throw new SecretStoreError("conflict");
+    const encoded =
+      method.kind === "workload-identity"
+        ? undefined
+        : external
+          ? existing!.value
+          : encodeCredentials(method, credentials);
+    const identity = await verifyAuthentication(
+      method,
+      encoded === undefined ? undefined : decodeCredentials(method, encoded),
+    );
+    if (identity.account !== review.account) throw new AuthenticationError("wrong_account");
+    if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(review.scopes)].toSorted()))
+      throw new AuthenticationError("scope_changed");
+    const selected = (await this.call(
+      "sanoma.connection.configure",
+      {
+        target: review.target,
+        requestId: review.requestId,
+        expectedRevision: review.expectedRevision,
+        definition: review.definition,
+        account: identity.account,
+        scopes: [...identity.scopes],
+      },
+      { actor, id: `connection-configure:${review.requestId}` },
+    )) as ConnectionSnapshot;
+    const ref = { vendor: selected.vendor, $connection: selected.id };
+    if (
+      (await this.config.connections.setupState(selected, actor)) === "pending" &&
+      !external &&
+      encoded !== undefined
+    ) {
+      let written = false;
+      try {
+        const receipt = await this.config.connections.storedVersion(selected.id, selected.revision);
+        if (receipt) {
+          if (existing?.version !== receipt || existing.value !== encoded) throw new SecretStoreError("conflict");
+        } else {
+          const stored = await this.storedSecrets.write(setup.credential!, encoded, {
+            expectedVersion: review.credentialVersion,
+            by: actor.id,
+          });
+          written = true;
+          await this.config.connections.recordStoredVersion(selected.id, selected.revision, stored.version);
+        }
+      } catch (error) {
+        if (written || (error as { code?: string })?.code === "unavailable")
+          await this.config.connections.uncertain(ref, selected.revision, actor.id);
+        throw error;
+      }
+    }
+    const connected = (await this.call(
+      "sanoma.connection.activate",
+      {
+        connection: ref,
+        expectedRevision: selected.revision,
+      },
+      { actor, id: `connection-activate:${review.requestId}` },
+    )) as ConnectionSnapshot;
+    await this.config.connections.assertCurrent(connected, actor.id);
+    return connected;
   }
 
   /**
-   * The values of these secrets, as a driver's `secrets.get` reads them: this process's
-   * environment, which wins, else the stored value, with who set it and when. A name with neither
-   * is left out. For server code: a page is told whether one is set, never its value.
+   * Values resolved through the selected store and explicit bindings, with version and change
+   * metadata. Missing names are left out. Server code only; pages receive status, never values.
    */
   async secrets(names: readonly string[]): Promise<Map<string, StoredSecret>> {
-    const rows = await storedCredentials(await this.db(), names);
     const found = new Map<string, StoredSecret>();
     for (const name of names) {
-      const env = process.env[name];
-      const row = rows.get(name);
-      if (env && env !== row?.value) found.set(name, { value: env, source: "environment" });
-      else if (row) found.set(name, { ...row, source: "stored" });
+      const row = await this.storedSecrets.read(name);
+      const location = this.storedSecrets.location(name);
+      if (row)
+        found.set(name, {
+          value: row.value,
+          source: location.store === "environment" ? "environment" : "stored",
+          version: row.version,
+          location,
+          ...(row.updatedBy && { setBy: row.updatedBy }),
+          ...(row.updatedAt && { setAt: row.updatedAt }),
+        });
     }
     return found;
   }
 
-  /**
-   * Each vendor's declared variables and their statuses now: from this process's environment,
-   * which wins, else from the stored credentials, with `source` saying which (a value equal to
-   * the stored one, as a worker in this process loads it, is `stored`), and who set a stored one
-   * and when. Never a value.
-   */
+  /** Non-secret statuses for the selected store and declared bindings. */
   async credentials(): Promise<Map<string, CredentialStatus[]>> {
     const names = [...credentialsOf(this.drivers, () => undefined).values()].flat().map((c) => c.name);
-    if (!names.length) return new Map();
-    const rows = await storedCredentials(await this.db(), names);
-    const statuses = credentialsOf(this.drivers, (name) => process.env[name] || rows.get(name)?.value);
-    const sourced = (c: CredentialStatus): CredentialStatus => {
-      const row = rows.get(c.name);
-      const env = process.env[c.name];
-      // A worker in this process loads the stored values into its environment: those are stored.
-      if (env && env !== row?.value) return { ...c, source: "environment" };
-      return row ? { ...c, source: "stored", setBy: row.setBy, setAt: row.setAt } : c;
-    };
-    return new Map([...statuses].map(([vendor, list]) => [vendor, list.map(sourced)]));
+    const rows = await this.secrets(names);
+    const statuses = credentialsOf(this.drivers, (name) => rows.get(name)?.value);
+    return new Map(
+      [...statuses].map(([vendor, list]) => [
+        vendor,
+        list.map((c) => {
+          const row = rows.get(c.name);
+          return {
+            ...c,
+            location: this.storedSecrets.location(c.name),
+            ...(row && { source: row.source, setBy: row.setBy, setAt: row.setAt }),
+          };
+        }),
+      ]),
+    );
   }
 
   async close() {
-    await Promise.all([this.dbos.destroy(), this.pool.close(), this.audit.close(), this.config.dataStore?.close()]);
+    await Promise.all([
+      this.dbos.destroy(),
+      this.pool.close(),
+      this.audit.close(),
+      this.config.dataStore?.close(),
+      this.config.connectionPool.close(),
+    ]);
   }
 
   /**
@@ -1285,6 +1584,8 @@ const sameJson = (a: unknown, b: unknown): boolean => isDeepStrictEqual(asJson(a
 
 /** A secret's value as `SanomaClient.secrets` reads it, and where from. */
 export interface StoredSecret {
+  version?: string;
+  location?: SecretLocation;
   value: string;
   source: "environment" | "stored";
   /** Who stored it (`setSecret`'s `by`), and when, as an ISO 8601 time. */
@@ -1293,7 +1594,7 @@ export interface StoredSecret {
 }
 
 /** What an environment variable's name looks like. */
-const VARIABLE = /^[A-Z_][A-Z0-9_]*$/;
+const VARIABLE = /^[A-Z][A-Z0-9_]*$/;
 
 const alreadyDecided = (runId: string, a: ApprovalState) =>
   new SanomaError(

package/src/collection.ts

@@ -99,10 +99,18 @@ export function collection<
   const F extends Record<string, Field>,
   const K extends RequiredTextKeys<F>,
 >(declaration: { name: N; key: K; fields: F; title?: string }): Collection<N, F, K> {
+  // Frame 2 of `callerFile` is this function's caller: the data file.
+  return collectionIn(appOfFile(callerFile()), declaration);
+}
+
+/** `collection()` in the app `app` names (none for the root's): what the loader's `collection` calls, knowing the file itself. */
+export function collectionIn<
+  const N extends string,
+  const F extends Record<string, Field>,
+  const K extends RequiredTextKeys<F>,
+>(app: string | undefined, declaration: { name: N; key: K; fields: F; title?: string }): Collection<N, F, K> {
   checkCollection(declaration);
   const { key, fields, title } = declaration;
-  // Frame 2 of `callerFile` is this function's caller: the data file.
-  const app = appOfFile(callerFile());
   const name = qualified(app, declaration.name);
   const record = z.strictObject(
     Object.fromEntries(