@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

package/src/dogwood/event-schema.test.ts

@@ -0,0 +1,218 @@
+/**
+ * Event-schema round trip: typed authoring in, `.dwschema` text out, asserted
+ * against fixtures whose shapes are upstream's.
+ *
+ * The fixtures under `./testdata/` are adapted from
+ * `dogwood-policy/dogwood`'s shipped examples and its bundled default schema
+ * (Apache-2.0; each file carries its provenance in a header comment). They are
+ * not byte copies — upstream aligns field types in columns and chant does not
+ * — so what is pinned here is the surface: the directive, the declarations,
+ * the spreads, the selectors, and where the pins land.
+ */
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+import {
+  concrete,
+  declaredEventKinds,
+  defaultEventSchema,
+  eventDeclaration,
+  eventSchema,
+  field,
+  pinContext,
+  pinPrincipal,
+  pinnedField,
+  principalType,
+  record,
+  renderEventSchema,
+  resourceType,
+  spreadInputs,
+  spreadOutputs,
+} from "./event-schema";
+import { readEventSchema } from "./scan";
+
+const TESTDATA = join(fileURLToPath(new URL(".", import.meta.url)), "testdata");
+const UPSTREAM = "dogwood-policy/dogwood@5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c";
+
+function fixture(name: string): string {
+  return readFileSync(join(TESTDATA, name), "utf-8");
+}
+
+/** The provenance header each fixture carries above the emitted bytes. */
+function attribution(...sources: string[]): string {
+  return [
+    `// Adapted from ${UPSTREAM} (Apache-2.0):`,
+    ...sources.map((s) => `//   ${s}`),
+    "// Upstream's shape; the bytes are what chant's typed builders emit.",
+    "",
+    "",
+  ].join("\n");
+}
+
+// ── The default shape ──────────────────────────────────────────────
+
+describe("the default (pinned) event schema", () => {
+  test("round-trips to upstream's pinned.dwschema shape", () => {
+    expect(fixture("pinned.dwschema")).toBe(
+      attribution("dogwood-language/configuration/event-schemas/pinned.dwschema") +
+        renderEventSchema(defaultEventSchema()),
+    );
+  });
+
+  test("every kind pins callerPrincipal to the deciding request's principal", () => {
+    const text = renderEventSchema(defaultEventSchema());
+    expect(text.match(/pin callerPrincipal: principalType\(A\) = principal,/g)).toHaveLength(3);
+    expect(readEventSchema(text).hasPin).toBe(true);
+  });
+
+  test("request is the deciding kind; response and error are history", () => {
+    const text = renderEventSchema(defaultEventSchema());
+    expect(text).toContain("decision event <A>::request {");
+    expect(text).toContain("\nevent <A>::response {");
+    expect(text).toContain("\nevent <A>::error {");
+    expect(declaredEventKinds(defaultEventSchema())).toEqual(["request", "response", "error"]);
+  });
+
+  test("dropping the pin is a named argument, and says so in the file", () => {
+    const text = renderEventSchema(defaultEventSchema({ pinCallerPrincipal: false }));
+    expect(text).not.toContain("pin callerPrincipal");
+    expect(text).toContain("// Cross-principal: callerPrincipal is NOT pinned");
+    expect(readEventSchema(text).hasPin).toBe(false);
+  });
+});
+
+// ── max_window ─────────────────────────────────────────────────────
+
+describe("the max_window directive", () => {
+  const raised = () =>
+    eventSchema(
+      [
+        eventDeclaration(
+          "request",
+          [
+            spreadInputs(),
+            field("callerPrincipal", principalType()),
+            field("callerResource", resourceType()),
+            field("requestId", concrete("String")),
+          ],
+          { decision: true },
+        ),
+        eventDeclaration("response", [
+          spreadInputs(),
+          spreadOutputs(),
+          field("callerPrincipal", principalType()),
+          field("callerResource", resourceType()),
+          field("requestId", concrete("String")),
+        ]),
+      ],
+      {
+        maxWindow: "30d",
+        comment:
+          "Raises the look-back cap from the 24h default to 30 days. The directive\nmust come first, before any event declaration.\n\nNo pinned field: this schema correlates across principals on purpose.",
+      },
+    );
+
+  test("round-trips to upstream's max_window_raised shape", () => {
+    expect(fixture("max-window-raised.dwschema")).toBe(
+      attribution("dogwood-docs/examples/max_window_raised/event.dwschema") + renderEventSchema(raised()),
+    );
+  });
+
+  test("the directive precedes every declaration, as the grammar requires", () => {
+    const lines = renderEventSchema(raised()).split("\n");
+    const directive = lines.findIndex((l) => l.startsWith("max_window"));
+    const firstEvent = lines.findIndex((l) => l.includes("event <A>::"));
+    expect(directive).toBeGreaterThan(-1);
+    expect(directive).toBeLessThan(firstEvent);
+  });
+
+  test("the scanner reads the cap back out", () => {
+    const facts = readEventSchema(renderEventSchema(raised()));
+    expect(facts.maxWindowText).toBe("30d");
+    expect(facts.maxWindowSeconds).toBe(30 * 86400);
+  });
+
+  test("an absent directive reads back as upstream's 24h default", () => {
+    const facts = readEventSchema(renderEventSchema(defaultEventSchema()));
+    expect(facts.maxWindowText).toBeUndefined();
+    expect(facts.maxWindowSeconds).toBe(24 * 3600);
+  });
+});
+
+// ── Author-defined kinds ───────────────────────────────────────────
+
+describe("author-defined event kinds", () => {
+  const custom = () =>
+    eventSchema(
+      [
+        eventDeclaration("attempt", [spreadInputs(), field("actor", principalType())], { decision: true }),
+        eventDeclaration("outcome", [spreadInputs(), spreadOutputs(), field("actor", principalType())]),
+      ],
+      {
+        comment:
+          "Author-defined event kinds — `attempt` decides, `outcome` is history — and\na renamed injected principal field.",
+      },
+    );
+
+  test("round-trips to upstream's login_attempt_custom_kind shape", () => {
+    expect(fixture("custom-kinds.dwschema")).toBe(
+      attribution("dogwood-docs/examples/login_attempt_custom_kind/event.dwschema") + renderEventSchema(custom()),
+    );
+  });
+
+  test("request/response are conventional, not required", () => {
+    expect(declaredEventKinds(custom())).toEqual(["attempt", "outcome"]);
+    expect(readEventSchema(renderEventSchema(custom())).kinds).toEqual(["attempt", "outcome"]);
+  });
+});
+
+// ── Field forms ────────────────────────────────────────────────────
+
+describe("field forms", () => {
+  test("a record type nests, and its members are addressed as name.member", () => {
+    const text = renderEventSchema(
+      eventSchema([
+        eventDeclaration("request", [
+          spreadInputs(),
+          field("session", record([field("id", concrete("String")), field("tenant", concrete("String"))])),
+        ]),
+      ]),
+    );
+    expect(text).toContain("    session: {\n        id: String,\n        tenant: String,\n    },");
+  });
+
+  test("a context pin renders its dotted path", () => {
+    const text = renderEventSchema(
+      eventSchema([
+        eventDeclaration("request", [pinnedField("tenant", concrete("String"), pinContext("input.tenant"))]),
+      ]),
+    );
+    expect(text).toContain("    pin tenant: String = context.input.tenant,");
+  });
+
+  test("a scope pin may carry an attribute tail", () => {
+    const text = renderEventSchema(
+      eventSchema([
+        eventDeclaration("request", [pinnedField("dept", concrete("String"), pinPrincipal("dept"))]),
+      ]),
+    );
+    expect(text).toContain("    pin dept: String = principal.dept,");
+  });
+
+  test("pinning a whole record is refused — upstream requires a leaf", () => {
+    expect(() => pinnedField("group", record([field("a", concrete("String"))]), pinPrincipal())).toThrow(
+      /must be a leaf/,
+    );
+  });
+
+  test("a duplicated event kind is refused at construction", () => {
+    expect(() =>
+      eventSchema([eventDeclaration("request", []), eventDeclaration("request", [])]),
+    ).toThrow(/declared twice/);
+  });
+
+  test("a schema with no declarations is refused", () => {
+    expect(() => eventSchema([])).toThrow(/at least one event kind/);
+  });
+});

package/src/dogwood/event-schema.ts

@@ -0,0 +1,318 @@
+/**
+ * Typed authoring for the `.dwschema` event-schema DSL.
+ *
+ * The `.dwschema`/`.cedarschema` question the epic flagged was a false alarm
+ * (#1657 §2): they are the two halves of one schema. The required half is the
+ * Cedar action schema (`--policy-schema`); this file is the optional half, the
+ * service side, which says what event *kinds* exist and what fields each one
+ * carries. Upstream's grammar is 136 lines of pest and is purely syntactic —
+ * it never consults an action schema, which is why every declaration is
+ * written against a symbolic action binder `<A>`:
+ *
+ * ```
+ * decision event <A>::request {
+ *     ...inputs(A),
+ *     pin callerPrincipal: principalType(A) = principal,
+ *     callerResource:      resourceType(A),
+ *     requestId:           String,
+ * }
+ * ```
+ *
+ * That symbolic binder is why DWDC010 can check an event *kind* against the
+ * emitted schema but not an action: the schema names no actions at all.
+ *
+ * ## The pin, and why opting out is explicit here
+ *
+ * `ServiceSchema::defaults()` — what runs when no `--event-schema` is passed —
+ * pins `callerPrincipal = principal` on every kind, so every temporal
+ * predicate is correlated to the current request's principal and events from
+ * other principals are invisible. Supplying *any* event schema opts out of the
+ * default wholesale, so a schema emitted without that pin silently widens
+ * every temporal predicate in the policy set to cross-principal.
+ *
+ * {@link defaultEventSchema} therefore carries the pin, and dropping it takes
+ * a named argument (`pinCallerPrincipal: false`) that also stamps a comment
+ * into the emitted file. DWDS010 reports the resulting schema either way, so
+ * the choice is visible in the build and not only in the source.
+ */
+
+import { renderWindow, window, type TemporalWindow, type WindowLike } from "./window";
+
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const TYPE_NAME = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)*$/;
+
+function assertIdent(value: string, what: string): string {
+  if (!IDENT.test(value)) throw new Error(`dogwood: ${what} must be an identifier — got "${value}"`);
+  return value;
+}
+
+// ── Field types ───────────────────────────────────────────────────
+
+/** The four selectors that read from the bound action. */
+export type EventSelector = "inputs" | "outputs" | "principalType" | "resourceType";
+
+/** `principalType(A)`, a nested `{ … }` record, or a concrete Cedar type. */
+export type EventFieldType =
+  | { readonly type: "selector"; readonly selector: EventSelector }
+  | { readonly type: "record"; readonly fields: readonly EventField[] }
+  | { readonly type: "concrete"; readonly name: string };
+
+/** `principalType(A)` — the action's principal entity type. */
+export function principalType(): EventFieldType {
+  return { type: "selector", selector: "principalType" };
+}
+
+/** `resourceType(A)` — the action's resource entity type. */
+export function resourceType(): EventFieldType {
+  return { type: "selector", selector: "resourceType" };
+}
+
+/** `String`, `Long`, `MyApp::OAuthUser` — a concrete (possibly qualified) type. */
+export function concrete(name: string): EventFieldType {
+  if (!TYPE_NAME.test(name)) throw new Error(`dogwood: a field type must be a Cedar type name — got "${name}"`);
+  return { type: "concrete", name };
+}
+
+/** `{ … }` — the named field becomes a group addressed as `name.member`. */
+export function record(fields: EventField[]): EventFieldType {
+  return { type: "record", fields };
+}
+
+// ── Pins ──────────────────────────────────────────────────────────
+
+/**
+ * The right-hand side of a pin: the request-side value the field is forced to
+ * match. `principal`/`resource` (with an optional attribute tail) or a
+ * `context.<path>`.
+ */
+export type PinTarget =
+  | { readonly ref: "principal" | "resource"; readonly attrs: readonly string[] }
+  | { readonly ref: "context"; readonly path: readonly string[] };
+
+/** `= principal`, or `= principal.dept`. */
+export function pinPrincipal(...attrs: string[]): PinTarget {
+  for (const a of attrs) assertIdent(a, "a pin attribute");
+  return { ref: "principal", attrs };
+}
+
+/** `= resource`, or `= resource.owner`. */
+export function pinResource(...attrs: string[]): PinTarget {
+  for (const a of attrs) assertIdent(a, "a pin attribute");
+  return { ref: "resource", attrs };
+}
+
+/** `= context.input.user`. At least one path segment; `context` alone is not a pin. */
+export function pinContext(path: string): PinTarget {
+  const segments = path.split(".");
+  if (segments.length === 0 || segments[0] === "") {
+    throw new Error("dogwood: a context pin needs at least one path segment (context.<field>)");
+  }
+  for (const s of segments) assertIdent(s, "a context pin segment");
+  return { ref: "context", path: segments };
+}
+
+// ── Fields ────────────────────────────────────────────────────────
+
+/** `...inputs(A)` / `...outputs(A)` — splice every field the selector yields. */
+export interface SpreadField {
+  readonly field: "spread";
+  readonly selector: Extract<EventSelector, "inputs" | "outputs">;
+}
+
+/** `[pin] name: <type> [= <pin target>]`. */
+export interface NamedField {
+  readonly field: "named";
+  readonly name: string;
+  readonly type: EventFieldType;
+  readonly pin?: PinTarget;
+}
+
+/** One entry in an event declaration's field list. */
+export type EventField = SpreadField | NamedField;
+
+/** `...inputs(A)`. */
+export function spreadInputs(): SpreadField {
+  return { field: "spread", selector: "inputs" };
+}
+
+/** `...outputs(A)`. */
+export function spreadOutputs(): SpreadField {
+  return { field: "spread", selector: "outputs" };
+}
+
+/** `name: <type>` — an injected field with an explicit type. */
+export function field(name: string, type: EventFieldType): NamedField {
+  return { field: "named", name: assertIdent(name, "a field name"), type };
+}
+
+/**
+ * `pin name: <type> = <target>` — a correlation against the decision request.
+ *
+ * Upstream requires the `pin` prefix and the `= …` clause together, and a
+ * pinned field must be a leaf (never a record type), so both are enforced here
+ * rather than deferred to the parser.
+ */
+export function pinnedField(name: string, type: EventFieldType, target: PinTarget): NamedField {
+  if (type.type === "record") {
+    throw new Error(`dogwood: a pinned field must be a leaf, and "${name}" is a record type`);
+  }
+  return { field: "named", name: assertIdent(name, "a field name"), type, pin: target };
+}
+
+// ── Declarations ──────────────────────────────────────────────────
+
+/** `[decision] event <A>::kind { fields }`. */
+export interface EventDeclaration {
+  /** `request`, `response`, `error`, or anything the author chooses. */
+  readonly kind: string;
+  /** True for the kind that carries the authorization decision. */
+  readonly decision?: boolean;
+  readonly fields: readonly EventField[];
+  /** Emitted as `// …` above the declaration. */
+  readonly comment?: string;
+}
+
+/** One `event` declaration. */
+export function eventDeclaration(
+  kind: string,
+  fields: EventField[],
+  options: { decision?: boolean; comment?: string } = {},
+): EventDeclaration {
+  return { kind: assertIdent(kind, "an event kind"), fields, decision: options.decision, comment: options.comment };
+}
+
+/** A whole `.dwschema` file. */
+export interface EventSchema {
+  /** `max_window = 30d`. Omitted means upstream's 24h default applies. */
+  readonly maxWindow?: TemporalWindow;
+  /** The action binder name, `A` by convention. */
+  readonly binder: string;
+  readonly events: readonly EventDeclaration[];
+  /** Header comment lines, emitted above everything. */
+  readonly comment?: string;
+}
+
+/** Assemble a schema, defaulting the action binder to `A`. */
+export function eventSchema(
+  events: EventDeclaration[],
+  options: { maxWindow?: WindowLike; binder?: string; comment?: string } = {},
+): EventSchema {
+  if (events.length === 0) throw new Error("dogwood: an event schema declares at least one event kind");
+  const kinds = new Set<string>();
+  for (const e of events) {
+    if (kinds.has(e.kind)) throw new Error(`dogwood: event kind "${e.kind}" is declared twice`);
+    kinds.add(e.kind);
+  }
+  return {
+    maxWindow: options.maxWindow === undefined ? undefined : window(options.maxWindow),
+    binder: assertIdent(options.binder ?? "A", "an action binder"),
+    events,
+    comment: options.comment,
+  };
+}
+
+/**
+ * The default event-schema shape: `request` (deciding), `response` and `error`,
+ * each pinned to the request's principal.
+ *
+ * This reproduces `configuration/event-schemas/pinned.dwschema`, which is what
+ * `ServiceSchema::defaults()` uses. Emitting it explicitly is the honest thing
+ * to do the moment a project supplies *any* event schema, because supplying
+ * one opts out of the built-in default entirely.
+ *
+ * @param options.pinCallerPrincipal Drop the pin to allow cross-principal
+ * correlation. A deliberate choice: it widens every temporal predicate in the
+ * policy set, so it stamps a comment into the emitted file and DWDS010 reports
+ * it in the build.
+ */
+export function defaultEventSchema(
+  options: {
+    maxWindow?: WindowLike;
+    pinCallerPrincipal?: boolean;
+    principalField?: string;
+    binder?: string;
+  } = {},
+): EventSchema {
+  const pinned = options.pinCallerPrincipal !== false;
+  const principalField = options.principalField ?? "callerPrincipal";
+
+  const common = (): EventField[] => [
+    pinned
+      ? pinnedField(principalField, principalType(), pinPrincipal())
+      : field(principalField, principalType()),
+    field("callerResource", resourceType()),
+    field("requestId", concrete("String")),
+    field("sessionId", concrete("String")),
+  ];
+
+  return eventSchema(
+    [
+      eventDeclaration("request", [spreadInputs(), ...common()], { decision: true }),
+      eventDeclaration("response", [spreadInputs(), spreadOutputs(), ...common()]),
+      eventDeclaration("error", [spreadInputs(), ...common()]),
+    ],
+    {
+      maxWindow: options.maxWindow,
+      binder: options.binder,
+      comment: pinned
+        ? "The default event-schema shape: request/response/error, each correlated to\nthe deciding request's principal."
+        : `Cross-principal: ${principalField} is NOT pinned, so temporal predicates see\nevents from every principal, not only the deciding request's. This widens\nevery predicate in the policy set and is a deliberate departure from\nupstream's default (see ServiceSchema::defaults).`,
+    },
+  );
+}
+
+// ── Rendering ─────────────────────────────────────────────────────
+
+function renderPinTarget(target: PinTarget): string {
+  return target.ref === "context" ? `context.${target.path.join(".")}` : [target.ref, ...target.attrs].join(".");
+}
+
+function renderFieldType(type: EventFieldType, binder: string, indent: string): string {
+  switch (type.type) {
+    case "selector":
+      return `${type.selector}(${binder})`;
+    case "concrete":
+      return type.name;
+    case "record":
+      return `{\n${renderFields(type.fields, binder, indent + "    ")}\n${indent}}`;
+  }
+}
+
+function renderFields(fields: readonly EventField[], binder: string, indent: string): string {
+  return fields
+    .map((f) => {
+      if (f.field === "spread") return `${indent}...${f.selector}(${binder}),`;
+      const pin = f.pin ? ` = ${renderPinTarget(f.pin)}` : "";
+      return `${indent}${f.pin ? "pin " : ""}${f.name}: ${renderFieldType(f.type, binder, indent)}${pin},`;
+    })
+    .join("\n");
+}
+
+function renderComment(comment: string): string[] {
+  return comment.split("\n").map((line) => `// ${line}`.trimEnd());
+}
+
+/** Render a schema to `.dwschema` text. */
+export function renderEventSchema(schema: EventSchema): string {
+  const lines: string[] = [];
+  if (schema.comment) lines.push(...renderComment(schema.comment), "");
+
+  if (schema.maxWindow) {
+    lines.push(`max_window = ${renderWindow(schema.maxWindow)}`, "");
+  }
+
+  for (const [index, event] of schema.events.entries()) {
+    if (index > 0) lines.push("");
+    if (event.comment) lines.push(...renderComment(event.comment));
+    lines.push(`${event.decision ? "decision " : ""}event <${schema.binder}>::${event.kind} {`);
+    if (event.fields.length > 0) lines.push(renderFields(event.fields, schema.binder, "    "));
+    lines.push("}");
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/** Every event kind a schema declares, in declaration order. */
+export function declaredEventKinds(schema: EventSchema): string[] {
+  return schema.events.map((e) => e.kind);
+}