@intentius/chant-lexicon-cedar 0.44.8 → 0.44.9

package/src/dogwood/testdata/pinned.dwschema

@@ -0,0 +1,31 @@
+// Adapted from dogwood-policy/dogwood@5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c (Apache-2.0):
+//   dogwood-language/configuration/event-schemas/pinned.dwschema
+// Upstream's shape; the bytes are what chant's typed builders emit.
+
+// The default event-schema shape: request/response/error, each correlated to
+// the deciding request's principal.
+
+decision event <A>::request {
+    ...inputs(A),
+    pin callerPrincipal: principalType(A) = principal,
+    callerResource: resourceType(A),
+    requestId: String,
+    sessionId: String,
+}
+
+event <A>::response {
+    ...inputs(A),
+    ...outputs(A),
+    pin callerPrincipal: principalType(A) = principal,
+    callerResource: resourceType(A),
+    requestId: String,
+    sessionId: String,
+}
+
+event <A>::error {
+    ...inputs(A),
+    pin callerPrincipal: principalType(A) = principal,
+    callerResource: resourceType(A),
+    requestId: String,
+    sessionId: String,
+}

package/src/dogwood/testdata/read-after-login.cedarschema

@@ -0,0 +1,20 @@
+// Adapted from dogwood-policy/dogwood@5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c (Apache-2.0):
+//   dogwood-docs/examples/read_after_login/schema.cedarschema
+// The action schema half — what `dogwood validate --policy-schema` reads.
+
+namespace Drupe {
+  type LoginInput = { user: String };
+  type ReadInput = { user: String };
+  entity Gateway;
+  entity OAuthUser = { id: String } tags String;
+  action "Login" appliesTo {
+    principal: [OAuthUser],
+    resource: [Gateway],
+    context: { input: LoginInput }
+  };
+  action "Read" appliesTo {
+    principal: [OAuthUser],
+    resource: [Gateway],
+    context: { input: ReadInput }
+  };
+}

package/src/dogwood/testdata/read-after-login.dw

@@ -0,0 +1,17 @@
+// Adapted from dogwood-policy/dogwood@5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c (Apache-2.0):
+//   dogwood-docs/examples/read_after_login/policy.dw
+// The bundle the CLI-gated DWDE checks are exercised against (#1659).
+
+// Permit Read only if the same user successfully logged in within the last
+// hour. The `when temporal { … }` clause reads the accumulated event history;
+// the `{ input.user: context.input.user }` pin correlates the past login's
+// user with the current request's user.
+@id("read_after_login")
+permit (
+    principal,
+    action == Drupe::Action::"Read",
+    resource
+)
+when temporal {
+    formerly within 1h Drupe::Action::"Login"::response{ input.user: context.input.user }
+};

package/src/dogwood/testdata/temporal-policies.dw

@@ -0,0 +1,53 @@
+// Adapted from dogwood-policy/dogwood@5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c (Apache-2.0):
+//   dogwood-docs/examples/read_after_login/policy.dw
+//   dogwood-docs/examples/temporal_sum_formerly_transfer/policy.dw
+//   dogwood-docs/examples/read_heartbeat_since_login_30s/policy.dw
+//   dogwood-docs/examples/temporal_count_formerly_login/policy.dw
+// Upstream's shape; the bytes are what chant's typed builders emit.
+
+// Sums the numeric value `?a` over occurrences of `?body` within window `?w`.
+def temporal sum_formerly(?a, ?w, ?body) {
+    sum ?a for (?a: Long), ($t: Timepoint). where formerly within ?w (?body && tp($t))
+};
+
+@id("read_after_login")
+permit (
+  principal,
+  action == Drupe::Action::"Read",
+  resource
+)
+when temporal {
+    formerly within 1h Drupe::Action::"Login"::response{ input.user: context.input.user }
+};
+
+@id("transfer_sum_over_100")
+permit (
+  principal,
+  action == Drupe::Action::"Alert",
+  resource
+)
+when temporal {
+    exists (total: Long). (sum_formerly(a, 1h, Drupe::Action::"Transfer"::request{ input.user: _, input.amount: a })) == total && total > 100
+};
+
+@id("no_tool_after_sensitive_read")
+forbid (
+  principal,
+  action == Drupe::Action::"Invoke",
+  resource
+)
+when guardrails { context.input.tool != "audit" }
+when temporal {
+    Drupe::Action::"Read"::response{ output.classification: c } since within 30m Drupe::Action::"Login"::request{}
+}
+unless { principal in Drupe::Group::"breakglass" };
+
+@id("rate_limited")
+permit (
+  principal,
+  action == Drupe::Action::"Transfer",
+  resource
+)
+when temporal {
+    (count for (t: Timepoint). where formerly within 15m (Drupe::Action::"Transfer"::request{} && tp(t))) < 5
+};

package/src/dogwood/upstream.ts

@@ -0,0 +1,41 @@
+/**
+ * The dogwood upstream pin.
+ *
+ * Not a `upstreamPin` on the plugin: that slot belongs to the cedar grammar
+ * (`@cedar-policy/cedar-wasm`, see `../spec/pin.ts`), and self-upgrade tooling
+ * bumps exactly one thing per lexicon. Dogwood's pin is a git SHA recorded by
+ * #1657, because upstream has no version to key off — zero tags, zero
+ * releases, and a workspace version of `1.0.0` that is an Amazon-internal
+ * package artifact every future sync will also report.
+ *
+ * The blob hashes are the narrow content pin the #1657 report recommends. The
+ * whole tree hash moves on every sync including docs-only ones, which makes it
+ * too noisy to gate on; these seven files are the surface chant actually
+ * depends on. The three `.pest` grammars pin the language, `default_macros.dw`
+ * pins the standard aggregate library (which is a file a sync can edit and a
+ * caller can replace with `--macros`), and the three `dogwood-cli/src` files
+ * pin the JSON report structs that are #1659's integration surface.
+ *
+ * Movement risk is structural, not incidental: content arrives as squashed
+ * "Sync from internal source" commits from a publish bot, against a repository
+ * nobody outside Amazon can see, with no changelog and no version bump.
+ */
+
+/** The pinned upstream revision and the files chant's surface is built against. */
+export const DOGWOOD_UPSTREAM = {
+  owner: "dogwood-policy",
+  repo: "dogwood",
+  /** Default-branch SHA verified in #1657 (committed 2026-08-06). */
+  revision: "5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c",
+  license: "Apache-2.0",
+  /** Git blob hashes at {@link revision} — the narrow content pin. */
+  contents: {
+    "dogwood-language/src/parser/grammar.pest": "adb0801303ee1b735585fe22a5d85175ecf6772c",
+    "dogwood-language/src/extension/temporal/grammar.pest": "dc31fe1634b5c37173f0a999619e9834069b7a22",
+    "dogwood-language/src/event_schema/grammar.pest": "bd3b064447dc0d09cc2f8eb28a7c657e746cc8a2",
+    "dogwood-language/configuration/default_macros.dw": "ecd67e5edcd566aa66b05ad51bc472afbaf22a7a",
+    "dogwood-cli/src/ops.rs": "2924c7eb0e569a745ff19c2d84cbba782fc56502",
+    "dogwood-cli/src/main.rs": "bfd68c9ff05883ed48e5738f658b5925542d817d",
+    "dogwood-cli/src/error.rs": "43f12afbbf25ad94e25130c83227eefd86f8d516",
+  },
+} as const;

package/src/dogwood/window.ts

@@ -0,0 +1,124 @@
+/**
+ * Temporal windows — the one thing dogwood's past-only operators cannot omit.
+ *
+ * `formerly`, `previous` and `since` all take a mandatory `within <n><unit>`
+ * clause; the unit is one of `s`, `m`, `h`, `d` and nothing else. Upstream's
+ * `temporal/grammar.pest` spells that out:
+ *
+ * ```
+ * within         = { "within" ~ within_payload }
+ * within_payload = { param_ref | (integer ~ time_unit) }
+ * time_unit      = { "s" | "m" | "h" | "d" }
+ * ```
+ *
+ * Typing the window as a value rather than as free text is what makes
+ * "a `formerly` without a window" unrepresentable in the builders (#1658's
+ * third lint wall) — you cannot call {@link formerly} without one.
+ *
+ * The `param_ref` arm (`within ?w`) is legal only inside a macro body; it is
+ * modelled by {@link MacroWindow} rather than by this type, so an ordinary
+ * policy cannot accidentally emit a sigil the expander would reject.
+ */
+
+/** The four units upstream's grammar admits. Anything else does not parse. */
+export type TimeUnit = "s" | "m" | "h" | "d";
+
+/** A `within` payload: a positive integer and one of the four units. */
+export interface TemporalWindow {
+  readonly value: number;
+  readonly unit: TimeUnit;
+}
+
+/**
+ * A window as written in a `.dw` file (`"1h"`, `"30m"`, `"7d"`).
+ *
+ * The template-literal arm means `formerly("1h", …)` type-checks and
+ * `formerly("1w", …)` does not, without anyone writing a runtime check first.
+ */
+export type WindowLike = TemporalWindow | `${number}${TimeUnit}`;
+
+/**
+ * `within ?w` — a window a macro takes as a parameter.
+ *
+ * The other arm of upstream's `within_payload`. Legal only inside a macro
+ * body; the expander resolves it against the call site's bare interval
+ * argument (`once(1h, …)`), which is why the call side has no `within`.
+ */
+export interface WindowParam {
+  readonly param: string;
+}
+
+/** Either a concrete window or a macro parameter standing in for one. */
+export type WindowValue = TemporalWindow | WindowParam;
+
+const WINDOW_TEXT = /^(\d+)([smhd])$/;
+const PARAM_TEXT = /^\?[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** True when the payload is `?w` rather than `1h`. */
+export function isWindowParam(value: WindowValue): value is WindowParam {
+  return "param" in value;
+}
+
+/**
+ * `within ?w` inside a macro body.
+ *
+ * Exported from `./macros.ts` too, which is where the sigil rules are
+ * documented and where a reader looking for it will be.
+ */
+export function windowParam(param: string): WindowParam {
+  if (!PARAM_TEXT.test(param)) {
+    throw new Error(`dogwood: a window parameter carries the "?" sigil — got "${param}"`);
+  }
+  return { param };
+}
+
+/** Seconds in one of each unit — the scale `max_window` comparisons run on. */
+const UNIT_SECONDS: Record<TimeUnit, number> = { s: 1, m: 60, h: 3600, d: 86400 };
+
+/** Narrow a {@link WindowLike} to the structured form, validating as it goes. */
+export function window(value: WindowLike): TemporalWindow {
+  if (typeof value !== "string") {
+    if (!Number.isInteger(value.value) || value.value < 0) {
+      throw new Error(`dogwood: a temporal window must be a non-negative integer, got ${String(value.value)}`);
+    }
+    if (!(value.unit in UNIT_SECONDS)) {
+      throw new Error(`dogwood: a temporal window unit must be s, m, h or d, got "${String(value.unit)}"`);
+    }
+    return { value: value.value, unit: value.unit };
+  }
+
+  const match = WINDOW_TEXT.exec(value);
+  if (!match) {
+    throw new Error(`dogwood: "${value}" is not a temporal window — write an integer and one of s, m, h, d (for example "1h")`);
+  }
+  return { value: Number(match[1]), unit: match[2] as TimeUnit };
+}
+
+/** `1h` — the surface form, in a `within` clause or as a macro-call argument. */
+export function renderWindow(value: WindowLike): string {
+  const w = window(value);
+  return `${w.value}${w.unit}`;
+}
+
+/** A `within` payload: `1h`, or the `?w` a macro body defers to its call site. */
+export function renderWindowValue(value: WindowValue): string {
+  return isWindowParam(value) ? value.param : renderWindow(value);
+}
+
+/** Narrow a window argument, letting a `?w` parameter through unchanged. */
+export function windowValue(value: WindowLike | WindowParam): WindowValue {
+  return typeof value === "object" && "param" in value ? windowParam(value.param) : window(value);
+}
+
+/** The window in seconds, so `90m` and `1h` are comparable to a `max_window`. */
+export function windowSeconds(value: WindowLike): number {
+  const w = window(value);
+  return w.value * UNIT_SECONDS[w.unit];
+}
+
+/**
+ * Upstream's fallback cap. `ServiceSchema::defaults()` and an event schema
+ * with no `max_window` directive both look back at most 24 hours, per the
+ * comment atop `event_schema/grammar.pest` ("absent → a 24h default").
+ */
+export const DEFAULT_MAX_WINDOW: TemporalWindow = { value: 24, unit: "h" };

package/src/index.ts

@@ -54,6 +54,30 @@ export type { CedarGenerateOptions, CedarGenerateResult } from "./import/generat
 export { CedarTemplateParser, CedarTemplateGenerator } from "./import/adapter";
 export { detectTemplate } from "./detect";
 
+// The dogwood temporal dialect (#1658) — typed temporal builders, the `.dw`
+// serializer leg, `.dwschema` event schemas. Pre-release; see ./dogwood.
+//
+// Namespaced rather than flattened: the temporal sub-language's builders are
+// named after its own grammar (`and`, `not`, `count`, `sum`, `str`, `field`,
+// `record`, `window`), and spilling those into the package root would collide
+// with a schema-generated entity class the moment someone declares one. The
+// three entity classes are re-exported flat because that is what a policy file
+// names.
+export * as dogwood from "./dogwood/index";
+export {
+  DOGWOOD_EVENT_SCHEMA_FILENAME,
+  DOGWOOD_EVENT_SCHEMA_TYPE,
+  DOGWOOD_MACRO_FILENAME,
+  DOGWOOD_MACRO_LIBRARY_TYPE,
+  DOGWOOD_POLICY_FILENAME,
+  DOGWOOD_POLICY_TYPE,
+  TemporalEventSchema,
+  TemporalMacroLibrary,
+  TemporalPolicy,
+} from "./dogwood/policy";
+export type { EventSchemaProps, MacroLibraryProps, TemporalPolicyProps } from "./dogwood/policy";
+export { DOGWOOD_UPSTREAM } from "./dogwood/upstream";
+
 // Lint rules
 export { rules as cedarLintRules } from "./lint/rules";
 

package/src/lint/audit-catalog.ts

@@ -127,4 +127,60 @@ export const cedarAuditCatalog: Record<string, RuleMeta> = {
     'Name the actions the grant needs (action == Action::"read", or action in [ … ]) so it does not widen as the schema gains actions.',
     { category: "security" },
   ),
+
+  // ── The dogwood dialect (DWD) ──────────────────────────────────
+  //
+  // A second id family under the same lexicon, declared on the serializer as
+  // `extraRulePrefixes` (#1349's mechanism, the way k8s owns ARGO and FLUX).
+  // Dogwood is a dialect of Cedar rather than a peer language — a `.dw` file
+  // stripped of Cedar semantics is meaningless — so its checks ship here, and
+  // its ids are their own family so a reader can tell which surface bit them.
+  DWDC010: auditRule(
+    "DWDC010",
+    "merge-worthy",
+    "guidance",
+    "Dogwood temporal predicate names an undeclared event kind",
+    "Declare the event kind in the emitted .dwschema, or correct the predicate to a kind the schema derives — upstream rejects the policy set otherwise.",
+    { category: "correctness" },
+  ),
+  DWDC011: auditRule(
+    "DWDC011",
+    "merge-worthy",
+    "guidance",
+    "Dogwood temporal window exceeds the event schema's max_window",
+    "Shorten the window, or raise max_window in the event schema. With no schema emitted the cap is upstream's 24h default.",
+    { category: "correctness" },
+  ),
+  DWDC012: auditRule(
+    "DWDC012",
+    "merge-worthy",
+    "guidance",
+    "Dogwood formerly/previous/since is missing its window",
+    "Give the operator a `within <n><s|m|h|d>` window — all three past-only operators require one. The typed builders take it as an argument.",
+    { category: "correctness" },
+  ),
+  DWDE010: auditRule(
+    "DWDE010",
+    "merge-worthy",
+    "guidance",
+    "Dogwood policy set fails `dogwood validate`",
+    "Fix what upstream's frontend names — a macro, a temporal type error, or a Cedar body the action schema rejects. If the finding is the advisory, install the dogwood binary (or set cedar.dogwood.binary) so full .dw validation can run at all; without it only the DWDC walls apply.",
+    { category: "correctness" },
+  ),
+  DWDE011: auditRule(
+    "DWDE011",
+    "merge-worthy",
+    "guidance",
+    "Cedar lowered from a dogwood policy set fails Cedar validation",
+    "Fix the entity type, action, or attribute Cedar's validator names in the lowered body — the temporal clauses became context slots, so everything the finding points at is ordinary Cedar the policy wrote.",
+    { category: "correctness" },
+  ),
+  DWDS010: auditRule(
+    "DWDS010",
+    "report-only",
+    "guidance",
+    "Dogwood event schema pins nothing, widening every temporal predicate",
+    "Pin a field to the deciding request (pin callerPrincipal: principalType(A) = principal), or record that cross-principal correlation is the intent — supplying any event schema opts out of upstream's default pin.",
+    { category: "security" },
+  ),
 };

package/src/lint/post-synth/dogwood-helpers.ts

@@ -0,0 +1,139 @@
+/**
+ * Turning a build's emitted files into `dogwood` CLI invocations (#1659).
+ *
+ * The DWDE checks both need the same thing: which of the emitted `.dw` files
+ * is a policy set, which is a macro library, which `.cedarschema` backs
+ * `--policy-schema`, and which `.dwschema` backs `--event-schema`. Planning
+ * that once here keeps the two checks from disagreeing about what they ran —
+ * DWDE010 validates a bundle and DWDE011 lowers the *same* bundle, and a
+ * finding from one that names different inputs than the other would be a
+ * puzzle rather than a report.
+ *
+ * Excluded from check auto-discovery by the "helper" filename filter.
+ */
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { blankComments, dogwoodPolicyFiles, dogwoodSchemaFiles, type DogwoodArtifact } from "../../dogwood/scan";
+import type { DogwoodBundle } from "../../dogwood/cli";
+
+/** One planned invocation: the files, and the names to blame in a finding. */
+export interface PreparedBundle {
+  lexicon: string;
+  /** The `.dw` policy set filename. */
+  source: string;
+  /** The `.cedarschema` filename passed as `--policy-schema`. */
+  policySchemaSource: string;
+  /** The `.dwschema` filename passed as `--event-schema`, when one was emitted. */
+  eventSchemaSource?: string;
+  bundle: DogwoodBundle;
+}
+
+/** What the CLI-gated checks should do with this build. */
+export interface DogwoodRunPlan {
+  /** True when the build emitted a `.dw` policy set at all. */
+  hasPolicies: boolean;
+  /** Every invocation to make. Empty when {@link blocked} is set. */
+  bundles: PreparedBundle[];
+  /** Why nothing can be run, when policies exist but a required input does not. */
+  blocked?: string;
+  /** The lexicon the `.dw` output came from, for a finding that names no file. */
+  lexicon?: string;
+}
+
+/**
+ * A `.dw` file holding only `def` declarations is a macro library, not a
+ * policy set.
+ *
+ * By structure rather than by filename: the serializer's default is
+ * `macros.dw`, but `MacroLibraryProps.filename` overrides it, and `chant
+ * audit` runs over trees chant never wrote. A policy set is a file with a
+ * `permit` or `forbid` head in it — upstream's policy grammar has no third
+ * effect — and a set with inlined macros still has one.
+ */
+export function looksLikeMacroLibrary(text: string): boolean {
+  return !/\b(permit|forbid)\s*\(/.test(blankComments(text));
+}
+
+function byName(a: DogwoodArtifact, b: DogwoodArtifact): number {
+  return a.source.localeCompare(b.source);
+}
+
+/**
+ * The Cedar action schema the CLI needs, as text.
+ *
+ * `--policy-schema` reads a human-readable `.cedarschema`; a `.cedarschema.json`
+ * is not a substitute, so it is not offered as one. Sorted by filename so a
+ * build emitting several picks the same one on every run.
+ */
+function findPolicySchema(ctx: PostSynthContext): DogwoodArtifact | undefined {
+  const found: DogwoodArtifact[] = [];
+  for (const [lexicon, output] of ctx.outputs) {
+    if (typeof output === "string") continue;
+    for (const [source, text] of Object.entries(output.files ?? {})) {
+      if (typeof text !== "string") continue;
+      if (!source.endsWith(".cedarschema")) continue;
+      found.push({ lexicon, source, text });
+    }
+  }
+  return found.sort(byName)[0];
+}
+
+/**
+ * Plan every `dogwood` invocation this build calls for.
+ *
+ * One bundle per policy set per emitted event schema. A build with several
+ * `.dwschema` files means several services, and `--event-schema` takes exactly
+ * one file, so the set is run against each and every finding names the schema
+ * it was found under — the alternative is picking one silently and reporting
+ * against a schema the reader did not choose. Macro libraries do combine: a
+ * library is a sequence of `def`s, so several concatenate into the one file
+ * `--macros` accepts.
+ */
+export function planDogwoodRuns(ctx: PostSynthContext): DogwoodRunPlan {
+  const files = dogwoodPolicyFiles(ctx).sort(byName);
+  const policySets = files.filter((f) => !looksLikeMacroLibrary(f.text));
+  if (policySets.length === 0) return { hasPolicies: false, bundles: [] };
+
+  const lexicon = policySets[0].lexicon;
+  const libraries = files.filter((f) => looksLikeMacroLibrary(f.text));
+  const macros = libraries.length > 0 ? libraries.map((f) => f.text).join("\n") : undefined;
+
+  const policySchema = findPolicySchema(ctx);
+  if (!policySchema) {
+    return {
+      hasPolicies: true,
+      bundles: [],
+      lexicon,
+      blocked:
+        "no Cedar action schema (.cedarschema) was emitted beside them, and `dogwood validate` requires one via --policy-schema",
+    };
+  }
+
+  const eventSchemas = dogwoodSchemaFiles(ctx).sort(byName);
+  const bundles: PreparedBundle[] = [];
+
+  for (const set of policySets) {
+    for (const events of eventSchemas.length > 0 ? eventSchemas : [undefined]) {
+      bundles.push({
+        lexicon: set.lexicon,
+        source: set.source,
+        policySchemaSource: policySchema.source,
+        ...(events ? { eventSchemaSource: events.source } : {}),
+        bundle: {
+          policies: set.text,
+          policySchema: policySchema.text,
+          ...(events ? { eventSchema: events.text } : {}),
+          ...(macros !== undefined ? { macros } : {}),
+        },
+      });
+    }
+  }
+
+  return { hasPolicies: true, bundles, lexicon };
+}
+
+/** How a finding names the inputs a run was made with. */
+export function describeBundle(prepared: PreparedBundle): string {
+  const parts = [`"${prepared.source}"`, `against "${prepared.policySchemaSource}"`];
+  if (prepared.eventSchemaSource) parts.push(`with "${prepared.eventSchemaSource}"`);
+  return parts.join(" ");
+}