@sanoma-ai/workflows 0.4.2 → 0.6.0

package/src/op.ts

@@ -304,9 +304,10 @@ export interface Driver {
 
 /**
  * What a connector package attaches to its connector (`withSetup`), for the config's resolver
- * to call: the config then names the connector alone, and never a driver, a fake or steps. Any may
- * be missing: a workflow using an operation of a connector with no driver is refused, and a
- * connector with no fake has none for sandbox runs.
+ * to call: the config then names the connector alone, and never a driver, a fake, steps or a
+ * login. Any may be missing: a workflow using an operation of a connector with no driver is
+ * refused, a connector with no fake has none for sandbox runs, and one with no login half signs
+ * no visitor in.
  */
 export interface ConnectorSetup {
   /** Makes the live driver, which reads its credentials from the environment when called: once per resolved config. */
@@ -315,6 +316,58 @@ export interface ConnectorSetup {
   fake?: () => Fake<any, any>;
   /** The connector's steps for Gherkin tests (`defineSteps`): a config's scenarios and the connector's own features can use them. */
   steps?: Steps;
+  /**
+   * Makes the connector's login half for one public site: once per site, by the app, when it
+   * starts; a login that needs tables migrates them here (serialized, idempotent).
+   */
+  login?: (context: LoginContext) => LoginHalf | Promise<LoginHalf>;
+}
+
+/** What the app gives a connector's login half (`ConnectorSetup.login`) when it makes it for a public site. */
+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,
+   * purpose `login <connector>`), hex; a login signs its cookies with it and never asks a person for a secret.
+   */
+  key: string;
+  /**
+   * Secrets' values by name, for a login that holds a vendor's credentials (an Auth0 client
+   * secret): the environment's first, then the stored credentials (the values `SanomaClient.secrets` reads).
+   */
+  secrets(names: readonly string[]): Promise<Map<string, string>>;
+  /**
+   * 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.
+   */
+  origins: readonly string[];
+}
+
+/**
+ * The app sets this header on every request to a public site from the socket's address,
+ * overwriting any copy a client sent; a login reads a visitor's address from it (for rate
+ * limits), never from `X-Forwarded-For`.
+ */
+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.
+ */
+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>;
+  /** 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;
+  close?(): Promise<void>;
 }
 
 /**

package/src/policy.ts

@@ -1,5 +1,6 @@
 import { type ApprovalState, type Approver, type Principal, sameApprover } from "./define.ts";
 import type { Effect, Op } from "./op.ts";
+import { CALL_WORKFLOW, isVisitor } from "./shared.ts";
 
 /** An operation as a policy sees it: plain data, without its schemas. */
 export type PolicyOp = Pick<Op, "id" | "vendor" | "resource" | "name" | "effect">;
@@ -96,6 +97,8 @@ export interface PreviewRequest {
   principal: Principal;
   action: { id: string; effect?: Effect };
   resource?: string;
+  /** Asked of an operation inside a run the principal started, not of a direct call: a visitor's permit is at the start. */
+  inRun?: boolean;
 }
 
 /**
@@ -108,20 +111,36 @@ export interface PreviewAnswer {
   approver?: Approver;
 }
 
-/** A policy that decides every call and start as `decide` does, and previews each as `answer`. */
-const decidingAll = (decide: () => Decision, answer: "allow" | "deny"): Policy =>
-  Object.freeze(
+/** Why a visitor is refused what no policy permits it: the runtime's own permit leaves visitors out. */
+export const VISITOR_DENIED = "A visitor may do nothing until a policy permits it";
+
+/**
+ * Allows every operation call and run start but a visitor's (`isVisitor`): the policy of a repo
+ * with no `policies/**\/*.cedar`. A visitor is refused a start and a direct call (a call of the
+ * `call` workflow), as the runtime's permit refuses them, and allowed every call inside a run.
+ */
+export const allowAll: Policy = Object.freeze(
+  Object.assign(
+    (call: PolicyCall): Decision =>
+      isVisitor(call.actor) && call.run.workflow === CALL_WORKFLOW ? deny(VISITOR_DENIED) : allow(),
+    {
+      start: (actor: Principal): Decision => (isVisitor(actor) ? deny(VISITOR_DENIED) : allow()),
+      preview: (requests: readonly PreviewRequest[]): PreviewAnswer[] =>
+        requests.map(({ principal, inRun }) => ({ answer: isVisitor(principal) && !inRun ? "deny" : "allow" })),
+    },
+  ),
+);
+
+/** Refuses every operation call and run start, and previews each as a deny, saying `reason`. */
+export const denyAll = (reason: string): Policy => {
+  const decide = () => deny(reason);
+  return Object.freeze(
     Object.assign(decide, {
       start: decide,
-      preview: (requests: readonly PreviewRequest[]): PreviewAnswer[] => requests.map(() => ({ answer })),
+      preview: (requests: readonly PreviewRequest[]): PreviewAnswer[] => requests.map(() => ({ answer: "deny" })),
     }),
   );
-
-/** Allows every operation call and run start: the policy of a repo with no `policies/**\/*.cedar`. */
-export const allowAll: Policy = decidingAll(() => allow(), "allow");
-
-/** Refuses every operation call and run start, and previews each as a deny, saying `reason`. */
-export const denyAll = (reason: string): Policy => decidingAll(() => deny(reason), "deny");
+};
 
 /**
  * True when an approval in the run was approved, covers the operation, and was addressed to

package/src/resources.ts

@@ -19,12 +19,16 @@ import { Principal } from "./define.ts";
 import { NotAdmittedError } from "./errors.ts";
 import {
   AGENTS,
+  ANONYMOUS,
+  ANONYMOUS_PRINCIPAL,
   declaresPeople,
+  isVisitor,
   type PeopleResource,
   personOf,
   principalOf,
   problemLine,
   RUNTIME_AGENTS,
+  VISITORS,
 } from "./shared.ts";
 
 /** A resource a data file declares, as read from the file without running it. */
@@ -122,6 +126,13 @@ const filesStamp = (root: string) =>
     })
     .join("\n");
 
+/** The names no data file may give a group: what each is already. */
+const RESERVED_GROUPS: ReadonlyMap<string, string> = new Map([
+  [AGENTS, "the group every agent is in"],
+  [VISITORS, "the group every visitor is in"],
+  [ANONYMOUS, "who a public page runs as when nobody is signed in"],
+]);
+
 /**
  * The people, agents and groups the data files under `root` declare (`sanoma.person`, `.agent`,
  * `.group`), read without running them, as `principalOf` takes them, with what is wrong in their
@@ -140,22 +151,21 @@ export function readPeople(root: string | undefined): DeclaredPeople {
   const ids = new Map<string, DeclaredResource>();
   for (const r of people) {
     if (r.type === "group") {
-      if (r.name === AGENTS) {
-        own.push({
-          file: r.file,
-          message: `${r.id} is named "${AGENTS}", the group every agent is in: give it another name`,
-        });
-      }
+      const reserved = RESERVED_GROUPS.get(r.name);
+      if (reserved)
+        own.push({ file: r.file, message: `${r.id} is named "${r.name}", ${reserved}: give it another name` });
       continue;
     }
     const id = r.name;
     const other = ids.get(id);
-    if (other || RUNTIME_AGENTS.includes(id)) {
+    if (other || RUNTIME_AGENTS.includes(id) || isVisitor({ id })) {
       own.push({
         file: r.file,
         message: other
           ? `${r.id} has the id "${id}", which ${other.id} has: give each person and agent their own`
-          : `${r.id} has the id "${id}", one of the runtime's own agents': give it another`,
+          : isVisitor({ id })
+            ? `${r.id} has the id "${id}", a visitor's (\`anonymous\` or \`visitor:<login>:<subject>\`): give it another`
+            : `${r.id} has the id "${id}", one of the runtime's own agents': give it another`,
       });
     }
     ids.set(id, r);
@@ -169,8 +179,10 @@ export function readPeople(root: string | undefined): DeclaredPeople {
  * Who `asking` is admitted as, by the people the data files declare (`readPeople`): the declared
  * principal (`principalOf`) of the id it names, a person's or an agent's; for a sign-in
  * (`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. Throws `NotAdmittedError`
- * for anyone else, and for everyone while the people's files have problems.
+ * 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.
  */
 export function admit(
   asking: { id?: string; email?: string; github?: string; groups?: string[]; onBehalfOf?: string },
@@ -178,6 +190,10 @@ export function admit(
   signIn = false,
 ): Principal {
   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 (problems.length) {
     // The runtime's own agents are declared by no file, so a broken one does not stop them (`check`'s scenarios).
     if (!signIn && asking.id !== undefined && RUNTIME_AGENTS.includes(asking.id)) {

package/src/scenario.ts

@@ -50,6 +50,7 @@ import {
   principalIdsOf,
   problemLine,
   RUNTIME_AGENTS,
+  visitorPrincipal,
 } from "./shared.ts";
 import type { Call, RunView, Seed } from "./steps.ts";
 
@@ -143,7 +144,7 @@ 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. */
+  /** Who starts the run, by id, when a `Given <who> is acting` says: a declared person or agent, `anonymous` or a visitor. */
   startedBy?: string;
   given: Given[];
   input: unknown;
@@ -404,7 +405,7 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
   const workflowOf = (name: unknown) => scope.workflows.get(name as string)!;
   // The people as the root's data files declare them when a step names one (`readPeople`, read
   // again only once a file changed): while they declare no one, any id and any group go.
-  /** `who`, as a run's start admits them (`admit`): a declared person or agent. */
+  /** `who`, as a run's start admits them (`admit`): a declared person or agent, or `anonymous`. */
   const actorNamed = (who: string) => {
     const declared = readPeople(scope.root);
     try {
@@ -434,6 +435,8 @@ function rulesOf(scope: Scope): { rules: Rule[]; parameterTypes: ParameterTypeSp
   };
   const rules: Rule[] = [
     { 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 },
     {
       kind: "given",
       source: "{op} was called with",

package/src/schema.ts

@@ -67,7 +67,7 @@ const WRITES = new Set(["save", "delete"]);
 /**
  * The Cedar schema for a resolved config and its people, namespace `Sanoma`:
  *
- * - `entity Group enum [...]`, the declared groups and `agents`, so a policy naming another fails
+ * - `entity Group enum [...]`, the declared groups, `agents` and `visitors`, so a policy naming another fails
  *   validation; `entity Principal in [Group] { onBehalfOf?: Principal }`; `Collection`;
  *   `Target in [Collection]`; `Workflow`;
  * - an action per operation id, in its effect's group (`effect:money`), on a `Target`, with

package/src/shared.ts

@@ -55,6 +55,41 @@ export const WORKFLOW_ACTION = "workflow:";
 /** A site's folder name under `sites/`, its URL segment: what the app mounts and `readSites` reads. */
 export const SITE_NAME = /^[a-z][a-z0-9-]*$/;
 
+/**
+ * A public site's language, as `defineSite({ locales })` names it: a BCP 47 language tag of a
+ * language and subtags (`en`, `fr`, `pt-BR`), which is also its URL segment (`/pt-BR/…`) and a
+ * content file's suffix (`<slug>.pt-BR.md`).
+ */
+export const LOCALE = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+/** A public site's domain: a host name of two labels or more, lowercase (`sanoma.example`). */
+export const DOMAIN_NAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$/;
+
+/**
+ * The public sites' domains as a host hands them to the app in `SANOMA_DOMAINS` (`HostSpec`'s
+ * `domains`): `<site>=<hostname>`, comma-separated, by site name.
+ */
+export const domainsText = (domains: Readonly<Record<string, string>>): string =>
+  Object.keys(domains)
+    .toSorted()
+    .map((site) => `${site}=${domains[site]}`)
+    .join(",");
+
+/** The domains `domainsText` wrote, by site name; throws for a pair that is not `<site>=<hostname>`, or a site named twice. */
+export function domainsOf(text: string): Record<string, string> {
+  const domains: Record<string, string> = {};
+  for (const pair of text.split(",")) {
+    const [site = "", domain = "", ...rest] = pair.trim().split("=");
+    if (!SITE_NAME.test(site) || !DOMAIN_NAME.test(domain) || rest.length || Object.hasOwn(domains, site)) {
+      throw new Error(
+        `SANOMA_DOMAINS has "${pair}": write <site>=<hostname>, each site once, such as www=sanoma.example`,
+      );
+    }
+    domains[site] = domain;
+  }
+  return domains;
+}
+
 /**
  * A record of a collection as `get`, `list` and `save` answer it: its key, the record, and when
  * and by whom it was last saved (`updatedBy`: a person's id, or `run:<id>` for a run). A record
@@ -196,6 +231,7 @@ export function refusalOf(
   run: DecidedRun,
   people: readonly PeopleResource[],
 ): string | undefined {
+  if (isVisitor(by)) return "a visitor decides no approval";
   if (typeof approver === "string") {
     return approver === by.id ? undefined : `${by.id} is not the approver; ${approverLabel(approver)} is`;
   }
@@ -213,6 +249,34 @@ export type PeopleResource = Pick<DeclaredResource, "vendor" | "type" | "desired
 /** The group every agent is in, the runtime's own among them: no data file declares it. */
 export const AGENTS = "agents";
 
+/** The group every visitor of a public site is in: no data file declares it. */
+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. */
+const VISITOR_ID = /^visitor:[^\s:]+:\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.
+ */
+export const isVisitor = (p: Pick<Principal, "id">): boolean => p.id === ANONYMOUS || VISITOR_ID.test(p.id);
+
+/**
+ * The visitor a public site's login vouches for: `subject` from the provider behind the `login`
+ * connector, in `visitors`. Throws for a login or subject that would make an id `isVisitor` does not tell.
+ */
+export function visitorPrincipal(login: string, subject: string): Principal {
+  const id = `visitor:${login}:${subject}`;
+  if (!VISITOR_ID.test(id)) throw new Error(`"${id}" is not a visitor's id: visitor:<login connector>:<subject>`);
+  return { id, groups: [VISITORS] };
+}
+
+/** Who a public page runs as when nobody is signed in. */
+export const ANONYMOUS_PRINCIPAL: Principal = Object.freeze({ id: ANONYMOUS, groups: [] });
+
 /** The runtime's own agents (scenarios, the host check, scheduled runs), declared whether a data file names them or not. */
 export const RUNTIME_AGENTS: readonly string[] = ["scenarios", "host-check", "schedule"];
 
@@ -224,9 +288,9 @@ type PersonFields = { id: string; name?: string; email?: string; github?: string
 type AgentFields = { id: string; onBehalfOf?: string };
 type GroupFields = { name: string; members: string[] };
 
-/** The groups a policy may name and a principal may be in: the declared ones and `agents`, sorted. */
+/** The groups a policy may name and a principal may be in: the declared ones, `agents` and `visitors`, sorted. */
 export const groupNamesOf = (resources: readonly PeopleResource[]): string[] =>
-  [...new Set([...peopleOfType<GroupFields>(resources, "group").map((g) => g.name), AGENTS])].toSorted();
+  [...new Set([...peopleOfType<GroupFields>(resources, "group").map((g) => g.name), AGENTS, VISITORS])].toSorted();
 
 /** The declared people (`sanoma.person`), in the order declared: not agents, who never sign in. */
 export const personsOf = (resources: readonly PeopleResource[]): PersonFields[] =>
@@ -261,9 +325,10 @@ export function principalOf(id: string, resources: readonly PeopleResource[]): P
 
 /**
  * Who `name` is as an approver: a declared group's name (or `agents`) as `{ group }`, else a
- * declared person's or agent's id; undefined when it is neither.
+ * declared person's or agent's id; undefined when it is neither, and for `visitors`, who decide nothing.
  */
 export function approverOf(name: string, resources: readonly PeopleResource[]): Approver | undefined {
+  if (name === VISITORS) return undefined;
   if (groupNamesOf(resources).includes(name)) return { group: name };
   return principalOf(name, resources) && name;
 }
@@ -337,6 +402,10 @@ export function problemLine(p: { file?: string; line?: number; column?: number;
   return p.line === undefined ? `${p.file}: ${p.message}` : `${p.file}:${p.line}:${p.column ?? 1}: ${p.message}`;
 }
 
+/** A warning as one line, as `problemLine` with `warning: ` before its message: what is worth fixing but not wrong. */
+export const warningLine = (p: Parameters<typeof problemLine>[0]): string =>
+  problemLine({ ...p, message: `warning: ${p.message}` });
+
 /**
  * Whether a host is this machine: `localhost`, `127.x.x.x` or `::1` (bare, or bracketed as a URL's
  * `hostname` has it). The one rule for what the app listens on and answers to, and for where the