@sanoma-ai/workflows 0.10.2 → 0.10.6

package/src/runtime-ops.ts

@@ -0,0 +1,313 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { keyBytes } from "./deployment-key.ts";
+import { type CallContext, defineConnector, defineDriver, DriverError, retryableStatus } from "./op.ts";
+import { generateSecret, SECRET_NAME } from "./secret.ts";
+import { sealInvite } from "./seal.ts";
+import { errorMessage } from "./shared.ts";
+import { sourceKeyPair, sshPublicKey } from "./ssh-key.ts";
+import { memoryTokens, type Tokens } from "./tokens.ts";
+import {
+  identityProvisioningCode,
+  memoryIdentityProvisioning,
+  type IdentityProvisioning,
+} from "./identity-provisioning.ts";
+
+// What a workflow cannot do itself and the runtime does for it, as operations of the vendor
+// `sanoma` (`sanoma.secret.*`, `sanoma.invite.mint`, `sanoma.token.*`): named in `uses`, decided by
+// the policy, recorded in the ledger, and never answering a secret's value. `resolveConfig`
+// registers them in every config with their driver (`runtimeDriver`), so a policy may name them;
+// a sandbox run calls `sandboxRuntimeDriver`, over its own secrets and tokens, posting nothing.
+
+/** A secret's name, as the store takes it (upper case), other than the runtime's own (`SANOMA_…`: its keys and credentials). */
+const SecretName = z
+  .string()
+  .regex(SECRET_NAME, "a secret's name: upper case, A-Z, 0-9 and _")
+  .refine((name) => !name.startsWith("SANOMA_"), "a SANOMA_ name is the runtime's own, not a workflow's to use");
+
+/** How long an instance gets to answer `POST /auth/invite`. */
+const INVITE_TIMEOUT_MS = 10_000;
+
+const DeploymentIdentity = z.object({
+  deployment: z.string().min(1).max(256),
+  company: z.string().min(1).max(256),
+  environment: z.string().min(1).max(256),
+  serviceAccount: z.string().regex(/^[a-z][a-z0-9-]+@[a-z][a-z0-9-]+\.iam\.gserviceaccount\.com$/),
+});
+const Generation = z.number().int().positive().max(Number.MAX_SAFE_INTEGER);
+const IdentityTarget = ({ deployment }: { deployment: string }) => deployment;
+
+// Enrollment implementations can see credential hashes and database credentials. Neither their
+// errors nor causes may be captured in durable driver history, including on an uncertain commit.
+async function identityWrite(write: () => Promise<void>): Promise<void> {
+  try {
+    await write();
+  } catch (error) {
+    const code = identityProvisioningCode(error) ?? "unavailable";
+    throw new DriverError(`Identity provisioning: ${code}`, { retryable: code === "unavailable" });
+  }
+}
+
+/**
+ * The runtime's own operations a workflow calls: `import { sanoma } from "sanoma"`, then
+ * `uses: [sanoma.secret.generate]` and `ctx.sanoma.secret.generate({ name, kind })`.
+ */
+export const sanoma = defineConnector("sanoma", {
+  identity: {
+    enroll: {
+      effect: "access",
+      idempotent: true,
+      description:
+        "Enroll a deployment identity, keeping its bootstrap credential in the secret store. A higher generation rotates it; mappings are immutable",
+      input: DeploymentIdentity.extend({ generation: Generation, validUntil: z.iso.datetime(), store: SecretName }),
+      output: z.object({ deployment: z.string(), generation: Generation, store: z.string() }),
+      target: IdentityTarget,
+      createsSecrets: ({ store }: { store: string }) => [store],
+    },
+    retire: {
+      effect: "access",
+      idempotent: true,
+      description:
+        "Shorten an old identity generation's validity after delivering its replacement; never extend access",
+      input: DeploymentIdentity.extend({ generation: Generation, validUntil: z.iso.datetime() }),
+      output: z.object({}),
+      target: IdentityTarget,
+    },
+    revoke: {
+      effect: "access",
+      idempotent: true,
+      description: "Disable all token renewal for a deployment. This deployment id cannot be re-enrolled",
+      input: DeploymentIdentity,
+      output: z.object({}),
+      target: IdentityTarget,
+    },
+  },
+  secret: {
+    generate: {
+      effect: "write",
+      // A value stored is kept: a retry answers what the first try stored.
+      idempotent: true,
+      description:
+        "Make a secret and store it under a name: a random value, or an RSA key pair whose private half (PEM) is stored and whose public half (OpenSSH) is answered. A name stored already is kept",
+      input: z.object({
+        name: SecretName,
+        kind: z.enum(["random", "ssh-rsa"]).describe("random: 32 random bytes; ssh-rsa: an RSA deploy key"),
+      }),
+      output: z.object({
+        name: z.string(),
+        publicKey: z.string().optional().describe("For ssh-rsa: the public half, `ssh-rsa <base64>`"),
+      }),
+      target: ({ name }: { name: string }) => name,
+      createsSecrets: ({ name }: { name: string }) => [name],
+    },
+    delete: {
+      effect: "write",
+      idempotent: true,
+      description: "Delete a stored secret; one not stored is nothing to do",
+      input: z.object({ name: SecretName }),
+      output: z.object({}),
+      target: ({ name }: { name: string }) => name,
+      createsSecrets: ({ name }: { name: string }) => [name],
+    },
+  },
+  invite: {
+    mint: {
+      effect: "access",
+      // Each try seals a new request (good for `sealInvite`'s few minutes), and the instance's newest
+      // invite for an email replaces the last.
+      idempotent: true,
+      description:
+        "Ask an instance for an invite link that signs a declared person in: a request sealed under the instance's signing key, named by a secret marker, posted to its /auth/invite",
+      input: z.object({
+        host: z.url({ protocol: /^https?$/ }).describe("The instance's address, such as https://acme.sanoma.work"),
+        email: z.email().describe("The email the instance's people file declares"),
+        key: z
+          .strictObject({ $secret: SecretName })
+          .describe('The instance\'s SANOMA_SIGNING_KEY, as stored here: secret("NAME")'),
+      }),
+      output: z.object({ url: z.string().describe("The one-use invite link the instance minted") }),
+      target: ({ host }: { host: string }) => host,
+      // A link that signs someone in: the ledger records that there was one, not what it was.
+      opaque: ["url"],
+    },
+  },
+  token: {
+    mint: {
+      effect: "access",
+      description:
+        "Mint an api token acting for a subject in groups, store it under a name, and answer its id (never the token)",
+      input: z.object({
+        subject: z.string().regex(/^\S+$/, "a principal's id, such as visitor:better-auth:<id>"),
+        groups: z.array(z.string().min(1)),
+        store: SecretName.describe("The secret the token is stored under"),
+      }),
+      output: z.object({ id: z.string() }),
+      target: ({ subject }: { subject: string }) => subject,
+      createsSecrets: ({ store }: { store: string }) => [store],
+    },
+    revoke: {
+      effect: "access",
+      idempotent: true,
+      description: "Revoke an api token: it resolves to nobody from now on",
+      input: z.object({ id: z.string().min(1) }),
+      output: z.object({}),
+      target: ({ id }: { id: string }) => `token:${id}`,
+    },
+  },
+});
+
+/** A `DriverError` that a retry would not change. */
+const refuse = (message: string) => new DriverError(`sanoma: ${message}`, { retryable: false });
+
+/** The token id a call mints, from its idempotency key: the same on every try of one call, so a retry finds its own. */
+function tokenIdOf(call: CallContext) {
+  const hex = createHash("sha256").update(call.idempotencyKey).digest("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20, 32)}`;
+}
+
+/** The 32 bytes of a signing key stored as text (base64, or base64url as `generate` makes one), or a refusal. */
+function signingKeyOf(secret: string, text: string | undefined): Buffer {
+  if (text === undefined) throw refuse(`the secret ${secret} is not set: store the instance's signing key under it`);
+  const key = keyBytes(text);
+  if (!key) throw refuse(`${secret} is not a signing key: 32 bytes in base64`);
+  return key;
+}
+
+/**
+ * Posts the sealed `request` to the instance's `/auth/invite`, and answers the link it minted
+ * (`sanoma.invite.mint`, and going live's sign-in); a `DriverError` otherwise, retryable by status.
+ */
+export async function postInvite(host: string, request: string): Promise<{ url: string }> {
+  const at = new URL("/auth/invite", host);
+  let res: Response;
+  try {
+    res = await fetch(at, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ request }),
+      // A redirect is answered as it is (a 3xx, not retried): the sealed request goes to `host` alone.
+      redirect: "manual",
+      signal: AbortSignal.timeout(INVITE_TIMEOUT_MS),
+    });
+  } catch (err) {
+    throw new DriverError(`sanoma: ${at.host} could not be reached: ${errorMessage(err)}`, {
+      retryable: true,
+      cause: err,
+    });
+  }
+  const body = (await res.json().catch(() => undefined)) as { url?: unknown; error?: unknown } | undefined;
+  if (res.ok && typeof body?.url === "string") return { url: body.url };
+  const why = typeof body?.error === "string" ? `: ${body.error}` : res.ok ? ": no url" : "";
+  throw new DriverError(`sanoma: ${at.host} answered ${res.status} to POST /auth/invite${why}`, {
+    retryable: !res.ok && retryableStatus(res.status),
+    status: res.status,
+  });
+}
+
+/**
+ * The driver of the runtime's own operations, over the call's secrets and `tokens` (the config's
+ * database's, `tokenStore`); `invite` posts a sealed request to an instance (`postInvite` by default).
+ */
+export function runtimeDriver({
+  tokens,
+  identities,
+  invite = postInvite,
+}: {
+  tokens: Tokens;
+  identities?: IdentityProvisioning;
+  invite?: (host: string, request: string, call: CallContext) => Promise<{ url: string }>;
+}) {
+  return defineDriver(sanoma, {
+    identity: {
+      async enroll({ store, ...input }, call) {
+        if (!identities) throw refuse("identity provisioning is not configured");
+        // Store before enrolling: a lost DB response retries with the same credential, never a new bearer.
+        const credential = await call.secrets.ensure(store, generateSecret);
+        if (!/^[A-Za-z0-9_-]{43}$/.test(credential)) throw refuse("invalid identity bootstrap credential");
+        await identityWrite(() =>
+          identities.enroll({ ...input, hash: createHash("sha256").update(credential).digest("hex") }),
+        );
+        return { deployment: input.deployment, generation: input.generation, store };
+      },
+      async retire(input) {
+        if (!identities) throw refuse("identity provisioning is not configured");
+        await identityWrite(() => identities.retire(input));
+        return {};
+      },
+      async revoke(input) {
+        if (!identities) throw refuse("identity provisioning is not configured");
+        await identityWrite(() => identities.revoke(input));
+        return {};
+      },
+    },
+    secret: {
+      async generate({ name, kind }, call) {
+        if (kind === "random") {
+          await call.secrets.ensure(name, generateSecret);
+          return { name };
+        }
+        // A pair made only when none is stored: the public half is always derived from what is.
+        let stored = await call.secrets.get(name);
+        if (stored === undefined) {
+          const pair = await sourceKeyPair();
+          stored = await call.secrets.ensure(name, () => pair.privateKey);
+        }
+        const publicKey = sshPublicKey(stored);
+        if (!publicKey)
+          throw refuse(`${name} holds a value that is not an RSA private key: delete it, or name another`);
+        return { name, publicKey };
+      },
+      async delete({ name }, call) {
+        await call.secrets.delete(name);
+        return {};
+      },
+    },
+    invite: {
+      async mint({ host, email, key }, call) {
+        const signingKey = signingKeyOf(key.$secret, await call.secrets.get(key.$secret));
+        const request = sealInvite({ email }, signingKey);
+        return invite(host, request, call);
+      },
+    },
+    token: {
+      async mint({ subject, groups, store }, call) {
+        const id = tokenIdOf(call);
+        const held = await call.secrets.get(store);
+        if (held !== undefined) {
+          // This call's own, stored by a try whose answer was lost.
+          if ((await tokens.resolve(held))?.principal.id === `token:${id}`) return { id };
+          throw refuse(`${store} holds a value already: delete it, or store the token under another name`);
+        }
+        let token: string;
+        try {
+          ({ token } = await tokens.mint({ id, subject, groups }));
+        } catch (err) {
+          // A try that minted this id and stopped before storing it left a token nobody holds: revoked here.
+          if ((await tokens.subjectOf(id)) === undefined) throw err;
+          await tokens.revoke({ id });
+          throw refuse(`an earlier try minted token ${id} and stopped before storing it: it is revoked, start again`);
+        }
+        if ((await call.secrets.ensure(store, () => token)) !== token) {
+          await tokens.revoke({ id });
+          throw refuse(`${store} was stored by someone else meanwhile: the token minted is revoked`);
+        }
+        return { id };
+      },
+      async revoke({ id }) {
+        await tokens.revoke({ id });
+        return {};
+      },
+    },
+  });
+}
+
+/**
+ * The runtime's own operations for one sandbox run: the run's secrets (in memory), tokens in
+ * memory, and an invite that posts nothing, answering a link on the host named.
+ */
+export const sandboxRuntimeDriver = () =>
+  runtimeDriver({
+    tokens: memoryTokens(),
+    identities: memoryIdentityProvisioning(),
+    invite: async (host, _request, call) => ({ url: new URL(`/auth/invite/sandbox-${tokenIdOf(call)}`, host).href }),
+  });

package/src/scenario.ts

@@ -13,7 +13,7 @@ import {
 } from "@cucumber/messages";
 import type { z } from "zod";
 import type { RunSummary, SanomaClient } from "./client.ts";
-import type { Approver } from "./define.ts";
+import type { Approver, Principal } from "./define.ts";
 import type { ResolvedConfig } from "./config.ts";
 import {
   buildLibrary,
@@ -162,8 +162,11 @@ export interface Scenario {
   text: string;
   /** Every step in order, for a list and for marking graph nodes. */
   steps: ScenarioStep[];
-  /** Who starts the run, by id, when a `Given <who> is acting` says: a declared person or agent, `anonymous` or a visitor. */
-  startedBy?: string;
+  /**
+   * Who starts the run when a `Given … is acting` says: a declared person or agent or `anonymous`
+   * by id, or a visitor, by id or, with the email and GitHub login its login verified, as a principal.
+   */
+  startedBy?: Principal | string;
   given: Given[];
   input: unknown;
   decisions: Decision[];
@@ -208,11 +211,11 @@ interface Then {
 
 /**
  * What a step of each kind reads into; `any` is a decision, which a step of any keyword may make,
- * and `actor` a `Given` saying who starts the run (`{who} is acting`), by id.
+ * and `actor` a `Given` saying who starts the run (`{who} is acting`), by id or as a principal.
  */
 interface Items {
   given: Unstepped<Given>[];
-  actor: string;
+  actor: Principal | string;
   when: When;
   then: Then;
   any: Unstepped<Decision>;
@@ -398,6 +401,12 @@ function builtFor(scope: Scope): Built {
 /** A `Then` step of the generic steps: its expectation, checked against the run's records. */
 const expecting = (expect: CoreExpectation): Then => ({ expect, verify: (run) => detailOf(expect, run.records) });
 
+/** The scenario's visitor (`a visitor is acting`) with what its login verified, as `publicFront` passes it on. */
+const visitorWith = (verified: { email: unknown; github?: unknown }): Principal => ({
+  ...visitorPrincipal("scenario", "visitor"),
+  ...(verified as Pick<Principal, "email" | "github">),
+});
+
 /** The rules a scope has, and the parameter types their expressions use. */
 function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSpec[] } {
   const { types, collections } = scope;
@@ -455,6 +464,13 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
     { kind: "actor", source: "{who} is acting", read: ([who]) => actorNamed(who as string) },
     // A visitor of a public site, as a login would vouch for one; `anonymous` is a `{who}`.
     { kind: "actor", source: "a visitor is acting", read: () => visitorPrincipal("scenario", "visitor").id },
+    // A visitor with the email its login verified, and a GitHub login it linked.
+    { kind: "actor", source: "a visitor {string} is acting", read: ([email]) => visitorWith({ email }) },
+    {
+      kind: "actor",
+      source: "a visitor {string} with GitHub {string} is acting",
+      read: ([email, github]) => visitorWith({ email, github }),
+    },
     {
       kind: "given",
       source: "{op} was called with",
@@ -985,7 +1001,9 @@ function compileWorld(built: Built, specs: Map<string, Spec>) {
         switch (rule.kind) {
           case "actor":
             if (spec.startedBy !== undefined)
-              throw new Error(`${spec.startedBy} is acting already: a run has one actor`);
+              throw new Error(
+                `${typeof spec.startedBy === "string" ? spec.startedBy : spec.startedBy.id} is acting already: a run has one actor`,
+              );
             spec.startedBy = rule.read(args, pickle);
             break;
           case "given": {

package/src/seal.ts

@@ -0,0 +1,95 @@
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { deriveSigningKey, signingKeyFor } from "./deployment-key.ts";
+
+// Small values sealed under a key of their own, derived from the deployment's SANOMA_SIGNING_KEY
+// for one purpose (HKDF-SHA256): a sign-in code in a `login-code` run's input, and a request for
+// an invite that a holder of the key sends to the instance (`POST /auth/invite`). AES-256-GCM, the
+// purpose as its additional data, so a value sealed for one purpose never opens for another.
+
+const IV = 12;
+const TAG = 16;
+
+/** The key for `purpose`: derived from `signingKey`, a deployment's signing key, else from this process's own. */
+const keyFor = (purpose: string, signingKey?: Buffer) =>
+  signingKey ? deriveSigningKey(signingKey, purpose) : signingKeyFor(purpose);
+
+/**
+ * `value` as JSON, sealed for `purpose` under `signingKey` (this process's own by default): base64url
+ * of the IV, the tag and the ciphertext.
+ */
+function seal(purpose: string, value: unknown, signingKey?: Buffer): string {
+  const iv = randomBytes(IV);
+  const cipher = createCipheriv("aes-256-gcm", keyFor(purpose, signingKey), iv).setAAD(Buffer.from(purpose));
+  const text = Buffer.concat([cipher.update(JSON.stringify(value), "utf8"), cipher.final()]);
+  return Buffer.concat([iv, cipher.getAuthTag(), text]).toString("base64url");
+}
+
+/** What `seal(purpose, …)` sealed, or undefined for anything else: another key, another purpose, a change. */
+function unseal(purpose: string, sealed: string): unknown {
+  const bytes = Buffer.from(sealed, "base64url");
+  if (bytes.length <= IV + TAG) return undefined;
+  try {
+    const decipher = createDecipheriv("aes-256-gcm", keyFor(purpose), bytes.subarray(0, IV))
+      .setAAD(Buffer.from(purpose))
+      .setAuthTag(bytes.subarray(IV, IV + TAG));
+    const text = Buffer.concat([decipher.update(bytes.subarray(IV + TAG)), decipher.final()]);
+    return JSON.parse(text.toString("utf8"));
+  } catch {
+    return undefined;
+  }
+}
+
+const CODE = "login code";
+const INVITE = "invite request";
+
+/**
+ * A sign-in code sealed with the email it is for, for a `login-code` run's input, so the run's
+ * input never shows it and a copy of it opens for no one else.
+ */
+export const sealLoginCode = (to: string, code: string): string => seal(CODE, { to, code });
+
+/** The code `sealLoginCode` sealed for `to`; throws for anything else, a code sealed for another email among it. */
+export function openLoginCode(sealed: string, to: string): string {
+  const opened = unseal(CODE, sealed) as { to?: unknown; code?: unknown } | undefined;
+  if (typeof opened?.code !== "string" || opened.to !== to) {
+    throw new Error(`The sign-in code is not one this deployment sealed for ${to}`);
+  }
+  return opened.code;
+}
+
+/** A request for an invite (`POST /auth/invite { request }`): for whom, until when (ms since the epoch), and a nonce. */
+export interface InviteRequest {
+  email: string;
+  exp: number;
+  nonce: string;
+}
+
+/** How long a sealed invite request is good for when `exp` is not given: five minutes. */
+const INVITE_REQUEST_MS = 5 * 60_000;
+
+/**
+ * A request for `email`'s invite, sealed under a key derived from `SANOMA_SIGNING_KEY` (purpose
+ * `invite request`), or from `signingKey`, another deployment's signing key (its 32 bytes): what
+ * a holder of the deployment's signing key sends the instance as `POST /auth/invite { request }`
+ * (going live, and Sanoma Cloud's birth invite, `sanoma.invite.mint`). `exp` defaults to five
+ * minutes from now, `nonce` to 16 random bytes.
+ */
+export function sealInvite(
+  { email, exp, nonce }: { email: string; exp?: number; nonce?: string },
+  signingKey?: Buffer,
+): string {
+  const request = {
+    email,
+    exp: exp ?? Date.now() + INVITE_REQUEST_MS,
+    nonce: nonce ?? randomBytes(16).toString("base64url"),
+  } satisfies InviteRequest;
+  return seal(INVITE, request, signingKey);
+}
+
+/** The request `sealInvite` sealed, while `exp` is after `now`; undefined for anything else, or once it expired. */
+export function openInvite(sealed: string, now = Date.now()): InviteRequest | undefined {
+  const request = unseal(INVITE, sealed) as Partial<InviteRequest> | undefined;
+  if (typeof request?.email !== "string" || typeof request.exp !== "number" || typeof request.nonce !== "string")
+    return undefined;
+  return request.exp > now ? (request as InviteRequest) : undefined;
+}

package/src/secret-store.ts

@@ -1,4 +1,4 @@
-import { deploymentKey } from "./deployment-key.ts";
+import { DEPLOYMENT_KEYS, type DeploymentKeyName, deploymentKey } from "./deployment-key.ts";
 /** Opaque values belong only in trusted runtime code, never workflow history or descriptions. */
 export interface SecretValue {
   value: string;
@@ -65,7 +65,7 @@ export interface SecretStore {
 export type SecretBinding =
   | { path: string; management: "sanoma" | "external"; env?: never; bootstrap?: never }
   | { env: string; management?: "external"; path?: never; bootstrap?: never }
-  | { bootstrap: "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY"; management?: "external"; env?: never; path?: never };
+  | { bootstrap: DeploymentKeyName; management?: "external"; env?: never; path?: never };
 
 export interface SecretConfiguration {
   /** Omitted: built-in encrypted Postgres, supplied by the runtime. */
@@ -145,10 +145,10 @@ export function checkSecretConfiguration(config: SecretConfiguration): void {
     invalid();
   for (const [name, b] of Object.entries(config.bindings ?? {})) {
     if (!namePattern.test(name) || !b || typeof b !== "object") invalid();
-    if (["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
+    if (DEPLOYMENT_KEYS.includes(name) && !("env" in b) && !("bootstrap" in b)) invalid();
     if ("bootstrap" in b) {
       if (
-        !["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(b.bootstrap!) ||
+        !DEPLOYMENT_KEYS.includes(b.bootstrap!) ||
         b.path !== undefined ||
         b.env !== undefined ||
         (b.management !== undefined && b.management !== "external")
@@ -194,8 +194,7 @@ export class SecretAccess {
     const binding = Object.hasOwn(this.bindings, name) ? this.bindings[name] : undefined;
     if (binding?.bootstrap !== undefined)
       return { store: "bootstrap", namespace: "", path: binding.bootstrap, management: "external" };
-    if (["SANOMA_SIGNING_KEY", "SANOMA_SECRETS_KEY"].includes(name) && !binding)
-      throw new SecretStoreError("invalid_configuration");
+    if (DEPLOYMENT_KEYS.includes(name) && !binding) throw new SecretStoreError("invalid_configuration");
     if (binding?.env !== undefined)
       return { store: "environment", namespace: "", path: binding.env, management: "external" };
     return {
@@ -213,7 +212,7 @@ export class SecretAccess {
   async read(name: string): Promise<SecretValue | undefined> {
     const location = this.location(name);
     if (location.store === "bootstrap" && location.namespace === "") {
-      const value = deploymentKey(location.path as "SANOMA_SIGNING_KEY" | "SANOMA_SECRETS_KEY").toString("base64");
+      const value = deploymentKey(location.path as DeploymentKeyName).toString("base64");
       return { value, version: "bootstrap" };
     }
     if (location.store === "environment" && location.namespace === "") {
@@ -238,10 +237,14 @@ export class SecretAccess {
     return secretStoreCall(() => this.store.write(location, value, options));
   }
 
-  async delete(name: string, options: { expectedVersion: string; by: string }): Promise<void> {
+  /** Deletes the value at `expectedVersion`; without one, the value stored now, and none stored is nothing to do. */
+  async delete(name: string, options: { expectedVersion?: string; by?: string } = {}): Promise<void> {
     const location = this.writable(name);
     if (this.store.capabilities.deletion === "unsupported") throw new SecretStoreError("unsupported");
-    await secretStoreCall(() => this.store.delete(location, options));
+    const expectedVersion = options.expectedVersion ?? (await this.read(name))?.version;
+    if (expectedVersion === undefined) return;
+    const by = options.by ?? "sanoma";
+    await secretStoreCall(() => this.store.delete(location, { expectedVersion, by }));
   }
 
   async ensure(name: string, make: () => string): Promise<string> {

package/src/secret.ts

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { DriverError } from "./op.ts";
 
 // Secrets are named, never written: `secret("NAME")` in a data file is a marker for a value in
@@ -44,6 +44,8 @@ export interface Secrets {
   get(name: string): Promise<string | undefined>;
   /** The stored value; when there is none, `make()`'s, stored first. */
   ensure(name: string, make: () => string): Promise<string>;
+  /** Deletes the stored value; none stored is nothing to do. The runtime's own `sanoma.secret.delete` calls it. */
+  delete(name: string): Promise<void>;
 }
 
 /** A named call can resolve only the auxiliary secret markers present in its authorized input. */
@@ -72,12 +74,22 @@ export function secretsForInput(input: unknown, secrets: Secrets, creates: reado
       check(name, true);
       return secrets.ensure(name, make);
     },
+    async delete(name) {
+      check(name, true);
+      return secrets.delete(name);
+    },
   };
 }
 
 /** A value for a secret with `generate`: 32 random bytes, base64url. */
 export const generateSecret = (): string => randomBytes(32).toString("base64url");
 
+/**
+ * A bearer token's sha256, hex: all a table keeps of one (the wakeup service's, the api tokens). A
+ * token is found by its hash (a unique index), so the secret itself is never compared.
+ */
+export const tokenHash = (token: string): string => createHash("sha256").update(token).digest("hex");
+
 /** `T` with each secret marker's place holding its value: what `resolveSecrets` returns. */
 export type Resolved<T> = T extends Secret
   ? string
@@ -117,5 +129,8 @@ export function memorySecrets(initial: Record<string, string> = {}): Secrets {
       if (!values.has(name)) values.set(name, make());
       return values.get(name)!;
     },
+    async delete(name) {
+      values.delete(name);
+    },
   };
 }

package/src/shared.ts

@@ -285,12 +285,20 @@ export const CHANGE_TOPIC = "change:event";
 /** Lists the apps on GitHub with Sanoma's claims: the one runtime operation a page may call (`isDirect`). */
 export const APPS_LIST = "sanoma.apps.list";
 
-/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call and change. */
+/**
+ * The built-in workflow that sends a staff or visitor sign-in code through the config's
+ * `login.sender`, started by the runtime's agent `login` (`LOGIN_AGENT`): its input's code is
+ * sealed, and the mail's body is recorded as `<text>` and `<html>`.
+ */
+export const LOGIN_CODE_WORKFLOW = "login-code";
+
+/** The workflows the runtime adds itself, which a config's own may not be named: drift, apply, call, change and login-code. */
 export const BUILT_IN_WORKFLOWS: ReadonlySet<string> = new Set([
   DRIFT_WORKFLOW,
   APPLY_WORKFLOW,
   CALL_WORKFLOW,
   CHANGE_WORKFLOW,
+  LOGIN_CODE_WORKFLOW,
 ]);
 
 /**
@@ -361,14 +369,22 @@ export const VISITORS = "visitors";
 /** The principal a public page runs as when nobody is signed in: no groups. */
 export const ANONYMOUS = "anonymous";
 
-/** `visitor:<login connector's vendor>:<provider subject>`: the only form a visitor's id takes. */
+/** `visitor:<login connector's vendor>:<provider subject>`: the form a signed-in visitor's id takes. */
 const VISITOR_ID = /^visitor:[^\s:]+:\S+$/;
 
+/** `token:<id>`: a caller of a public site's api with a token (`SanomaClient.tokens`), a visitor too. */
+const TOKEN_ID = /^token:\S+$/;
+
 /**
- * True for `anonymous` and for a visitor's id: a principal no data file declares and the staff
- * logins never admit. Marked by the id alone, since a principal crosses to the worker as JSON.
+ * True for `anonymous`, a visitor's id and a token's (`token:<id>`): a principal no data file
+ * declares and the staff logins never admit. Marked by the id alone, since a principal crosses to
+ * the worker as JSON.
  */
-export const isVisitor = (p: Pick<Principal, "id">): boolean => p.id === ANONYMOUS || VISITOR_ID.test(p.id);
+export const isVisitor = (p: Pick<Principal, "id">): boolean =>
+  p.id === ANONYMOUS || VISITOR_ID.test(p.id) || isToken(p);
+
+/** True for an api token's principal (`token:<id>`), whose groups are its row's. */
+export const isToken = (p: Pick<Principal, "id">): boolean => TOKEN_ID.test(p.id);
 
 /**
  * The visitor a public site's login vouches for: `subject` from the provider behind the `login`
@@ -389,8 +405,16 @@ export const WAKEUP_AGENT = "wakeup";
 export const SCHEDULE_AGENT = "schedule";
 /** The runtime's agent that checks and deploys the hosts: drift's, and apply's after a push to `main` (`SanomaClient.remoteEvent`). */
 export const HOST_CHECK_AGENT = "host-check";
-/** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration), declared whether a data file names them or not. */
-export const RUNTIME_AGENTS: readonly string[] = ["scenarios", HOST_CHECK_AGENT, SCHEDULE_AGENT, WAKEUP_AGENT];
+/** The runtime's agent that sends a sign-in code (`LOGIN_CODE_WORKFLOW`): a company's policy exempts it from its holds on sending. */
+export const LOGIN_AGENT = "login";
+/** The runtime's own agents (scenarios, the host check, scheduled runs, the wakeup's registration, sign-in codes), declared whether a data file names them or not. */
+export const RUNTIME_AGENTS: readonly string[] = [
+  "scenarios",
+  HOST_CHECK_AGENT,
+  SCHEDULE_AGENT,
+  WAKEUP_AGENT,
+  LOGIN_AGENT,
+];
 
 /** The declared resources of one of the runtime's people types, by `desired`. */
 const peopleOfType = <T>(resources: readonly PeopleResource[], type: "person" | "agent" | "group") =>