@sanoma-ai/workflows 0.10.1 → 0.10.3

package/src/kms-secrets.ts

@@ -0,0 +1,271 @@
+import { createCipheriv, createDecipheriv, randomBytes, randomUUID } from "node:crypto";
+import type { protos } from "@google-cloud/kms";
+import crc32c from "crc-32/crc32c.js";
+import type { Db } from "./db.ts";
+import { SecretStoreError, type SecretAddress, type SecretStore, type SecretValue } from "./secret-store.ts";
+
+/** Install with a privileged connection; runtime needs only SELECT/INSERT/UPDATE/DELETE on its company database. */
+export const KMS_SECRETS_SQL = `
+CREATE SCHEMA IF NOT EXISTS sanoma_kms;
+REVOKE ALL ON SCHEMA sanoma_kms FROM PUBLIC;
+CREATE TABLE IF NOT EXISTS sanoma_kms.secrets (
+  company text NOT NULL, namespace text NOT NULL, path text NOT NULL,
+  version uuid NOT NULL, envelope jsonb NOT NULL,
+  updated_by text NOT NULL, updated_at timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY (company, namespace, path)
+);
+REVOKE ALL ON sanoma_kms.secrets FROM PUBLIC;
+DO $revoke$
+DECLARE api_role text;
+BEGIN
+  FOREACH api_role IN ARRAY ARRAY['anon', 'authenticated', 'service_role'] LOOP
+    IF EXISTS (SELECT 1 FROM pg_catalog.pg_roles WHERE rolname = api_role) THEN
+      EXECUTE format('REVOKE ALL ON SCHEMA sanoma_kms FROM %I', api_role);
+      EXECUTE format('REVOKE ALL ON sanoma_kms.secrets FROM %I', api_role);
+    END IF;
+  END LOOP;
+END;
+$revoke$;
+`;
+
+/** Promise interface implemented by Google's KeyManagementServiceClient. */
+export interface GcpKmsClient {
+  encrypt(
+    request: protos.google.cloud.kms.v1.IEncryptRequest,
+  ): Promise<[protos.google.cloud.kms.v1.IEncryptResponse, ...unknown[]]>;
+  decrypt(
+    request: protos.google.cloud.kms.v1.IDecryptRequest,
+  ): Promise<[protos.google.cloud.kms.v1.IDecryptResponse, ...unknown[]]>;
+}
+
+export interface KmsPostgresOptions {
+  /** Fixed by trusted deployment bootstrap. IAM must independently restrict the runtime to this company’s CryptoKeys. */
+  company: string;
+  /** Full GCP CryptoKey resource name for new writes, using its primary version. */
+  keyName: string;
+  /** Retained CryptoKey names allowed for reads during key replacement/backup recovery. */
+  decryptKeyNames?: readonly string[];
+  /** Explicit client under a company-scoped IAM identity, never fleet credentials. Caller owns its lifecycle. */
+  kms: GcpKmsClient;
+  /** Company-scoped database access. Caller owns connection lifecycle; never shared admin authority. */
+  database: () => Promise<Db>;
+}
+
+interface Envelope {
+  format: "sanoma-gcp-kms-v1";
+  key: string;
+  keyVersion: string;
+  wrapped: string;
+  nonce: string;
+  ciphertext: string;
+  tag: string;
+}
+interface Row {
+  version: string;
+  envelope: Envelope;
+  updated_by: string;
+  updated_at: Date;
+}
+const FORMAT = "sanoma-gcp-kms-v1";
+const MAX_BYTES = 65_536;
+const keyName =
+  /^projects\/[a-zA-Z0-9-]+\/locations\/[a-z0-9-]+\/keyRings\/[a-zA-Z0-9_-]+\/cryptoKeys\/[a-zA-Z0-9_-]+$/;
+const nonempty = (v: string) =>
+  typeof v === "string" && v.length > 0 && Buffer.byteLength(v, "utf8") <= 1024 && !v.includes("\0");
+const failed = (error: unknown): never => {
+  if (error instanceof SecretStoreError) throw error;
+  const code = (error as { code?: string | number } | null)?.code;
+  throw new SecretStoreError(
+    code === 7 || code === 16 || code === "42501"
+      ? "denied"
+      : code === 3
+        ? "invalid_value"
+        : code === 5 || code === 9 || code === "42P01"
+          ? "invalid_configuration"
+          : "unavailable",
+  );
+};
+const safe = async <T>(run: () => Promise<T>): Promise<T> => {
+  try {
+    return await run();
+  } catch (e) {
+    return failed(e);
+  }
+};
+const bytes = (v: string, length?: number, max = MAX_BYTES): Buffer => {
+  if (
+    typeof v !== "string" ||
+    v.length > Math.ceil((length ?? max) / 3) * 4 ||
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(v)
+  )
+    throw new SecretStoreError("invalid_value");
+  const b = Buffer.from(v, "base64");
+  if (length !== undefined && b.length !== length) throw new SecretStoreError("invalid_value");
+  return b;
+};
+
+const versionOf = (name: unknown, key: string): name is string =>
+  typeof name === "string" &&
+  name.startsWith(`${key}/cryptoKeyVersions/`) &&
+  /^[1-9][0-9]{0,19}$/.test(name.slice(`${key}/cryptoKeyVersions/`.length));
+const checksum = (value: Uint8Array) => crc32c.buf(value) >>> 0;
+
+/** Versioned envelope encryption; no plaintext/data-key cache, no SANOMA_SECRETS_KEY and no Secrets Manager. */
+export function kmsPostgresStore(options: KmsPostgresOptions): SecretStore {
+  const { company, keyName: writeKey, kms, database } = options;
+  const keys = new Set([writeKey, ...(options.decryptKeyNames ?? [])]);
+  if (!nonempty(company) || [...keys].some((k) => !nonempty(k) || !keyName.test(k)))
+    throw new SecretStoreError("invalid_configuration");
+  const context = (address: SecretAddress, version: string) => {
+    if (!nonempty(address.namespace) || !nonempty(address.path)) throw new SecretStoreError("invalid_configuration");
+    return { company, namespace: address.namespace, path: address.path, version, format: FORMAT };
+  };
+  const seal = async (address: SecretAddress, value: string, version: string): Promise<Envelope> => {
+    const bound = context(address, version);
+    const aad = Buffer.from(JSON.stringify(bound));
+    const dataKey = randomBytes(32);
+    try {
+      const [encrypted] = await kms.encrypt({
+        name: writeKey,
+        plaintext: dataKey,
+        plaintextCrc32c: { value: checksum(dataKey) },
+        additionalAuthenticatedData: aad,
+        additionalAuthenticatedDataCrc32c: { value: checksum(aad) },
+      });
+      const wrapped =
+        typeof encrypted.ciphertext === "string" ? bytes(encrypted.ciphertext, undefined, 6144) : encrypted.ciphertext;
+      if (
+        !versionOf(encrypted.name, writeKey) ||
+        !wrapped?.length ||
+        wrapped.length > 6144 ||
+        !encrypted.verifiedPlaintextCrc32c ||
+        !encrypted.verifiedAdditionalAuthenticatedDataCrc32c ||
+        Number(encrypted.ciphertextCrc32c?.value ?? NaN) !== checksum(wrapped)
+      )
+        throw new SecretStoreError("invalid_value");
+      const nonce = randomBytes(12);
+      const cipher = createCipheriv("aes-256-gcm", dataKey, nonce).setAAD(
+        Buffer.from(JSON.stringify({ ...bound, keyVersion: encrypted.name })),
+      );
+      const ciphertext = Buffer.concat([cipher.update(value, "utf8"), cipher.final()]);
+      return {
+        format: FORMAT,
+        key: writeKey,
+        keyVersion: encrypted.name,
+        wrapped: Buffer.from(wrapped).toString("base64"),
+        nonce: nonce.toString("base64"),
+        ciphertext: ciphertext.toString("base64"),
+        tag: cipher.getAuthTag().toString("base64"),
+      };
+    } finally {
+      dataKey.fill(0);
+    }
+  };
+  const open = async (address: SecretAddress, row: Row): Promise<SecretValue> => {
+    const e = row.envelope;
+    if (!e || e.format !== FORMAT || !keys.has(e.key) || !versionOf(e.keyVersion, e.key))
+      throw new SecretStoreError("invalid_value");
+    const nonce = bytes(e.nonce, 12),
+      tag = bytes(e.tag, 16),
+      ciphertext = bytes(e.ciphertext),
+      wrapped = bytes(e.wrapped, undefined, 6144);
+    if (ciphertext.length > MAX_BYTES || !wrapped.length || wrapped.length > 6144)
+      throw new SecretStoreError("invalid_value");
+    const bound = context(address, row.version);
+    const aad = Buffer.from(JSON.stringify(bound));
+    const [decrypted] = await kms.decrypt({
+      name: e.key,
+      ciphertext: wrapped,
+      ciphertextCrc32c: { value: checksum(wrapped) },
+      additionalAuthenticatedData: aad,
+      additionalAuthenticatedDataCrc32c: { value: checksum(aad) },
+    });
+    const dataKey = typeof decrypted.plaintext === "string" ? bytes(decrypted.plaintext, 32) : decrypted.plaintext;
+    try {
+      if (dataKey?.length !== 32 || Number(decrypted.plaintextCrc32c?.value ?? NaN) !== checksum(dataKey))
+        throw new SecretStoreError("invalid_value");
+      const decipher = createDecipheriv("aes-256-gcm", dataKey, nonce)
+        .setAAD(Buffer.from(JSON.stringify({ ...bound, keyVersion: e.keyVersion })))
+        .setAuthTag(tag);
+      let plaintext: Buffer;
+      try {
+        plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+      } catch {
+        throw new SecretStoreError("invalid_value");
+      }
+      try {
+        return {
+          value: plaintext.toString("utf8"),
+          version: row.version,
+          updatedBy: row.updated_by,
+          updatedAt: row.updated_at.toISOString(),
+        };
+      } finally {
+        plaintext.fill(0);
+      }
+    } finally {
+      dataKey?.fill(0);
+    }
+  };
+  return {
+    id: "kms-postgres",
+    capabilities: Object.freeze({
+      writable: true,
+      maxBytes: MAX_BYTES,
+      conditionalWrites: "atomic",
+      deletion: "destroy",
+      changeDetection: "read",
+    }),
+    validate: (namespace) =>
+      safe(async () => {
+        const address = { namespace, path: "__validation__" },
+          version = randomUUID();
+        const envelope = await seal(address, "validation", version);
+        await open(address, { envelope, version, updated_by: "validation", updated_at: new Date() });
+        await (await database()).query("SELECT version FROM sanoma_kms.secrets WHERE company=$1 LIMIT 0", [company]);
+        // Own-key usability only. Cross-company authorization requires live IAM proof with another existing key.
+      }),
+    read: (address) =>
+      safe(async () => {
+        context(address, "read");
+        const { rows } = await (
+          await database()
+        ).query<Row>(
+          "SELECT version,envelope,updated_by,updated_at FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3",
+          [company, address.namespace, address.path],
+        );
+        return rows[0] && open(address, rows[0]);
+      }),
+    write: (address, value, { expectedVersion, by }) =>
+      safe(async () => {
+        if (Buffer.byteLength(value, "utf8") > MAX_BYTES) throw new SecretStoreError("too_large");
+        if (!nonempty(by)) throw new SecretStoreError("invalid_value");
+        const version = randomUUID(),
+          envelope = await seal(address, value, version);
+        const args = [company, address.namespace, address.path, version, JSON.stringify(envelope), by];
+        const sql =
+          expectedVersion === null
+            ? "INSERT INTO sanoma_kms.secrets(company,namespace,path,version,envelope,updated_by) VALUES($1,$2,$3,$4,$5,$6) ON CONFLICT(company,namespace,path) DO NOTHING RETURNING version,envelope,updated_by,updated_at"
+            : "UPDATE sanoma_kms.secrets SET version=$4,envelope=$5,updated_by=$6,updated_at=now() WHERE company=$1 AND namespace=$2 AND path=$3 AND version::text=$7 RETURNING version,envelope,updated_by,updated_at";
+        const { rows } = await (
+          await database()
+        ).query<Row>(sql, expectedVersion === null ? args : [...args, expectedVersion]);
+        if (!rows[0]) throw new SecretStoreError("conflict");
+        // Return the caller's value, never make a second decrypt after a successful commit.
+        return { value, version, updatedBy: by, updatedAt: rows[0].updated_at.toISOString() };
+      }),
+    delete: (address, { expectedVersion }) =>
+      safe(async () => {
+        context(address, expectedVersion);
+        const { rowCount } = await (
+          await database()
+        ).query("DELETE FROM sanoma_kms.secrets WHERE company=$1 AND namespace=$2 AND path=$3 AND version::text=$4", [
+          company,
+          address.namespace,
+          address.path,
+          expectedVersion,
+        ]);
+        if (!rowCount) throw new SecretStoreError("conflict");
+      }),
+  };
+}

package/src/ledger.ts

@@ -1,5 +1,6 @@
 import type { ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, readFile, truncate } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -8,7 +9,7 @@ import { type Db, LEDGER_TABLE as TABLE, lazyPool, pgCode } from "./db.ts";
 import type { Approver, Principal } from "./define.ts";
 import { type ErrorInfo, isFinal, keepCode } from "./errors.ts";
 import { shown, warn } from "./log.ts";
-import type { Effect } from "./op.ts";
+import type { Effect, SignInMethod } from "./op.ts";
 import type { RecordedDecision } from "./policy.ts";
 import type { Run } from "./run.ts";
 import { errorMessage } from "./shared.ts";
@@ -137,8 +138,58 @@ export type LedgerRecord = {
   | { type: "run.finished"; output: unknown }
   /** `error` as for `op.called`. */
   | { type: "run.failed"; error: ErrorInfo }
+  /**
+   * A declared person signed in to the staff login, by `method`; written outside any run, in the
+   * person's own `signin:<person>` (`signInRecord`), its `at` when.
+   */
+  | { type: "signin.recorded"; person: string; method: SignInMethod }
+  /** `by` minted an invite for the declared `person`, good until `expiresAt` (ISO 8601); in `invite:<person>`, outside any run. */
+  | { type: "invite.minted"; person: string; by: string; expiresAt: string }
 );
 
+/** What a sign-in's or an invite's record names as its workflow: the staff login, which is no run. */
+const LOGIN = "login";
+
+/**
+ * The record of a sign-in or an invite, written outside any run (`SanomaClient.recordSignIn`,
+ * `recordInvite`): in the run `signin:<person>` or `invite:<person>`, each with an id of its own,
+ * `seq` 0, so a person's records read in the order they were written.
+ */
+export function loginRecord(
+  app: string,
+  actor: Principal,
+  body: Extract<LedgerBody, { type: "signin.recorded" | "invite.minted" }>,
+  at = Date.now(),
+): LedgerRecord {
+  const runId = `${body.type === "signin.recorded" ? "signin" : "invite"}:${body.person}`;
+  return {
+    v: 1,
+    app,
+    id: `${runId}:${body.type}:${at}:${randomUUID()}`,
+    runId,
+    seq: 0,
+    at,
+    actor,
+    workflow: LOGIN,
+    ...body,
+  } as LedgerRecord;
+}
+
+/** When each of `people` last signed in, and how, by id: from their `signin:<person>` records; one who never did is left out. */
+export async function lastSignIns(
+  store: LedgerStore,
+  people: readonly string[],
+): Promise<Record<string, { at: number; method: SignInMethod }>> {
+  const last = await Promise.all(
+    people.map(async (person) => {
+      const records = await store.read(`signin:${person}`);
+      const latest = records.reduce<LedgerRecord | undefined>((a, r) => (a && a.at > r.at ? a : r), undefined);
+      return latest?.type === "signin.recorded" ? [[person, { at: latest.at, method: latest.method }] as const] : [];
+    }),
+  );
+  return Object.fromEntries(last.flat());
+}
+
 /**
  * The `ctx.all` member a record was written in. `id` is `all:<seq>`, the run's next `seq` when
  * the `ctx.all` began, so a replay names it the same; `index` is the member's position, `size`

package/src/login-code.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { defineWorkflow, type WorkflowDefinition } from "./define.ts";
+import type { Op } from "./op.ts";
+import { openLoginCode } from "./seal.ts";
+import type { LOGIN_CODE_WORKFLOW } from "./shared.ts";
+
+// The built-in `login-code` workflow: one mail with a sign-in code, through the config's
+// `login.sender`. The app starts it as the runtime's agent `login` (`LOGIN_AGENT`) with the code
+// sealed (`sealLoginCode`), so neither the run's input nor the ledger shows it: the call is
+// recorded with its body as `<text>` (`recorded` in `call.ts`). It is a workflow like any other:
+// the call goes through `ctx`, under the policy, in the ledger.
+
+/** An operation on `ctx`. */
+type OpCall = (input: unknown) => Promise<unknown>;
+
+/** The workflow's input: to whom, and the code, sealed. */
+const LoginCodeInput = z.object({ to: z.string().min(1), code: z.string().min(1) });
+
+/** What a sign-in code is sent as, for checks before any is: a sender must take it, and the policy is asked about it. */
+export const CODE_MAIL = { to: "person@example.com", subject: "Your sign-in code", text: "<text>" };
+
+/** The mail's text: the code, what it is for, and how long it lasts; nothing else, and no link. */
+const textOf = (company: string, code: string) =>
+  `Your sign-in code for ${company} is ${code}.\n\n` +
+  "It works once, for five minutes. If you did not ask for it, ignore this mail.\n";
+
+/** The login-code workflow for a config: it sends through `sender`, saying it is `company`'s. */
+export function loginCodeWorkflow(
+  sender: Op,
+  company: string,
+): WorkflowDefinition<readonly Op[], typeof LoginCodeInput> {
+  return defineWorkflow({
+    // The literal, held to the one name: the outline finds a workflow by a string, or a const of its own file.
+    name: "login-code" satisfies typeof LOGIN_CODE_WORKFLOW,
+    title: "Send a sign-in code",
+    trigger: "manual",
+    input: LoginCodeInput,
+    uses: [sender],
+    run: async (ctx, input) => {
+      const { vendor, resource, name } = sender;
+      const mail = {
+        to: input.to,
+        subject: `Your ${company} sign-in code`,
+        text: textOf(company, openLoginCode(input.code, input.to)),
+      };
+      // `ctx` called directly, so the outline places the call.
+      return (ctx as unknown as Record<string, Record<string, Record<string, OpCall>>>)[vendor]![resource]![name]!(
+        mail,
+      );
+    },
+  });
+}

package/src/op.ts

@@ -360,12 +360,31 @@ export interface ConnectorSetup {
 /** What the app gives a connector's model half (`ConnectorSetup.model`): the secrets, as a login half reads them. */
 export type ModelContext = Pick<LoginContext, "secrets">;
 
-/** What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it for a public site. */
+/**
+ * What a login vouches for about who is asking: a name they gave (`id`, the loopback's), a
+ * verified email, a GitHub login. The app admits the declared person they match (`personOf`).
+ */
+export interface LoginIdentity {
+  id?: string;
+  email?: string;
+  github?: string;
+}
+
+/** How a login half lets a person in: an email code, GitHub, an invite link, an email and a password. */
+export type LoginMethod = "code" | "github" | "invite" | "password";
+
+/** How a person signed in to the staff login, which the ledger records (`signin.recorded`): all but a password. */
+export type SignInMethod = Exclude<LoginMethod, "password">;
+
+/**
+ * What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it: for a
+ * public site, once per site; for the staff login, once, with `staff`.
+ */
 export interface LoginContext {
   /** The company's database (`resolved.databaseUrl`), where a login like Better Auth keeps its users. */
   databaseUrl: string;
   /**
-   * A 32-byte key derived from the deployment's `SANOMA_SECRETS_KEY` for this login (HKDF-SHA256,
+   * A 32-byte key derived from the deployment's `SANOMA_SIGNING_KEY` for this login (HKDF-SHA256,
    * purpose `login <connector>`), hex; a login signs its cookies with it and never asks a person for a secret.
    */
   key: string;
@@ -377,9 +396,24 @@ export interface LoginContext {
   /**
    * The origins the site answers on, scheme included and `:*` for any port:
    * `["http://www.localhost:*", "https://sanoma.example"]`; a login needs the protocol for its
-   * cookies and allowed hosts.
+   * cookies and allowed hosts. Empty for the staff login, which answers on any host the app does.
    */
   origins: readonly string[];
+  /**
+   * Sends a sign-in code to an email, through the config's `login.sender` (a run of the built-in
+   * `login-code` workflow, as the runtime's agent `login`); absent when the config names no
+   * sender, and then the login offers no code.
+   */
+  sendCode?(email: string, code: string): Promise<void>;
+  /** For the staff login only: who it may let in, the company's social clients, and where it tells of a sign-in. */
+  staff?: {
+    /** Whether the people files declare the person `identity` names; a login never makes a user for anyone else. */
+    admits(identity: LoginIdentity): boolean;
+    /** The company's own OAuth clients, each a method when given. */
+    social: { github?: { clientId: string; clientSecret: string } };
+    /** Tells the app of a sign-in by `method` of the person `identity` names, which the ledger records. Must not throw. */
+    record(method: SignInMethod, identity: LoginIdentity): Promise<void>;
+  };
 }
 
 /**
@@ -390,23 +424,62 @@ export interface LoginContext {
 export const CLIENT_IP_HEADER = "x-sanoma-client-ip";
 
 /**
- * A connector's login half: how a public site tells who a visitor is. The app makes one with
- * `login(context)` once per public site, when it starts; a login that keeps tables in the
- * database migrates them itself there, serialized and idempotent. It answers the provider's
- * subject only; the app makes the principal from it (`visitor:<connector>:<subject>`, in
- * `visitors`), so a connector never sets a visitor's groups. A visitor's address, for rate
- * limits, is the `CLIENT_IP_HEADER` header.
+ * A request's origin, https when a proxy that ends TLS says so (`x-forwarded-proto: https`), as
+ * Start's `getRequestUrl({ xForwardedProto: true })` reads it: the absolute URLs a page or an invite writes, and a login's cookies, take it.
+ */
+export function requestOrigin(request: Request): string {
+  const url = new URL(request.url);
+  if (request.headers.get("x-forwarded-proto") === "https") url.protocol = "https:";
+  return url.origin;
+}
+
+/** Whether a change comes from the page's own origin (a login's CSRF check): the browser says so, or its `Origin` names the request's host. */
+export function sameOrigin(request: Request): boolean {
+  const site = request.headers.get("sec-fetch-site");
+  if (site !== null) return site === "same-origin";
+  const origin = URL.parse(request.headers.get("origin") ?? "");
+  return origin !== null && origin.host === request.headers.get("host");
+}
+
+/**
+ * A connector's login half: how a public site tells who a visitor is, and, made with
+ * `LoginContext.staff`, how the app's staff sign in. The app makes one with `login(context)` once
+ * per public site (and once for staff), when it starts; a login that keeps tables in the database
+ * migrates them itself there, serialized and idempotent. It answers the provider's subject and
+ * what it verified; the app makes the principal from it (`visitor:<connector>:<subject>`, in
+ * `visitors`, or the declared person the identity matches), so a connector never sets groups. A
+ * visitor's address, for rate limits, is the `CLIENT_IP_HEADER` header.
  */
 export interface LoginHalf {
-  /** Who signed in, as the provider's stable subject, or null; never throws for a missing or bad cookie. */
-  verify(request: Request): Promise<{ subject: string } | null>;
+  /**
+   * Who signed in, as the provider's stable subject, with their email when the provider verified
+   * it and their GitHub login when they signed in with GitHub; null for a missing or bad cookie,
+   * for which it never throws.
+   */
+  verify(request: Request): Promise<{ subject: string; email?: string; github?: string } | null>;
   /** Answers its own routes, `/auth/<vendor>/*`; undefined for any other request. */
   handle(request: Request): Promise<Response | undefined>;
   /** The path a page POSTs to sign out, which `handle` serves; the app's own Sign out POSTs it with no body. */
   signOut?: string;
+  /** How a person may sign in now: what the sign-in page offers. */
+  methods?: readonly LoginMethod[];
+  /**
+   * A staff login's invite for `email`, a declared person's: a one-use token, good for
+   * `INVITE_SECONDS`, which replaces the last one minted for that email. `request` is the
+   * request that asked for it, on the host the invite is for.
+   */
+  invite?(email: string, request: Request): Promise<string>;
+  /**
+   * The invite a token is, while it is good: for whom, and the path (on the login's routes) that
+   * signs them in with it, using it up.
+   */
+  invitation?(token: string): Promise<{ email: string; path: string } | undefined>;
   close?(): Promise<void>;
 }
 
+/** How long an invite lasts: 24 hours. */
+export const INVITE_SECONDS = 24 * 60 * 60;
+
 /**
  * The connector with `setup` laid over what it already carries, as a connector package exports
  * it: `export const ghost = withSetup(ghostOps, { driver: ghostDriver, fake: fakeGhost, steps: ghostSteps })`. A

package/src/outline.ts

@@ -193,7 +193,7 @@ const PARAM =
   "run must take ctx as its first parameter, by one name: destructured, its calls cannot be read into the graph";
 const CTX_USE =
   "ctx is only called, directly (`await ctx.<vendor>.<resource>.<op>(…)`, `ctx.approval(…)`, `ctx.sleep(…)`, " +
-  "`ctx.all([…])`) or read for ctx.runId: passed on, aliased or destructured, its calls are not in the graph";
+  "`ctx.all([…])`) or read for ctx.runId or ctx.startedBy: passed on, aliased or destructured, its calls are not in the graph";
 const CTX_CALL = (what: string) =>
   `ctx.${what} is not a call the graph can draw: an operation is ctx.<vendor>.<resource>.<op>(…), ` +
   "and the built-ins are ctx.approval(…), ctx.sleep(…), ctx.all([…]) and ctx.now()";
@@ -237,7 +237,7 @@ interface Where {
 }
 
 /** The members of `ctx` that are read, not placed: no record, no node. */
-const READS = new Set(["now", "runId"]);
+const READS = new Set(["now", "runId", "startedBy"]);
 
 /**
  * The nodes of `fn`'s body (`run`'s, or a callback's the outline reads), each with an empty `path`
@@ -282,7 +282,7 @@ export function outlineBody(
     return uses;
   };
 
-  /** `ctx.runId`, read. */
+  /** `ctx.runId` or `ctx.startedBy`, read. */
   const isRead = (member: Node) =>
     !member.computed &&
     unwrap(member.object)?.type === "Identifier" &&

package/src/resource.ts

@@ -238,7 +238,7 @@ const record = z.record(z.string(), z.unknown());
 export const PLAN_ACTIONS = ["none", "create", "update", "replace", "delete"] as const;
 export type PlanAction = (typeof PLAN_ACTIONS)[number];
 
-/** The operations of a writable type that change its objects: only the apply workflow calls them (`isChangeOp`). */
+/** The operations of a writable type that change its objects (`isChangeOp`): apply's for a declared object, any workflow's for another. */
 export const CHANGE_OPS = ["create", "update", "delete"] as const;
 
 const opsOf = <S extends z.ZodObject>(schema: S) => {
@@ -293,7 +293,8 @@ export type ResourceOps<S extends z.ZodObject, W extends boolean = false> = Spec
 
 /**
  * True for an operation that changes a writable type's objects (`CHANGE_OPS`), which only the
- * apply workflow may call: by its vendor, resource and name, so a copy of a connector is told too.
+ * apply workflow may call on a declared object (a workflow's call is refused one, `refuseDeclared`
+ * in `call.ts`): by its vendor, resource and name, so a copy of a connector is told too.
  */
 export function isChangeOp(
   op: { readonly vendor: string; readonly resource: string; readonly name: string },
@@ -565,8 +566,9 @@ function pathsIn(value: unknown, paths: ReadonlySet<string>, prefix = ""): strin
  *   returns the same: `{ gone: true }` when the object no longer exists, else its fresh
  *   `state`. A driver may import first when it is given no state.
  *
- * A `writable` type has the change operations too, which only the apply workflow may call
- * (`isChangeOp`): `create`, `update` and `delete` effect `write` (`delete` idempotent), and `plan`:
+ * A `writable` type has the change operations too, which only the apply workflow may call on a
+ * declared object, and any workflow on another (`isChangeOp`): `create`, `update` and `delete`
+ * effect `write` (`delete` idempotent), and `plan`:
  *
  * - `plan` (`read`, idempotent) takes `{ id?, state?, handle?, desired? }`, no `desired` for a
  *   delete and no `id` for a create, and returns `{ action, planned?, unknown, replace }`:
@@ -691,7 +693,8 @@ export function defineResource<
         if (!underAny(path, writeOnly)) {
           throw new Error(`${what}: ${at} is not write-only, so it takes a value, not a secret (${value.$secret})`);
         }
-        if (isSanomaSecret(value.$secret) && !(host && underAny(path, new Set([host.inputs.secrets])))) {
+        const hostSecrets = host?.inputs.secrets;
+        if (isSanomaSecret(value.$secret) && !(hostSecrets !== undefined && underAny(path, new Set([hostSecrets])))) {
           throw new Error(`${what}: ${at} names ${value.$secret}, one of sanoma's own: only a host's secrets may`);
         }
         secrets.add(at);

package/src/resources.ts

@@ -17,6 +17,7 @@ import {
   ANONYMOUS_PRINCIPAL,
   type At,
   declaresPeople,
+  isToken,
   isVisitor,
   type PeopleResource,
   personOf,
@@ -138,8 +139,10 @@ export function readPeople(root: string | undefined): DeclaredPeople {
  * (`signIn`), of the person it matches (`personOf`: email, GitHub login, then id), never an agent.
  * While no person is declared, whoever names an id is taken as given. A visitor's id (`isVisitor`)
  * is taken whatever the files say, with the groups stamped here (`visitors`, or none for
- * `anonymous`), never through a sign-in: the staff logins admit no visitor. Throws
- * `NotAdmittedError` for anyone else, and for everyone while the people's files have problems.
+ * `anonymous`), never through a sign-in: the staff logins admit no visitor. A visitor keeps the
+ * `email` its login verified; a `subject` is never taken from the caller (a token's is its row's,
+ * which `SanomaClient.start` reads). Throws `NotAdmittedError` for anyone else, and for
+ * everyone while the people's files have problems.
  */
 export function admit(
   asking: { id?: string; email?: string; github?: string; groups?: string[]; onBehalfOf?: string },
@@ -149,7 +152,10 @@ export function admit(
   const who = asking.github ?? asking.id ?? asking.email ?? "This sign-in";
   if (asking.id !== undefined && isVisitor({ id: asking.id })) {
     if (signIn) throw new NotAdmittedError(who);
-    return asking.id === ANONYMOUS ? ANONYMOUS_PRINCIPAL : { id: asking.id, groups: [VISITORS] };
+    if (asking.id === ANONYMOUS) return ANONYMOUS_PRINCIPAL;
+    // A token's groups are its row's (`SanomaClient.tokens`), which only the public front reads; a visitor's are stamped.
+    if (isToken({ id: asking.id })) return { id: asking.id, groups: [...(asking.groups ?? [])] };
+    return { id: asking.id, groups: [VISITORS], ...(asking.email && { email: asking.email }) };
   }
   if (problems.length) {
     // The runtime's own agents are declared by no file, so a broken one does not stop them (`check`'s scenarios).
@@ -160,7 +166,10 @@ export function admit(
   }
   if (!declaresPeople(people)) {
     const given = Principal.safeParse(asking).data;
-    if (given) return given;
+    if (given) {
+      const { email: _email, subject: _subject, ...principal } = given;
+      return principal;
+    }
   } else {
     const id = signIn ? personOf(asking, people) : asking.id;
     const admitted = id === undefined ? undefined : principalOf(id, people);

package/src/run.ts

@@ -1,6 +1,7 @@
 import type { ConnectionRef, ConnectionRegistry, ConnectionSnapshot } from "./connection.ts";
 import { AsyncLocalStorage } from "node:async_hooks";
 import type { Collection } from "./collection.ts";
+import type { DeclaredObjects } from "./config.ts";
 import type { DeadlineRegistry } from "./deadlines.ts";
 import type { ApprovalState, Approver, Principal, WorkflowDefinition } from "./define.ts";
 import type { Fake } from "./fake.ts";
@@ -53,6 +54,8 @@ export interface WorkerState {
   /** The worker's `source`, when it was given one. */
   source?: Source;
   types: ReadonlyMap<string, Resource>;
+  /** The objects the data files declare, read at each call: a workflow's change operation may not aim at one (`refuseDeclared`). */
+  declaredObjects(): Promise<DeclaredObjects>;
   /** The collections, by name, which scenarios' steps may name (`data.<name>`). */
   collections: ReadonlyMap<string, Collection>;
   steps: readonly Steps[];