@sanoma-ai/workflows 0.10.2 → 0.10.6

package/src/call.ts

@@ -11,6 +11,7 @@ import {
   SleepFor,
   type SleepRequest,
   SleepUntil,
+  type StartedBy,
   scriptPath,
   type Use,
   type WorkflowDefinition,
@@ -33,14 +34,18 @@ import { callAt, callName, type CallNode } from "./outline.ts";
 import { allowAll, type Decision, type Policy, type PolicyCall, policyOpOf, type RecordedDecision } from "./policy.ts";
 import type { Run, StartHold, WorkerState } from "./run.ts";
 import { reservedFor, runtimeHold } from "./change.ts";
+import { isChangeOp } from "./resource.ts";
 import { readPeople } from "./resources.ts";
 import {
+  APPLY_WORKFLOW,
   approverLabel,
   CALL_WORKFLOW,
   CHANGE_MERGE,
   DATA_VENDOR,
   errorMessage,
   fitsOp,
+  LOGIN_CODE_WORKFLOW,
+  problemLine,
   type Saved,
   WORKFLOW_ACTION,
 } from "./shared.ts";
@@ -64,11 +69,18 @@ export function isInfrastructureError(err: unknown, state: Pick<WorkerState, "st
   return takenByDbos(err) || (state.stopped && errorCode(err) === undefined);
 }
 
-/** The value as the ledger records it: each of the operation's `opaque` fields as `"<name>"`. */
-export function recorded(op: Op, value: unknown): unknown {
-  if (!op.opaque?.length || typeof value !== "object" || value === null || Array.isArray(value)) return value;
+/** The fields of a mail a `login-code` run sends that the ledger never shows: its body, which holds the code. */
+const LOGIN_CODE_BODY = ["text", "html"];
+
+/**
+ * The value as the ledger records it: each of the operation's `opaque` fields as `"<name>"`, and
+ * in a run of `workflow` `login-code`, the mail's `text` and `html` too, so no colleague reads another's code.
+ */
+export function recorded(op: Op, value: unknown, workflow?: string): unknown {
+  const hidden = [...(op.opaque ?? []), ...(workflow === LOGIN_CODE_WORKFLOW ? LOGIN_CODE_BODY : [])];
+  if (!hidden.length || typeof value !== "object" || value === null || Array.isArray(value)) return value;
   const out: Record<string, unknown> = { ...value };
-  for (const name of op.opaque) if (out[name] !== undefined) out[name] = `<${name}>`;
+  for (const name of hidden) if (out[name] !== undefined) out[name] = `<${name}>`;
   return out;
 }
 
@@ -80,13 +92,12 @@ const isSchemaError = (err: unknown) => err instanceof Error && err.name === "Zo
 
 /**
  * Whether DBOS should try an idempotent step again: not when the reply failed the output
- * schema (it would fail again), and not when the driver said the vendor's answer is final
- * (a `DriverError` with `retryable: false`, such as a 4xx). Read by code and property, never
- * `instanceof`: the error may come from another copy of this package.
+ * schema (it would fail again), and not when the error says its answer is final (`retryable:
+ * false`: a `DriverError` for a 4xx, a `SecretStoreError` other than `unavailable`). Read by
+ * property, never `instanceof`: the error may come from another copy of this package.
  */
 function shouldRetry(err: unknown): boolean {
-  if (isSchemaError(err)) return false;
-  return !(errorCode(err) === "driver_failed" && isFinal(err));
+  return !isSchemaError(err) && !isFinal(err);
 }
 
 /*
@@ -184,11 +195,20 @@ export function buildCtx(wf: WorkflowDefinition<any, any>, run: Run): any {
     );
   }
   if (uses.includes("all")) members.all = placed("all", (node, list) => all(run, list, node.path));
-  return guarded(members, "ctx", wf.name);
+  return guarded(members, "ctx", wf.name, { startedBy: startedByOf(run.actor) });
 }
 
-/** `members`, each object in it included, refusing any member not in it (`strict`). */
-function guarded(members: Record<string, unknown>, path: string, workflow: string): Record<string, unknown> {
+/** Who started the run, as `ctx.startedBy` shows it: a plain frozen record, whose absent fields read as undefined. */
+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(
+  members: Record<string, unknown>,
+  path: string,
+  workflow: string,
+  plain: Record<string, unknown> = {},
+): Record<string, unknown> {
   const out: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(members)) {
     out[key] =
@@ -196,7 +216,7 @@ function guarded(members: Record<string, unknown>, path: string, workflow: strin
         ? guarded(value as Record<string, unknown>, `${path}.${key}`, workflow)
         : value;
   }
-  return strict(out, path, workflow);
+  return strict({ ...out, ...plain }, path, workflow);
 }
 
 /** Where a `ctx` member was called from, as a stack frame says. */
@@ -425,6 +445,50 @@ function ask(
   return policy.version === undefined ? decision : { ...decision, policyVersion: policy.version };
 }
 
+/**
+ * Refuses a change operation (`isChangeOp`) aimed at an object the data files declare, which only
+ * apply changes: an `update` or `delete` of an id the lockfile binds or a data file names, and a
+ * `create` or `update` whose identity (what its type's `find` makes of `desired`) a data file
+ * declares or the lockfile binds. Any other object is the workflow's own, its change an ordinary
+ * write. While the files have problems, which objects they declare is not known, so it refuses.
+ */
+async function refuseDeclared(run: Run, op: Op, input: unknown) {
+  const type = `${op.vendor}.${op.resource}`;
+  const { id, desired } = input as { id?: unknown; desired?: Record<string, unknown> };
+  const targets: string[] = [];
+  if (op.name !== "create" && typeof id === "string") targets.push(id);
+  const find = run.state.types.get(type)?.find;
+  if (op.name !== "delete" && desired && find) {
+    try {
+      targets.push(find(desired));
+    } catch (err) {
+      throw new SanomaError(
+        "invalid_input",
+        `${op.id}: its desired names no ${type} (${errorMessage(err)}), so it cannot be told from a declared one`,
+        { op: op.id, workflow: run.workflow },
+      );
+    }
+  }
+  if (!targets.length) return;
+  const declared = await run.state.declaredObjects();
+  if (declared.problems.length) {
+    throw new SanomaError(
+      "invalid_input",
+      `${op.id} waits for the data files to be fixed, since only apply changes a declared resource: ${declared.problems.map(problemLine).join("; ")}`,
+      { op: op.id, workflow: run.workflow },
+    );
+  }
+  for (const target of targets) {
+    const key = declared.keys.get(`${type} ${target}`);
+    if (key === undefined) continue;
+    throw new SanomaError(
+      "invalid_input",
+      `${op.id} changes ${key}, a declared resource, which only apply does: change the data file instead`,
+      { op: op.id, workflow: run.workflow, declared: key },
+    );
+  }
+}
+
 async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?: ConnectionRef) {
   // The worker's declaration, never the workflow's: its effect, schemas and retry setting.
   const op = run.state.ops.get(id);
@@ -437,9 +501,8 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?:
         : `No connector or fake for ${id} in this worker: no fake its connectors attach implements it`,
     );
   }
-  // Only apply changes a declared resource, and only change takes a change's steps; `resolveConfig`
-  // refuses any other workflow that uses such an operation.
-  const reserved = reservedFor(op, run.state.types);
+  // Only change takes a change's steps; `resolveConfig` refuses any other workflow that uses one.
+  const reserved = reservedFor(op);
   if (reserved && run.workflow !== reserved.workflow) {
     throw new SanomaError("invalid_input", `${op.id} ${reserved.does}, which only ${reserved.workflow} does`, {
       op: op.id,
@@ -469,12 +532,15 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?:
     DBOS.runStep(
       async () => {
         if (run.sandbox === undefined) await run.state.connections?.assertCurrent(connection, run.actor.id);
+        // Read in the step, so a replay reuses the first answer, and asked again after each
+        // approval, so a call made after a long wait sees the files as they are then.
+        if (run.workflow !== APPLY_WORKFLOW && isChangeOp(op, run.state.types)) await refuseDeclared(run, op, parsed);
         return decide(run, op, parsed, connection);
       },
       { name: `policy:${op.id}` },
     );
   let decision = await decideStep();
-  const logged = recorded(op, parsed);
+  const logged = recorded(op, parsed, run.workflow);
   const call = {
     type: "op.called",
     op: op.id,
@@ -567,7 +633,11 @@ async function callOp(run: Run, id: string, input: unknown, place: Placed, ref?:
   try {
     await write(
       run,
-      entry(run, { ...call, output: recorded(op, output), durationMs, attempt: result.attempt }, { seq, at }),
+      entry(
+        run,
+        { ...call, output: recorded(op, output, run.workflow), durationMs, attempt: result.attempt },
+        { seq, at },
+      ),
     );
   } catch (err) {
     // The vendor acted, and nothing records it. A workflow that caught this and called again

package/src/change.ts

@@ -3,18 +3,9 @@ import type { ApprovalState, Approver } from "./define.ts";
 import { errorInfo } from "./errors.ts";
 import { type CallContext, defineConnector, defineDriver, type Driver, DriverError } from "./op.ts";
 import { approve, approvedFor, type Decision, deny } from "./policy.ts";
-import { isChangeOp, type Resource } from "./resource.ts";
 import { currentRun } from "./run.ts";
 import type { Secrets } from "./secret.ts";
-import {
-  APPLY_WORKFLOW,
-  CHANGE_MERGE,
-  CHANGE_WORKFLOW,
-  DRAFT_ID,
-  errorMessage,
-  groupNamesOf,
-  type PeopleResource,
-} from "./shared.ts";
+import { CHANGE_MERGE, CHANGE_WORKFLOW, DRAFT_ID, errorMessage, groupNamesOf, type PeopleResource } from "./shared.ts";
 import {
   type CheckResult,
   type RemoteContext,
@@ -117,17 +108,15 @@ export const changeOps = defineConnector("sanoma", {
 
 /**
  * The built-in workflow that alone may call `op`, what the operation does and what to do instead:
- * `apply` for a writable resource type's change operations (`isChangeOp`), `change` for
- * `sanoma.change.*`; undefined for any other. `resolveConfig` refuses a workflow that uses one, and
- * a run's call of one outside its workflow fails.
+ * `change` for `sanoma.change.*`; undefined for any other. `resolveConfig` refuses a workflow that
+ * uses one, and a run's call of one outside its workflow fails. A resource type's change
+ * operations are not reserved: any workflow may call them for an object no data file declares,
+ * and the call refuses a declared one (`refuseDeclared` in `call.ts`), which only apply changes.
  */
-export function reservedFor(
-  op: { readonly vendor: string; readonly resource: string; readonly name: string },
-  types: ReadonlyMap<string, Pick<Resource, "writable">>,
-): { workflow: string; does: string; instead: string } | undefined {
-  if (isChangeOp(op, types)) {
-    return { workflow: APPLY_WORKFLOW, does: "changes a declared resource", instead: "change the data file" };
-  }
+export function reservedFor(op: {
+  readonly vendor: string;
+  readonly resource: string;
+}): { workflow: string; does: string; instead: string } | undefined {
   if (op.vendor === "sanoma" && op.resource === "change") {
     return { workflow: CHANGE_WORKFLOW, does: "changes the company's repository", instead: "send a draft for review" };
   }

package/src/client.ts

@@ -26,6 +26,7 @@ import {
 } from "./approvals.ts";
 import { beforeOf, decideCall, decideStart, recorded, startHoldOf } from "./call.ts";
 import { type Chats, chatStore } from "./chats.ts";
+import { type Tokens, tokenStore } from "./tokens.ts";
 import { collectionsDriver } from "./collection.ts";
 import { type ResolvedConfig, resolveConfig, type SanomaConfig } from "./config.ts";
 import { configuredSecrets } from "./credentials.ts";
@@ -58,9 +59,9 @@ import {
   SanomaError,
   vendorCodeOf,
 } from "./errors.ts";
-import { insertRecord, type LedgerRecord, type OwnedLedger, ownedLedger } from "./ledger.ts";
+import { insertRecord, lastSignIns, type LedgerRecord, loginRecord, type OwnedLedger, ownedLedger } from "./ledger.ts";
 import { warn } from "./log.ts";
-import type { CallContext, Driver, Op } from "./op.ts";
+import type { CallContext, Driver, Op, SignInMethod } from "./op.ts";
 import { allowAll, type RecordedDecision } from "./policy.ts";
 import { admit, readPeople } from "./resources.ts";
 import type { RunArgs, StartHold } from "./run.ts";
@@ -78,6 +79,7 @@ import {
   errorMessage,
   HOST_CHECK_AGENT,
   isEnded,
+  isToken,
   isVisitor,
   refusalOf,
   type RunStatus,
@@ -268,6 +270,8 @@ export class SanomaClient {
   private readonly storedSecrets: SecretAccess;
   /** The operator agent's chats: their rows and their transcripts, in the config's database. */
   readonly chats: Chats;
+  /** The api tokens a public site's api takes as a bearer (`token:<id>`, a visitor): minted, revoked, resolved. */
+  readonly tokens: Tokens;
   private readonly options: ClientOptions;
 
   private constructor(
@@ -284,6 +288,7 @@ export class SanomaClient {
     this.pool = lazyPool(config.databaseUrl, "client");
     this.storedSecrets = configuredSecrets(config.secrets, () => this.db());
     this.chats = chatStore(() => this.db());
+    this.tokens = tokenStore(() => this.db());
   }
 
   /**
@@ -315,11 +320,13 @@ export class SanomaClient {
     input: z.input<S>,
     options: StartOptions,
   ): Promise<string> {
-    const startedBy = await this.admitted(
-      parseOrThrow(
-        PrincipalOrId,
-        options?.startedBy,
-        '`startedBy` must be a principal, such as "alice" or { id: "alice" }',
+    const startedBy = await this.withSubject(
+      await this.admitted(
+        parseOrThrow(
+          PrincipalOrId,
+          options?.startedBy,
+          '`startedBy` must be a principal, such as "alice" or { id: "alice" }',
+        ),
       ),
     );
     if (typeof workflow === "string") {
@@ -639,6 +646,32 @@ export class SanomaClient {
     return row ? { runId: row.workflowID, output: row.output, at: row.updatedAt ?? row.createdAt } : null;
   }
 
+  /** Records that the declared `person` signed in to the staff login, by `method`: a ledger record outside any run. */
+  async recordSignIn(person: string, method: SignInMethod): Promise<void> {
+    const actor = await this.admitted({ id: person });
+    await this.audit.store.append(
+      loginRecord(this.config.appName, actor, { type: "signin.recorded", person: actor.id, method }),
+    );
+  }
+
+  /** Records that `by` minted an invite for the declared `person`, good until `expiresAt`: a ledger record outside any run. */
+  async recordInvite(person: string, options: { by: string; expiresAt: Date }): Promise<void> {
+    const [actor, invited] = await Promise.all([this.admitted({ id: options.by }), this.admitted({ id: person })]);
+    await this.audit.store.append(
+      loginRecord(this.config.appName, actor, {
+        type: "invite.minted",
+        person: invited.id,
+        by: actor.id,
+        expiresAt: options.expiresAt.toISOString(),
+      }),
+    );
+  }
+
+  /** When each of `people` last signed in to the staff login, and how, by id (`recordSignIn`); one who never did is left out. */
+  lastSignIns(people: readonly string[]): Promise<Record<string, { at: number; method: SignInMethod }>> {
+    return lastSignIns(this.audit.store, people);
+  }
+
   /** The run's audit record, in order, from the ledger store. */
   async ledger(runId: string): Promise<LedgerRecord[]> {
     await this.mustExist(runId);
@@ -1470,6 +1503,14 @@ export class SanomaClient {
     return admit(principal, readPeople(this.config.root));
   }
 
+  /** An api token's principal (`token:<id>`) with the subject its row acts for, refused once the token is revoked; anyone else as given. */
+  private async withSubject(principal: Principal): Promise<Principal> {
+    if (!isToken(principal)) return principal;
+    const subject = await this.tokens.subjectOf(principal.id.slice("token:".length));
+    if (subject === undefined) throw new NotAdmittedError(principal.id);
+    return { ...principal, subject };
+  }
+
   /** `options.by`, who sets or clears a credential, admitted (`admitted`): their id; never a visitor's. */
   private async admittedBy(options: { by: string }): Promise<string> {
     const by = parseOrThrow(z.string().min(1), options?.by, '`by` must name who is asking, such as "alice"');

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. */