@sanoma-ai/workflows 0.1.0 → 0.2.0

package/src/client.ts

@@ -9,6 +9,7 @@ import { deleteCredential, storeCredential, storedCredentials } from "./credenti
 import { dbosClient, lazyPool, type LazyPool } from "./db.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
 import { type ApprovalState, notApprover, Principal, type WorkflowDefinition } from "./define.ts";
+import { APPLY_WORKFLOW, type ApplyInput, type ApplyReport } from "./apply.ts";
 import { DRIFT_WORKFLOW, type DriftReport } from "./drift.ts";
 import { parseOrThrow, SanomaError } from "./errors.ts";
 import { type LedgerRecord, type OwnedLedger, ownedLedger } from "./ledger.ts";
@@ -335,31 +336,55 @@ export class SanomaClient {
    * `invalid_input` when the config's connectors declare no resource types, so it has none.
    */
   async drift(options: StartOptions): Promise<string> {
-    const drift = this.config.workflows.get(DRIFT_WORKFLOW);
-    if (!drift) {
-      throw new SanomaError(
-        "invalid_input",
-        "The config's connectors declare no resource types, so there is nothing to check for drift",
-      );
-    }
-    return this.start(drift, {}, options);
+    return this.start(this.builtIn(DRIFT_WORKFLOW), {}, options);
+  }
+
+  /** The report of a drift run once it ends: as `applyReport` for apply. */
+  async driftReport(runId: string): Promise<DriftReport> {
+    return (await this.reportOf(runId, DRIFT_WORKFLOW)) as DriftReport;
+  }
+
+  /**
+   * Starts the built-in apply workflow, which reads the config's data files itself, with `input`
+   * (`only`, `bind`, `answers`; `{}` for all). Returns the run id; `applyReport` waits for its
+   * report. Throws `invalid_input` when the config's connectors declare no resource types.
+   */
+  async apply(input: ApplyInput, options: StartOptions): Promise<string> {
+    return this.start(this.builtIn(APPLY_WORKFLOW), input, options);
   }
 
   /**
-   * The report of a drift run once it ends. Throws `run_not_found`, `invalid_input` for another
+   * The report of an apply run once it ends. Throws `run_not_found`, `invalid_input` for another
    * workflow's run, the run's error when it failed, and `run_running` when it has not ended
    * within 30 s.
    */
-  async driftReport(runId: string): Promise<DriftReport> {
+  async applyReport(runId: string): Promise<ApplyReport> {
+    return (await this.reportOf(runId, APPLY_WORKFLOW)) as ApplyReport;
+  }
+
+  /** The built-in workflow `name`; `invalid_input` when the config has none, as its connectors declare no resource types. */
+  private builtIn(name: string) {
+    const workflow = this.config.workflows.get(name);
+    if (!workflow) {
+      throw new SanomaError(
+        "invalid_input",
+        `The config's connectors declare no resource types, so it has no built-in ${name} workflow`,
+      );
+    }
+    return workflow;
+  }
+
+  /** The output of a run of the built-in `workflow` once it ends. */
+  private async reportOf(runId: string, workflow: string): Promise<unknown> {
     const row = await this.mustExist(runId, { loadOutput: true });
-    if (row.workflowName !== DRIFT_WORKFLOW) {
-      throw new SanomaError("invalid_input", `Run ${runId} is a run of ${row.workflowName}, not of ${DRIFT_WORKFLOW}`, {
+    if (row.workflowName !== workflow) {
+      throw new SanomaError("invalid_input", `Run ${runId} is a run of ${row.workflowName}, not of ${workflow}`, {
         runId,
         workflow: row.workflowName,
       });
     }
     // A finished run's report came with its row; else wait for the run.
-    return (row.status === "SUCCESS" ? row.output : await this.awaitResult(runId, 30_000)) as DriftReport;
+    return row.status === "SUCCESS" ? row.output : await this.awaitResult(runId, 30_000);
   }
 
   /**
@@ -395,6 +420,42 @@ export class SanomaClient {
     await deleteCredential(await this.credentialsDb(), name);
   }
 
+  /**
+   * Stores a secret as `by`, and tells the workers: a value under any variable's name, declared by
+   * a driver or not, such as a data file's `secret("NAME")` or the app's own (its GitHub App's
+   * keys). A name a driver declares is checked as `setCredential` checks it; any other name must
+   * look like a variable's, and the value must not be empty (`invalid_input`, never the value).
+   */
+  async setSecret(name: string, value: string, options: { by: string }): Promise<void> {
+    if ([...credentialsOf(this.drivers, () => undefined).values()].flat().some((c) => c.name === name)) {
+      return this.setCredential(name, value, options);
+    }
+    const setBy = actorOf(options);
+    const problem = !VARIABLE.test(name) ? "That is not a variable name" : !value ? "Enter a value" : undefined;
+    if (problem) {
+      const path = VARIABLE.test(name) ? "value" : "name";
+      throw new SanomaError("invalid_input", problem, { issues: [{ path: [path], message: problem, code: "custom" }] });
+    }
+    await storeCredential(await this.credentialsDb(), { name, value, setBy });
+  }
+
+  /**
+   * 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.
+   */
+  async secrets(names: readonly string[]): Promise<Map<string, StoredSecret>> {
+    const rows = await storedCredentials(await this.credentialsDb(), 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" });
+    }
+    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
@@ -518,6 +579,15 @@ const asJson = (v: unknown): unknown => (v === undefined ? undefined : JSON.pars
 /** True when the two are the same JSON, whatever the order of their keys. */
 const sameJson = (a: unknown, b: unknown): boolean => isDeepStrictEqual(asJson(a), asJson(b));
 
+/** A secret's value as `SanomaClient.secrets` reads it, and where from. */
+export interface StoredSecret {
+  value: string;
+  source: "environment" | "stored";
+  /** Who stored it (`setSecret`'s `by`), and when, as an ISO 8601 time. */
+  setBy?: string;
+  setAt?: string;
+}
+
 /** What an environment variable's name looks like. */
 const VARIABLE = /^[A-Z_][A-Z0-9_]*$/;
 

package/src/config.ts

@@ -2,8 +2,10 @@ import { existsSync, readFileSync, statSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { DBOS } from "@dbos-inc/dbos-sdk";
+import { type ApplyDeclared, applyWorkflow } from "./apply.ts";
+import { applySteps } from "./apply-steps.ts";
 import { callerFile, type Use, type WorkflowDefinition } from "./define.ts";
-import { DRIFT_WORKFLOW, type DriftDeclared, driftWorkflow } from "./drift.ts";
+import { DRIFT_WORKFLOW, driftWorkflow } from "./drift.ts";
 import { statusesOf, unconfigured } from "./env.ts";
 import type { Fake } from "./fake.ts";
 import type { LedgerStore } from "./ledger.ts";
@@ -21,7 +23,9 @@ import {
   VENDOR,
 } from "./op.ts";
 import type { Policy } from "./policy.ts";
-import { type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
+import { isChangeOp, type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
+import { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS } from "./shared.ts";
+import { sourceDriver, sourceOps } from "./source.ts";
 import type { Steps } from "./steps.ts";
 import { computeVersion } from "./version.ts";
 
@@ -86,7 +90,7 @@ export interface ResolvedConfig {
   version: string;
   /** The DBOS queue runs are started on: `sanoma:<appName>`. */
   queueName: string;
-  /** The operations the connectors declare, by id. */
+  /** The operations the connectors declare, by id, and the built-in `sanoma.source.resolve` when one declares a host type. */
   ops: Map<string, Op>;
   /** The drivers' functions, by operation id, each guarded by its driver's `env` (`indexDrivers`). */
   drivers: Map<string, DriverFn>;
@@ -104,8 +108,8 @@ export interface ResolvedConfig {
   /** The steps scenarios can use besides the generic ones: each connector's (`withSetup`), once each, then the config's own. */
   steps: readonly Steps[];
   /**
-   * By name; each checked against `ops` and `drivers`. The config's, and the built-in `drift`
-   * (`DRIFT_WORKFLOW`) when its connectors declare resource types.
+   * By name; each checked against `ops` and `drivers`. The config's, and the built-ins `drift`
+   * (`DRIFT_WORKFLOW`) and `apply` (`APPLY_WORKFLOW`) when its connectors declare resource types.
    */
   workflows: Map<string, WorkflowDefinition<any, any>>;
   policy: Policy;
@@ -185,18 +189,19 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const root = rootOf(config);
   const appName = appNameAt(root);
   const scenarios = scenariosAt(root);
-  const ops = indexConnectors(config.connectors);
+  const types = resourceTypesOf(config.connectors);
+  // Built-in: `sanoma.source.resolve`, which apply and drift call for a host's revision.
+  const hosts = [...types.values()].some((type) => type.host);
+  const ops = indexConnectors([...config.connectors, ...(hosts ? [sourceOps] : [])]);
   const driversByVendor = new Map([...makersOf(config.connectors, "driver")].map(([vendor, make]) => [vendor, make()]));
-  const drivers = indexDrivers([...driversByVendor.values()], ops);
+  const drivers = indexDrivers([...driversByVendor.values(), ...(hosts ? [sourceDriver] : [])], ops);
   const fakes = makersOf(config.connectors, "fake");
   const names = new Map<string, WorkflowDefinition<any, any>>();
   for (const wf of config.workflows) {
-    if (wf.name === DRIFT_WORKFLOW) {
-      throw new Error(
-        `A workflow is named "${DRIFT_WORKFLOW}", the name of the built-in drift workflow; name it otherwise`,
-      );
+    if (BUILT_IN_WORKFLOWS.has(wf.name)) {
+      throw new Error(`A workflow is named "${wf.name}", the name of a built-in workflow; name it otherwise`);
     }
-    checkUses(wf, ops, drivers);
+    checkUses(wf, ops, drivers, types);
     const other = names.get(wf.name);
     if (other && other !== wf) {
       throw new Error(
@@ -205,12 +210,14 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     }
     names.set(wf.name, wf);
   }
-  // Built-in: checking the resources the data files declare against their vendors.
-  const types = resourceTypesOf(config.connectors);
+  // Built-in: checking the resources the data files declare against their vendors, and applying them.
   if (types.size) {
-    const declared = () =>
-      DBOS.runStep(() => readDeclared(root, config.connectors, types), { name: "drift:data-files" });
-    names.set(DRIFT_WORKFLOW, driftWorkflow(types, ops, drivers, declared));
+    const read = () => readDeclared(root, config.connectors, types);
+    names.set(
+      DRIFT_WORKFLOW,
+      driftWorkflow(types, ops, drivers, () => DBOS.runStep(read, { name: "drift:data-files" })),
+    );
+    names.set(APPLY_WORKFLOW, applyWorkflow(types, ops, drivers, applySteps(appName, root, read)));
   }
   return {
     appName,
@@ -280,26 +287,32 @@ function scenariosAt(root: string | undefined): URL | undefined {
 }
 
 /**
- * The data files under `root`, as a drift run records them: each resource without its write-only
- * values, which a run never compares and never records, and the problems.
+ * The data files under `root` and the lockfile beside them, in one read, as a drift or apply run
+ * records them: each resource with its binding, without its write-only values (a secret marker
+ * names one, and stays), which a run never compares and never records, the bindings, the orphans
+ * and the problems.
  */
 async function readDeclared(
   root: string | undefined,
   connectors: readonly Connector<any, any>[],
   types: ReadonlyMap<string, Resource>,
-): Promise<DriftDeclared> {
-  // Loaded when a drift run reads the files, not with the worker: the reader parses with oxc-parser.
+): Promise<Omit<ApplyDeclared, "rebinds">> {
+  // Loaded when a run reads the files, not with the worker: the reader parses with oxc-parser.
   const { readDataFiles } = await import("./resources.ts");
-  const { resources, problems } = readDataFiles(root, connectors, types);
+  const { resources, bindings, orphans, problems } = readDataFiles(root, connectors, types);
   return {
-    resources: resources.map(({ id, vendor, type, name, desired, refs }) => ({
+    resources: resources.map(({ id, vendor, type, name, identity, binding, desired, refs }) => ({
       id,
       vendor,
       type,
       name,
+      ...(identity !== undefined && { identity }),
+      ...(binding !== undefined && { binding }),
       desired: withoutWriteOnly(types.get(`${vendor}.${type}`)!.fields, desired),
       refs,
     })),
+    bindings,
+    orphans,
     problems,
   };
 }
@@ -362,13 +375,23 @@ function guarded(vendor: string, env: DriverEnv, fn: DriverFn): DriverFn {
  * Every operation a workflow uses must be one the config's connectors declare, with a driver.
  * The workflow normally imports the same connector object; a copy is accepted only if it
  * declares the same effect and retry setting, and the worker's declaration is used either way.
+ * None may change a declared resource (`isChangeOp`): only the built-in apply workflow does.
  */
-function checkUses(wf: WorkflowDefinition<any, any>, ops: Map<string, Op>, impls: Map<string, unknown>) {
+function checkUses(
+  wf: WorkflowDefinition<any, any>,
+  ops: Map<string, Op>,
+  impls: Map<string, unknown>,
+  types: ReadonlyMap<string, Resource>,
+) {
   const problems: string[] = [];
   for (const op of (wf.uses as readonly Use[]).filter(isOp)) {
     const known = ops.get(op.id);
     if (!known) problems.push(`${op.id} is not declared by any connector in \`connectors\``);
-    else if (known !== op && (known.effect !== op.effect || known.idempotent !== op.idempotent)) {
+    else if (isChangeOp(known, types)) {
+      problems.push(
+        `${op.id} changes a declared resource, which only ${APPLY_WORKFLOW} does: change the data file instead`,
+      );
+    } else if (known !== op && (known.effect !== op.effect || known.idempotent !== op.idempotent)) {
       problems.push(
         `${op.id} is declared with effect "${op.effect}"${op.idempotent ? " (idempotent)" : ""}, ` +
           `but its connector says "${known.effect}"${known.idempotent ? " (idempotent)" : ""}`,

package/src/credentials.ts

@@ -1,20 +1,73 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import { setTimeout as sleep } from "node:timers/promises";
 import { Client } from "pg";
 import { credentialsOf } from "./env.ts";
 import { CREDENTIALS_TABLE as TABLE, type Db, prepareDatabase } from "./db.ts";
 import { info, warn } from "./log.ts";
 import type { Driver } from "./op.ts";
+import type { Secrets } from "./secret.ts";
 import { errorMessage } from "./shared.ts";
 
 // Where the credentials set from the app live: one table in the config's database, beside DBOS's
 // own (made by `prepareDatabase` in db.ts). A value is read here only, by the worker to load it
-// into its environment and by the client to check it, and leaves neither. The write
-// (`storeCredential`) and the read (`storedCredentials`) are the only places that touch `value`,
-// so a hosted deployment's encryption goes there.
+// into its environment or hand it to a driver (`storedSecrets`) and by the client to check it,
+// and leaves none of them. The write (`storeCredential`, `ensureCredential`) and the read
+// (`storedCredentials`) are the only places that touch `value`, which holds it encrypted
+// (`encrypt`) under `SANOMA_SECRETS_KEY`.
 
 /** Where a change is announced, with the variable's name as the payload. */
 const CHANNEL = "sanoma_credentials";
 
+/** The variable holding the key the stored values are encrypted with: 32 bytes, base64. */
+export const SECRETS_KEY = "SANOMA_SECRETS_KEY";
+
+/** What starts an encrypted value; a value without it is a plaintext one stored before encryption, read as it is. */
+const V1 = "v1:";
+const CIPHER = "aes-256-gcm";
+const TAG_BYTES = 16;
+
+/** The key from the environment, or an error naming the variable. */
+function secretsKey(): Buffer {
+  const text = process.env[SECRETS_KEY];
+  if (!text) {
+    throw new Error(
+      `${SECRETS_KEY} is not set: it encrypts the stored credentials; set it to 32 random bytes, base64 (\`openssl rand -base64 32\`)`,
+    );
+  }
+  const key = Buffer.from(text, "base64");
+  if (key.length !== 32) throw new Error(`${SECRETS_KEY} must be 32 bytes, base64; it is ${key.length} bytes`);
+  return key;
+}
+
+/**
+ * `name`'s value encrypted for the table: `v1:<iv, base64>:<ciphertext and tag, base64>`,
+ * AES-256-GCM, with the name as associated data, so a value moved to another row does not decrypt.
+ */
+export function encrypt(name: string, value: string): string {
+  const iv = randomBytes(12);
+  const cipher = createCipheriv(CIPHER, secretsKey(), iv).setAAD(Buffer.from(name));
+  const sealed = Buffer.concat([cipher.update(value, "utf8"), cipher.final(), cipher.getAuthTag()]);
+  return `${V1}${iv.toString("base64")}:${sealed.toString("base64")}`;
+}
+
+/** The value `name`'s row holds: decrypted, or a plaintext one as it is (it is encrypted on its next write). */
+export function decrypt(name: string, stored: string): string {
+  if (!stored.startsWith(V1)) return stored;
+  const key = secretsKey();
+  const [iv = "", body = ""] = stored.slice(V1.length).split(":");
+  const sealed = Buffer.from(body, "base64");
+  try {
+    const decipher = createDecipheriv(CIPHER, key, Buffer.from(iv, "base64")).setAAD(Buffer.from(name));
+    decipher.setAuthTag(sealed.subarray(-TAG_BYTES));
+    return Buffer.concat([decipher.update(sealed.subarray(0, -TAG_BYTES)), decipher.final()]).toString("utf8");
+  } catch (err) {
+    throw new Error(
+      `the stored ${name} cannot be decrypted: ${SECRETS_KEY} is not the key it was stored with, or the row was not stored as ${name}`,
+      { cause: err },
+    );
+  }
+}
+
 /** The stored rows of these names, values included: for loading into an environment or checking, never for showing. */
 export async function storedCredentials(
   db: Db,
@@ -24,7 +77,9 @@ export async function storedCredentials(
     `SELECT name, value, set_by, set_at FROM ${TABLE} WHERE name = ANY($1)`,
     [names],
   );
-  return new Map(rows.map((r) => [r.name, { value: r.value, setBy: r.set_by, setAt: r.set_at.toISOString() }]));
+  return new Map(
+    rows.map((r) => [r.name, { value: decrypt(r.name, r.value), setBy: r.set_by, setAt: r.set_at.toISOString() }]),
+  );
 }
 
 /** Upserts the value and announces it, in one statement, so a worker never hears of a change it cannot read. */
@@ -36,10 +91,40 @@ export async function storeCredential(
     `WITH stored AS (INSERT INTO ${TABLE} (name, value, set_by) VALUES ($1, $2, $3) ` +
       "ON CONFLICT (name) DO UPDATE SET value = EXCLUDED.value, set_by = EXCLUDED.set_by, set_at = now() " +
       `RETURNING name) SELECT pg_notify('${CHANNEL}', name) FROM stored`,
-    [name, value, setBy],
+    [name, encrypt(name, value), setBy],
   );
 }
 
+/**
+ * The stored value of `name`; when there is none, `make()`'s, stored first and announced. Of two
+ * at once, the first stored wins, and both return it.
+ */
+export async function ensureCredential(
+  db: Db,
+  { name, make, setBy }: { name: string; make: () => string; setBy: string },
+): Promise<string> {
+  const stored = (await storedCredentials(db, [name])).get(name);
+  if (stored) return stored.value;
+  await db.query(
+    `WITH stored AS (INSERT INTO ${TABLE} (name, value, set_by) VALUES ($1, $2, $3) ON CONFLICT (name) DO NOTHING ` +
+      `RETURNING name) SELECT pg_notify('${CHANNEL}', name) FROM stored`,
+    [name, encrypt(name, make()), setBy],
+  );
+  return (await storedCredentials(db, [name])).get(name)!.value;
+}
+
+/**
+ * The secrets store a live driver is given (`CallContext.secrets`): a variable the environment
+ * sets wins, as it does for a driver's `env`; else the stored value. `ensure` stores what it
+ * makes as `setBy`.
+ */
+export function storedSecrets(db: () => Promise<Db>, setBy: string): Secrets {
+  return {
+    get: async (name) => process.env[name] || (await storedCredentials(await db(), [name])).get(name)?.value,
+    ensure: async (name, make) => process.env[name] || ensureCredential(await db(), { name, make, setBy }),
+  };
+}
+
 /** Deletes the row, announcing it when there was one. */
 export async function deleteCredential(db: Db, name: string): Promise<void> {
   await db.query(

package/src/datafile.ts

@@ -1,6 +1,7 @@
 import { basename, dirname, join } from "node:path";
 import type { Node } from "./ast.ts";
 import { inside, nearestDir, RELATIVE } from "./paths.ts";
+import { type Secret, SECRET_NAME } from "./secret.ts";
 
 // The one definition of what a data file may hold, over an ESTree program from oxc: the reader
 // (`resources.ts`), `lintResources` (`lint.ts`) and the oxlint plugin (`plugin.ts`) all
@@ -22,8 +23,26 @@ export class Reference {
   }
 }
 
-/** A value in a data file: a literal, or a reference to a declared resource. */
-export type DataValue = null | boolean | number | string | Reference | DataValue[] | { [field: string]: DataValue };
+const REFERENCE = Symbol.for("sanoma.reference");
+Object.defineProperty(Reference.prototype, REFERENCE, { value: true });
+
+/** True for a `Reference`, made by any copy of this package: read by a registered symbol, not `instanceof`. */
+export const isReference = (value: unknown): value is Reference =>
+  typeof value === "object" && value !== null && REFERENCE in value;
+
+/** What `secret("NAME")` stands for in a data file: its marker, `{ $secret: "NAME", generate?: true }`. */
+export type SecretRef = Secret;
+
+/** A value in a data file: a literal, a reference to a declared resource, or a secret's marker. */
+export type DataValue =
+  | null
+  | boolean
+  | number
+  | string
+  | Reference
+  | SecretRef
+  | DataValue[]
+  | { [field: string]: DataValue };
 
 /** An `import { name } from "…"`: of a connector's constructors (`from "…/resources"`), or of another data file's resource. */
 export interface DataFileImport {
@@ -61,12 +80,16 @@ export interface DataFile {
 /** A connector's constructors entry: a package specifier that ends in `/resources`. */
 const CONSTRUCTORS = /^(@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*\/resources$/;
 
+/** Where a data file imports `secret` from; checked before `CONSTRUCTORS`, which they match too. */
+export const SECRET_ENTRIES: ReadonlySet<string> = new Set(["sanoma/resources", "@sanoma-ai/workflows/resources"]);
+const SECRET_CALL = '`secret("NAME")` or `secret("NAME", { generate: true })`, NAME upper case (A-Z, 0-9 and _)';
+
 const SHAPE =
   "a data file holds only imports, `export const <name> = <vendor>.<type>({ … })` and `export default [ … ]`";
 const IMPORTS =
   "import resource constructors from a connector's resources entry " +
   '(`import { github } from "@sanoma-ai/connector-github/resources"`) ' +
-  'and resources from other data files (`import { site } from "./github.ts"`)';
+  'and resources from other data files (`import { site } from "./github.ts"`), and `secret` from "sanoma/resources"';
 const VALUES = "write a string, number, boolean, null, object or array, or name a declared resource";
 
 /**
@@ -94,6 +117,8 @@ export function readDataFile(
   const exports: DataFileExport[] = [];
   // Names a refused import or declaration binds: reported once, where they are bound.
   const refused = new Set<string>();
+  // The local names of `secret`.
+  const secrets = new Set<string>();
 
   // Imports and top-level names first, each once: imports are hoisted, and a reference may name
   // a resource declared further down. An unexported const is refused where it is declared, not
@@ -163,6 +188,21 @@ export function readDataFile(
       fail(s, `import "${spec}" is not allowed in a data file: it imports nothing, and a data file runs no code`);
       return;
     }
+    if (SECRET_ENTRIES.has(spec)) {
+      for (const sp of s.specifiers) {
+        if (
+          sp.type === "ImportSpecifier" &&
+          sp.importKind !== "type" &&
+          (sp.imported.name ?? sp.imported.value) === "secret"
+        ) {
+          secrets.add(sp.local.name);
+        } else {
+          fail(sp, `a data file imports only \`secret\` from "${spec}": \`import { secret } from "${spec}"\``);
+          refused.add(sp.local.name);
+        }
+      }
+      return;
+    }
     for (const sp of s.specifiers) {
       if (sp.type !== "ImportSpecifier") {
         const how = sp.type === "ImportNamespaceSpecifier" ? `import * as ${sp.local.name}` : `import ${sp.local.name}`;
@@ -332,6 +372,10 @@ export function readDataFile(
         );
       }
       case "CallExpression":
+        if (node.callee.type === "Identifier" && secrets.has(node.callee.name)) return readSecret(node);
+        if (node.callee.type === "Identifier" && node.callee.name === "secret" && !bound.has("secret")) {
+          return refuse(node, `import secret to name one: \`import { secret } from "sanoma/resources"\``);
+        }
         return refuse(
           node,
           node.callee.type === "MemberExpression" &&
@@ -369,12 +413,36 @@ export function readDataFile(
       return refuse(p, "a method or accessor is not allowed in a data file: a field holds a value");
     }
     if (p.computed) return refuse(p.key, "a computed key is not allowed in a data file: write the field's name");
-    const key = p.key.type === "Identifier" ? p.key.name : p.key.type === "Literal" ? String(p.key.value) : undefined;
+    const key = keyName(p.key);
     if (key === undefined) return refuse(p.key, "write the field's name, or a string");
+    if (key === "$secret") return refuse(p.key, `name a secret with ${SECRET_CALL}`);
     const v = value(p.value);
     return v === undefined ? undefined : [key, v];
   }
 
+  /** A `secret(…)` call's marker: literal arguments only. */
+  function readSecret(node: Node): SecretRef | undefined {
+    const [name, options, ...extra] = node.arguments;
+    if (name?.type !== "Literal" || typeof name.value !== "string" || extra.length) {
+      return refuse(node, `write the secret's name as a string: ${SECRET_CALL}`);
+    }
+    if (!SECRET_NAME.test(name.value))
+      return refuse(name, `${JSON.stringify(name.value)} is not a secret's name: ${SECRET_CALL}`);
+    if (options === undefined) return { $secret: name.value };
+    const [generate, ...others] = options.type === "ObjectExpression" ? options.properties : [];
+    if (
+      others.length ||
+      generate?.type !== "Property" ||
+      generate.computed ||
+      (generate.key.name ?? generate.key.value) !== "generate" ||
+      generate.value.type !== "Literal" ||
+      typeof generate.value.value !== "boolean"
+    ) {
+      return refuse(options, `a secret's options are \`{ generate: true }\` or none: ${SECRET_CALL}`);
+    }
+    return generate.value.value ? { $secret: name.value, generate: true } : { $secret: name.value };
+  }
+
   function reference(node: Node): Reference | undefined {
     const name: string = node.name;
     if (name === "undefined")
@@ -399,6 +467,10 @@ export function readDataFile(
   return { imports, exports, declared: [...declared], problems };
 }
 
+/** A property's name: an identifier's, or a literal's as a string; undefined for any other key. */
+export const keyName = (key: Node): string | undefined =>
+  key.type === "Identifier" ? key.name : key.type === "Literal" ? String(key.value) : undefined;
+
 /** A node's kind, for a message: `a function declaration`, `an if statement`. */
 function describe(node: Node): string {
   const words = String(node.type)