@sanoma-ai/workflows 0.10.3 → 0.10.6

package/src/apply.ts

@@ -24,9 +24,13 @@ import {
   afterCreateStuck,
   fieldPathOf,
   holderOf,
+  type Missing,
   type PlanAction,
   type Resource,
+  same,
+  type Unfilled,
   valueAt,
+  withFrom,
 } from "./resource.ts";
 import type { ResourceProblem } from "./resources.ts";
 import { type APPLY_WORKFLOW, errorMessage } from "./shared.ts";
@@ -60,13 +64,14 @@ export type ApplyInput = z.infer<typeof ApplyInput>;
 /**
  * One declared resource, or orphaned binding, by what apply does with it: `create` it (as the
  * vendor plans: `planned`, the paths `unknown` until it exists), `update` or `replace` its bound
- * object (the declared `fields` that differ, the paths that force the replace), `bind` it to an
+ * object (the declared `fields` that differ, the paths that force the replace, any `unknown` until
+ * it is done: a `from` field whose resource changes first), `bind` it to an
  * object its identity `found` or the input `given`, ask about a `gone` object or an `orphan`ed
  * binding (unless `answer`ed), or `none`.
  */
 export type PlanStep = { id: string; vendor: string; type: string; connection?: ConnectionRef } & (
   | { action: "create"; planned: Record<string, unknown>; unknown: string[] }
-  | { action: "update" | "replace"; binding: string; fields: DriftField[]; replace: string[] }
+  | { action: "update" | "replace"; binding: string; fields: DriftField[]; replace: string[]; unknown?: string[] }
   | { action: "bind"; binding: string; source: "found" | "given" }
   | { action: "gone"; binding: string; answer?: PlanAnswer }
   | { action: "orphan"; key: string; binding: string; answer?: PlanAnswer }
@@ -183,22 +188,40 @@ function inDependencyOrder<T extends { id: string; refs: Record<string, string>
   return out;
 }
 
+/** What a run knows of the declared resources as it goes, by declared id, which `desiredOf` reads. */
+interface Known {
+  /** The lockfile's bindings, as the run has changed them so far. */
+  bindings: Bindings;
+  /** The clone URL and commit a host wanted runs. */
+  hosts: ReadonlyMap<string, { source: string; revision: string }>;
+  /** Where each host answers, as its state says. */
+  urls: ReadonlyMap<string, string>;
+  /**
+   * A resource's state as found or as its step left it, to read a `from` reference's path in;
+   * undefined while it has none known there.
+   */
+  stateOf: (named: string, from: string) => State | undefined;
+}
+
 /**
  * What a change operation is given of a declaration: its fields, where it names a resource the
  * vendor may hold by another field (`by`, as a repository's node id), that resource's binding id
- * when it has one, made in this run or before; a wakeup's `host`, the URL its host answers at
- * (`urls`, by the host's declared id) once its state says.
+ * when it has one, made in this run or before; where a `from` reference names one, that
+ * resource's state at its path, or while it has none there, `null` (`unknown`) or nothing
+ * (`drop`), as `missing` says, with those references as `unfilled`; a wakeup's `host`,
+ * the URL its host answers at (`urls`, by the host's declared id) once its state says.
  */
 function desiredOf(
   r: Declaration,
   types: ReadonlyMap<string, Resource>,
-  bindings: Bindings,
-  hosts: ReadonlyMap<string, { source: string; revision: string }>,
-  urls: ReadonlyMap<string, string>,
-): State {
+  known: Known,
+  missing: Missing | ((named: string, from: string) => Missing),
+): { desired: State; unfilled: Unfilled[] } {
+  const { bindings, hosts, urls, stateOf } = known;
   const { fields, host, wakeup } = types.get(`${r.vendor}.${r.type}`)!;
   const { references = {} } = fields;
-  const out = structuredClone(r.desired);
+  const filled = withFrom(references, r.desired, r.refs, stateOf, missing);
+  const out = filled.desired === r.desired ? structuredClone(r.desired) : filled.desired;
   for (const [at, target] of Object.entries(r.refs)) {
     const bound = bindings[target]?.id;
     const place = holderOf(out, at);
@@ -220,9 +243,16 @@ function desiredOf(
       if (place) place.holder[place.key] = value;
     }
   }
-  return out;
+  return { desired: out, unfilled: filled.unfilled };
 }
 
+/** Whether two dotted paths name the same field, or one a field inside the other. */
+const overlaps = (a: string, b: string) => a === b || a.startsWith(`${b}.`) || b.startsWith(`${a}.`);
+
+/** Why a step cannot write a field a `from` reference takes: its resource has no state, or nothing at the path. */
+const waitingFor = ({ at, named, from, stated }: Unfilled) =>
+  `its ${at} come from ${named}, ${stated ? `whose state has no ${from} yet` : "which has no state yet"}`;
+
 /** Why apply cannot `what` (create, update, delete) an object of a type. */
 const cannotChange = (type: Pick<Resource, "vendor" | "type" | "writable"> | undefined, what: string) =>
   type?.writable
@@ -292,6 +322,9 @@ function decide(
   return result.status === "drifted" ? { step, problem: cannot("update") } : { step };
 }
 
+/** Whether apply makes a declared resource: one unbound (`absent`) or `gone`. */
+const creates = (result: DriftResult) => result.status === "absent" || result.status === "gone";
+
 /** The step a `plan` answer makes of a declared resource: a create for one unbound or gone, else an update, a replace or none. */
 function fromPlan(
   r: Declaration,
@@ -299,12 +332,21 @@ function fromPlan(
   p: { action: PlanAction; planned?: State; unknown: string[]; replace: string[] },
 ): { step?: PlanStep; problem?: ResourceProblem } {
   const head = { id: r.id, vendor: r.vendor, type: r.type };
-  const creating = result.status === "absent" || result.status === "gone";
+  const creating = creates(result);
   if (creating && p.action === "create") {
     return { step: { ...head, action: "create", planned: p.planned ?? {}, unknown: p.unknown } };
   }
   if (!creating && (p.action === "update" || p.action === "replace")) {
-    return { step: { ...head, action: p.action, binding: result.binding!, fields: result.fields, replace: p.replace } };
+    return {
+      step: {
+        ...head,
+        action: p.action,
+        binding: result.binding!,
+        fields: result.fields,
+        replace: p.replace,
+        ...(p.unknown.length && { unknown: p.unknown }),
+      },
+    };
   }
   if (!creating && p.action === "none") return { step: { ...head, action: "none", binding: result.binding! } };
   return { problem: problemOf(r.id, `the vendor plans to ${p.action} it, which apply does not do here`) };
@@ -432,9 +474,14 @@ function messageOf(step: PlanStep, before: Binding | undefined, after: Binding |
  * and right after one that changes a binding, the lockfile written and committed
  * (`steps.write`), so an object made is never left unbound. An update is given the plan's action
  * and replace (`expect`), and refuses (`plan_changed`) when the vendor now plans otherwise; a
- * reference to a resource made in this run is given its new binding, and a wakeup's `host` the
- * URL its host's state gives (`outputs(state).url`), found or made in this run. A failed step is reported
- * and the run goes on; a failure that ends the run (`isRunControlError`) ends it.
+ * reference to a resource made in this run is given its new binding, a `from` reference that
+ * resource's state at its path as an earlier step left it (planned as `null` while this apply
+ * changes it there, or a create's while it has none there, so the change is planned and approved
+ * up front, and the step planned again once the value is known: done without a write when it
+ * plans `none`, else expecting the fresh plan; a step whose resource still has none there, its
+ * step failed or not done, fails before its driver is called), and a wakeup's `host` the URL its host's state gives
+ * (`outputs(state).url`), found or made in this run. A failed step is reported and the run
+ * goes on; a failure that ends the run (`isRunControlError`) ends it.
  */
 export function applyWorkflow(
   types: ReadonlyMap<string, Resource>,
@@ -499,15 +546,21 @@ export function applyWorkflow(
           }
         }
       }
-      // Where each declared host answers, as its state says, found now or made below: a wakeup is given it.
+      // Each declared resource's state, found now or made below, for a `from` reference to it, and
+      // where each declared host answers, as its state says: a wakeup is given it.
+      const states = new Map<string, State>();
       const urls = new Map<string, string>();
-      const answersAt = (r: Declaration, state: State) => {
+      // The resources whose step to change them has started and not left a state yet.
+      const unsettled = new Set<string>();
+      const keep = (r: Declaration, state: State) => {
+        states.set(r.id, state);
+        unsettled.delete(r.id);
         const url = types.get(`${r.vendor}.${r.type}`)?.host?.outputs(state).url;
         if (url) urls.set(r.id, url);
       };
       for (const resource of resources) {
         const now = found.get(resource.id);
-        if (now && "state" in now) answersAt(resource, now.state);
+        if (now && "state" in now) keep(resource, now.state);
       }
       // A host wanted runs the commit its ref names now, resolved before planning: a merge is a change
       // to it. One bound by the input needs none.
@@ -534,32 +587,69 @@ export function applyWorkflow(
         }
       }
       const drift = new Map(compare(types, resources, found, revisions).map((result) => [result.id, result]));
-      const desired = new Map(resources.map((r) => [r.id, desiredOf(r, types, locked, hosts, urls)]));
-
+      // Each declaration's fields as planned, each after the ones it names. A `from` field whose
+      // value this apply changes is planned unknown (`null`), so the change it makes is in the plan,
+      // and the approval: its resource created or replaced, or updated where the update's plan
+      // leaves the path unknown or plans another value there. One whose resource has no state
+      // there is `null` in a create's plan, and left out of a bound object's, as drift does, and
+      // run so.
+      const desired = new Map<string, State>();
+      // For each resource a step changes: whether the change touches a path of its state.
+      const touches = new Map<string, (from: string) => boolean>();
+      // For each step, the `from` fields planned left out: run so, not waited for.
+      const dropped = new Map<string, Set<string>>();
+      // The steps planned with a `from` field `null`: planned again at their step, once known.
+      const awaited = new Set<string>();
       const planned: PlanStep[] = [];
+      const add = (step: PlanStep, after?: State) => {
+        planned.push(step);
+        const before = states.get(step.id);
+        if (runOf(step) === "create" || step.action === "replace") touches.set(step.id, () => true);
+        else if (step.action === "update")
+          touches.set(
+            step.id,
+            (from) =>
+              (step.unknown ?? []).some((path) => overlaps(path, from)) ||
+              after === undefined ||
+              !same(valueAt(after, from), valueAt(before, from)),
+          );
+      };
       for (const resource of inDependencyOrder(resources).filter((r) => wanted(r.id))) {
         const result = drift.get(resource.id)!;
+        const changesAt = (named: string, from: string) => touches.get(named)?.(from) ?? false;
+        const missing = (named: string, from: string): Missing =>
+          creates(result) || changesAt(named, from) ? "unknown" : "drop";
+        const stateOf = (named: string, from: string) => (changesAt(named, from) ? undefined : states.get(named));
+        const { desired: fields, unfilled } = desiredOf(
+          resource,
+          types,
+          { bindings: locked, hosts, urls, stateOf },
+          missing,
+        );
+        desired.set(resource.id, fields);
+        const left = unfilled.filter((u) => missing(u.named, u.from) === "drop").map((u) => u.at);
+        if (left.length) dropped.set(resource.id, new Set(left));
+        if (left.length < unfilled.length) awaited.add(resource.id);
         const unresolved = revisions.get(resource.id);
         // A host whose ref could not be resolved has no commit to run (compare says so only for one it found).
         const next =
           unresolved && "error" in unresolved && result.status !== "error"
             ? { problem: problemOf(resource.id, unresolved.error) }
-            : decide(resource, result, found.get(resource.id)!, input, desired.get(resource.id)!, types, usable);
+            : decide(resource, result, found.get(resource.id)!, input, fields, types, usable);
         if (next.ask !== undefined) {
           try {
-            const answer = fromPlan(
-              resource,
-              result,
-              await ctx[resource.vendor]![resource.type]!.plan(next.ask, { connection: resource.connection }),
-            );
-            if (answer.step) planned.push(answer.step);
+            const answered = await ctx[resource.vendor]![resource.type]!.plan(next.ask, {
+              connection: resource.connection,
+            });
+            const answer = fromPlan(resource, result, answered);
+            if (answer.step) add(answer.step, answered.planned);
             if (answer.problem) problems.push(answer.problem);
           } catch (err) {
             if (isRunControlError(err)) throw err;
             problems.push(problemOf(resource.id, `could not be planned: ${errorMessage(err)}`));
           }
         }
-        if (next.step) planned.push(next.step);
+        if (next.step) add(next.step);
         if (next.problem) problems.push(next.problem);
       }
       const orphaned = orphansOf(orphans, input, wanted, usable, types);
@@ -579,47 +669,74 @@ export function applyWorkflow(
       }
 
       const bindings: Bindings = { ...locked };
+      // A resource whose step failed or waited has no state known where its change touches it: a
+      // `from` reference there fails, never given the state before; elsewhere the state stands.
+      const settled = (named: string, from: string) =>
+        unsettled.has(named) && touches.get(named)?.(from) ? undefined : states.get(named);
+      const known: Known = { bindings, hosts, urls, stateOf: settled };
       const results: ApplyResult[] = [];
       let written = false;
       let revision: string | undefined;
       for (const step of plan.steps) {
-        const todo = runOf(step);
+        const declared = declarations.get(step.id);
+        const binding = "binding" in step ? step.binding : "";
+        const run = runOf(step);
+        const writing = run === "create" || run === "update";
+        // For a step that writes them, its fields as the run knows them now, a `from` field from
+        // its resource's state as an earlier step left it. One not known yet is left out, so a
+        // driver is never given `null`: planned unknown, the step fails, its driver not called;
+        // planned left out (its resource had no state there and no change), it runs without.
+        const filled = declared && writing ? desiredOf(declared, types, known, "drop") : undefined;
+        const unfilled = filled?.unfilled.find((u) => !dropped.get(step.id)?.has(u.at));
+        const waiting = unfilled && waitingFor(unfilled);
+        // Unsettled until the step leaves its new state (`keep`). Its URL stays: a host answers
+        // where it did until a change moves it.
+        if (writing) unsettled.add(step.id);
+        const todo = waiting === undefined ? run : "none";
         const key = keyOf(step);
         const type = `${step.vendor}.${step.type}`;
         const before = bindings[key];
-        const binding = "binding" in step ? step.binding : "";
-        const declared = declarations.get(step.id);
         const spec = types.get(type);
         let state: State | undefined;
         try {
           if (todo === "create") {
             const made = await ctx[step.vendor]![step.type]!.create(
-              {
-                desired: desiredOf(declared!, types, bindings, hosts, urls),
-              },
+              { desired: filled!.desired },
               { connection: step.connection },
             );
             bindings[key] = { type, id: made.id, ...(step.connection && { connection: step.connection }) };
             state = made.state;
           } else if (todo === "update" && (step.action === "update" || step.action === "replace")) {
-            const expect = { action: step.action, replace: step.replace };
-            const changed = await ctx[step.vendor]![step.type]!.update(
-              {
-                id: binding,
-                desired: desiredOf(declared!, types, bindings, hosts, urls),
-                expect,
-              },
-              { connection: step.connection },
-            );
-            bindings[key] = { type, id: changed.id, ...(step.connection && { connection: step.connection }) };
-            state = changed.state;
+            // A step planned with a `from` field unknown (its resource changed first) is planned again with its fields as now known: the approval covered the change in kind,
+            // and the vendor now says which. Nothing to write, it is done; else the update expects
+            // the fresh plan, an action other than an update or replace refused as changed.
+            let expect: Expect = { action: step.action, replace: step.replace };
+            let unchanged = false;
+            if (awaited.has(step.id)) {
+              const fresh = await ctx[step.vendor]![step.type]!.plan(
+                { id: binding, desired: filled!.desired },
+                { connection: step.connection },
+              );
+              unchanged = fresh.action === "none";
+              if (fresh.action === "update" || fresh.action === "replace")
+                expect = { action: fresh.action, replace: fresh.replace };
+            }
+            if (unchanged) unsettled.delete(step.id);
+            else {
+              const changed = await ctx[step.vendor]![step.type]!.update(
+                { id: binding, desired: filled!.desired, expect },
+                { connection: step.connection },
+              );
+              bindings[key] = { type, id: changed.id, ...(step.connection && { connection: step.connection }) };
+              state = changed.state;
+            }
           } else if (todo === "delete") {
             await ctx[step.vendor]![step.type]!.delete({ id: binding }, { connection: step.connection });
             delete bindings[key];
           } else if (todo === "bind")
             bindings[key] = { type, id: binding, ...(step.connection && { connection: step.connection }) };
           else if (todo === "forget") delete bindings[key];
-          if (state && declared) answersAt(declared, state);
+          if (state && declared) keep(declared, state);
           const after = bindings[key];
           if (after?.id !== before?.id) {
             const wrote = await steps.write(key, after, messageOf(step, before, after));
@@ -630,7 +747,8 @@ export function applyWorkflow(
           // id, again every few seconds until its output passes `until`; one that never does fails
           // the step, and the rest are not called. The loop `callAfterCreate` has, inline: a
           // function defined here may not close over `ctx`.
-          let stuck: string | undefined;
+          // A step waiting on a `from` reference ran as `none`, and fails here with why.
+          let stuck = waiting;
           for (const hook of todo === "create" ? (spec?.afterCreate ?? []) : []) {
             if (stuck === undefined) {
               const [vendor = "", group = "", name = ""] = hook.op.split(".");

package/src/call.ts

@@ -199,8 +199,8 @@ export function buildCtx(wf: WorkflowDefinition<any, any>, run: Run): any {
 }
 
 /** Who started the run, as `ctx.startedBy` shows it: a plain frozen record, whose absent fields read as undefined. */
-const startedByOf = ({ id, email, subject }: Principal): StartedBy =>
-  Object.freeze({ id, ...(email && { email }), ...(subject && { subject }) });
+const startedByOf = ({ id, email, github, subject }: Principal): StartedBy =>
+  Object.freeze({ id, ...(email && { email }), ...(github && { github }), ...(subject && { subject }) });
 
 /** `members`, each object in it included, refusing any member not in it (`strict`), with `plain`'s as they are. */
 function guarded(

package/src/cloud-identity.ts

@@ -1,6 +1,12 @@
 import { createHash, randomBytes } from "node:crypto";
 import { Compute, OAuth2Client } from "google-auth-library";
 import type { Db } from "./db.ts";
+import { enrollmentBroker } from "./identity-broker.ts";
+export { provisioningIdentityBroker, attachedGoogleIdTokenIssuer } from "./provisioning-identity.ts";
+export type { ProvisioningIdentity, ProvisioningIdToken } from "./provisioning-identity.ts";
+
+export { postgresIdentityProvisioning, IdentityProvisioningError } from "./identity-provisioning.ts";
+export type { IdentityProvisioning, DeploymentIdentity, EnrollIdentity } from "./identity-provisioning.ts";
 
 const LIFETIME = 600_000;
 const SCOPE = "https://www.googleapis.com/auth/cloud-platform";
@@ -15,7 +21,7 @@ export class CloudIdentityError extends Error {
   }
 }
 
-/** Provisioning only. Deliver the value once through deployment secrets; persist only its hash. */
+/** Provisioning only. Deliver through deployment secrets; persist only its hash in the enrollment database. */
 export function createDeploymentCredential(): { credential: string; hash: string } {
   const credential = randomBytes(32).toString("base64url");
   return { credential, hash: credentialHash(credential) };
@@ -103,12 +109,6 @@ export interface IdentityBrokerOptions {
   /** Must durably record the decision without token values. A failure prevents delivery. */
   audit(event: IdentityAudit): Promise<void>;
 }
-const validEnrollment = (e: IdentityEnrollment | undefined): e is IdentityEnrollment =>
-  !!e &&
-  [e.deployment, e.company, e.environment].every((v) => typeof v === "string" && v.length > 0 && v.length <= 256) &&
-  ACCOUNT.test(e.serviceAccount) &&
-  Number.isSafeInteger(e.generation) &&
-  e.generation > 0;
 const validToken = (token: CloudAccessToken, now: number) =>
   typeof token?.accessToken === "string" &&
   token.accessToken.length > 0 &&
@@ -117,77 +117,17 @@ const validToken = (token: CloudAccessToken, now: number) =>
   Number.isFinite(token.expiresAt) &&
   token.expiresAt > now &&
   token.expiresAt <= now + LIFETIME + 30_000;
-const reply = (status: number, body: unknown) =>
-  Response.json(body, {
-    status,
-    headers: { "Cache-Control": "no-store", Pragma: "no-cache" },
-  });
-
-// Node/edge adapters can represent an empty POST as a stream. Reject actual bytes,
-// without buffering attacker-controlled input or waiting indefinitely for its end.
-async function hasBody(request: Request): Promise<boolean> {
-  if (!request.body) return false;
-  const reader = request.body.getReader();
-  let timeout: ReturnType<typeof setTimeout> | undefined;
-  try {
-    const first = await Promise.race([
-      reader.read(),
-      new Promise<never>((_, reject) => {
-        timeout = setTimeout(() => reject(new CloudIdentityError()), 5_000);
-      }),
-    ]);
-    return !first.done;
-  } finally {
-    clearTimeout(timeout);
-    void reader.cancel().catch(() => {});
-  }
-}
-
 /** POST /token with a deployment bearer credential and no query or body. No enrollment endpoint. */
 export function identityBroker(options: IdentityBrokerOptions): (request: Request) => Promise<Response> {
-  return async (request) => {
-    let enrollment: IdentityEnrollment | undefined;
-    try {
-      const url = new URL(request.url);
-      if (url.pathname !== "/token" || request.method !== "POST") return reply(404, { error: "not_found" });
-      if (url.search || (await hasBody(request))) return reply(400, { error: "invalid_request" });
-      const authorization = request.headers.get("authorization") ?? "";
-      const credential = authorization.startsWith("Bearer ") ? authorization.slice(7) : "";
-      const hash = CREDENTIAL.test(credential) ? credentialHash(credential) : undefined;
-      enrollment = hash ? await options.enrollments.active(hash) : undefined;
-      if (!validEnrollment(enrollment)) {
-        await options.audit({ result: "denied" });
-        return reply(401, { error: "unauthorized" });
-      }
-      // Copy authoritative values before any awaits; caller fields never select a target or lifetime.
-      enrollment = {
-        deployment: enrollment.deployment,
-        company: enrollment.company,
-        environment: enrollment.environment,
-        serviceAccount: enrollment.serviceAccount,
-        generation: enrollment.generation,
-      };
-      const token = await options.issue(enrollment.serviceAccount);
-      if (!validToken(token, Date.now())) throw new CloudIdentityError();
-      const current = await options.enrollments.active(hash!);
-      if (
-        !current ||
-        (Object.keys(enrollment) as (keyof IdentityEnrollment)[]).some((key) => current[key] !== enrollment![key])
-      ) {
-        await options.audit({ result: "denied", enrollment });
-        return reply(401, { error: "unauthorized" });
-      }
-      await options.audit({ result: "issued", enrollment, expiresAt: token.expiresAt });
-      return reply(200, { accessToken: token.accessToken, expiresAt: token.expiresAt });
-    } catch {
-      try {
-        await options.audit({ result: "unavailable", ...(enrollment && { enrollment }) });
-      } catch {
-        /* fail closed */
-      }
-      return reply(503, { error: "unavailable" });
-    }
-  };
+  return enrollmentBroker({
+    ...options,
+    path: "/token",
+    method: "POST",
+    accept: () => true,
+    issue: (enrollment) => options.issue(enrollment.serviceAccount),
+    valid: validToken,
+    body: (token) => ({ accessToken: token.accessToken, expiresAt: token.expiresAt }),
+  });
 }
 
 /** Cloud Run attached identity only: no ADC environment file or service-account private key fallback. */

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,7 +53,7 @@ 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 { checkFromRefs, type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
 import { CODE_MAIL, loginCodeWorkflow } from "./login-code.ts";
 import {
   APPLY_WORKFLOW,
@@ -107,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`. */
@@ -349,6 +352,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   ]);
   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(
@@ -357,7 +361,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       changeDriver(remotes),
       connectionDriver(connections),
       appsListDriver,
-      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()) }),
+      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()), identities: config.identityProvisioning }),
       ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],

package/src/define.ts

@@ -23,6 +23,11 @@ export interface Principal {
    * 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`.
@@ -35,17 +40,20 @@ export const Principal: z.ZodType<Principal> = z.object({
   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 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.
+ * `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;
 }
 

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

package/src/drift.ts

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
 import { isRunControlError } from "./errors.ts";
 import type { Op } from "./op.ts";
-import { type DriftField, diffDeclared, fieldPathOf, type Resource, valueAt } from "./resource.ts";
+import { type DriftField, diffDeclared, fieldPathOf, type Resource, valueAt, withFrom } from "./resource.ts";
 import type { DeclaredResource, ResourceProblem } from "./resources.ts";
 import { type DRIFT_WORKFLOW, errorMessage } from "./shared.ts";
 import { SOURCE_RESOLVE, type sourceOps } from "./source.ts";
@@ -128,8 +128,10 @@ export const observed = (out: { gone: boolean; state?: State }): Found =>
  * Each declared resource against what its import `found`: `error`, `absent` (unbound, with the
  * binding id of what its identity found as `found`), `gone`, else the state and the declared
  * fields compared by `diffDeclared`, a reference against the state of the resource it names
- * (so GitHub's node id for a repository counts as its name). A host with a `revisions` entry
- * also compares its revision against the commit its ref names now (or is that entry's `error`).
+ * (so GitHub's node id for a repository counts as its name), and a `from` reference's field
+ * against that resource's state at its path, left out while that resource is absent, gone or
+ * unreadable (its own row says so). A host with a `revisions` entry also compares its revision
+ * against the commit its ref names now (or is that entry's `error`).
  */
 export function compare(
   types: ReadonlyMap<string, Resource>,
@@ -137,6 +139,12 @@ export function compare(
   found: ReadonlyMap<string, Found>,
   revisions: ReadonlyMap<string, Revision> = new Map(),
 ): DriftResult[] {
+  const bound = new Set(resources.filter((r) => r.binding !== undefined).map((r) => r.id));
+  // A resource's state as a `from` reference takes it: only a bound one's, read in this run.
+  const stateOf = (target: string) => {
+    const now = found.get(target);
+    return bound.has(target) && now && "state" in now ? now.state : undefined;
+  };
   return resources.map(({ id, vendor, type, name, binding, desired, refs }): DriftResult => {
     const row = { id, type, vendor, name, ...(binding !== undefined && { binding }) };
     const now = found.get(id)!;
@@ -158,7 +166,8 @@ export function compare(
       const named = found.get(target);
       if (named && "state" in named) accept[at] = by.map((field) => named.state[field]).filter((v) => v != null);
     }
-    const fields = diffDeclared(resource, now.state, desired, accept);
+    const declared = withFrom(resource.fields.references, desired, refs, stateOf, "drop").desired;
+    const fields = diffDeclared(resource, now.state, declared, accept);
     const resolved = revisions.get(id);
     if (resolved && "error" in resolved) return { ...row, status: "error", fields: [], error: resolved.error };
     // A host whose state does not say which commit it runs is not compared.