@intentius/chant-lexicon-cedar 0.44.8 → 0.44.10

package/src/agentcore/enforcement.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import {
+  AGENTCORE_ENFORCEMENT,
+  describeStage,
+  enforcementMode,
+  enforcementStage,
+  isEnforcing,
+} from "./enforcement";
+
+describe("EnforcementMode", () => {
+  it("carries the two wire values AWS::BedrockAgentCore::Policy declares", () => {
+    // The CloudFormation enum, verbatim: ["ACTIVE", "LOG_ONLY"], default ACTIVE.
+    expect(Object.values(AGENTCORE_ENFORCEMENT).sort()).toEqual(["ACTIVE", "LOG_ONLY"]);
+    expect(AGENTCORE_ENFORCEMENT.logOnly).toBe("LOG_ONLY");
+    expect(AGENTCORE_ENFORCEMENT.enforce).toBe("ACTIVE");
+  });
+
+  it("maps a stage onto the wire value", () => {
+    expect(enforcementMode("log-only")).toBe("LOG_ONLY");
+    expect(enforcementMode("enforce")).toBe("ACTIVE");
+  });
+
+  it("round-trips a stage through the wire value", () => {
+    for (const stage of ["log-only", "enforce"] as const) {
+      expect(enforcementStage(enforcementMode(stage))).toBe(stage);
+    }
+  });
+
+  it("reads an absent EnforcementMode as enforcing, which is AWS's default", () => {
+    expect(enforcementStage(undefined)).toBe("enforce");
+    expect(isEnforcing(undefined)).toBe(true);
+  });
+
+  it("says which stage reaches the gateway", () => {
+    expect(isEnforcing("ACTIVE")).toBe(true);
+    expect(isEnforcing("LOG_ONLY")).toBe(false);
+  });
+
+  it("explains a stage the same way everywhere", () => {
+    expect(describeStage("log-only")).toMatch(/logged and do not affect the response/);
+    expect(describeStage("enforce")).toMatch(/reaches the gateway/);
+  });
+});

package/src/agentcore/enforcement.ts

@@ -0,0 +1,92 @@
+/**
+ * `EnforcementMode` — the dial that makes a policy rollout observable before it
+ * is binding (#1660).
+ *
+ * `AWS::BedrockAgentCore::Policy` carries an optional `EnforcementMode` with
+ * exactly two values, and the CloudFormation schema says what they mean:
+ *
+ * > Whether the policy contributes to the enforce decision returned to Gateway.
+ * > LOG_ONLY policies are still evaluated but their decisions are observed
+ * > only, allowing customers to validate a policy against real traffic before
+ * > promoting it.
+ *
+ * That is observe-before-enforce, in the substrate, per policy — the same shape
+ * chant already has at the ops layer, and the reason epic #1646 picked
+ * AgentCore as the deployment target for the temporal dialect rather than
+ * inventing a staging mechanism. A temporal policy is the case that needs it
+ * most: `formerly within 24h …` cannot be reasoned about from the source alone,
+ * because whether it fires depends on traffic nobody has replayed yet.
+ *
+ * ### The two names, and why chant does not reuse AWS's
+ *
+ * The wire values are `LOG_ONLY` and `ACTIVE`. `ACTIVE` is a poor name for
+ * "enforcing" — it reads as "not disabled", and `LOG_ONLY` is active too; it is
+ * evaluated on every request. So the authoring vocabulary here is
+ * `"log-only"` / `"enforce"`, and {@link enforcementMode} is the one place the
+ * translation happens. The wire values are exported as well, for a caller that
+ * has one in hand from a live read.
+ *
+ * ### The showcase seam (loomster#171)
+ *
+ * loomster#171 wants a staged policy rollout it can demonstrate end to end:
+ * ship the policy log-only, watch what it would have denied, promote it. This
+ * module is that seam. The whole rollout is one argument —
+ * `agentCoreStagedPolicy(name, policy, stage)` — so the promotion is a
+ * one-token diff a reviewer can see, rather than a hand-edited string in a
+ * CloudFormation resource. Anything more elaborate (which environments are
+ * promoted, who decides) belongs to the caller's own config; this module's job
+ * is to make the two states nameable and the transition legible.
+ */
+
+/**
+ * The wire values `EnforcementMode` takes, keyed by the stage they implement.
+ *
+ * A typed constant pair rather than a bare union so a caller reads
+ * `AGENTCORE_ENFORCEMENT.logOnly` at the call site and cannot typo the string.
+ */
+export const AGENTCORE_ENFORCEMENT = {
+  /** Evaluated on every request; its decision is observed, never returned. */
+  logOnly: "LOG_ONLY",
+  /** Contributes to the decision Gateway returns. AWS's own default. */
+  enforce: "ACTIVE",
+} as const;
+
+/** The `EnforcementMode` property value, as CloudFormation spells it. */
+export type AgentCoreEnforcementMode = (typeof AGENTCORE_ENFORCEMENT)[keyof typeof AGENTCORE_ENFORCEMENT];
+
+/** The stage of a rollout, in the vocabulary the seam is authored in. */
+export type AgentCoreStage = "log-only" | "enforce";
+
+/**
+ * The `EnforcementMode` a stage deploys as.
+ *
+ * Omitting `EnforcementMode` entirely is legal and means `ACTIVE` — AWS's
+ * schema declares that default. This helper never returns `undefined`, so a
+ * policy that went through it says which stage it is in on the face of the
+ * template, and a diff that promotes one shows the change.
+ */
+export function enforcementMode(stage: AgentCoreStage): AgentCoreEnforcementMode {
+  return stage === "log-only" ? AGENTCORE_ENFORCEMENT.logOnly : AGENTCORE_ENFORCEMENT.enforce;
+}
+
+/** The stage a wire value came from — the inverse of {@link enforcementMode}. */
+export function enforcementStage(mode: AgentCoreEnforcementMode | undefined): AgentCoreStage {
+  return mode === AGENTCORE_ENFORCEMENT.logOnly ? "log-only" : "enforce";
+}
+
+/** True when the policy's decision reaches Gateway rather than only the log. */
+export function isEnforcing(mode: AgentCoreEnforcementMode | undefined): boolean {
+  return enforcementStage(mode) === "enforce";
+}
+
+/**
+ * One line of prose for a stage, for a description or a plan summary.
+ *
+ * Kept here rather than at the call sites so every surface that explains a
+ * staged policy explains it the same way.
+ */
+export function describeStage(stage: AgentCoreStage): string {
+  return stage === "log-only"
+    ? "Evaluated against real traffic; decisions are logged and do not affect the response."
+    : "Enforcing: this policy's decision reaches the gateway.";
+}

package/src/agentcore/scan.ts

@@ -0,0 +1,119 @@
+/**
+ * Finding embedded AgentCore policy statements in a build's emitted output
+ * (#1660).
+ *
+ * The DWD walls read emitted *text* rather than the in-memory model, for the
+ * reason `../dogwood/scan.ts` sets out: `chant audit` runs over artifacts chant
+ * did not write, and a wall that only fires on chant's own output is not a
+ * wall. An embedded statement is the same situation one lexicon further out —
+ * the statement lands in whatever the aws lexicon emitted, so this reads the
+ * emitted template rather than reaching for a resource class the cedar lexicon
+ * deliberately does not import.
+ *
+ * Structural, not CloudFormation-specific. The thing being looked for is an
+ * object with a `Definition.Policy.Statement` string, which is AgentCore's
+ * language-agnostic arm wherever it appears — in a CFN template's
+ * `Resources.<id>.Properties`, in a plan JSON, in a fixture. The nearest
+ * enclosing key is carried along as the name to blame, which for a CFN template
+ * is the logical id.
+ */
+
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { isRecord } from "../policy-text";
+
+/** One `Definition.Policy.Statement` found in an emitted artifact. */
+export interface EmbeddedAgentCoreStatement {
+  /** The lexicon whose output carried it. */
+  lexicon: string;
+  /** The filename, or the lexicon's primary output when it had no name. */
+  source: string;
+  /** The nearest enclosing key — a CloudFormation logical id, in practice. */
+  logicalId?: string;
+  /** The statement text, verbatim. */
+  statement: string;
+}
+
+/** The `Cedar` arm as well, for a check that needs to tell the two apart. */
+export interface EmbeddedAgentCoreDefinition extends EmbeddedAgentCoreStatement {
+  arm: "Cedar" | "Policy";
+}
+
+function walk(
+  node: unknown,
+  logicalId: string | undefined,
+  found: Array<{ logicalId?: string; arm: "Cedar" | "Policy"; statement: string }>,
+): void {
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, logicalId, found);
+    return;
+  }
+  if (!isRecord(node)) return;
+
+  const definition = node.Definition;
+  if (isRecord(definition)) {
+    for (const arm of ["Cedar", "Policy"] as const) {
+      const value = definition[arm];
+      if (isRecord(value) && typeof value.Statement === "string") {
+        found.push({ ...(logicalId ? { logicalId } : {}), arm, statement: value.Statement });
+      }
+    }
+  }
+
+  for (const [key, value] of Object.entries(node)) {
+    // `Properties` is CloudFormation's own wrapper, so it is not the name to
+    // blame — the logical id one level up is.
+    walk(value, key === "Properties" ? logicalId : key, found);
+  }
+}
+
+/** Every emitted text in a build, with the lexicon and filename that carried it. */
+function emittedTexts(ctx: PostSynthContext): Array<{ lexicon: string; source: string; text: string }> {
+  const out: Array<{ lexicon: string; source: string; text: string }> = [];
+  for (const [lexicon, output] of ctx.outputs) {
+    if (typeof output === "string") {
+      if (output.length > 0) out.push({ lexicon, source: lexicon, text: output });
+      continue;
+    }
+    if (typeof output.primary === "string" && output.primary.length > 0) {
+      out.push({ lexicon, source: lexicon, text: output.primary });
+    }
+    for (const [filename, content] of Object.entries(output.files ?? {})) {
+      if (typeof content === "string") out.push({ lexicon, source: filename, text: content });
+    }
+  }
+  return out;
+}
+
+/**
+ * Every AgentCore policy definition embedded in a build's emitted output.
+ *
+ * Non-JSON output is skipped rather than reported: most emitted files are not
+ * JSON, and a parse failure here says nothing about whether a statement is
+ * there.
+ */
+export function embeddedAgentCoreDefinitions(ctx: PostSynthContext): EmbeddedAgentCoreDefinition[] {
+  const results: EmbeddedAgentCoreDefinition[] = [];
+
+  for (const { lexicon, source, text } of emittedTexts(ctx)) {
+    const trimmed = text.trimStart();
+    if (!trimmed.startsWith("{") && !trimmed.startsWith("[")) continue;
+
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(text);
+    } catch {
+      continue;
+    }
+
+    const found: Array<{ logicalId?: string; arm: "Cedar" | "Policy"; statement: string }> = [];
+    walk(parsed, undefined, found);
+    for (const hit of found) results.push({ lexicon, source, ...hit });
+  }
+
+  return results;
+}
+
+/** Only the language-agnostic arm — the one a `.dw` statement travels in. */
+export function embeddedAgentCorePolicyStatements(ctx: PostSynthContext): EmbeddedAgentCoreStatement[] {
+  return embeddedAgentCoreDefinitions(ctx).filter((d) => d.arm === "Policy");
+}