@intentius/chant-lexicon-aws 0.18.11 → 0.18.13

package/src/lint/post-synth/waw051.test.ts

@@ -0,0 +1,78 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw051, checkCognitoImplicitGrant } from "./waw051";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW051: Cognito Implicit OAuth Grant Allowed", () => {
+  test("check metadata", () => {
+    expect(waw051.id).toBe("WAW051");
+    expect(waw051.description).toContain("implicit");
+  });
+
+  test("flags a client allowing the implicit grant", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyClient: {
+          Type: "AWS::Cognito::UserPoolClient",
+          Properties: { AllowedOAuthFlows: ["implicit"] },
+        },
+      },
+    });
+    const diags = checkCognitoImplicitGrant(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW051");
+  });
+
+  test("flags when implicit is one of several allowed flows", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyClient: {
+          Type: "AWS::Cognito::UserPoolClient",
+          Properties: { AllowedOAuthFlows: ["code", "implicit"] },
+        },
+      },
+    });
+    expect(checkCognitoImplicitGrant(ctx)).toHaveLength(1);
+  });
+
+  test("no diagnostic for the authorization code grant only", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyClient: {
+          Type: "AWS::Cognito::UserPoolClient",
+          Properties: { AllowedOAuthFlows: ["code"] },
+        },
+      },
+    });
+    expect(checkCognitoImplicitGrant(ctx)).toHaveLength(0);
+  });
+
+  test("no diagnostic when AllowedOAuthFlows is unset", () => {
+    const ctx = makeCtx({
+      Resources: { MyClient: { Type: "AWS::Cognito::UserPoolClient", Properties: {} } },
+    });
+    expect(checkCognitoImplicitGrant(ctx)).toHaveLength(0);
+  });
+
+  test("skips intrinsic AllowedOAuthFlows values", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyClient: {
+          Type: "AWS::Cognito::UserPoolClient",
+          Properties: { AllowedOAuthFlows: { Ref: "FlowsParam" } },
+        },
+      },
+    });
+    expect(checkCognitoImplicitGrant(ctx)).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-UserPoolClient resources", () => {
+    const ctx = makeCtx({
+      Resources: { MyPool: { Type: "AWS::Cognito::UserPool", Properties: {} } },
+    });
+    expect(checkCognitoImplicitGrant(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw051.ts

@@ -0,0 +1,49 @@
+/**
+ * WAW051: Cognito Implicit OAuth Grant Allowed
+ *
+ * Flags UserPoolClients whose AllowedOAuthFlows include the deprecated
+ * "implicit" grant — it returns tokens directly in the redirect URL (exposed
+ * in browser history/referrer headers) instead of via a code exchange.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, isIntrinsic } from "./cf-refs";
+
+export function checkCognitoImplicitGrant(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::Cognito::UserPoolClient") continue;
+
+      const props = resource.Properties ?? {};
+      const flows = props.AllowedOAuthFlows;
+
+      if (isIntrinsic(flows) || !Array.isArray(flows)) continue;
+
+      if (flows.some((f) => f === "implicit")) {
+        diagnostics.push({
+          checkId: "WAW051",
+          severity: "error",
+          message: `Cognito UserPoolClient "${logicalId}" allows the implicit OAuth grant — use the authorization code grant instead`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw051: PostSynthCheck = {
+  id: "WAW051",
+  description: "Cognito UserPoolClient allows the deprecated implicit OAuth grant",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkCognitoImplicitGrant(ctx);
+  },
+};

package/src/lint/post-synth/waw052.test.ts

@@ -0,0 +1,54 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw052, checkCognitoMfaRequired } from "./waw052";
+
+function makeCtx(template: object, env?: string) {
+  return { ...createPostSynthContext({ aws: template }), env };
+}
+
+const template = {
+  Resources: {
+    MyPool: { Type: "AWS::Cognito::UserPool", Properties: { MfaConfiguration: "OPTIONAL" } },
+  },
+};
+
+describe("WAW052: Cognito MFA Not Required (full tier)", () => {
+  test("check metadata", () => {
+    expect(waw052.id).toBe("WAW052");
+    expect(waw052.description).toContain("MFA");
+  });
+
+  test("warns (not errors) on the light tier — no env set", () => {
+    const diags = checkCognitoMfaRequired(makeCtx(template));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW052");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("warns on a non-production env", () => {
+    expect(checkCognitoMfaRequired(makeCtx(template, "dev"))[0].severity).toBe("warning");
+  });
+
+  test("errors on the full/production tier", () => {
+    const diags = checkCognitoMfaRequired(makeCtx(template, "production"));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].severity).toBe("error");
+  });
+
+  test("flags MfaConfiguration: OFF too", () => {
+    const offTemplate = { Resources: { MyPool: { Type: "AWS::Cognito::UserPool", Properties: { MfaConfiguration: "OFF" } } } };
+    expect(checkCognitoMfaRequired(makeCtx(offTemplate, "prod"))).toHaveLength(1);
+  });
+
+  test("no diagnostic when MfaConfiguration: ON, even in prod", () => {
+    const onTemplate = { Resources: { MyPool: { Type: "AWS::Cognito::UserPool", Properties: { MfaConfiguration: "ON" } } } };
+    expect(checkCognitoMfaRequired(makeCtx(onTemplate, "prod"))).toHaveLength(0);
+  });
+
+  test("skips intrinsic MfaConfiguration values", () => {
+    const paramTemplate = {
+      Resources: { MyPool: { Type: "AWS::Cognito::UserPool", Properties: { MfaConfiguration: { Ref: "MfaParam" } } } },
+    };
+    expect(checkCognitoMfaRequired(makeCtx(paramTemplate, "prod"))).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw052.ts

@@ -0,0 +1,51 @@
+/**
+ * WAW052: Cognito MFA Not Required (full tier)
+ *
+ * Flags UserPools without MfaConfiguration: ON. Tier-aware (#894), same
+ * seam as WAW040: a relaxed "light" stack (local/Floci, or no --env/
+ * ownership.env set) only warns; the strict "full"/production tier
+ * (ctx.env === "prod"/"production"/"full") fails the build.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, isIntrinsic, isFullTierEnv } from "./cf-refs";
+
+export function checkCognitoMfaRequired(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+  const severity = isFullTierEnv(ctx.env) ? "error" : "warning";
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::Cognito::UserPool") continue;
+
+      const props = resource.Properties ?? {};
+      const mfaConfiguration = props.MfaConfiguration;
+
+      if (isIntrinsic(mfaConfiguration)) continue;
+
+      if (mfaConfiguration !== "ON") {
+        diagnostics.push({
+          checkId: "WAW052",
+          severity,
+          message: `Cognito UserPool "${logicalId}" does not require MFA (MfaConfiguration: ON) — require it on the full/production tier`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw052: PostSynthCheck = {
+  id: "WAW052",
+  description: "Cognito UserPool does not require MFA (full tier)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkCognitoMfaRequired(ctx);
+  },
+};

package/src/lint/post-synth/waw053.test.ts

@@ -0,0 +1,59 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw053, checkEcrScanOnPush } from "./waw053";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW053: ECR Image Scanning Disabled", () => {
+  test("check metadata", () => {
+    expect(waw053.id).toBe("WAW053");
+    expect(waw053.description).toContain("scan");
+  });
+
+  test("flags a repository with no ImageScanningConfiguration", () => {
+    const ctx = makeCtx({
+      Resources: { MyRepo: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "app" } } },
+    });
+    const diags = checkEcrScanOnPush(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW053");
+  });
+
+  test("flags ScanOnPush: false", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyRepo: {
+          Type: "AWS::ECR::Repository",
+          Properties: { ImageScanningConfiguration: { ScanOnPush: false } },
+        },
+      },
+    });
+    expect(checkEcrScanOnPush(ctx)).toHaveLength(1);
+  });
+
+  test("no diagnostic when ScanOnPush: true", () => {
+    const ctx = makeCtx({
+      Resources: {
+        MyRepo: {
+          Type: "AWS::ECR::Repository",
+          Properties: { ImageScanningConfiguration: { ScanOnPush: true } },
+        },
+      },
+    });
+    expect(checkEcrScanOnPush(ctx)).toHaveLength(0);
+  });
+
+  test("skips intrinsic ImageScanningConfiguration/ScanOnPush values", () => {
+    const ctx = makeCtx({
+      Resources: { MyRepo: { Type: "AWS::ECR::Repository", Properties: { ImageScanningConfiguration: { Ref: "ScanParam" } } } },
+    });
+    expect(checkEcrScanOnPush(ctx)).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-ECR resources", () => {
+    const ctx = makeCtx({ Resources: { MyBucket: { Type: "AWS::S3::Bucket", Properties: {} } } });
+    expect(checkEcrScanOnPush(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw053.ts

@@ -0,0 +1,53 @@
+/**
+ * WAW053: ECR Image Scanning Disabled
+ *
+ * Flags ECR repositories without ImageScanningConfiguration.ScanOnPush: true
+ * — pushed images aren't scanned for known CVEs.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, isIntrinsic } from "./cf-refs";
+
+export function checkEcrScanOnPush(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::ECR::Repository") continue;
+
+      const props = resource.Properties ?? {};
+      const scanConfig = props.ImageScanningConfiguration;
+
+      if (isIntrinsic(scanConfig)) continue;
+
+      const scanOnPush =
+        typeof scanConfig === "object" && scanConfig !== null ? (scanConfig as Record<string, unknown>).ScanOnPush : undefined;
+
+      if (isIntrinsic(scanOnPush)) continue;
+
+      if (scanOnPush !== true) {
+        diagnostics.push({
+          checkId: "WAW053",
+          severity: "error",
+          message: `ECR repository "${logicalId}" does not have ImageScanningConfiguration.ScanOnPush: true — pushed images aren't scanned for vulnerabilities`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw053: PostSynthCheck = {
+  id: "WAW053",
+  description: "ECR repository does not scan images on push",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkEcrScanOnPush(ctx);
+  },
+};

package/src/lint/post-synth/waw054.test.ts

@@ -0,0 +1,49 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw054, checkEcrTagImmutability } from "./waw054";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW054: ECR Tag Mutability Not Immutable", () => {
+  test("check metadata", () => {
+    expect(waw054.id).toBe("WAW054");
+    expect(waw054.description).toContain("immutable");
+  });
+
+  test("flags a repository with no ImageTagMutability set (defaults to MUTABLE)", () => {
+    const ctx = makeCtx({
+      Resources: { MyRepo: { Type: "AWS::ECR::Repository", Properties: { RepositoryName: "app" } } },
+    });
+    const diags = checkEcrTagImmutability(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW054");
+  });
+
+  test("flags ImageTagMutability: MUTABLE", () => {
+    const ctx = makeCtx({
+      Resources: { MyRepo: { Type: "AWS::ECR::Repository", Properties: { ImageTagMutability: "MUTABLE" } } },
+    });
+    expect(checkEcrTagImmutability(ctx)).toHaveLength(1);
+  });
+
+  test("no diagnostic when ImageTagMutability: IMMUTABLE", () => {
+    const ctx = makeCtx({
+      Resources: { MyRepo: { Type: "AWS::ECR::Repository", Properties: { ImageTagMutability: "IMMUTABLE" } } },
+    });
+    expect(checkEcrTagImmutability(ctx)).toHaveLength(0);
+  });
+
+  test("skips intrinsic ImageTagMutability values", () => {
+    const ctx = makeCtx({
+      Resources: { MyRepo: { Type: "AWS::ECR::Repository", Properties: { ImageTagMutability: { Ref: "MutabilityParam" } } } },
+    });
+    expect(checkEcrTagImmutability(ctx)).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-ECR resources", () => {
+    const ctx = makeCtx({ Resources: { MyBucket: { Type: "AWS::S3::Bucket", Properties: {} } } });
+    expect(checkEcrTagImmutability(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw054.ts

@@ -0,0 +1,49 @@
+/**
+ * WAW054: ECR Tag Mutability Not Immutable
+ *
+ * Flags ECR repositories without ImageTagMutability: IMMUTABLE — mutable tags
+ * let a previously deployed/scanned/signed tag (e.g. "prod") silently point at
+ * different image content later.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, isIntrinsic } from "./cf-refs";
+
+export function checkEcrTagImmutability(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::ECR::Repository") continue;
+
+      const props = resource.Properties ?? {};
+      const mutability = props.ImageTagMutability;
+
+      if (isIntrinsic(mutability)) continue;
+
+      if (mutability !== "IMMUTABLE") {
+        diagnostics.push({
+          checkId: "WAW054",
+          severity: "error",
+          message: `ECR repository "${logicalId}" does not have ImageTagMutability: IMMUTABLE — a tag can silently be repointed at different image content`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw054: PostSynthCheck = {
+  id: "WAW054",
+  description: "ECR repository does not have immutable image tags",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkEcrTagImmutability(ctx);
+  },
+};

package/src/lint/post-synth/waw055.test.ts

@@ -0,0 +1,43 @@
+import { describe, test, expect } from "vitest";
+import { createPostSynthContext } from "@intentius/chant-test-utils";
+import { waw055, checkLogsRetention } from "./waw055";
+
+function makeCtx(template: object) {
+  return createPostSynthContext({ aws: template });
+}
+
+describe("WAW055: CloudWatch Logs Retention Not Set", () => {
+  test("check metadata", () => {
+    expect(waw055.id).toBe("WAW055");
+    expect(waw055.description).toContain("retention");
+  });
+
+  test("flags a log group with no RetentionInDays", () => {
+    const ctx = makeCtx({
+      Resources: { MyLogs: { Type: "AWS::Logs::LogGroup", Properties: { LogGroupName: "/app/logs" } } },
+    });
+    const diags = checkLogsRetention(ctx);
+    expect(diags).toHaveLength(1);
+    expect(diags[0].checkId).toBe("WAW055");
+    expect(diags[0].severity).toBe("warning");
+  });
+
+  test("no diagnostic when RetentionInDays is set", () => {
+    const ctx = makeCtx({
+      Resources: { MyLogs: { Type: "AWS::Logs::LogGroup", Properties: { RetentionInDays: 90 } } },
+    });
+    expect(checkLogsRetention(ctx)).toHaveLength(0);
+  });
+
+  test("skips intrinsic RetentionInDays values", () => {
+    const ctx = makeCtx({
+      Resources: { MyLogs: { Type: "AWS::Logs::LogGroup", Properties: { RetentionInDays: { Ref: "RetentionParam" } } } },
+    });
+    expect(checkLogsRetention(ctx)).toHaveLength(0);
+  });
+
+  test("no diagnostic for non-LogGroup resources", () => {
+    const ctx = makeCtx({ Resources: { MyBucket: { Type: "AWS::S3::Bucket", Properties: {} } } });
+    expect(checkLogsRetention(ctx)).toHaveLength(0);
+  });
+});

package/src/lint/post-synth/waw055.ts

@@ -0,0 +1,49 @@
+/**
+ * WAW055: CloudWatch Logs Retention Not Set
+ *
+ * Flags Logs::LogGroup resources without RetentionInDays — an unset
+ * retention means "Never expire," which is rarely the intended cost/
+ * compliance posture.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { parseCFTemplate, isIntrinsic } from "./cf-refs";
+
+export function checkLogsRetention(ctx: PostSynthContext): PostSynthDiagnostic[] {
+  const diagnostics: PostSynthDiagnostic[] = [];
+
+  for (const [_lexicon, output] of ctx.outputs) {
+    const template = parseCFTemplate(output);
+    if (!template?.Resources) continue;
+
+    for (const [logicalId, resource] of Object.entries(template.Resources)) {
+      if (resource.Type !== "AWS::Logs::LogGroup") continue;
+
+      const props = resource.Properties ?? {};
+      const retention = props.RetentionInDays;
+
+      if (isIntrinsic(retention)) continue;
+
+      if (retention === undefined) {
+        diagnostics.push({
+          checkId: "WAW055",
+          severity: "warning",
+          message: `Log group "${logicalId}" has no RetentionInDays set — logs are kept forever by default; set an explicit retention period`,
+          entity: logicalId,
+          lexicon: "aws",
+        });
+      }
+    }
+  }
+
+  return diagnostics;
+}
+
+export const waw055: PostSynthCheck = {
+  id: "WAW055",
+  description: "CloudWatch Logs log group has no retention period set",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    return checkLogsRetention(ctx);
+  },
+};

package/src/op/activities/floci.test.ts

@@ -6,6 +6,8 @@ import {
   flociHealthUrl,
   flociEnv,
   isFlociReady,
+  FLOCI_SPEC,
+  FLOCI_EMULATOR,
 } from "./floci";
 
 describe("flociRunCommand (#704)", () => {
@@ -55,6 +57,30 @@ describe("flociHealthUrl / flociEnv (#704)", () => {
   });
 });
 
+describe("FLOCI_SPEC / FLOCI_EMULATOR — the aws plugin's emulator capability (#920)", () => {
+  test("spec pins the Floci container identity the shared lifecycle boots", () => {
+    expect(FLOCI_SPEC.name).toBe("chant-floci");
+    expect(FLOCI_SPEC.image).toBe("floci/floci:latest");
+    expect(FLOCI_SPEC.containerPort).toBe(4566);
+    expect(FLOCI_SPEC.healthPath).toBe("/_localstack/health");
+  });
+
+  test("ready predicate gates on cloudformation appearing in the health body", () => {
+    expect(FLOCI_SPEC.ready?.('{"services": {"cloudformation": "available"}}')).toBe(true);
+    expect(FLOCI_SPEC.ready?.('{"services": {"s3": "available"}}')).toBe(false);
+  });
+
+  test("capability env redirects the aws SDK at the running endpoint with test creds", () => {
+    expect(FLOCI_EMULATOR.spec).toBe(FLOCI_SPEC);
+    expect(FLOCI_EMULATOR.env("http://localhost:4566")).toEqual({
+      AWS_ENDPOINT_URL: "http://localhost:4566",
+      AWS_ACCESS_KEY_ID: "test",
+      AWS_SECRET_ACCESS_KEY: "test",
+      AWS_REGION: "us-east-1",
+    });
+  });
+});
+
 describe("isFlociReady (#704)", () => {
   test("true when the health body names the required service", () => {
     const body = '{"services": {"s3": "available", "cloudformation": "available"}}';

package/src/op/activities/floci.ts

@@ -1,4 +1,4 @@
-import { emulatorLifecycle } from "@intentius/chant/op";
+import { emulatorLifecycle, type EmulatorSpec, type EmulatorCapability } from "@intentius/chant/op";
 
 const DEFAULT_NAME = "chant-floci";
 const DEFAULT_PORT = 4566;
@@ -49,14 +49,30 @@ export function flociEnv(port: number, region: string): Record<string, string> {
 // AWS runs the LocalStack-compatible floci/floci image, so readiness is gated on
 // a service (`cloudformation`) appearing in `/_localstack/health` — unlike the
 // bespoke az/gcp fakes. Shared lifecycle: emulatorLifecycle (#746).
-const flociFor = (readyService: string) =>
-  emulatorLifecycle({
-    name: DEFAULT_NAME,
-    image: DEFAULT_IMAGE,
-    containerPort: DEFAULT_PORT,
-    healthPath: "/_localstack/health",
-    ready: (body) => isFlociReady(body, readyService),
-  });
+const flociSpecFor = (readyService: string): EmulatorSpec => ({
+  name: DEFAULT_NAME,
+  image: DEFAULT_IMAGE,
+  containerPort: DEFAULT_PORT,
+  healthPath: "/_localstack/health",
+  ready: (body) => isFlociReady(body, readyService),
+});
+
+/** The Floci emulator spec — the aws plugin's `emulator` capability (#920). */
+export const FLOCI_SPEC: EmulatorSpec = flociSpecFor(DEFAULT_READY_SERVICE);
+
+/** The aws plugin's emulator capability (#920): Floci + the AWS env that points
+ * the SDK / `chant graph --live` / a triggered Op at it. */
+export const FLOCI_EMULATOR: EmulatorCapability = {
+  spec: FLOCI_SPEC,
+  env: (endpoint) => ({
+    AWS_ENDPOINT_URL: endpoint,
+    AWS_ACCESS_KEY_ID: "test",
+    AWS_SECRET_ACCESS_KEY: "test",
+    AWS_REGION: DEFAULT_REGION,
+  }),
+};
+
+const flociFor = (readyService: string) => emulatorLifecycle(flociSpecFor(readyService));
 
 const builders = flociFor(DEFAULT_READY_SERVICE);
 

package/src/plugin.ts

@@ -14,6 +14,7 @@ import { readFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "url";
 import { awsSerializer } from "./serializer";
+import { FLOCI_EMULATOR } from "./op/activities/floci";
 import { awsReferenceCatalog } from "./reference-catalog";
 import { resolveTemplateAttrs } from "./live-attrs";
 import { CFParser } from "./import/parser";
@@ -31,6 +32,8 @@ import { awsHover } from "./lsp/hover";
 export const awsPlugin: LexiconPlugin = {
   name: "aws",
   serializer: awsSerializer,
+  // Local emulator (#920): Floci + the AWS env that redirects the SDK / observe.
+  emulator: FLOCI_EMULATOR,
   // Audit rule metadata for this lexicon's WAW* checks (#687).
   auditCatalog: () => awsAuditCatalog,
   // Live edge reconstruction for `chant graph --live` (#778).