@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

package/src/dogwood/replay-op.ts

@@ -0,0 +1,242 @@
+/**
+ * `PolicyReplayOp` — replay a declared `.dw` set against a recorded event
+ * trace and report divergence (#1661, epic #1646).
+ *
+ * Shape follows `WorkflowAuditOp`: an observe-dial Op whose last phase is a
+ * finding mode (`report | issue | pull-request`). What it observes is not a
+ * moving upstream but a moving *history* — a policy set that was correct
+ * against last week's traffic can decide differently against this week's, and
+ * the deterministic build cannot see that.
+ *
+ * ## Packaging: the composite ships from cedar, not from temporal
+ *
+ * `WorkflowAuditOp` and `PipelineAuditOp` live in the temporal lexicon because
+ * they hand back a `TemporalSchedule` alongside the Op, and that resource is
+ * temporal's. This composite hands back an Op and nothing else, so it has no
+ * reason to reach across — it imports `@intentius/chant/op` only, exactly as
+ * the fly lexicon's `flyDeploy` composite does. cedar therefore keeps zero
+ * runtime dependency on `@intentius/chant-lexicon-temporal`.
+ *
+ * The scheduled form is a two-line project-side pairing rather than a config
+ * flag, and that is the deliberate cost of the decision:
+ *
+ * ```ts
+ * import { TemporalSchedule } from "@intentius/chant-lexicon-temporal";
+ *
+ * export const { op } = PolicyReplayOp({ name: "policy-replay", … });
+ * export const schedule = new TemporalSchedule({
+ *   scheduleId: "policy-replay-schedule",
+ *   spec: { cronExpressions: ["0 6 * * *"] },
+ *   action: { workflowType: "policyReplayWorkflow", taskQueue: "policy-replay" },
+ * });
+ * ```
+ *
+ * A project that wants that already installs the temporal lexicon; a project
+ * that only wants `chant run policy-replay` on the local executor should not
+ * have to. `examples/policy-replay` is the worked recipe for both.
+ *
+ * ## Phases
+ *
+ * ```
+ * Artifacts  chantBuild — emit policies.dw, the .cedarschema and the
+ *            .dwschema the replay reads (skippable when they are checked in)
+ * Replay     dogwoodReplay — run `dogwood replay --format json` over the
+ *            bundle and the trace, write the divergence report
+ * Report     dogwoodReplayReport — read that report and act on the mode
+ * ```
+ *
+ * The report file is the seam between the last two phases, the same way
+ * `dist/fly.json` is the seam between `build:fly` and `flyApply`: Op steps do
+ * not pass return values to one another, so a phase boundary needs an artifact
+ * to be a real boundary rather than a cosmetic one.
+ */
+
+import { Op, activity, build, phase, type ActivityStep, type OpResource } from "@intentius/chant/op";
+import type { PolicyReplayMode, ReplayExpectation } from "./replay-activity";
+
+/** Where the Replay phase writes its report by default. */
+export const DEFAULT_REPLAY_REPORT_PATH = "dist/dogwood-replay.json";
+
+/** Options for {@link dogwoodReplayStep}. Mirrors `DogwoodReplayArgs`. */
+export interface DogwoodReplayStepOpts {
+  policies?: string;
+  policiesPath?: string;
+  policySchema?: string;
+  policySchemaPath?: string;
+  eventSchema?: string;
+  eventSchemaPath?: string;
+  macros?: string;
+  macrosPath?: string;
+  providers?: string;
+  providersPath?: string;
+  trace?: string;
+  tracePath?: string;
+  expect?: readonly ReplayExpectation[];
+  mode?: PolicyReplayMode;
+  binary?: string;
+  cwd?: string;
+  reportPath?: string;
+  profile?: ActivityStep["profile"];
+}
+
+/**
+ * Replay a policy bundle against a trace — the typed twin of `flyApplyStep`.
+ *
+ * Resolves to the `dogwoodReplay` activity by name, which `loadActivities`
+ * binds when the project lists the `cedar` lexicon. Defaults to the
+ * `policyCheck` profile.
+ */
+export const dogwoodReplayStep = (opts: DogwoodReplayStepOpts): ActivityStep => {
+  const { profile, ...args } = opts;
+  return activity("dogwoodReplay", args as Record<string, unknown>, profile ?? "policyCheck");
+};
+
+/** Options for {@link dogwoodReplayReportStep}. */
+export interface DogwoodReplayReportStepOpts {
+  reportPath?: string;
+  mode?: PolicyReplayMode;
+  title?: string;
+  cwd?: string;
+  failOnDivergence?: boolean;
+  profile?: ActivityStep["profile"];
+}
+
+/** Read a written replay report and act on its finding mode. */
+export const dogwoodReplayReportStep = (opts: DogwoodReplayReportStepOpts = {}): ActivityStep => {
+  const { profile, ...args } = opts;
+  return activity("dogwoodReplayReport", args as Record<string, unknown>, profile ?? "fastIdempotent");
+};
+
+/** Options for {@link PolicyReplayOp}. */
+export interface PolicyReplayOpConfig {
+  /** Op name (kebab-case) — the `chant run <name>` target and the task queue base. */
+  name: string;
+  overview?: string;
+  /** Defaults to {@link name}. */
+  taskQueue?: string;
+
+  /**
+   * Directory every relative path below resolves against, and the one the
+   * build script runs in. Default `.`.
+   */
+  path?: string;
+  /**
+   * npm script that emits the `.dw` bundle. Default `build`. Pass `false` when
+   * the artifacts are checked in — the Artifacts phase is then omitted rather
+   * than run as a no-op, so the Op's phase list says what it really does.
+   */
+  buildScript?: string | false;
+
+  /** Emitted `.dw` policy set. Default `dist/policies.dw`. */
+  policiesPath?: string;
+  /** Emitted Cedar action schema. Required by the CLI; default `dist/app.cedarschema`. */
+  policySchemaPath?: string;
+  /** Emitted `.dwschema`, when the project declares one. */
+  eventSchemaPath?: string;
+  /** Emitted macro library, when the project ships one out of line. */
+  macrosPath?: string;
+  /** `providers.json`, with the Rhai inlined under `implementation.script`. */
+  providersPath?: string;
+
+  /** The recorded trace to replay. Required — there is nothing to replay without one. */
+  tracePath: string;
+
+  /** What each decision point must decide. Empty replays and reports verdicts. */
+  expect?: readonly ReplayExpectation[];
+
+  /** What to produce on divergence. Default `report`. */
+  onFinding?: PolicyReplayMode;
+  /** Title for the issue or pull request the finding mode calls for. */
+  title?: string;
+  /**
+   * Fail the Op when the replay diverged. Default false — an observe-dial Op
+   * reports by default, and a red run is a decision the caller makes.
+   */
+  failOnDivergence?: boolean;
+
+  /** Where the Replay phase writes its report. Default {@link DEFAULT_REPLAY_REPORT_PATH}. */
+  reportPath?: string;
+  /** Explicit `dogwood` binary path, for a runner that knows where it built one. */
+  binary?: string;
+}
+
+/** What {@link PolicyReplayOp} hands back. */
+export interface PolicyReplayOpResources {
+  /** The Op — discovered by `chant run <name>`, emitted by `chant build`. */
+  op: InstanceType<typeof OpResource>;
+}
+
+/**
+ * Assemble the replay Op: emit the artifacts, replay them, act on the finding.
+ *
+ * @example
+ * ```typescript
+ * export const { op } = PolicyReplayOp({
+ *   name: "policy-replay",
+ *   tracePath: "trace/read-after-login.log",
+ *   expect: [
+ *     { timestamp: 10, verdict: "allow", determiningRules: [0] },
+ *     { timestamp: 7200, verdict: "deny", note: "the login is two hours stale" },
+ *   ],
+ *   onFinding: "issue",
+ * });
+ * ```
+ */
+export function PolicyReplayOp(config: PolicyReplayOpConfig): PolicyReplayOpResources {
+  const path = config.path ?? ".";
+  const mode = config.onFinding ?? "report";
+  const reportPath = config.reportPath ?? DEFAULT_REPLAY_REPORT_PATH;
+
+  const phases = [];
+
+  if (config.buildScript !== false) {
+    phases.push(phase("Artifacts", [build(path, { script: config.buildScript ?? "build" })]));
+  }
+
+  phases.push(
+    phase("Replay", [
+      {
+        ...dogwoodReplayStep({
+          cwd: path,
+          policiesPath: config.policiesPath ?? "dist/policies.dw",
+          policySchemaPath: config.policySchemaPath ?? "dist/app.cedarschema",
+          ...(config.eventSchemaPath ? { eventSchemaPath: config.eventSchemaPath } : {}),
+          ...(config.macrosPath ? { macrosPath: config.macrosPath } : {}),
+          ...(config.providersPath ? { providersPath: config.providersPath } : {}),
+          tracePath: config.tracePath,
+          ...(config.expect ? { expect: config.expect } : {}),
+          mode,
+          ...(config.binary ? { binary: config.binary } : {}),
+          reportPath,
+        }),
+        // The divergence count as a workflow search attribute, so "show me the
+        // replays that found something" is one filter rather than a log read.
+        outcomeAttribute: { name: "Divergences", from: "findings" },
+      },
+    ]),
+    phase("Report", [
+      dogwoodReplayReportStep({
+        cwd: path,
+        reportPath,
+        mode,
+        ...(config.title ? { title: config.title } : {}),
+        ...(config.failOnDivergence ? { failOnDivergence: true } : {}),
+      }),
+    ]),
+  );
+
+  return {
+    op: Op({
+      name: config.name,
+      overview:
+        config.overview ??
+        "Replay the declared dogwood policy set against a recorded event trace and report divergence",
+      taskQueue: config.taskQueue ?? config.name,
+      searchAttributes: {
+        Audit: "true",
+        Surface: "cedar-dogwood",
+      },
+      phases,
+    }),
+  };
+}

package/src/dogwood/scan.ts

@@ -0,0 +1,287 @@
+/**
+ * Reading the emitted dogwood artifacts back, for the DWD post-synth checks.
+ *
+ * The checks judge the *text*, not the in-memory model, for the same reason
+ * the CED checks judge `policies.cedar.json`: `chant audit` runs over a
+ * checked-in artifact chant did not write, and a wall that only fires on
+ * chant's own output is not a wall. It also means the typed builders and the
+ * walls are independent — DWDC012 catches a windowless `formerly` even though
+ * the builders cannot construct one, because `raw()` and a hand-written `.dw`
+ * both can.
+ *
+ * This is scanning, not parsing. Upstream owns the parser and #1659 owns
+ * shelling to it; what is here is the subset of the surface that answers the
+ * three questions the walls ask, plus enough comment handling not to be fooled
+ * by a commented-out clause.
+ */
+
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { DEFAULT_MAX_WINDOW, windowSeconds, type TimeUnit } from "./window";
+import { DOGWOOD_EVENT_SCHEMA_SUFFIX, DOGWOOD_POLICY_SUFFIX } from "./serialize";
+
+/** One emitted artifact, with everything needed to name it in a finding. */
+export interface DogwoodArtifact {
+  /** The lexicon output it came from. */
+  lexicon: string;
+  /** The filename, which is what a finding points the reader at. */
+  source: string;
+  /** The file's text. */
+  text: string;
+}
+
+/** Every `.dw` policy file in the build output. */
+export function dogwoodPolicyFiles(ctx: PostSynthContext): DogwoodArtifact[] {
+  return filesWithSuffix(ctx, DOGWOOD_POLICY_SUFFIX);
+}
+
+/** Every `.dwschema` event-schema file in the build output. */
+export function dogwoodSchemaFiles(ctx: PostSynthContext): DogwoodArtifact[] {
+  return filesWithSuffix(ctx, DOGWOOD_EVENT_SCHEMA_SUFFIX);
+}
+
+function filesWithSuffix(ctx: PostSynthContext, suffix: string): DogwoodArtifact[] {
+  const found: DogwoodArtifact[] = [];
+  for (const [lexicon, output] of ctx.outputs) {
+    if (typeof output === "string") continue;
+    for (const [filename, content] of Object.entries(output.files ?? {})) {
+      if (typeof content !== "string") continue;
+      if (!filename.endsWith(suffix)) continue;
+      found.push({ lexicon, source: filename, text: content });
+    }
+  }
+  return found;
+}
+
+// ── Comments ──────────────────────────────────────────────────────
+
+/**
+ * Blank out `//` comments, leaving string literals intact.
+ *
+ * String literals stay because a predicate's action id lives inside one
+ * (`Drupe::Action::"Read"`), and blanking those would blind every scan below.
+ * The walk is string-aware in the other direction too: a `//` inside a quoted
+ * value (a URL, say) is not a comment.
+ *
+ * Comment bytes become spaces so every offset in the result still lines up
+ * with the original file.
+ */
+export function blankComments(text: string): string {
+  const out = text.split("");
+  let inString = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < text.length && text[i] !== "\n") {
+        out[i] = " ";
+        i++;
+      }
+    }
+  }
+  return out.join("");
+}
+
+// ── Temporal regions ──────────────────────────────────────────────
+
+/**
+ * The stretches of a `.dw` file that the temporal sub-parser reads: every
+ * `temporal { … }` marker body, and every `def temporal … { … }` macro body.
+ *
+ * Scanning only these is what keeps a Cedar `when { … }` clause from being
+ * mistaken for temporal source — `context.retryWindow == 3` should not read as
+ * a window, and a Cedar attribute named `since` is not the `since` operator.
+ */
+export function temporalRegions(text: string): string[] {
+  const source = blankComments(text);
+  const regions: string[] = [];
+
+  const markers = /\btemporal\s*\{/g;
+  for (let m = markers.exec(source); m !== null; m = markers.exec(source)) {
+    const body = matchedBlock(source, m.index + m[0].length - 1);
+    if (body !== undefined) regions.push(body);
+  }
+
+  const macros = /\bdef\s+temporal\s+[A-Za-z_][A-Za-z0-9_]*\s*\([^)]*\)\s*\{/g;
+  for (let m = macros.exec(source); m !== null; m = macros.exec(source)) {
+    const body = matchedBlock(source, m.index + m[0].length - 1);
+    if (body !== undefined) regions.push(body);
+  }
+
+  return regions;
+}
+
+/** The text between `text[open]` (a `{`) and its matching `}`, or undefined. */
+function matchedBlock(text: string, open: number): string | undefined {
+  let depth = 0;
+  let inString = false;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (ch === "\\") i++;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return text.slice(open + 1, i);
+    }
+  }
+  return undefined;
+}
+
+// ── What the walls ask ────────────────────────────────────────────
+
+/** One `Ns::Action::"Name"::kind` predicate head found in temporal source. */
+export interface TemporalPredicateRef {
+  /** The qualified action, quoted id and all. */
+  action: string;
+  /** The event kind segment after the quoted id. */
+  kind: string;
+}
+
+const PREDICATE = /([A-Za-z_][A-Za-z0-9_]*(?:::[A-Za-z_][A-Za-z0-9_]*)*::"[^"]*")::([A-Za-z_][A-Za-z0-9_]*)/g;
+
+/** Every temporal predicate head in a `.dw` file, in source order. */
+export function scanPredicates(text: string): TemporalPredicateRef[] {
+  const refs: TemporalPredicateRef[] = [];
+  for (const region of temporalRegions(text)) {
+    for (let m = PREDICATE.exec(region); m !== null; m = PREDICATE.exec(region)) {
+      refs.push({ action: m[1], kind: m[2] });
+    }
+    PREDICATE.lastIndex = 0;
+  }
+  return refs;
+}
+
+/** One window literal found in temporal source. */
+export interface WindowRef {
+  /** As written: `48h`. */
+  text: string;
+  seconds: number;
+  /** `within` for an operator's window, `argument` for a bare macro-call interval. */
+  position: "within" | "argument";
+}
+
+const WITHIN_WINDOW = /\bwithin\s+(\d+)([smhd])\b/g;
+/** A bare interval in macro-call argument position: `once(1h, …)`, `f(a, 30m)`. */
+const ARGUMENT_WINDOW = /[(,]\s*(\d+)([smhd])\s*(?=[,)])/g;
+
+/**
+ * Every window literal in a `.dw` file's temporal source.
+ *
+ * Both shapes count against `max_window`: a macro-call interval is the window
+ * a `within ?w` in the macro body resolves to, so `once(48h, …)` looks back
+ * exactly as far as `formerly within 48h` does.
+ */
+export function scanWindows(text: string): WindowRef[] {
+  const windows: WindowRef[] = [];
+  for (const region of temporalRegions(text)) {
+    for (let m = WITHIN_WINDOW.exec(region); m !== null; m = WITHIN_WINDOW.exec(region)) {
+      windows.push(windowRef(m[1], m[2], "within"));
+    }
+    WITHIN_WINDOW.lastIndex = 0;
+    for (let m = ARGUMENT_WINDOW.exec(region); m !== null; m = ARGUMENT_WINDOW.exec(region)) {
+      windows.push(windowRef(m[1], m[2], "argument"));
+    }
+    ARGUMENT_WINDOW.lastIndex = 0;
+  }
+  return windows;
+}
+
+function windowRef(value: string, unit: string, position: WindowRef["position"]): WindowRef {
+  const w = { value: Number(value), unit: unit as TimeUnit };
+  return { text: `${w.value}${w.unit}`, seconds: windowSeconds(w), position };
+}
+
+/**
+ * Every `formerly` / `previous` / `since` that is not followed by a `within`.
+ *
+ * Unrepresentable through the builders — {@link formerly} and its siblings all
+ * take the window as an argument — but reachable through `raw()`, through a
+ * hand-written `.dw`, and through an audit of a file chant never wrote.
+ */
+export function scanWindowlessOperators(text: string): string[] {
+  const found: string[] = [];
+  const pattern = /\b(formerly|previous|since)\b(?!\s+within\b)/g;
+  for (const region of temporalRegions(text)) {
+    for (let m = pattern.exec(region); m !== null; m = pattern.exec(region)) {
+      found.push(m[1]);
+    }
+    pattern.lastIndex = 0;
+  }
+  return found;
+}
+
+// ── The event schema side ─────────────────────────────────────────
+
+/** What a `.dwschema` file says, as far as the walls need to know. */
+export interface EventSchemaFacts {
+  /** Every declared event kind. */
+  kinds: string[];
+  /** The `max_window` directive in seconds, or upstream's 24h default when absent. */
+  maxWindowSeconds: number;
+  /** As written (`30d`), or undefined when the directive is absent. */
+  maxWindowText?: string;
+  /** True when at least one field carries a `pin … = …`. */
+  hasPin: boolean;
+}
+
+const EVENT_DECL = /\bevent\s*<\s*[A-Za-z_][A-Za-z0-9_]*\s*>\s*::\s*([A-Za-z_][A-Za-z0-9_]*)/g;
+const MAX_WINDOW = /\bmax_window\s*=\s*(\d+)([smhd])\b/;
+const PINNED_FIELD = /\bpin\s+[A-Za-z_][A-Za-z0-9_]*\s*:/;
+
+/** Read a `.dwschema` file's declarations. */
+export function readEventSchema(text: string): EventSchemaFacts {
+  const source = blankComments(text);
+
+  const kinds: string[] = [];
+  for (let m = EVENT_DECL.exec(source); m !== null; m = EVENT_DECL.exec(source)) {
+    if (!kinds.includes(m[1])) kinds.push(m[1]);
+  }
+  EVENT_DECL.lastIndex = 0;
+
+  const max = MAX_WINDOW.exec(source);
+  return {
+    kinds,
+    maxWindowSeconds: max
+      ? windowSeconds({ value: Number(max[1]), unit: max[2] as TimeUnit })
+      : windowSeconds(DEFAULT_MAX_WINDOW),
+    maxWindowText: max ? `${max[1]}${max[2]}` : undefined,
+    hasPin: PINNED_FIELD.test(source),
+  };
+}
+
+/**
+ * The look-back cap in force for a build.
+ *
+ * With no emitted schema, `ServiceSchema::defaults()` applies and the cap is
+ * 24h. With several, the tightest one wins — a window legal under one schema
+ * and not another is a window some consumer will reject.
+ */
+export function effectiveMaxWindowSeconds(schemas: EventSchemaFacts[]): { seconds: number; text: string } {
+  if (schemas.length === 0) {
+    return {
+      seconds: windowSeconds(DEFAULT_MAX_WINDOW),
+      text: `${DEFAULT_MAX_WINDOW.value}${DEFAULT_MAX_WINDOW.unit}`,
+    };
+  }
+  let tightest = schemas[0];
+  for (const s of schemas) if (s.maxWindowSeconds < tightest.maxWindowSeconds) tightest = s;
+  return {
+    seconds: tightest.maxWindowSeconds,
+    text: tightest.maxWindowText ?? `${DEFAULT_MAX_WINDOW.value}${DEFAULT_MAX_WINDOW.unit}`,
+  };
+}