@sanoma-ai/workflows 0.10.2 → 0.10.3

package/src/index.ts

@@ -1,6 +1,8 @@
 export {
   type CallContext,
   CLIENT_IP_HEADER,
+  requestOrigin,
+  sameOrigin,
   type Connector,
   type ConnectorSetup,
   type ConnectorVendor,
@@ -12,13 +14,17 @@ export {
   type Effect,
   isOp,
   isSvgElement,
+  INVITE_SECONDS,
   type LoginContext,
   type LoginHalf,
+  type LoginIdentity,
+  type LoginMethod,
   type ModelContext,
   type Op,
   type OpSpec,
   type ResourceGroup,
   retryableStatus,
+  type SignInMethod,
   type VendorInfo,
   withSetup,
 } from "./op.ts";
@@ -33,6 +39,7 @@ export {
   type Builtin,
   type Ctx,
   type SleepRequest,
+  type StartedBy,
   type StepOptions,
   type Trigger,
   type Use,
@@ -56,6 +63,7 @@ export {
 export {
   declaredWakeup,
   defineConfig,
+  envWakeup,
   resolveConfig,
   resolveDatabaseUrl,
   type ResolvedConfig,
@@ -201,9 +209,16 @@ export {
   storeDatabaseUrl,
 } from "./database.ts";
 export type { Chat, Chats } from "./chats.ts";
+export type { Tokens } from "./tokens.ts";
+export { type InviteRequest, openInvite, sealInvite, sealLoginCode } from "./seal.ts";
+export { postInvite, sanoma } from "./runtime-ops.ts";
+export { sourceKeyPair, sshPublicKey } from "./ssh-key.ts";
 export {
   checkWakeup,
   type DeclaredWakeup,
+  type EnvWakeup,
+  HOST_URL,
+  WAKE_PATH,
   type WakeupOutputs,
   type WakeupRegistration,
   type WakeupSpec,
@@ -243,6 +258,8 @@ export {
   principalOf,
   RUNTIME_AGENTS,
   HOST_CHECK_AGENT,
+  LOGIN_AGENT,
+  LOGIN_CODE_WORKFLOW,
   SCHEDULE_AGENT,
   credentialReady,
   DEFAULT_SLEEP_NAME,
@@ -298,7 +315,7 @@ export {
 export { checkSecretStore, type SecretStoreCheck } from "./secret-store-check.ts";
 
 export { postgresSecretStore } from "./credentials.ts";
-export { deploymentKey } from "./deployment-key.ts";
+export { deploymentKey, signingKeyFor } from "./deployment-key.ts";
 
 export {
   defineConnection,

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