@sanoma-ai/workflows 0.0.0-stage → 0.2.0

package/src/plugin.ts

@@ -0,0 +1,37 @@
+import { readDataFile } from "./datafile.ts";
+
+// An oxlint JS plugin with one rule, `sanoma/data-file`: the data-file subset `readResources`
+// reads, the same check as `lintResources`, on the tree oxlint has already parsed. The
+// package's `oxlint.json` turns it on for `resources/**`. Typed here by the little it uses, so
+// the package needs no oxlint types.
+
+interface Context {
+  filename: string;
+  report(diagnostic: { message: string; node: { range: [number, number] } }): void;
+}
+
+const plugin = {
+  meta: { name: "sanoma" },
+  rules: {
+    "data-file": {
+      meta: {
+        type: "problem",
+        docs: {
+          description:
+            "A data file under resources/ holds only imports, `export const <name> = <vendor>.<type>({ … })` with literal fields, and `export default [ … ]`",
+        },
+      },
+      create(context: Context) {
+        return {
+          Program(program: unknown) {
+            for (const { start, end, message } of readDataFile(program, context.filename).problems) {
+              context.report({ message, node: { range: [start, end] } });
+            }
+          },
+        };
+      },
+    },
+  },
+};
+
+export default plugin;

package/src/policy.ts

@@ -0,0 +1,139 @@
+import { z } from "zod";
+import { type ApprovalState, Approver, Covers, type Principal, sameApprover } from "./define.ts";
+import type { Effect, Op } from "./op.ts";
+
+/** An operation as a policy sees it: plain data, without its schemas. */
+export type PolicyOp = Pick<Op, "id" | "vendor" | "resource" | "name" | "effect">;
+
+/**
+ * An operation as a policy sees it, for a `PolicyCall`: what the runtime passes, so a policy
+ * test can build a call from the connector, `{ op: policyOpOf(shop.order.refund), ... }`.
+ */
+export const policyOpOf = ({ id, vendor, resource, name, effect }: Op): PolicyOp => ({
+  id,
+  vendor,
+  resource,
+  name,
+  effect,
+});
+
+/** What a policy sees for each operation a run calls. Plain data, so a test can build one by hand. */
+export interface PolicyCall {
+  op: PolicyOp;
+  /** The same as `op.effect`. */
+  effect: Effect;
+  /** The resource instance the call acts on, from the operation's `target`, when it declares one. */
+  target?: string;
+  /** The operation's input, already checked against its schema. */
+  input: unknown;
+  /** Who started the run. */
+  actor: Principal;
+  /**
+   * The run so far: a copy of its approvals, including those the policy asked for earlier.
+   * A policy request has `requestedBy: "policy"` and the `op` it held.
+   */
+  run: { id: string; workflow: string; approvals: readonly ApprovalState[] };
+}
+
+/**
+ * A policy's answer. `reasons` say why, for whoever reads the ledger; they change nothing
+ * about what happens to the call.
+ */
+export type Decision =
+  | { kind: "allow"; reasons?: string[] }
+  | { kind: "deny"; reason: string; reasons?: string[] }
+  | ApproveDecision;
+
+/**
+ * Hold the call until the approver decides: a person's id, or `{ group }` for anyone in it.
+ * The approval covers the held operation, and `covers` adds others, so a policy can let their
+ * later calls through once it is approved.
+ */
+interface ApproveDecision {
+  kind: "approve";
+  approver: Approver;
+  title?: string;
+  covers?: Op[];
+}
+
+const ReasonList = z.array(z.string(), { error: "reasons must be a list of strings" }).optional();
+
+/**
+ * Checks a policy's answer. Parsing also copies it, so nothing else the policy returned is kept,
+ * and turns `covers` into op ids.
+ */
+export const DecisionSchema = z.discriminatedUnion(
+  "kind",
+  [
+    z.object({ kind: z.literal("allow"), reasons: ReasonList }),
+    z.object({ kind: z.literal("deny"), reason: z.string({ error: "deny needs a reason" }), reasons: ReasonList }),
+    z.object({
+      kind: z.literal("approve"),
+      approver: Approver,
+      title: z.string({ error: "the title must be a string" }).optional(),
+      covers: Covers,
+    }),
+  ],
+  { error: "not a decision" },
+);
+
+/**
+ * A decision as checked and as the ledger records it: `covers` by op id, and the `version` of
+ * the policy that made it, when it has one.
+ */
+export type RecordedDecision = z.output<typeof DecisionSchema> & { policyVersion?: string };
+
+export const allow = (reasons?: string[]): Decision =>
+  reasons === undefined ? { kind: "allow" } : { kind: "allow", reasons };
+export const deny = (reason: string, reasons?: string[]): Decision =>
+  reasons === undefined ? { kind: "deny", reason } : { kind: "deny", reason, reasons };
+
+/** Holds the call for `approver`. `covers` lists other operations the approval also stands for. */
+export function approve(approver: Approver, { title, covers }: { title?: string; covers?: Op[] } = {}): Decision {
+  return {
+    kind: "approve",
+    approver,
+    ...(title === undefined ? {} : { title }),
+    ...(covers === undefined ? {} : { covers }),
+  };
+}
+
+/**
+ * Decides whether a run may make an operation call: allow it, deny it (the run fails),
+ * or hold it until someone approves. Runs are replayed after a restart, so a policy must
+ * decide the same way every time from the call alone: no clock, randomness or network.
+ * `lintWorkflow` checks a policy file for these too. Each decision is recorded once made,
+ * and a replay reuses it, but a call interrupted before that is decided again. A policy
+ * must not have side effects.
+ */
+export type Policy = ((call: PolicyCall) => Decision | Promise<Decision>) & {
+  /** Names this version of the policy, from `definePolicy(fn, { version })`. */
+  readonly version?: string;
+};
+
+/** A policy, optionally named with a version so a reader can tell which rules decided a call. */
+export function definePolicy(
+  policy: (call: PolicyCall) => Decision | Promise<Decision>,
+  options: { version?: string } = {},
+): Policy {
+  if (typeof policy !== "function") throw new Error("definePolicy expects a function of the call");
+  if (options.version !== undefined && (typeof options.version !== "string" || !options.version.trim())) {
+    throw new Error("definePolicy: `version` must be a non-empty string");
+  }
+  const defined = (call: PolicyCall) => policy(call);
+  return Object.freeze(options.version === undefined ? defined : Object.assign(defined, { version: options.version }));
+}
+
+/** Allows every operation call. A config says so explicitly: `policy: allowAll`. */
+export const allowAll: Policy = definePolicy(() => allow());
+
+/**
+ * True when an approval in the run was approved, covers the operation, and was addressed to
+ * `approver`. Check all three: a workflow can request an approval covering any operation from
+ * anyone it names, so an approval's `covers` alone does not say the right person approved.
+ */
+export function approvedFor(approvals: readonly ApprovalState[], opId: string, approver: Approver): boolean {
+  return approvals.some(
+    (a) => a.status === "approved" && a.covers.includes(opId) && sameApprover(a.approver, approver),
+  );
+}