@sanoma-ai/workflows 0.4.2 → 0.5.0

package/src/cedar.ts

@@ -18,25 +18,30 @@ import {
   type PolicyCall,
   type PreviewAnswer,
   type PreviewRequest,
+  VISITOR_DENIED,
 } from "./policy.ts";
-import { readPeople } from "./resources.ts";
+import { admit, readPeople } from "./resources.ts";
 import { cedarValue, cedarWasm, contextTypeOf, messageOf, NAMESPACE, schemaOf } from "./schema.ts";
 import {
+  ANONYMOUS,
   approverLabel,
   approverOf,
+  CALL_WORKFLOW,
   DATA_VENDOR,
   groupNamesOf,
+  isVisitor,
   type PeopleResource,
   principalIdsOf,
   principalOf,
   problemLine,
+  VISITORS,
   WORKFLOW_ACTION,
 } from "./shared.ts";
 
 // A company's policies in Cedar (`policies/**/*.cedar`), decided with `@cedar-policy/cedar-wasm`
 // against the schema of its resolved config (`schemaOf`). Allow is the default: the runtime adds
-// the one `permit`, so a company's policies are `forbid`s, each a hold when it carries
-// `@hold(...)` and a deny otherwise.
+// the one `permit` for people and agents, so a company's policies are `forbid`s, each a hold when
+// it carries `@hold(...)` and a deny otherwise, and the `permit`s that let visitors in.
 
 /** Where a company's policies are, under its root. */
 export const POLICIES_DIR = "policies";
@@ -58,6 +63,8 @@ export interface CedarPolicySource {
   title?: string;
   /** `@reason(...)`: the message of its deny. */
   reason?: string;
+  /** Whom a `permit` is for, when its principal is exactly `in Sanoma::Group::"visitors"` or `== Sanoma::Principal::"anonymous"`. */
+  scope?: typeof VISITORS | typeof ANONYMOUS;
 }
 
 /** What is wrong in the policies, at a file, line and column when Cedar says where. */
@@ -70,7 +77,10 @@ export interface PolicyProblem {
   message: string;
 }
 
-/** The runtime's own policy: allow whatever no `forbid` refuses. */
+/**
+ * The runtime's own policy: allow whatever no `forbid` refuses. A visitor's start or direct call
+ * is asked of the company's permits first (`cedarPolicy`): the runtime's permit leaves visitors out there.
+ */
 const ALLOW_ID = "allow-by-default";
 const ALLOW = "permit (principal, action, resource);";
 
@@ -132,7 +142,7 @@ export function loadPolicies(files: readonly { file: string; text: string }[]):
         problems.push(...answer.errors.map((e) => problemOf(e, file, part, start)));
         return;
       }
-      const { effect, annotations = {} } = answer.json;
+      const { effect, principal, annotations = {} } = answer.json;
       const id = annotations.id ?? `${file}#${n + 1}`;
       if (ids.has(id)) {
         const whose = id === ALLOW_ID ? "the runtime's own policy's" : "another policy's";
@@ -149,16 +159,28 @@ export function loadPolicies(files: readonly { file: string; text: string }[]):
         ...(annotations.hold !== undefined && { hold: annotations.hold }),
         ...(annotations.title !== undefined && { title: annotations.title }),
         ...(annotations.reason !== undefined && { reason: annotations.reason }),
+        ...scopeOf(principal),
       });
     });
   }
   return { policies, problems };
 }
 
+/** A permit's `scope`: whom its principal names, when that is exactly the visitors or `anonymous`. */
+function scopeOf(principal: PolicyJson["principal"]): Pick<CedarPolicySource, "scope"> {
+  if (!("entity" in principal) || !("id" in principal.entity)) return {};
+  const { op, entity } = principal;
+  const is = ({ type, id }: { type: string; id: string }) => entity.type === type && entity.id === id;
+  if (op === "in" && is(uid("Group", VISITORS))) return { scope: VISITORS };
+  if (op === "==" && is(uid("Principal", ANONYMOUS))) return { scope: ANONYMOUS };
+  return {};
+}
+
 /**
  * The policies checked against the schema of the resolved config (`validate`, strict), and what
- * Cedar cannot check: a `permit` (the runtime's is the only one), and a `@hold` naming neither a
- * declared group, nor a declared person, nor `on-behalf-of`. In the order written, each at its
+ * Cedar cannot check: a `permit` for anyone but the visitors or `anonymous` (the runtime's is the
+ * only one for people and agents), and a `@hold` naming neither a declared group, nor a declared
+ * person, nor `on-behalf-of`. In the order written, each at its
  * file, line and column, once per place: a policy scoped to every action fails the same way for each.
  */
 export function validatePolicies(
@@ -187,7 +209,16 @@ export function validatePolicies(
       .toSorted((a, b) => a.line! - b.line! || (a.column ?? 0) - (b.column ?? 0));
     const ours: PolicyProblem[] = [];
     if (p.effect === "permit") {
-      ours.push({ ...place, message: "a permit changes nothing: every call no forbid refuses is allowed already" });
+      if (p.scope === undefined) {
+        ours.push({
+          ...place,
+          message:
+            'a permit is allowed only for visitors: its principal must be `in Sanoma::Group::"visitors"` or ' +
+            '`== Sanoma::Principal::"anonymous"`; for people and agents every call no forbid refuses is allowed already',
+        });
+      } else if (p.hold !== undefined) {
+        ours.push({ ...place, message: "a permit holds nothing: write the @hold on a forbid" });
+      }
     } else if (p.hold !== undefined && p.hold !== ON_BEHALF_OF && approverOf(p.hold, people) === undefined) {
       ours.push({ ...place, message: `@hold("${p.hold}") names no declared group or person, nor "${ON_BEHALF_OF}"` });
     }
@@ -197,9 +228,14 @@ export function validatePolicies(
 
 /**
  * The policy a repo's Cedar files make, the runtime's `permit` added; its `version` a hash of the
- * policies' ids and text. It decides each call with `statefulIsAuthorized`
- * over the policy set and the schema of `resolved` (`schemaOf`), each parsed once:
+ * policies' ids and text. The runtime's permit leaves visitors out (`isVisitor`) of a run's start,
+ * a direct call (a call of the `call` workflow) and a preview not `inRun`: those are asked of the
+ * company's permits alone first. Any other call in a run is decided as anyone's, so a visitor let
+ * start a run makes its calls, forbids holding still. It decides each call with
+ * `statefulIsAuthorized` over the policy set and the schema of `resolved` (`schemaOf`), each parsed once:
  *
+ * - a visitor's start or direct call no company `permit` allows: `deny`, `VISITOR_DENIED`, never
+ *   held, so a visitor cannot ask anyone for what no policy lets it do;
  * - allow: `allow`, with the policies that allowed as `reasons`;
  * - deny, a determining `forbid` without `@hold`: `deny` with its `@reason`, or "Refused by <id>";
  * - deny by `@hold` forbids only: each lifted once an approval addressed to its approver and
@@ -221,14 +257,22 @@ export function cedarPolicy(
   const cedar = cedarWasm();
   const schema = schemaOf(resolved, people);
   const staticPolicies = { ...Object.fromEntries(policies.map((p) => [p.id, p.text])), [ALLOW_ID]: ALLOW };
+  // What lets a visitor in at a start or a direct call: the company's permits alone, the forbids aside.
+  const permits = Object.fromEntries(policies.filter((p) => p.effect === "permit").map((p) => [p.id, p.text]));
   const version = hash(staticPolicies);
-  // Cedar caches both per thread, by name: one for these policies over this schema.
+  // Cedar caches both per thread, by name: one for these policies over this schema, and its permits.
   const set = `sanoma-${hash({ staticPolicies, schema })}`;
-  for (const answer of [cedar.preparsePolicySet(set, { staticPolicies }), cedar.preparseSchema(set, schema)]) {
+  const permitsSet = `${set}-permits`;
+  for (const answer of [
+    cedar.preparsePolicySet(set, { staticPolicies }),
+    cedar.preparsePolicySet(permitsSet, { staticPolicies: permits }),
+    cedar.preparseSchema(set, schema),
+  ]) {
     if (answer.type === "failure") {
       throw new Error(`The Cedar policies do not parse: ${answer.errors.map(messageOf).join("; ")}`);
     }
   }
+  const hasPermits = Object.keys(permits).length > 0;
   const directory = directoryOf(people);
 
   /**
@@ -270,33 +314,50 @@ export function cedarPolicy(
     };
   };
 
-  /** May `actor` take `action` on `target` with `context`, given the run's `approvals` so far. */
+  /**
+   * May `actor` take `action` on `target` with `context`, given the run's `approvals` so far; at a
+   * start or a direct call (`atStart`), a visitor only where a company permit lets it in.
+   */
   const authorize = (
     actor: Principal,
     action: string,
     target: string | undefined,
     context: Record<string, unknown>,
     approvals: PolicyCall["run"]["approvals"],
+    atStart: boolean,
   ): Decision => {
     const principal = directory.principal(actor);
-    const check = (asked: Record<string, unknown>) =>
-      cedar.statefulIsAuthorized({
-        ...requestOf(principal, action, target, () => asked),
-        preparsedSchemaName: set,
-        validateRequest: true,
-        preparsedPolicySetId: set,
-      });
-    let answer = check(context);
-    // A record saved under fields since changed does not fit the schema as `before`. When the rest
-    // of the call does, it is asked again without the schema (the context is plain values), the
-    // action's groups given as entities: a policy reading a field the record lacks fails, so denies.
-    const { before, ...rest } = context;
-    if (answer.type === "failure" && before !== undefined && check(rest).type === "success") {
+    /** The answer of the policy set `id`. */
+    const ask = (id: string) => {
+      const check = (asked: Record<string, unknown>) =>
+        cedar.statefulIsAuthorized({
+          ...requestOf(principal, action, target, () => asked),
+          preparsedSchemaName: set,
+          validateRequest: true,
+          preparsedPolicySetId: id,
+        });
+      const answer = check(context);
+      // A record saved under fields since changed does not fit the schema as `before`. When the rest
+      // of the call does, it is asked again without the schema (the context is plain values), the
+      // action's groups given as entities: a policy reading a field the record lacks fails, so denies.
+      const { before, ...rest } = context;
+      if (answer.type === "success" || before === undefined || check(rest).type === "failure") return answer;
       const request = requestOf(principal, action, target, () => context);
       const groups = schema[NAMESPACE]?.actions[action]?.memberOf ?? [];
       request.entities.push({ uid: request.action, attrs: {}, parents: groups.map((g) => uid("Action", g.id)) });
-      answer = cedar.statefulIsAuthorized({ ...request, preparsedPolicySetId: set });
+      return cedar.statefulIsAuthorized({ ...request, preparsedPolicySetId: id });
+    };
+    // Refused, never held: a visitor cannot ask anyone for what no policy lets it do.
+    if (atStart && isVisitor(principal)) {
+      const permitted = hasPermits ? ask(permitsSet) : undefined;
+      // A request the schema refuses is told below, as anyone's; a permit that fails, by its id.
+      if (permitted?.type !== "failure" && permitted?.response.decision !== "allow") {
+        const failed = permitted?.response.diagnostics.errors[0];
+        if (failed) return deny(`${failed.policyId} failed: ${messageOf(failed.error)}`, [failed.policyId]);
+        return deny(VISITOR_DENIED);
+      }
     }
+    const answer = ask(set);
     // A request the schema refuses (an input Cedar cannot hold) is denied, not an error of the call.
     if (answer.type === "failure")
       return deny(`The call does not fit the Cedar schema: ${answer.errors.map(messageOf).join("; ")}`);
@@ -326,22 +387,34 @@ export function cedarPolicy(
       call.target,
       { input: call.input, ...(call.before !== undefined && { before: call.before }) },
       call.run.approvals,
+      call.run.workflow === CALL_WORKFLOW,
     );
 
   const start = (actor: Principal, workflow: string, input: unknown, approvals: readonly ApprovalState[] = []) =>
-    authorize(actor, `${WORKFLOW_ACTION}${workflow}`, undefined, { input }, approvals);
+    authorize(actor, `${WORKFLOW_ACTION}${workflow}`, undefined, { input }, approvals, true);
 
   const preview = (requests: readonly PreviewRequest[]): PreviewAnswer[] =>
-    requests.map(({ principal: actor, action, resource }) => {
+    requests.map(({ principal: actor, action, resource, inRun }) => {
       const principal = directory.principal(actor);
-      const answer = cedar.isAuthorizedPartial({
-        ...requestOf(principal, action.id, resource, unknown),
-        schema,
-        validateRequest: false,
-        policies: { staticPolicies },
-      });
-      if (answer.type === "failure") throw new Error(answer.errors.map(messageOf).join("; "));
-      const { decision, mustBeDetermining, nontrivialResiduals, residuals } = answer.response;
+      const partial = (asked: Record<string, string>) => {
+        const answer = cedar.isAuthorizedPartial({
+          ...requestOf(principal, action.id, resource, unknown),
+          schema,
+          validateRequest: false,
+          policies: { staticPolicies: asked },
+        });
+        if (answer.type === "failure") throw new Error(answer.errors.map(messageOf).join("; "));
+        return answer.response;
+      };
+      if (!inRun && isVisitor(principal)) {
+        const gate = hasPermits ? partial(permits) : undefined;
+        if (gate?.decision !== "allow") {
+          // A permit the input decides: the answer depends on it, whatever the rest says.
+          const open = policies.find((p) => gate?.nontrivialResiduals.includes(p.id));
+          return open ? { answer: "depends", rule: ruleOf(open) } : { answer: "deny" };
+        }
+      }
+      const { decision, mustBeDetermining, nontrivialResiduals, residuals } = partial(staticPolicies);
       if (decision === "allow") return { answer: "allow" };
       if (decision === "deny") {
         const { refusing, holds } = forbidsOf(mustBeDetermining, principal);
@@ -357,23 +430,59 @@ export function cedarPolicy(
   return Object.freeze(Object.assign(decide, { version, preview, start }));
 }
 
+/**
+ * Whether a company `permit` could let a visitor take `action`, in its action group `group`
+ * (`start`, or its operation's `effect:<effect>`): asked of the permits whose `scope` is in
+ * `scopes`, each with its principal taken as its scope says and its `when` and `unless` left out,
+ * on the workflow a start names, or on any target. False means none can apply, so a visitor's
+ * start or direct call of it is refused whatever its input (`VISITOR_DENIED`).
+ */
+export function visitorPermits(
+  policies: readonly CedarPolicySource[],
+): (scopes: ReadonlySet<string>, action: string, group: string) => boolean {
+  const cedar = cedarWasm();
+  const permits = policies.flatMap(({ id, effect, scope, text }) => {
+    if (effect !== "permit" || scope === undefined) return [];
+    const answer = cedar.policyToJson(text);
+    if (answer.type !== "success") return [];
+    const json: PolicyJson = { ...answer.json, principal: { op: "All" }, conditions: [] };
+    return [{ id, scope, json }];
+  });
+  return (scopes, action, group) => {
+    const asked = permits.filter((p) => scopes.has(p.scope));
+    if (!asked.length) return false;
+    const uidOf = uid("Action", action);
+    const answer = cedar.isAuthorizedPartial({
+      principal: uid("Principal", ANONYMOUS),
+      action: uidOf,
+      // An operation's target is the call's: unknown, so a permit naming one may apply.
+      resource: action.startsWith(WORKFLOW_ACTION) ? uid("Workflow", action.slice(WORKFLOW_ACTION.length)) : null,
+      context: {},
+      entities: [{ uid: uidOf, attrs: {}, parents: [uid("Action", group)] }],
+      policies: { staticPolicies: Object.fromEntries(asked.map((p) => [p.id, p.json])) },
+    });
+    // A request Cedar cannot evaluate is not a refusal this can be sure of.
+    return answer.type === "failure" || answer.response.decision !== "deny";
+  };
+}
+
 /**
  * The policy of the repo at `root`: its `policies/**\/*.cedar` over `resolved` and the people its
  * data files declare (`readPeople`, `cedarPolicy`), or `allowAll` when it has none. With problems
  * (`loadPolicies`, `validatePolicies`), each a printable line (`file:line:col: <policy id>:
  * <message>`), a policy that refuses every call, start and preview naming the first: a repo never
- * runs on part of its rules.
+ * runs on part of its rules. `policies` are what it is made from: undefined while they have problems.
  */
 export function policyAt(
   root: string | undefined,
   resolved: Pick<ResolvedConfig, "ops" | "workflows" | "collections">,
-): { policy: Policy; problems: string[] } {
+): { policy: Policy; policies?: CedarPolicySource[]; problems: string[] } {
   const files = root === undefined ? [] : readPolicyFiles(root);
-  if (!files.length) return { policy: allowAll, problems: [] };
+  if (!files.length) return { policy: allowAll, policies: [], problems: [] };
   const { people } = readPeople(root);
   const { policies, problems } = loadPolicies(files);
   problems.push(...validatePolicies(resolved, policies, people));
-  if (!problems.length) return { policy: cedarPolicy(resolved, policies, people), problems: [] };
+  if (!problems.length) return { policy: cedarPolicy(resolved, policies, people), policies, problems: [] };
   const lines = problems.map(({ policy, ...p }) =>
     problemLine({ ...p, message: policy ? `${policy}: ${p.message}` : p.message }),
   );
@@ -411,6 +520,8 @@ interface Directory {
 function directoryOf(people: readonly PeopleResource[]): Directory {
   const groups = new Set(groupNamesOf(people));
   const principal = (actor: Principal): Principal => {
+    // A visitor is told by its id, as `admit` takes it: never in a declared group.
+    if (isVisitor(actor)) return admit(actor, { people, problems: [] });
     // An admitted principal (`admit`) carries its groups as the files say now: those are taken as
     // they are. One without groups is given those declared when the policy was made.
     const declared = actor.groups === undefined ? principalOf(actor.id, people) : undefined;

package/src/client.ts

@@ -19,6 +19,7 @@ import {
   type ErrorInfo,
   errorCode,
   errorInfo,
+  NotAdmittedError,
   parseOrThrow,
   PolicyDeniedError,
   SanomaError,
@@ -35,6 +36,7 @@ import {
   DATA_VENDOR,
   errorMessage,
   isEnded,
+  isVisitor,
   refusalOf,
   type RunStatus,
   WORKFLOW_ACTION,
@@ -263,7 +265,8 @@ export class SanomaClient {
   /**
    * The policy's answer to starting a run of `workflow` as `startedBy` (`decideStart`), for a
    * workflow of the config's own: a deny throws `policy_denied`; a hold is what the run waits on
-   * before its body. A run `runId` names already is returned as it is, whatever the policy says now.
+   * before its body. A run `runId` names already is returned as it is, whatever the policy says now, but to a visitor.
+   * A visitor (`isVisitor`) starts no built-in but `call`, whose calls the policy decides as direct ones.
    */
   private async startHold(
     workflow: string,
@@ -272,8 +275,17 @@ export class SanomaClient {
     runId: string | undefined,
   ): Promise<StartHold | undefined> {
     const { policy } = this.config;
-    if (BUILT_IN_WORKFLOWS.has(workflow) || policy === allowAll) return undefined;
-    if (runId !== undefined && (await this.row(runId))) return undefined;
+    const visitor = isVisitor(startedBy);
+    const builtIn = BUILT_IN_WORKFLOWS.has(workflow);
+    if (visitor && builtIn && workflow !== CALL_WORKFLOW) {
+      throw new PolicyDeniedError(
+        `${WORKFLOW_ACTION}${workflow}`,
+        "A visitor may not start the runtime's own workflows",
+      );
+    }
+    if (builtIn || (policy === allowAll && !visitor)) return undefined;
+    // A visitor's start is decided whatever run its id names: a visitor shares an id (`anonymous`) with others.
+    if (!visitor && runId !== undefined && (await this.row(runId))) return undefined;
     const decision = decideStart(policy, workflow, input, startedBy);
     if (decision.kind === "allow") return undefined;
     if (decision.kind === "deny") throw new PolicyDeniedError(`${WORKFLOW_ACTION}${workflow}`, decision.reason);
@@ -805,9 +817,10 @@ export class SanomaClient {
     return admit(principal, readPeople(this.config.root));
   }
 
-  /** `options.by`, who sets or clears a credential, admitted (`admitted`): their id. */
+  /** `options.by`, who sets or clears a credential, admitted (`admitted`): their id; never a visitor's. */
   private async admittedBy(options: { by: string }): Promise<string> {
     const by = parseOrThrow(z.string().min(1), options?.by, '`by` must name who is asking, such as "alice"');
+    if (isVisitor({ id: by })) throw new NotAdmittedError(by);
     return (await this.admitted({ id: by })).id;
   }
 

package/src/config.ts

@@ -32,7 +32,7 @@ import {
   setupOf,
   VENDOR,
 } from "./op.ts";
-import { policyAt } from "./cedar.ts";
+import { type CedarPolicySource, policyAt } from "./cedar.ts";
 import type { Policy } from "./policy.ts";
 import { isChangeOp, type Resource, resourceTypesOf, withoutWriteOnly } from "./resource.ts";
 import { APPLY_WORKFLOW, BUILT_IN_WORKFLOWS, CALL_WORKFLOW, DATA_VENDOR } from "./shared.ts";
@@ -120,6 +120,8 @@ export interface ResolvedConfig {
   driversByVendor: Map<string, Driver>;
   /** The makers of the fakes the connectors attach, by vendor id in `connectors` order: each sandbox run makes its own. */
   fakes: Map<string, () => Fake<any, any>>;
+  /** The makers of the login halves the connectors attach, by vendor id in `connectors` order: the app makes one per public site that names it. */
+  logins: ReadonlyMap<string, NonNullable<ConnectorSetup["login"]>>;
   /** `scenarios/` in `root`, as a `file:` URL, when that directory exists. */
   scenarios?: URL;
   /** The resource types the connectors declare, by `<vendor>.<type>`: what the drift workflow checks and scenarios seed. */
@@ -145,6 +147,8 @@ export interface ResolvedConfig {
    * (`policyAt`), `allowAll` without any, and one that refuses everything while they have problems.
    */
   policy: Policy;
+  /** The policies `policy` is made from (`loadPolicies`), none without any; undefined while they have problems. */
+  policies?: readonly CedarPolicySource[];
   /** What is wrong in the policies, one printable line each (`file:line:col: <policy id>: <message>`). */
   policyProblems: string[];
   /** The config's `ledger`, when it gives one; the worker and the client otherwise make `postgresLedger` on `databaseUrl` (`ownedLedger`). */
@@ -278,7 +282,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
   // Built-in: a direct call the policy holds for an approval, made a run, when any operation may be called directly.
   const call = callWorkflow(ops, drivers, types);
   if (call.uses.length) names.set(CALL_WORKFLOW, call);
-  const { policy, problems: policyProblems } = policyAt(root, { ops, workflows: names, collections });
+  const { policy, policies, problems: policyProblems } = policyAt(root, { ops, workflows: names, collections });
   return {
     appName,
     databaseUrl,
@@ -289,6 +293,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     drivers,
     driversByVendor,
     fakes,
+    logins: makersOf(config.connectors, "login"),
     ...(scenarios && { scenarios }),
     types,
     steps: [...new Set([...config.connectors.flatMap((c) => setupOf(c).steps ?? []), ...(config.steps ?? [])])],
@@ -296,6 +301,7 @@ export function resolveConfig(config: SanomaConfig): ResolvedConfig {
     ...(dataStore && { dataStore }),
     workflows: names,
     policy,
+    ...(policies && { policies }),
     policyProblems,
     ...(ledger !== undefined && { ledger }),
     ...(root !== undefined && { root }),

package/src/describe.ts

@@ -1,3 +1,4 @@
+import { join } from "node:path";
 import type { z } from "zod";
 import { type LintProblem, readSource, type SourceFile } from "./ast.ts";
 import { type Field, recordSchemaOf } from "./collection.ts";
@@ -8,7 +9,7 @@ import { lintWorkflow } from "./lint.ts";
 import { type Effect, VENDOR, type VendorInfo } from "./op.ts";
 import { type Outline, outlineWithSource } from "./outline.ts";
 import { allowAll, policyOpOf } from "./policy.ts";
-import { type ResourceFields, resourceTypesOf } from "./resource.ts";
+import { type Resource, type ResourceFields, resourceTypesOf, valueAt } from "./resource.ts";
 import {
   type DataFiles,
   type DeclaredCollection,
@@ -303,6 +304,12 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
   });
   workflows.sort((a, b) => a.name.localeCompare(b.name));
   addApiNameProblems(workflows, new Set(ops.map((op) => op.vendor)));
+  const sites = readSites(
+    resolved.root,
+    { workflows, collections, ops },
+    { vendors: new Set(Object.keys(vendors)), logins: new Set(resolved.logins.keys()) },
+    resolved.policies,
+  );
 
   return {
     appName: resolved.appName,
@@ -314,16 +321,52 @@ export function describeConfig(config: SanomaConfig): ConfigDescription {
     collections,
     resources: dataFiles.resources,
     orphans: dataFiles.orphans,
-    problems: dataFiles.problems,
+    problems: [...dataFiles.problems, ...domainProblems(resolved.root, dataFiles.resources, resources, sites, read)],
     policy: {
       defined: resolved.policy !== allowAll,
       ...(resolved.policy.version === undefined ? {} : { version: resolved.policy.version }),
       ...(resolved.policyProblems.length ? { problems: resolved.policyProblems } : {}),
     },
-    sites: readSites(resolved.root, { workflows, collections, ops }),
+    sites,
   };
 }
 
+/**
+ * Each site a host's `domains` (its type's `host.inputs.domains`) names that is not a public
+ * site, and each domain it gives more than one site, at the host's declaration: the app serves
+ * only a public site at a domain, and one site at each.
+ */
+function domainProblems(
+  root: string | undefined,
+  declared: readonly DeclaredResource[],
+  types: ReadonlyMap<string, Resource>,
+  sites: readonly SiteEntry[],
+  read: (path: string) => SourceFile | string,
+): ResourceProblem[] {
+  const isPublic = new Set(sites.filter((site) => site.public).map((site) => site.name));
+  const problems: ResourceProblem[] = [];
+  for (const resource of declared) {
+    const path = types.get(`${resource.vendor}.${resource.type}`)?.host?.inputs.domains;
+    const domains = (path === undefined ? {} : (valueAt(resource.desired, path) ?? {})) as Record<string, unknown>;
+    const messages = Object.keys(domains)
+      .filter((name) => !isPublic.has(name))
+      .map((name) => `domains names "${name}", which is not a public site (defineSite({ public: true }))`);
+    const named = Object.entries(domains).filter(([, value]) => typeof value === "string");
+    // A host name's case is not its own: `publicHosts` compares them lowercased.
+    for (const [domain, entries] of Map.groupBy(named, ([, value]) => (value as string).toLowerCase())) {
+      const names = entries.map(([name]) => name);
+      if (names.length < 2) continue;
+      const others = `${names.length === 2 ? "both " : ""}${names.slice(0, -1).join(", ")}`;
+      messages.push(`${domain} is the domain of ${others} and ${names.at(-1)}`);
+    }
+    if (!messages.length || root === undefined) continue;
+    const file = read(join(root, resource.file));
+    const at = typeof file === "string" ? {} : file.at(resource.span[0]);
+    for (const message of messages) problems.push({ file: resource.file, ...at, message });
+  }
+  return problems;
+}
+
 /**
  * A site's `api` names each workflow `apiNameOf(name)` beside the vendors' operations and the
  * collections (`api.data`), so a workflow whose name comes out as another's, a vendor's id or

package/src/host.ts

@@ -42,6 +42,8 @@ export interface HostSpec {
     secrets: string;
     /** The port the app listens on. */
     port: string;
+    /** A public site's domain, by site name: the app serves each site at the root of its domain (`SANOMA_DOMAINS`). */
+    domains?: string;
   };
   /**
    * The field apply fills with the commit `ref` resolves to, before it plans: hidden, as a data

package/src/index.ts

@@ -1,5 +1,6 @@
 export {
   type CallContext,
+  CLIENT_IP_HEADER,
   type Connector,
   type ConnectorSetup,
   type ConnectorVendor,
@@ -11,6 +12,8 @@ export {
   type Effect,
   isOp,
   isSvgElement,
+  type LoginContext,
+  type LoginHalf,
   type Op,
   type OpSpec,
   type ResourceGroup,
@@ -88,6 +91,7 @@ export {
   type PreviewAnswer,
   type PreviewRequest,
   type RecordedDecision,
+  VISITOR_DENIED,
 } from "./policy.ts";
 export {
   cedarPolicy,
@@ -148,6 +152,8 @@ export { dbosClient } from "./db.ts";
 // Also at `@sanoma-ai/workflows/shared`, which a browser bundle can import.
 export {
   AGENTS,
+  ANONYMOUS,
+  ANONYMOUS_PRINCIPAL,
   approverLabel,
   approverOf,
   declaresPeople,
@@ -161,11 +167,14 @@ export {
   errorMessage,
   isEnded,
   isLoopback,
+  isVisitor,
   mayDecide,
   problemAt,
   problemLine,
   RUN_STATUSES,
   type RunStatus,
+  VISITORS,
+  visitorPrincipal,
 } from "./shared.ts";
 // describeConfig, with the outline and every problem lintWorkflow finds, lives at
 // `@sanoma-ai/workflows/describe`: what a UI renders from, apart from what runs. The worker reads

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>;
 }
 
 /**