@sanoma-ai/workflows 0.10.2 → 0.10.6

package/src/config.ts

@@ -1,4 +1,5 @@
 import { configuredSecrets } from "./credentials.ts";
+import type { IdentityProvisioning } from "./identity-provisioning.ts";
 import { secretsForInput } from "./secret.ts";
 import { isRunControlError } from "./errors.ts";
 import { currentRun } from "./run.ts";
@@ -52,15 +53,26 @@ import {
 } from "./op.ts";
 import { type CedarPolicySource, policyAt } from "./cedar.ts";
 import type { Policy } from "./policy.ts";
-import { type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
-import { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS, CALL_WORKFLOW, CHANGE_WORKFLOW, DATA_VENDOR } from "./shared.ts";
+import { checkFromRefs, type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
+import { CODE_MAIL, loginCodeWorkflow } from "./login-code.ts";
+import {
+  APPLY_WORKFLOW,
+  BUILT_IN_WORKFLOWS,
+  CALL_WORKFLOW,
+  CHANGE_WORKFLOW,
+  DATA_VENDOR,
+  LOGIN_CODE_WORKFLOW,
+} from "./shared.ts";
 import { fakeSourceDriver, type RemoteHalf, SOURCE_RESOLVE, sourceDriver, sourceOps } from "./source.ts";
 import { appsListDriver, appsListOps } from "./apps-list.ts";
+import { runtimeDriver, sandboxRuntimeDriver, sanoma } from "./runtime-ops.ts";
+import { tokenStore } from "./tokens.ts";
 import type { Steps } from "./steps.ts";
 import { checkSchedule } from "./schedules.ts";
 import { changeCodeOf, computeVersion } from "./version.ts";
-import type { DeclaredResource } from "./resources.ts";
-import { checkWakeupOps, type DeclaredWakeup } from "./wakeup.ts";
+import type { DeclaredResource, ResourceProblem } from "./resources.ts";
+import { checkWakeupOps, type DeclaredWakeup, type EnvWakeup, HOST_URL } from "./wakeup.ts";
+import { instanceUrl, WAKEUP_TOKEN } from "./wakeup-service.ts";
 import { sanomaWakeupDriver, wakeupSteps } from "./wakeup-driver.ts";
 import { wakeupOps } from "./wakeup-type.ts";
 import { checkDatabaseOps } from "./database.ts";
@@ -96,6 +108,8 @@ export interface SanomaConfig {
   ledger?: LedgerStore;
   /** Credential storage and explicit bindings. Omitted: encrypted Postgres, no environment fallback. */
   secrets?: SecretConfiguration;
+  /** Trusted control plane only: separate broker enrollment writer. Absent in company runtimes. */
+  identityProvisioning?: IdentityProvisioning;
   connections?: readonly ConnectionDefinition[];
   connectionRules?: readonly ConnectionRule[];
   /** Postgres for the runtime. Defaults to `SANOMA_DATABASE_URL`, then `DEFAULT_DATABASE_URL`. */
@@ -131,6 +145,13 @@ export interface SanomaConfig {
    * that sets it and declares a wakeup of its own.
    */
   wakeup?: true;
+  /**
+   * How the staff and visitor logins send a sign-in code: `sender`, an operation of a connector in
+   * `connectors` with the effect `send` that takes `{ to, subject, text }`, such as
+   * `resend.emails.send`. With it, the runtime registers the built-in `login-code` workflow,
+   * which the runtime's agent `login` runs; without it, nobody signs in by code.
+   */
+  login?: { sender: Op };
 }
 
 /** A config, checked, with everything a worker, client or app derives from it. */
@@ -150,9 +171,12 @@ export interface ResolvedConfig {
   changeCode: string;
   /** The DBOS queue runs are started on: `sanoma:<appName>`. */
   queueName: string;
+  /** The config's `login`, checked (`checkSender`); the built-in `login-code` workflow sends through its `sender`. */
+  login?: { sender: Op };
   /**
    * The operations the connectors declare, by id, the built-in `sanoma.change.*` (`changeOps`, in
-   * every config), `sanoma.source.resolve` and `sanoma.wakeup`'s when one declares a host type,
+   * every config) and the runtime's own a workflow may use (`sanoma`, runtime-ops.ts, in every
+   * config), `sanoma.source.resolve` and `sanoma.wakeup`'s when one declares a host type,
    * and the collections' (`data.<name>.<op>`).
    */
   ops: Map<string, Op>;
@@ -177,6 +201,11 @@ export interface ResolvedConfig {
    * declares a host type.
    */
   hosts(): Promise<string[]>;
+  /**
+   * The objects the data files under `root` declare, read at each call: what a workflow's change
+   * operation may not aim at, since only apply changes a declared object.
+   */
+  declaredObjects(): Promise<DeclaredObjects>;
   /**
    * `root`, as a `file:` URL, when `scenarios/` or an app's `apps/<app>/scenarios/` in it is a
    * directory: the feature files under those, each named by its path from the root.
@@ -310,17 +339,20 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const declared = [...collections.values()];
   const dataStore = declared.length ? lazyPool(databaseUrl, "data") : undefined;
   // Built-in, in every config: a change's operations, which the template's policy names
-  // (`sanoma.change.merge`), and the listing of apps a page may call (`sanoma.apps.list`).
+  // (`sanoma.change.merge`), the listing of apps a page may call (`sanoma.apps.list`), and what a
+  // workflow asks the runtime to do for it (`sanoma`, runtime-ops.ts).
   const ops = indexConnectors([
     ...running,
     changeOps,
     connectionOps,
     appsListOps,
+    sanoma,
     ...(hostTyped ? [sourceOps] : []),
     ...(dataStore ? [collectionsConnector(declared)] : []),
   ]);
   checkWakeupOps(types, ops);
   checkDatabaseOps(types, ops);
+  checkFromRefs(types);
   const driversByVendor = new Map([...makersOf(running, "driver")].map(([vendor, make]) => [vendor, make()]));
   const remotes = new Map([...makersOf(config.connectors, "remote")].map(([vendor, make]) => [vendor, make()]));
   const drivers = indexDrivers(
@@ -329,6 +361,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       changeDriver(remotes),
       connectionDriver(connections),
       appsListDriver,
+      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()), identities: config.identityProvisioning }),
       ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
@@ -342,7 +375,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     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, types);
+    checkUses(wf, ops, drivers);
     checkSchedule(wf);
     const other = names.get(wf.name);
     if (other && other !== wf) {
@@ -368,9 +401,13 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   const hosts = async () =>
     (await read()).resources.filter((r) => types.get(`${r.vendor}.${r.type}`)?.host).map((r) => r.id);
   names.set(CHANGE_WORKFLOW, changeWorkflow(changeOps, changeSteps({ remotes, hosts })));
+  const declaredObjects = () => readDeclaredObjects(root, connectors, declarable);
   // Built-in: a direct call the policy holds for an approval, made a run, when any operation may be called directly.
   const call = callWorkflow(ops, drivers, types);
   if (call.uses.length) names.set(CALL_WORKFLOW, call);
+  // Built-in: sending a sign-in code, when the config names how.
+  const login = config.login && { sender: checkSender(config.login, ops, drivers) };
+  if (login) names.set(LOGIN_CODE_WORKFLOW, loginCodeWorkflow(login.sender, appName));
   const { policy, policies, problems: policyProblems } = policyAt(root, { ops, workflows: names, collections });
   return {
     secrets: config.secrets ?? {},
@@ -382,6 +419,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     version: computeVersion({ appName, workflows: [...names.values()] }),
     changeCode: changeCodeOf(names.get(CHANGE_WORKFLOW)!),
     queueName: `sanoma:${appName}`,
+    ...(login && { login }),
     ops,
     drivers,
     driversByVendor,
@@ -390,6 +428,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     models: makersOf(config.connectors, "model"),
     remotes,
     hosts,
+    declaredObjects,
     ...(scenarios && { scenarios }),
     types,
     steps: [...new Set([...running.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
@@ -404,6 +443,26 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   };
 }
 
+/**
+ * The config's `login.sender`, as the config's operations have it: refused unless it is an
+ * operation of a connector in `connectors`, with the effect `send`, a driver, and an input that
+ * takes `{ to, subject, text }`.
+ */
+function checkSender(login: unknown, ops: ReadonlyMap<string, Op>, drivers: ReadonlyMap<string, unknown>): Op {
+  const sender: unknown = (login as { sender?: unknown } | null)?.sender;
+  const fix = "name a connector's send operation, such as `login: { sender: resend.emails.send }`";
+  if (!isOp(sender)) throw new Error(`The config's \`login.sender\` is not an operation: ${fix}`);
+  const op = ops.get(sender.id);
+  if (!op) throw new Error(`The config's \`login.sender\`, ${sender.id}, is of no connector in \`connectors\`: add it`);
+  if (op.effect !== "send")
+    throw new Error(`The config's \`login.sender\`, ${op.id}, does not send (its effect is ${op.effect}): ${fix}`);
+  if (!drivers.has(op.id))
+    throw new Error(`The config's \`login.sender\`, ${op.id}, has no driver: the connector package must attach one`);
+  if (!op.input.safeParse(CODE_MAIL).success)
+    throw new Error(`The config's \`login.sender\`, ${op.id}, does not take an email as { to, subject, text }: ${fix}`);
+  return op;
+}
+
 /**
  * The config's collections by name, checked: each one `collection()` made, no two with one name,
  * and no connector of their vendor, `DATA_VENDOR`.
@@ -431,11 +490,13 @@ function collectionsOf(config: SanomaConfig): Map<string, Collection> {
 /**
  * The built-in drivers a sandbox run calls beside its fakes (`seedSandbox`), for the built-in
  * operations among `ops` that no fake implements: `sanoma.apps.list`'s own, which needs no
- * credentials and changes nothing (GitHub's public search), and `sanoma.source.resolve`'s fake
- * (`fakeSourceDriver`), for a config with a host type.
+ * credentials and changes nothing (GitHub's public search), the runtime's own operations over the
+ * run's secrets and tokens of its own (`sandboxRuntimeDriver`, made for each run), and
+ * `sanoma.source.resolve`'s fake (`fakeSourceDriver`), for a config with a host type.
  */
 export const sandboxDrivers = (ops: ReadonlyMap<string, unknown>): Driver[] => [
   appsListDriver,
+  sandboxRuntimeDriver(),
   ...(ops.has(SOURCE_RESOLVE) ? [fakeSourceDriver] : []),
 ];
 
@@ -545,6 +606,47 @@ export async function declaredWakeup(config: SanomaConfig): Promise<DeclaredWake
   };
 }
 
+/**
+ * The wakeup `env` names (`EnvWakeup`): its host's URL, `SANOMA_HOST_URL`, as the wakeup service
+ * keeps one (`instanceUrl`), and its token, `SANOMA_WAKEUP_TOKEN`, when both are set and the URL is
+ * one; undefined otherwise. A host Sanoma Cloud made gives both to an instance that declares no
+ * wakeup of its own.
+ */
+export function envWakeup(env: NodeJS.ProcessEnv): EnvWakeup | undefined {
+  const host = env[HOST_URL]?.trim();
+  const token = env[WAKEUP_TOKEN]?.trim();
+  const checked = host ? instanceUrl(host) : undefined;
+  return checked && "url" in checked && token ? { url: checked.url, token } : undefined;
+}
+
+/**
+ * The objects a company's data files declare, which only apply changes (`refuseDeclared` in
+ * `call.ts`), by `<vendor>.<type> <id or name>` to their key: each binding in the lockfile, an
+ * orphan's too, by its id, and each declaration by its identity (what its type's `find` made);
+ * and the files' problems, while which the declared objects are not known.
+ */
+export interface DeclaredObjects {
+  keys: ReadonlyMap<string, string>;
+  problems: readonly ResourceProblem[];
+}
+
+/** The objects the data files under `root` and its lockfile declare (`DeclaredObjects`): none without a root. */
+async function readDeclaredObjects(
+  root: string | undefined,
+  connectors: readonly Connector<any, any>[],
+  declarable: ReadonlyMap<string, Resource>,
+): Promise<DeclaredObjects> {
+  if (root === undefined) return { keys: new Map(), problems: [] };
+  // Loaded when a call asks, not with the worker.
+  const { loadDataFiles } = await import("./resources.ts");
+  const { resources, bindings, problems } = loadDataFiles(root, connectors, declarable);
+  const named = resources.flatMap((r) =>
+    r.identity === undefined ? [] : [[`${r.vendor}.${r.type} ${r.identity}`, r.id] as const],
+  );
+  const bound = Object.entries(bindings).map(([key, { type, id }]) => [`${type} ${id}`, key] as const);
+  return { keys: new Map([...named, ...bound]), 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
@@ -693,19 +795,15 @@ 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 use an operation a built-in workflow alone calls (`reservedFor`): a declared resource's
- * change, which only apply makes, or a change's step, which only the change workflow takes.
+ * None may use an operation a built-in workflow alone calls (`reservedFor`): a change's step, which
+ * only the change workflow takes. A resource type's change operations are allowed: the call
+ * refuses one aimed at a declared object (`DeclaredObjects`), which only apply changes.
  */
-function checkUses(
-  wf: WorkflowDefinition<any, any>,
-  ops: Map<string, Op>,
-  impls: Map<string, unknown>,
-  types: ReadonlyMap<string, Resource>,
-) {
+function checkUses(wf: WorkflowDefinition<any, any>, ops: Map<string, Op>, impls: Map<string, unknown>) {
   const problems: string[] = [];
   for (const op of (wf.uses as readonly Use[]).filter(isOp)) {
     const known = ops.get(op.id);
-    const reserved = known && reservedFor(known, types);
+    const reserved = known && reservedFor(known);
     if (!known) problems.push(`${op.id} is not declared by any connector in \`connectors\``);
     else if (reserved) {
       problems.push(`${op.id} ${reserved.does}, which only ${reserved.workflow} does: ${reserved.instead} instead`);

package/src/db.ts

@@ -5,7 +5,7 @@ import { warn } from "./log.ts";
 import { errorMessage } from "./shared.ts";
 
 // The runtime's own tables live in the config's database, beside DBOS's: the credentials, the
-// ledger, the collections' records, the wakeup's row and the operator agent's chats. What they
+// ledger, the collections' records, the wakeup's row, the operator agent's chats and the api tokens. What they
 // share is here: the one preparation of a database, a pool that opens once it is prepared and
 // survives a dropped connection, and a table creation two processes may race.
 
@@ -28,6 +28,8 @@ export const WAKEUP_TABLE = "sanoma_wakeup";
 export const CHATS_TABLE = "sanoma_chats";
 /** Each chat's messages, the AI SDK's UI messages as JSON, in `seq` order. */
 export const CHAT_MESSAGES_TABLE = "sanoma_chat_messages";
+/** The api tokens (`tokens.ts`): each one's SHA-256, never the token, whom it acts for, its groups, and when it was revoked. */
+export const API_TOKENS_TABLE = "sanoma_api_tokens";
 
 /** The runtime's tables, each with the word the messages name it by. */
 const TABLES: readonly [what: string, ddl: string][] = [
@@ -97,6 +99,11 @@ const TABLES: readonly [what: string, ddl: string][] = [
     `CREATE TABLE IF NOT EXISTS ${CHAT_MESSAGES_TABLE} (chat_id text NOT NULL REFERENCES ${CHATS_TABLE} (id) ` +
       "ON DELETE CASCADE, id text NOT NULL, seq integer NOT NULL, message jsonb NOT NULL, PRIMARY KEY (chat_id, id))",
   ],
+  [
+    "api tokens",
+    `CREATE TABLE IF NOT EXISTS ${API_TOKENS_TABLE} (id text PRIMARY KEY, hash text NOT NULL UNIQUE, ` +
+      "subject text NOT NULL, groups jsonb NOT NULL, created_at timestamptz NOT NULL DEFAULT now(), revoked_at timestamptz)",
+  ],
 ];
 
 /** The Postgres error code of `err`, or an empty string when it has none. */

package/src/deadlines.ts

@@ -8,7 +8,7 @@ import { warn } from "./log.ts";
 import type { CallContext, DriverFn, Op } from "./op.ts";
 import type { Secrets } from "./secret.ts";
 import { errorMessage, WAKEUP_AGENT } from "./shared.ts";
-import type { WakeupRegistration } from "./wakeup.ts";
+import { type EnvWakeup, WAKE_PATH, type WakeupRegistration } from "./wakeup.ts";
 
 // What a worker knows of its own runs that DBOS cannot tell it: which are executing and which are
 // blocked in a `ctx` wait, and until when. DBOS sees both as PENDING. A worker that registers a
@@ -133,15 +133,15 @@ export interface SelfStop {
   at: string | null;
 }
 
-/** What the stop rule acts on: the wakeup row, the wakeup's register operation, and the worker. */
+/** Registers a deadline with the instance's wakeup, replacing what it held; throws when it could not. */
+export type RegisterWakeup = (registration: WakeupRegistration) => Promise<void>;
+
+/** What the stop rule acts on: the wakeup row, how a deadline is registered, and the worker. */
 export interface StopRule {
   /** The wakeup row's database. */
   db: () => Promise<Db>;
-  /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
-  wakeup: string;
-  /** The wakeup type's register operation, and its driver (none when the connector attaches none). */
-  register: { op: Op; fn: DriverFn | undefined };
-  secrets: Secrets;
+  /** The declared wakeup's register operation (`declaredRegister`), or the host's own route (`envRegister`). */
+  register: RegisterWakeup;
   deadlines: Deadlines;
   idle: () => Promise<boolean>;
   everyMs: number;
@@ -174,7 +174,7 @@ export function stopWhenIdle(rule: StopRule): { close(): void } {
     const db = await rule.db();
     if (at !== null) {
       try {
-        await registerWakeup(rule, { at });
+        await rule.register({ at });
       } catch (err) {
         const message = errorMessage(err);
         await recordWakeupError(db, message);
@@ -214,18 +214,64 @@ export function stopWhenIdle(rule: StopRule): { close(): void } {
   };
 }
 
+/** A declared wakeup's register operation, and what its call needs. */
+export interface DeclaredRegister {
+  /** The wakeup type's register operation. */
+  op: Op;
+  /** Its driver: none when the connector attaches none. */
+  fn: DriverFn | undefined;
+  /** The instance's secrets, which the driver reads the wakeup's token from. */
+  secrets: Secrets;
+  /** The declared wakeup's binding, else its declaration's id: what scopes a registration's idempotency key to this instance. */
+  wakeup: string;
+}
+
+/**
+ * Registers through the declared wakeup's register operation, as `SanomaClient.call` calls a
+ * driver: its input parsed, a `CallContext` of the runtime's, and no ledger record, which is a run's.
+ */
+export function declaredRegister({ op, fn, secrets, wakeup }: DeclaredRegister): RegisterWakeup {
+  return async (registration) => {
+    if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
+    // Fresh each time: a repeat of an earlier `at` after another registration must re-arm it, so no
+    // two registrations share a key (real drivers never dedupe on it anyway).
+    const key = `wakeup:${wakeup}:${randomUUID()}`;
+    const context: CallContext = {
+      idempotencyKey: key,
+      runId: key,
+      opId: op.id,
+      attempt: 1,
+      secrets,
+      by: WAKEUP_AGENT,
+    };
+    await fn(op.input.parse(registration), context);
+  };
+}
+
 /**
- * Calls the wakeup's register operation, as `SanomaClient.call` calls a driver: its input parsed,
- * a `CallContext` of the runtime's, and no ledger record, which is a run's.
+ * Registers at the host's own wake route, as the environment names it (`EnvWakeup`): `PUT
+ * {url}/__sanoma/wake` with the token as a bearer and the registration as JSON, no driver and no
+ * secret store. 204 is taken; anything else fails with its status and the route's own `error`.
  */
-export async function registerWakeup(
-  { register: { op, fn }, secrets, wakeup }: Pick<StopRule, "register" | "secrets" | "wakeup">,
-  registration: WakeupRegistration,
-) {
-  if (!fn) throw new Error(`${op.id} has no driver: the connector package must attach one`);
-  // Fresh each time: a repeat of an earlier `at` after another registration must re-arm it, so no
-  // two registrations share a key (real drivers never dedupe on it anyway).
-  const key = `wakeup:${wakeup}:${randomUUID()}`;
-  const context: CallContext = { idempotencyKey: key, runId: key, opId: op.id, attempt: 1, secrets, by: WAKEUP_AGENT };
-  await fn(op.input.parse(registration), context);
+export function envRegister({ url, token }: EnvWakeup): RegisterWakeup {
+  return async (registration) => {
+    const where = `PUT ${url}${WAKE_PATH}`;
+    let res: Response;
+    try {
+      res = await fetch(`${url}${WAKE_PATH}`, {
+        method: "PUT",
+        headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+        body: JSON.stringify(registration),
+        // A redirect is no answer of the host's, and would carry the token elsewhere.
+        redirect: "manual",
+        signal: AbortSignal.timeout(30_000),
+      });
+    } catch (err) {
+      throw new Error(`${where}: no answer (${errorMessage(err)})`, { cause: err });
+    }
+    if (res.status === 204) return;
+    const body: unknown = await res.json().catch(() => undefined);
+    const error = (body as { error?: unknown } | undefined)?.error;
+    throw new Error(`${where} answered ${res.status}${typeof error === "string" ? `: ${error}` : ""}`);
+  };
 }

package/src/define.ts

@@ -18,14 +18,45 @@ export interface Principal {
   groups?: string[];
   /** For an agent: the id of the person whose instruction it carries. */
   onBehalfOf?: string;
+  /**
+   * For a visitor: the email their site's login verified (`LoginHalf.verify`), which the app
+   * passes on. Admission keeps it for a visitor alone; a run's `ctx.startedBy.email`.
+   */
+  email?: string;
+  /**
+   * For a visitor: the GitHub login their site's login verified (`LoginHalf.verify`: signed in
+   * with GitHub, or linked it), kept as `email` is; a run's `ctx.startedBy.github`.
+   */
+  github?: string;
+  /**
+   * For an api token (`token:<id>`): the subject its row acts for, which `SanomaClient.start`
+   * reads from the row, never from the caller; a run's `ctx.startedBy.subject`.
+   */
+  subject?: string;
 }
 
 export const Principal: z.ZodType<Principal> = z.object({
   id: z.string().regex(/\S/, "id must not be blank"),
   groups: z.array(z.string()).optional(),
   onBehalfOf: z.string().regex(/\S/, "onBehalfOf must not be blank").optional(),
+  email: z.string().optional(),
+  github: z.string().optional(),
+  subject: z.string().optional(),
 });
 
+/**
+ * Who started a run, as its workflow sees it (`ctx.startedBy`): the principal's id (`alice`,
+ * `visitor:<login>:<subject>`, `token:<id>`), with the email and GitHub login a visitor's login
+ * verified, and for an api token the subject its row acts for, so a workflow can tell whose a
+ * record is.
+ */
+export interface StartedBy {
+  readonly id: string;
+  readonly email?: string;
+  readonly github?: string;
+  readonly subject?: string;
+}
+
 /** A built-in a workflow may call, as its description lists them. */
 export type Builtin = WorkflowEntry["builtins"][number];
 export type Use = Op | Builtin;
@@ -227,6 +258,8 @@ interface BaseCtx {
    */
   now(): Promise<number>;
   readonly runId: string;
+  /** Who started the run: read, never called (`StartedBy`). */
+  readonly startedBy: StartedBy;
 }
 
 export type Ctx<U extends readonly Use[]> = BaseCtx &

package/src/deployment-key.ts

@@ -1,10 +1,12 @@
+import { hkdfSync } from "node:crypto";
 import { readFileSync } from "node:fs";
 
+/** The deployment's own keys: bound only to the environment or bootstrap, never written by the runtime. */
+export const DEPLOYMENT_KEYS: readonly string[] = ["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"];
+export type DeploymentKeyName = "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY";
+
 /** Bootstrap only: never resolves through the secret store that the key unlocks. */
-export function deploymentKey(
-  name: "SANOMA_SECRETS_KEY" | "SANOMA_SIGNING_KEY",
-  env: NodeJS.ProcessEnv = process.env,
-): Buffer {
+export function deploymentKey(name: DeploymentKeyName, env: NodeJS.ProcessEnv = process.env): Buffer {
   const value = env[name];
   const file = env[`${name}_FILE`];
   if (value && file) throw new Error(`Set only one of ${name} and ${name}_FILE`);
@@ -16,8 +18,32 @@ export function deploymentKey(
       throw new Error(`${name}_FILE could not be read`);
     }
   }
-  if (!encoded || !/^[A-Za-z0-9+/]{43}=$/.test(encoded) || Buffer.from(encoded, "base64").length !== 32) {
-    throw new Error(`${name} must be 32 random bytes in base64; supply ${name} or ${name}_FILE`);
-  }
-  return Buffer.from(encoded, "base64");
+  const key = encoded ? keyBytes(encoded) : undefined;
+  if (!key) throw new Error(`${name} must be 32 random bytes in base64; supply ${name} or ${name}_FILE`);
+  return key;
+}
+
+/**
+ * The 32 bytes of a key written as text: padded base64 (`sanoma key`), or base64url without
+ * padding (a `secret(..., { generate: true })` marker's value). Anything else is `undefined`.
+ */
+export function keyBytes(text: string): Buffer | undefined {
+  if (/^[A-Za-z0-9+/]{43}=$/.test(text)) return Buffer.from(text, "base64");
+  if (/^[A-Za-z0-9_-]{43}$/.test(text)) return Buffer.from(text, "base64url");
+  return undefined;
 }
+
+/**
+ * A 32-byte key of its own for `purpose`, derived from a deployment's signing key (HKDF-SHA256
+ * over its base64 text), as that deployment derives it from its `SANOMA_SIGNING_KEY`.
+ */
+export const deriveSigningKey = (signingKey: Buffer, purpose: string): Buffer =>
+  Buffer.from(hkdfSync("sha256", signingKey.toString("base64"), "", purpose, 32));
+
+/**
+ * A 32-byte key of its own for `purpose`, derived from `SANOMA_SIGNING_KEY` (`deriveSigningKey`):
+ * each use of the signing key (a login's cookies, the setup's state, sealed values) gets a key no
+ * other use shares.
+ */
+export const signingKeyFor = (purpose: string): Buffer =>
+  deriveSigningKey(deploymentKey("SANOMA_SIGNING_KEY"), purpose);

package/src/describe.ts

@@ -4,7 +4,8 @@ import { type AppEntry, appsAt } from "./apps.ts";
 import { readSource, type SourceFile } from "./ast.ts";
 import { readPolicyFiles } from "./cedar.ts";
 import { recordSchemaOf } from "./collection.ts";
-import { connectorsOf, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
+import { decideCall } from "./call.ts";
+import { connectorsOf, type ResolvedConfig, resolveConfig, rootOf, type SanomaConfig } from "./config.ts";
 import { type Builtin, jsonSchemaOf, opIdsOf, type Use } from "./define.ts";
 import {
   CAPABILITIES,
@@ -17,6 +18,7 @@ import {
 } from "./description.ts";
 import { isDirect } from "./direct.ts";
 import { type CredentialStatus, credentialsOf } from "./env.ts";
+import { CODE_MAIL } from "./login-code.ts";
 import { lintWorkflow } from "./lint.ts";
 import { fresh, stampOf, stampsOf } from "./load.ts";
 import { LOCKFILE } from "./lockfile.ts";
@@ -27,7 +29,17 @@ import { allowAll, policyOpOf } from "./policy.ts";
 import { type Resource, resourceTypesOf, valueAt } from "./resource.ts";
 import { type DeclaredResource, inAppPeople, loadDataFiles, type ResourceProblem } from "./resources.ts";
 import { apiNameProblem } from "./sdk.ts";
-import { apiNameOf, BUILT_IN_WORKFLOWS, DATA_VENDOR, errorMessage, problemLine } from "./shared.ts";
+import {
+  apiNameOf,
+  BUILT_IN_WORKFLOWS,
+  DATA_VENDOR,
+  errorMessage,
+  LOGIN_AGENT,
+  LOGIN_CODE_WORKFLOW,
+  type PeopleResource,
+  principalOf,
+  problemLine,
+} from "./shared.ts";
 import { readSites, type SiteEntry } from "./sites.ts";
 
 // `@sanoma-ai/workflows/describe`: what a UI renders from, apart from the main entry.
@@ -282,6 +294,7 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
       ...appProblems,
       ...appClashes(apps, collections, sites),
       ...domainProblems(dataFiles.resources, resources, sites),
+      ...loginProblems(resolved, dataFiles.resources),
     ],
     apps,
     policy: {
@@ -291,9 +304,33 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
       files: resolved.root === undefined ? [] : readPolicyFiles(resolved.root),
     },
     sites,
+    ...(resolved.login && { login: { sender: resolved.login.sender.id } }),
   };
 }
 
+/**
+ * The policy holding or denying the sign-in code: `login.sender` as the runtime's agent `login`
+ * in a run of `login-code` must be allowed, or nobody receives a code.
+ */
+function loginProblems(resolved: ResolvedConfig, people: readonly PeopleResource[]): ResourceProblem[] {
+  if (!resolved.login || resolved.policyProblems.length) return [];
+  const { sender } = resolved.login;
+  const agent = principalOf(LOGIN_AGENT, people)!;
+  const run = { id: "check", workflow: LOGIN_CODE_WORKFLOW, approvals: [] };
+  const decision = decideCall(resolved.policy, sender, CODE_MAIL, agent, run);
+  if (decision.kind === "allow") return [];
+  const does = decision.kind === "deny" ? "denies" : "holds";
+  const by = decision.reasons?.length ? ` (${decision.reasons.join(", ")})` : "";
+  return [
+    {
+      file: "policies",
+      message:
+        `the policy ${does} ${sender.id} for the sign-in code${by}, so nobody receives one: exempt the runtime's ` +
+        `agent, \`unless { principal == Sanoma::Principal::"${LOGIN_AGENT}" }\``,
+    },
+  ];
+}
+
 /** That the root's `kind` `name`, in `file`, is named as an app is. */
 const appClash = (kind: string, name: string, file: string): ResourceProblem => ({
   file,

package/src/description.ts

@@ -422,5 +422,7 @@ export const ConfigDescriptionSchema = z.strictObject({
    * the config does not have as its problems; none when the root has no `sites/`.
    */
   sites: z.array(SiteEntrySchema),
+  /** The config's `login`: the operation its sign-in codes are sent with, by id. */
+  login: z.strictObject({ sender: z.string() }).optional(),
 });
 export type ConfigDescription = z.infer<typeof ConfigDescriptionSchema>;

package/src/dns.ts

@@ -0,0 +1,29 @@
+import { z } from "zod";
+
+/**
+ * A DNS record as one resource's state gives it and another's input takes it, through a `from`
+ * reference (`FieldReference.from`): the records a sending domain asks for (`resend.domain`'s
+ * `dns_records`), which a zone's record set writes (`cloudflare.records`' `records`).
+ */
+export const dnsRecord = z
+  .object({
+    type: z.enum(["TXT", "MX", "CNAME", "CAA"]),
+    /** The full name, lower case, with no trailing dot: `resend._domainkey.example.com`. */
+    name: z
+      .string()
+      .refine((name) => name === name.toLowerCase(), "a record's name is lower case")
+      .refine((name) => !name.endsWith("."), "a record's name has no trailing dot"),
+    /** As the zone holds it: a TXT record's text unquoted. */
+    content: z.string(),
+    /** An MX record's priority. */
+    priority: z.number().int().optional(),
+    /** In seconds; 1 is automatic, the zone's default. */
+    ttl: z.number().int().optional(),
+  })
+  .refine(({ type, content }) => type !== "TXT" || !/^".*"$/s.test(content), {
+    message: "a TXT record's content is its text, not wrapped in quotes",
+    path: ["content"],
+  });
+
+/** One DNS record: see `dnsRecord`. */
+export type DnsRecord = z.infer<typeof dnsRecord>;