@intentius/chant-lexicon-cedar 0.44.9 → 0.44.12

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/serialize.ts

@@ -207,3 +207,40 @@ export function serializeDogwood(entities: Map<string, Declarable>): DogwoodSeri
 
   return { files, warnings };
 }
+
+/** One declared temporal policy, resolved: chant name, policy id, walked props. */
+export interface DogwoodPolicyRecord {
+  /** The chant entity name — the export name on the `*.ts` file. */
+  name: string;
+  /** The policy id, as it appears in `@id(…)`. */
+  id: string;
+  /** Props with references resolved, ready for `renderTemporalPolicyText`. */
+  props: Record<string, unknown>;
+}
+
+/**
+ * Every `Dogwood::TemporalPolicy` in a build, with references walked and ids
+ * resolved — the temporal counterpart of `cedarPolicyRecords` (#1660).
+ *
+ * `serializeDogwood` above renders whole *files*; the AgentCore embedding needs
+ * the policies one at a time, because `AWS::BedrockAgentCore::Policy` carries a
+ * single statement and `EnforcementMode` is set per policy. Both paths walk
+ * references through the same visitor, so a scope that names another declared
+ * entity resolves identically whichever one rendered it.
+ */
+export function dogwoodPolicyRecords(entities: Map<string, Declarable>): DogwoodPolicyRecord[] {
+  const entityNames = new Map<Declarable, string>();
+  for (const [name, entity] of entities) {
+    entityNames.set(entity, name);
+  }
+
+  const records: DogwoodPolicyRecord[] = [];
+  for (const [name, entity] of entities) {
+    if (isPropertyDeclarable(entity)) continue;
+    if (entity.entityType !== DOGWOOD_POLICY_TYPE) continue;
+
+    const props = walkValue(getProps(entity), entityNames, dogwoodVisitor) as Record<string, unknown>;
+    records.push({ name, id: resolvePolicyId(name, props), props });
+  }
+  return records;
+}

package/src/dogwood/trace.test.ts

@@ -0,0 +1,231 @@
+/**
+ * Trace construction (#1661).
+ *
+ * The line grammar is #1657 §6, read from `interpreter/log_parse.rs` at the
+ * pinned SHA. The tests that matter most are not the rendering ones — they are
+ * the two traps, because both produce a *green* replay rather than a failing
+ * one: a field in only one bag, and an action name that is not fully
+ * qualified.
+ */
+import { describe, expect, test } from "vitest";
+import {
+  auditTrace,
+  decimalValue,
+  entityRef,
+  rawValue,
+  renderTrace,
+  renderTraceLine,
+  renderTraceValue,
+  traceEntity,
+  traceEvent,
+  traceFixture,
+} from "./trace";
+
+const ALICE = 'Drupe::OAuthUser::"alice"';
+const GATEWAY = 'Drupe::Gateway::"gw1"';
+
+function login(over: Partial<Parameters<typeof traceEvent>[0]> = {}) {
+  return traceEvent({
+    timestamp: 0,
+    action: 'Drupe::Action::"Login"',
+    scope: { principal: ALICE, resource: GATEWAY },
+    context: { input: { user: "alice" } },
+    record: { callerPrincipal: entityRef(ALICE), requestId: "u1" },
+    ...over,
+  });
+}
+
+// ── The line grammar ───────────────────────────────────────────────
+
+describe("renderTraceLine", () => {
+  test("renders the envelopes in the one order the parser accepts", () => {
+    const line = renderTraceLine(
+      traceEvent({
+        timestamp: 0,
+        action: 'Drupe::Action::"Login"',
+        scope: { principal: ALICE, resource: GATEWAY },
+        entities: [traceEntity(ALICE, { id: "alice" }, ['Drupe::Gateway::"gw1"'])],
+        context: { input: { user: "alice" } },
+        record: { requestId: "u1" },
+      }),
+    );
+
+    expect(line).toBe(
+      `@0 scope(principal: ${ALICE}, resource: ${GATEWAY}) ` +
+        `entities(${ALICE}: { id: "alice" } in [${GATEWAY}]) ` +
+        `request_context(input: { user: "alice" }) ` +
+        `Drupe::Action::"Login"::request(input: { user: "alice" }, requestId: "u1")`,
+    );
+  });
+
+  test("every envelope is optional", () => {
+    const line = renderTraceLine({
+      timestamp: 42,
+      action: 'Drupe::Action::"Read"',
+      kind: "response",
+      record: { requestId: "u9" },
+    });
+    expect(line).toBe(`@42 Drupe::Action::"Read"::response(requestId: "u9")`);
+  });
+
+  test("a whole trace is one event per line, newline-terminated", () => {
+    const text = renderTrace([login(), login({ timestamp: 10, kind: "response" })]);
+    expect(text.split("\n")).toHaveLength(3);
+    expect(text.endsWith("\n")).toBe(true);
+  });
+});
+
+describe("values", () => {
+  test("Cedar surface forms, by JS type", () => {
+    expect(renderTraceValue("a")).toBe('"a"');
+    expect(renderTraceValue(7)).toBe("7");
+    expect(renderTraceValue(true)).toBe("true");
+    expect(renderTraceValue([1, "a"])).toBe('[1, "a"]');
+    expect(renderTraceValue({ a: 1 })).toBe("{ a: 1 }");
+  });
+
+  test("an entity reference renders unquoted", () => {
+    expect(renderTraceValue(entityRef(ALICE))).toBe(ALICE);
+  });
+
+  test("a decimal keeps its scale, which a JS number cannot", () => {
+    expect(renderTraceValue(decimalValue("1.50"))).toBe("1.50");
+    // The failure mode this exists to prevent: 1.50 as a number is 1.5.
+    expect(() => renderTraceValue(1.5)).toThrow(/decimalValue/);
+  });
+
+  test("raw text passes through, for shapes this module has no type for", () => {
+    expect(renderTraceValue(rawValue("ip(\"10.0.0.1\")"))).toBe('ip("10.0.0.1")');
+  });
+
+  test("a value containing // survives, because the format has no comments", () => {
+    expect(renderTraceValue("https://example.test/a")).toBe('"https://example.test/a"');
+  });
+
+  test("quotes and backslashes are escaped, not dropped", () => {
+    expect(renderTraceValue('a "b" \\ c')).toBe('"a \\"b\\" \\\\ c"');
+  });
+});
+
+// ── Trap 1: the action must be fully qualified ─────────────────────
+
+describe("fully-qualified actions", () => {
+  test("a short action name is rejected at construction", () => {
+    // The trap: a bare name leaves every temporal predicate unmatched while
+    // Cedar still authorizes, so the replay is green and tested nothing.
+    expect(() => traceEvent({ timestamp: 0, action: "Transfer", record: {} })).toThrow(
+      /fully qualified/,
+    );
+    expect(() => traceEvent({ timestamp: 0, action: '"Transfer"', record: {} })).toThrow(
+      /fully qualified/,
+    );
+  });
+
+  test("so is a short entity reference, in scope or in value position", () => {
+    expect(() => entityRef("alice")).toThrow(/fully qualified/);
+    expect(() =>
+      traceEvent({
+        timestamp: 0,
+        action: 'Drupe::Action::"Read"',
+        scope: { principal: "alice", resource: GATEWAY },
+        record: {},
+      }),
+    ).toThrow(/fully qualified/);
+  });
+});
+
+// ── Trap 2: both bags ──────────────────────────────────────────────
+
+describe("both-bag population", () => {
+  test("a context group is written to the envelope AND the logged record", () => {
+    const event = login();
+    expect(event.requestContext).toEqual({ input: { user: "alice" } });
+    expect(event.record).toMatchObject({ input: { user: "alice" } });
+  });
+
+  test("record-only fields stay out of the Cedar request", () => {
+    const event = login();
+    expect(event.requestContext).not.toHaveProperty("requestId");
+    expect(event.record).toHaveProperty("requestId");
+  });
+
+  test("the weaker forms exist, but have to be typed out", () => {
+    const recordOnly = login({ bags: "record-only" });
+    expect(recordOnly.requestContext).toBeUndefined();
+    expect(recordOnly.record).toHaveProperty("input");
+
+    const contextOnly = login({ bags: "context-only" });
+    expect(contextOnly.requestContext).toHaveProperty("input");
+    expect(contextOnly.record).not.toHaveProperty("input");
+  });
+});
+
+describe("auditTrace", () => {
+  test("a trace built the default way has nothing to report", () => {
+    expect(auditTrace([login(), login({ timestamp: 10 })])).toEqual([]);
+  });
+
+  test("a record-only decision event is a single-bag finding", () => {
+    const issues = auditTrace([login({ bags: "record-only" })]);
+    expect(issues.map((i) => i.kind)).toContain("no-request-context");
+  });
+
+  test("a context-only decision event is a single-bag finding", () => {
+    const issues = auditTrace([login({ bags: "context-only" })]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0].kind).toBe("single-bag");
+    expect(issues[0].message).toMatch(/temporal predicates over input\.\* silently miss/);
+  });
+
+  test("a history-only event needs no request context — it never becomes one", () => {
+    // `response` does not decide under the default event schema, so an absent
+    // envelope there is not a weakening. Only the deciding kinds are held to it.
+    const historyOnly = traceEvent({
+      timestamp: 0,
+      action: 'Drupe::Action::"Login"',
+      kind: "response",
+      bags: "record-only",
+      context: { input: { user: "alice" } },
+      record: { requestId: "u1" },
+    });
+    expect(auditTrace([historyOnly])).toEqual([]);
+    // …but say `response` decides, and it is held to the same bar.
+    expect(auditTrace([historyOnly], { decisionKinds: ["response"] })).not.toEqual([]);
+  });
+
+  test("an out-of-order timestamp is reported — history accumulates in file order", () => {
+    const issues = auditTrace([login({ timestamp: 10 }), login({ timestamp: 0 })]);
+    expect(issues.map((i) => i.kind)).toEqual(["out-of-order"]);
+  });
+
+  test("an event that logs nothing can match no predicate", () => {
+    const empty = traceEvent({
+      timestamp: 0,
+      action: 'Drupe::Action::"Read"',
+      context: { input: { user: "alice" } },
+      bags: "context-only",
+    });
+    expect(auditTrace([empty]).map((i) => i.kind).sort()).toEqual(["empty-record", "single-bag"]);
+  });
+});
+
+describe("traceFixture", () => {
+  test("hands back the text when the trace is honest", () => {
+    const fixture = traceFixture([login(), login({ timestamp: 10 })]);
+    expect(fixture.issues).toEqual([]);
+    expect(fixture.text.split("\n").filter(Boolean)).toHaveLength(2);
+  });
+
+  test("refuses a fixture that would weaken its own replay", () => {
+    expect(() => traceFixture([login({ bags: "context-only" })])).toThrow(/weaken its own replay/);
+  });
+
+  test("…unless the weakening is named, which is the point of naming it", () => {
+    const fixture = traceFixture([login({ bags: "context-only" })], { allow: ["single-bag"] });
+    expect(fixture.issues.map((i) => i.kind)).toEqual(["single-bag"]);
+  });
+
+  test("the error names the allow-list entry that would silence it", () => {
+    expect(() => traceFixture([login({ bags: "context-only" })])).toThrow(/allow: \["single-bag"\]/);
+  });
+});