@sanoma-ai/workflows 0.10.1 → 0.10.3

package/src/cloud-identity.ts

@@ -0,0 +1,266 @@
+import { createHash, randomBytes } from "node:crypto";
+import { Compute, OAuth2Client } from "google-auth-library";
+import type { Db } from "./db.ts";
+
+const LIFETIME = 600_000;
+const SCOPE = "https://www.googleapis.com/auth/cloud-platform";
+const CREDENTIAL = /^[A-Za-z0-9_-]{43}$/;
+const ACCOUNT = /^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/;
+
+/** A safe error boundary: no HTTP response, credentials, SDK cause or request options. */
+export class CloudIdentityError extends Error {
+  constructor() {
+    super("Cloud identity unavailable");
+    this.name = "CloudIdentityError";
+  }
+}
+
+/** Provisioning only. Deliver the value once through deployment secrets; persist only its hash. */
+export function createDeploymentCredential(): { credential: string; hash: string } {
+  const credential = randomBytes(32).toString("base64url");
+  return { credential, hash: credentialHash(credential) };
+}
+const credentialHash = (credential: string) => createHash("sha256").update(credential).digest("hex");
+
+export interface IdentityEnrollment {
+  deployment: string;
+  company: string;
+  environment: string;
+  serviceAccount: string;
+  generation: number;
+}
+export interface IdentityEnrollments {
+  /** Return an enrollment only while this hash/generation and deployment are active. Never cache. */
+  active(hash: string): Promise<IdentityEnrollment | undefined>;
+}
+
+/** Install in the broker's own database using provisioning authority, never a company database. */
+export const CLOUD_IDENTITY_SQL = `
+CREATE SCHEMA IF NOT EXISTS sanoma_identity;
+REVOKE ALL ON SCHEMA sanoma_identity FROM PUBLIC;
+CREATE TABLE IF NOT EXISTS sanoma_identity.deployments (
+  id text PRIMARY KEY, company text NOT NULL, environment text NOT NULL,
+  service_account text NOT NULL, enabled boolean NOT NULL DEFAULT true
+);
+CREATE TABLE IF NOT EXISTS sanoma_identity.credentials (
+  hash text PRIMARY KEY CHECK (hash ~ '^[0-9a-f]{64}$'),
+  deployment text NOT NULL REFERENCES sanoma_identity.deployments(id),
+  generation bigint NOT NULL CHECK (generation > 0),
+  valid_from timestamptz NOT NULL DEFAULT now(), valid_until timestamptz NOT NULL,
+  revoked boolean NOT NULL DEFAULT false,
+  UNIQUE (deployment, generation), CHECK (valid_until > valid_from),
+  CHECK (isfinite(valid_from) AND isfinite(valid_until))
+);
+REVOKE ALL ON ALL TABLES IN SCHEMA sanoma_identity FROM PUBLIC;
+`;
+
+/** Give the broker SELECT only; enrollment, rotation and revocation use a separate database role. */
+export function postgresIdentityEnrollments(database: () => Promise<Db>): IdentityEnrollments {
+  return {
+    async active(hash) {
+      const { rows } = await (
+        await database()
+      ).query<{
+        deployment: string;
+        company: string;
+        environment: string;
+        service_account: string;
+        generation: string;
+      }>(
+        `SELECT d.id AS deployment, d.company, d.environment, d.service_account, c.generation
+          FROM sanoma_identity.credentials c JOIN sanoma_identity.deployments d ON d.id = c.deployment
+          WHERE c.hash = $1 AND NOT c.revoked AND d.enabled
+            AND c.valid_from <= clock_timestamp() AND c.valid_until > clock_timestamp()`,
+        [hash],
+      );
+      const row = rows[0];
+      return (
+        row && {
+          deployment: row.deployment,
+          company: row.company,
+          environment: row.environment,
+          serviceAccount: row.service_account,
+          generation: Number(row.generation),
+        }
+      );
+    },
+  };
+}
+
+export interface CloudAccessToken {
+  accessToken: string;
+  expiresAt: number;
+}
+export interface IdentityAudit {
+  result: "issued" | "denied" | "unavailable";
+  enrollment?: IdentityEnrollment;
+  expiresAt?: number;
+}
+export interface IdentityBrokerOptions {
+  enrollments: IdentityEnrollments;
+  /** Trusted issuer with attached platform authority; target comes exclusively from enrollment. */
+  issue(serviceAccount: string): Promise<CloudAccessToken>;
+  /** 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 &&
+  token.accessToken.length <= 8192 &&
+  !/[\s\r\n]/.test(token.accessToken) &&
+  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" });
+    }
+  };
+}
+
+/** Cloud Run attached identity only: no ADC environment file or service-account private key fallback. */
+export function attachedGoogleTokenIssuer(): IdentityBrokerOptions["issue"] {
+  const auth = new Compute({ scopes: [SCOPE] });
+  return async (serviceAccount) => {
+    if (!ACCOUNT.test(serviceAccount)) throw new CloudIdentityError();
+    try {
+      const response = await auth.request<{ accessToken: string; expireTime: string }>({
+        url: `https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/${serviceAccount}:generateAccessToken`,
+        method: "POST",
+        data: { scope: [SCOPE], lifetime: "600s" },
+        timeout: 10_000,
+      });
+      const token = { accessToken: response.data.accessToken, expiresAt: Date.parse(response.data.expireTime) };
+      if (!validToken(token, Date.now())) throw new CloudIdentityError();
+      return token;
+    } catch {
+      throw new CloudIdentityError();
+    }
+  };
+}
+
+/** A per-runtime Google SDK auth client. Short-lived access tokens are kept only in this instance's memory. */
+export function cloudIdentityAuth(options: {
+  endpoint: string;
+  /** Read the current deployment credential from protected bootstrap; called again on renewal. */
+  credential(): Promise<string>;
+}): OAuth2Client {
+  let endpoint: URL;
+  try {
+    endpoint = new URL(options.endpoint);
+  } catch {
+    throw new CloudIdentityError();
+  }
+  if (
+    endpoint.protocol !== "https:" ||
+    endpoint.username ||
+    endpoint.password ||
+    endpoint.search ||
+    endpoint.hash ||
+    endpoint.pathname !== "/token"
+  )
+    throw new CloudIdentityError();
+  const client = new OAuth2Client({ eagerRefreshThresholdMillis: 60_000 });
+  let pending: Promise<{ access_token: string; expiry_date: number }> | undefined;
+  client.refreshHandler = () => {
+    if (pending) return pending;
+    pending = (async () => {
+      try {
+        const credential = await options.credential();
+        if (!CREDENTIAL.test(credential)) throw new CloudIdentityError();
+        const response = await fetch(endpoint, {
+          method: "POST",
+          headers: { Authorization: `Bearer ${credential}` },
+          cache: "no-store",
+          redirect: "error",
+          signal: AbortSignal.timeout(10_000),
+        });
+        if (!response.ok) throw new CloudIdentityError();
+        const raw = await response.text();
+        if (raw.length > 16_384) throw new CloudIdentityError();
+        const token = JSON.parse(raw) as CloudAccessToken;
+        const now = Date.now();
+        if (!validToken(token, now) || token.expiresAt <= now + 60_000) throw new CloudIdentityError();
+        return { access_token: token.accessToken, expiry_date: token.expiresAt };
+      } catch {
+        throw new CloudIdentityError();
+      } finally {
+        pending = undefined;
+      }
+    })();
+    return pending;
+  };
+  return client;
+}

package/src/config.ts

@@ -53,14 +53,25 @@ import {
 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 { 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";
@@ -131,6 +142,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 +168,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 +198,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,12 +336,14 @@ 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)] : []),
   ]);
@@ -329,6 +357,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
       changeDriver(remotes),
       connectionDriver(connections),
       appsListDriver,
+      runtimeDriver({ tokens: tokenStore(() => connectionPool.db()) }),
       ...(hostTyped ? [sourceDriver] : []),
       ...(dataStore ? [collectionsDriver(declared, dataStore)] : []),
     ],
@@ -342,7 +371,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 +397,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 +415,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 +424,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 +439,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 +486,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 +602,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 +791,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/connection.ts

@@ -565,7 +565,10 @@ export class ConnectionRegistry {
     const method = this.catalog.methods.get(row.vendor)![row.method]!;
     const bundle = row.credential ? await this.secrets?.read(row.credential) : undefined;
     if (row.credential && !bundle) throw new SecretStoreError("unavailable");
-    const identity = await verifyAuthentication(method, bundle && decodeCredentials(method, bundle.value));
+    const identity = await verifyAuthentication(method, bundle && decodeCredentials(method, bundle.value), {
+      connectionId: row.id,
+      vendor: row.vendor,
+    });
     if (identity.account !== row.account) throw new AuthenticationError("wrong_account");
     if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(row.scopes)].toSorted()))
       throw new AuthenticationError("scope_changed");
@@ -670,7 +673,10 @@ export class ConnectionRegistry {
       material.credentials = decodeCredentials(method, bundle.value);
       material.credentialVersion = bundle.version;
     }
-    const identity = await verifyAuthentication(method, material.credentials);
+    const identity = await verifyAuthentication(method, material.credentials, {
+      connectionId: selected.id,
+      vendor: selected.vendor,
+    });
     if (identity.account !== selected.account) throw new AuthenticationError("wrong_account");
     if (JSON.stringify(identity.scopes) !== JSON.stringify([...new Set(selected.scopes)].toSorted()))
       throw new AuthenticationError("scope_changed");

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