@sanoma-ai/workflows 0.4.1 → 0.5.0

package/src/sites.ts

@@ -1,11 +1,21 @@
 import { existsSync, readdirSync } from "node:fs";
 import { join, relative, sep } from "node:path";
 import { childrenOf, type LintProblem, type Node, readSource, type SourceFile } from "./ast.ts";
+import { type CedarPolicySource, visitorPermits } from "./cedar.ts";
 import { keyName } from "./datafile.ts";
 import type { ConfigDescription } from "./describe.ts";
 import { stringValue, unwrap } from "./outline.ts";
 import { filesUnder, isDirectory } from "./paths.ts";
-import { apiNameOf, DATA_VENDOR, SITE_NAME } from "./shared.ts";
+import { START } from "./schema.ts";
+import {
+  ANONYMOUS,
+  apiNameOf,
+  BUILT_IN_WORKFLOWS,
+  DATA_VENDOR,
+  SITE_NAME,
+  VISITORS,
+  WORKFLOW_ACTION,
+} from "./shared.ts";
 
 // What a company's sites call, read from their source with oxc and never run: the reverse index
 // a workflow's page shows as Used by, and the names `sanoma check` holds to the config.
@@ -19,7 +29,13 @@ export interface SiteCall {
    * `api` gives; that name itself when none is), the collection's name, or the operation's id.
    */
   target: string;
-  /** `<RunForm workflow="…" />` from `@sanoma-ai/app/ui`, or a call on `api` from `sanoma/site`. */
+  /**
+   * What it calls of the workflow (`start`, or a read of its runs: `result`, `latest`, …) or the
+   * collection (`list`, `save`, …), as written; absent for a workflow called as itself or by
+   * `RunForm`, which starts it, and for an operation.
+   */
+  method?: string;
+  /** `<RunForm workflow="…" />` or a call on `api`, from `sanoma/site`. */
   via: "RunForm" | "api";
   /** The file, relative to the config's root, with `/`: `sites/sales/routes/index.tsx`. */
   file: string;
@@ -41,17 +57,26 @@ export interface SiteEntry {
   name: string;
   /** `defineSite({ title })` in its `site.ts`, when that is a string literal. */
   title?: string;
+  /** `defineSite({ public: true })`: served to visitors, not people. */
+  public?: true;
+  /** `defineSite({ login })`, the connector whose login half signs visitors in, as written: one that names none is among `problems`. */
+  login?: string;
+  /** The host a public site answers on: set by `startApp` from its `domains`, never by `readSites`. */
+  domain?: string;
   /** Its calls, by file and then in the file's order. */
   calls: SiteCall[];
-  /** Each call to a workflow, a collection or an operation the config does not have, or to an operation a page may not call directly, at its file. */
+  /**
+   * Each call to a workflow, a collection or an operation the config does not have, or to an
+   * operation a page may not call directly, or, on a public site, that no policy lets a visitor
+   * make, at its file; then what is wrong in its `site.ts`.
+   */
   problems: (LintProblem & { file: string })[];
 }
 
 /** Where a site's code is: its pages and its components. */
 const SITE_DIRS = ["routes", "components"];
-/** Where `api` and `defineSite` come from: `sanoma/site`, which re-exports the app's. */
+/** Where `api`, `RunForm` and `defineSite` come from: `sanoma/site`, which re-exports the app's. */
 const SITE_SOURCES: ReadonlySet<string> = new Set(["sanoma/site", "@sanoma-ai/app/site"]);
-const UI_SOURCES: ReadonlySet<string> = new Set(["@sanoma-ai/app/ui"]);
 const KIND_NAMES = { workflow: "workflow", collection: "collection", op: "operation" } as const;
 /** What makes a route from its id, whose first argument is the id. */
 const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLazyFileRoute"]);
@@ -60,17 +85,25 @@ const ROUTE_MAKERS: ReadonlySet<string> = new Set(["createFileRoute", "createLaz
  * The sites under `root`: each folder of `sites/` with a `routes/` whose name is a URL segment,
  * by name (as `@sanoma-ai/app/build`'s `sitesOf` mounts them). Reads `routes/**` and
  * `components/**` (`.ts` and `.tsx`, less tests and declarations) of each with oxc, never running
- * them: each `<RunForm workflow="…" />` whose `RunForm` is imported from `@sanoma-ai/app/ui`, and
- * each use of `api` imported from `sanoma/site`, called or passed on (`queryFn: api.data.leads.list`):
+ * them: each `<RunForm workflow="…" />` and each use of `api`, both imported from `sanoma/site`,
+ * called or passed on (`queryFn: api.data.leads.list`):
  * `api.<name>` and `api.<name>.<method>` are a workflow, `api.data.<collection>.<op>` a collection,
  * and `api.<vendor>.<resource>.<op>` an operation. A name that is not written out (a variable, a
  * template with holes, a computed member) is skipped, as is a use through a namespace import or a
  * destructured `api`. A call to what `description` does not have, or to an operation a page may
- * not call directly, is a problem.
+ * not call directly, is a problem. So is a `login` in `site.ts` that does not name one of
+ * `connectors.logins` (the vendors whose connector has a login half) on a public site. Given the
+ * company's `policies` (undefined while they have problems, which refuse every call), so is a
+ * public site's start or direct call that no company `permit` could let a visitor make
+ * (`visitorPermits`): one for `anonymous`, or on a site with a login, one for `anonymous` or the
+ * `visitors`, whatever its conditions. Whatever the policies, so is a public site's call of a
+ * built-in workflow, and its read of a workflow's runs but `.result`, which `callApi` refuses a visitor.
  */
 export function readSites(
   root: string | undefined,
   description: Pick<ConfigDescription, "workflows" | "collections" | "ops">,
+  connectors: SiteConnectors,
+  policies?: readonly CedarPolicySource[],
 ): SiteEntry[] {
   if (root === undefined) return [];
   const dir = join(root, "sites");
@@ -80,6 +113,40 @@ export function readSites(
   const ops = new Map(description.ops.map((op) => [op.id, op]));
   // A workflow's api name to its name: two of one api name are a problem on the workflows.
   const byApiName = new Map(description.workflows.map((wf) => [apiNameOf(wf.name), wf.name]));
+  const permits = policies && visitorPermits(policies);
+
+  /**
+   * Why a visitor's `call`, which exists, is certainly refused on a public site that has `login`:
+   * as `callApi` refuses it whatever the policy says, or as no permit could allow it.
+   */
+  const refused = (call: SiteCall, login: string | undefined): string | undefined => {
+    const why = `a visitor's call to ${KIND_NAMES[call.kind]} "${call.target}" is refused`;
+    let action: string;
+    let group: string;
+    if (call.kind === "workflow") {
+      if (BUILT_IN_WORKFLOWS.has(call.target)) return `${why}: a visitor may not start the runtime's own workflows`;
+      if (call.method === "result") return undefined;
+      if (call.method !== undefined && call.method !== "start") {
+        return `${why}: a visitor reads only the result of a run it started`;
+      }
+      [action, group] = [`${WORKFLOW_ACTION}${call.target}`, START];
+    } else {
+      action = call.kind === "op" ? call.target : `${DATA_VENDOR}.${call.target}.${call.method}`;
+      const op = ops.get(action);
+      if (!op) return undefined;
+      group = `effect:${op.effect}`;
+    }
+    if (!permits) return undefined;
+    const [scopes, principal] =
+      login === undefined
+        ? [[ANONYMOUS], `== Sanoma::Principal::"${ANONYMOUS}"`]
+        : [[ANONYMOUS, VISITORS], `in Sanoma::Group::"${VISITORS}"`];
+    if (permits(new Set(scopes), action, group)) return undefined;
+    return (
+      `${why}: no permit in policies/ names ${scopes.join(" or ")} for ${action}. ` +
+      `Add: permit (principal ${principal}, action == Sanoma::Action::"${action}", resource);`
+    );
+  };
 
   /** A call as written, resolved as the app's `callApi` resolves it, with why it would fail. */
   const resolve = ({ kind, name, via, ...at }: Written): { call: SiteCall; problem?: string } => {
@@ -110,12 +177,17 @@ export function readSites(
         const file = readSource(path);
         return typeof file === "string" ? [] : usesIn(file, relative(root, path).split(sep).join("/")).map(resolve);
       });
-      const title = titleOf(join(dir, name, "site.ts"));
+      const siteFile = `sites/${name}/site.ts`;
+      const { problems: optionProblems, ...options } = siteOptionsOf(join(root, siteFile), connectors);
       const calls = resolved.map((r) => r.call);
-      const problems = resolved.flatMap(({ call: { file, line, column }, problem }) =>
-        problem === undefined ? [] : [{ file, line, column, message: problem }],
-      );
-      return { name, ...(title !== undefined && { title }), calls, problems };
+      const problems = [
+        ...resolved.flatMap(({ call, problem }) => {
+          const message = problem ?? (options.public ? refused(call, options.login) : undefined);
+          return message === undefined ? [] : [{ file: call.file, line: call.line, column: call.column, message }];
+        }),
+        ...optionProblems.map((p) => ({ file: siteFile, ...p })),
+      ];
+      return { name, ...options, calls, problems };
     });
 }
 
@@ -125,7 +197,7 @@ type Written = Omit<SiteCall, "target"> & { name: string };
 /** The uses in one file, in its order. */
 function usesIn({ program, at }: SourceFile, file: string): Written[] {
   const api = importedAs(program, SITE_SOURCES, "api");
-  const runForm = importedAs(program, UI_SOURCES, "RunForm");
+  const runForm = importedAs(program, SITE_SOURCES, "RunForm");
   if (!api.size && !runForm.size) return [];
   const found: Omit<Written, "page">[] = [];
   let page: string | undefined;
@@ -156,7 +228,7 @@ function usesIn({ program, at }: SourceFile, file: string): Written[] {
 }
 
 /** What a member path on `api` names; undefined for a path on anything else, a name not written out, or no name. */
-function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" | "name"> | undefined {
+function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" | "name" | "method"> | undefined {
   const path: string[] = [];
   let node = member;
   while (node?.type === "MemberExpression") {
@@ -166,10 +238,12 @@ function apiPath(member: Node, api: ReadonlySet<string>): Pick<Written, "kind" |
     node = unwrap(node.object);
   }
   if (node?.type !== "Identifier" || !api.has(node.name)) return undefined;
-  const [first, second] = path as [string, ...string[]];
-  if (first === DATA_VENDOR) return path.length === 3 ? { kind: "collection", name: second! } : undefined;
+  const [first, second, third] = path as [string, ...string[]];
+  if (first === DATA_VENDOR)
+    return path.length === 3 ? { kind: "collection", name: second!, method: third } : undefined;
   if (path.length === 3) return { kind: "op", name: path.join(".") };
-  return path.length <= 2 ? { kind: "workflow", name: first } : undefined;
+  if (path.length > 2) return undefined;
+  return { kind: "workflow", name: first, ...(second !== undefined && { method: second }) };
 }
 
 /** The local names `imported` has in the file, imported as a value from one of `sources`. */
@@ -187,22 +261,80 @@ function importedAs(program: Node, sources: ReadonlySet<string>, imported: strin
   return names;
 }
 
-/** A site's title: the string `title` its `site.ts` exports by default through `defineSite`. */
-function titleOf(path: string): string | undefined {
+/** The connectors a site's `login` is checked against: the config's vendors, and those with a login half. */
+type SiteConnectors = { vendors: ReadonlySet<string>; logins: ReadonlySet<string> };
+
+/** A property of an object literal that is written out: not a spread, its name not computed. */
+const isWritten = (p: Node) => p.type === "Property" && !p.computed;
+
+/** What `site.ts` that `sanoma` cannot read without running it is told. */
+const unread = (what: string, as: string) => `${what} is read without running site.ts: write it as ${as}`;
+
+/**
+ * What `site.ts` says of its site, read without running it, and what is wrong there: its default
+ * export must be `defineSite({ … })` written out, so it can be read at all; then `title` when it is
+ * a string, `public` and `login`, which must be literals. `login` is kept as written; one on a
+ * site that is not public, or naming no connector of the config with a login half, is a problem.
+ */
+function siteOptionsOf(
+  path: string,
+  connectors: SiteConnectors,
+): Pick<SiteEntry, "title" | "public" | "login"> & { problems: LintProblem[] } {
   const file = readSource(path);
-  if (typeof file === "string") return undefined;
-  const defineSite = importedAs(file.program, SITE_SOURCES, "defineSite");
-  const exported = file.program.body.find((s: Node) => s.type === "ExportDefaultDeclaration")?.declaration;
-  const call = unwrap(exported);
+  if (typeof file === "string") return { problems: [] };
+  const problems: LintProblem[] = [...file.problems];
+  const problem = (at: Node, message: string) => void problems.push({ ...file.at(at.start), message });
+  const exported = file.program.body.find((s: Node) => s.type === "ExportDefaultDeclaration");
+  if (!exported) return { problems };
+  const call = unwrap(exported.declaration);
   const callee = unwrap(call?.callee);
   const options = unwrap(call?.arguments?.[0]);
-  if (call?.type !== "CallExpression" || callee?.type !== "Identifier" || !defineSite.has(callee.name))
+  const defineSite = importedAs(file.program, SITE_SOURCES, "defineSite");
+  // Anything not written out (a variable, a spread, a computed key) could make the site public unseen.
+  const written =
+    call?.type === "CallExpression" &&
+    callee?.type === "Identifier" &&
+    defineSite.has(callee.name) &&
+    (options === undefined || options.type === "ObjectExpression");
+  if (!written) {
+    problem(
+      exported,
+      unread("its default export", '`defineSite({ … })` from "sanoma/site", its options an object literal'),
+    );
+    return { problems };
+  }
+  for (const p of options?.properties ?? []) {
+    if (!isWritten(p)) problem(p, unread("each of `defineSite`'s options", "a property with its name"));
+  }
+  // The last of a name, as the object it makes has.
+  const property = (name: string): Node =>
+    options?.properties.findLast((p: Node) => isWritten(p) && keyName(p.key) === name);
+
+  const title = stringValue(property("title")?.value);
+  const publicAt = property("public");
+  const flag = unwrap(publicAt?.value);
+  const isPublic = flag?.type === "Literal" && flag.value === true;
+  const publicUnread = publicAt !== undefined && !(flag?.type === "Literal" && typeof flag.value === "boolean");
+  if (publicUnread) problem(publicAt, unread("`public`", "`true` or `false`"));
+
+  const loginAt = property("login");
+  const login = stringValue(loginAt?.value);
+  const loginProblem = (): string | undefined => {
+    if (login === undefined) return unread("`login`", "a string");
+    // When `public` is what is wrong, it is said there.
+    if (!isPublic && !publicUnread) return "a login is for a public site: add `public: true`, or remove `login`";
+    if (!connectors.vendors.has(login)) return `login names "${login}", which is not a connector in sanoma.config.ts`;
+    if (!connectors.logins.has(login)) return `login names "${login}", whose connector has no login half`;
     return undefined;
-  if (options?.type !== "ObjectExpression") return undefined;
-  const title = options.properties.find(
-    (p: Node) => p.type === "Property" && !p.computed && keyName(p.key) === "title",
-  );
-  return stringValue(title?.value);
+  };
+  const message = loginAt && loginProblem();
+  if (message) problem(loginAt, message);
+  return {
+    ...(title !== undefined && { title }),
+    ...(isPublic && { public: true as const }),
+    ...(login !== undefined && { login }),
+    problems,
+  };
 }
 
 /**

package/src/vendor-info.ts

@@ -0,0 +1,53 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import type { VendorInfo } from "./op.ts";
+import { upFrom } from "./paths.ts";
+
+/** A logo file's path in the package: relative, never out of it (`..`), an SVG. */
+const LogoFile = z.string().regex(/^(?!\/)(?!.*\.\.)[\w./-]+\.svg$/, "a relative path to an .svg file in the package");
+
+/**
+ * The `sanoma` field of a connector's package.json: the vendor's name and its logo files, beside
+ * package.json. The app reads the same field from npm to list connectors not installed.
+ */
+export const SanomaPackageField = z.object({
+  title: z.string().min(1),
+  logo: LogoFile.optional(),
+  logoDark: LogoFile.optional(),
+});
+
+/**
+ * A connector's `VendorInfo`, read from its own package.json, the one place it is written: the
+ * package's `name` and `homepage`, and the `sanoma` field's `title` and logo files, such as
+ * `"sanoma": { "title": "Ghost", "logo": "logo.svg", "logoDark": "logo-dark.svg" }`. The app
+ * lists connectors not installed from the same field on npm. `moduleUrl` is any module of the
+ * package, whose nearest package.json is read: `vendorInfo(import.meta.url)`.
+ */
+export function vendorInfo(moduleUrl: string | URL): VendorInfo {
+  const from = dirname(fileURLToPath(moduleUrl));
+  const root = upFrom(from, (dir) => (existsSync(join(dir, "package.json")) ? dir : undefined)) ?? from;
+  const read = (path: string) => readFileSync(join(root, path), "utf8").trim();
+  const pkg = JSON.parse(read("package.json")) as { name: string; homepage?: string; sanoma?: unknown };
+  const field = SanomaPackageField.safeParse(pkg.sanoma);
+  if (!field.success) {
+    throw new Error(
+      `${pkg.name}: package.json needs a "sanoma" field with a title, and logos as .svg paths in the package: ${z.prettifyError(field.error)}`,
+    );
+  }
+  const { title, logo, logoDark } = field.data;
+  const svg = (path: string) => {
+    try {
+      return read(path);
+    } catch {
+      throw new Error(`${pkg.name}: the "sanoma" field's logo ${path} is not in the package`);
+    }
+  };
+  return {
+    title,
+    ...(logo && { logo: { svg: svg(logo), ...(logoDark && { dark: svg(logoDark) }) } }),
+    package: pkg.name,
+    ...(pkg.homepage && { homepage: pkg.homepage }),
+  };
+}

package/src/version.ts

@@ -5,8 +5,10 @@ import { dirname, join } from "node:path";
 import { jsonSchemaOf, opIdsOf, type WorkflowDefinition } from "./define.ts";
 import { upFrom } from "./paths.ts";
 
-/** This package's version. A unit test keeps it equal to package.json. */
-export const RUNTIME_VERSION = "0.4.1";
+/** This package's version, from its package.json: one level above `src/` and `dist/` alike. */
+export const RUNTIME_VERSION = (
+  JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")) as { version: string }
+).version;
 
 /**
  * The sequence of DBOS calls the runtime makes around each `ctx` call: policy step, approval