feat(apigateway): AWS-service integration builder (#270)

[laazyj]

Closes #270.

What

Adds awsServiceIntegration(service, action) — a first-class integration for direct API Gateway → AWS service calls (DynamoDB, SQS, S3, …) that owns its credentials role and is a consumer-side grantee, implementing the pattern ADR-0013 deferred to #270.

const scan = awsServiceIntegration("dynamodb", "Scan")
  .requestTemplates(ref("table", (r) => ({ "application/json": scanTemplate(r.table.tableName) })))
  .grant(tableGrants.read(ref("table", (r) => r.table))); // owns role; grantee

compose(
  { table: createTableBuilder(), api: createRestApiBuilder().addResource("gadgets", (g) => g.addMethod("GET", scan)) },
  { table: [], api: ["table"] }, // api → table; no reverse edge, no cycle
);

Why

addMethod previously accepted only a fully user-constructed Integration, so an AwsIntegration's credentialsRole — the identity API Gateway assumes to call the service — had no owner in the builder surface and could not be a grantee. This mirrors FunctionBuilder owning its execution role: you .grant(...) and it routes onto the owned role.

How

• New branded builder (aws-service-integration.ts): creates a least-privilege role assumed by apigateway.amazonaws.com, sets it as the integration's credentialsRole, resolves its target via a single ref, and exposes .grant(...) backed by a GrantQueue<IGrantable> applied to that role. The grant is declared on the consumer, so the compose edge stays consumer → resource.
• Plug-in seam: RestApiBuilder.addMethod accepts the branded integration; ResourceBuilder.applyTo detects the Symbol.for brand and builds it under the method's resource scope (rather than the plain resolve path, since it needs a build-time scope for its role).
• Result completeness: the owned role is surfaced on RestApiBuilderResult.integrationRoles, keyed by "{path} {method}" (e.g. "/gadgets GET").

AWS Well-Architected

• Least privilege by construction — the role starts empty; every permission comes from an explicit .grant(...).
• Confused-deputy mitigation, default on — an aws:SourceArn trust condition scopes the role to the owning API. Overridable via .restrictToApi(false), .configureRole, or an external .role(ref).

AWS recommended alarms

Adds the AWS-recommended IntegrationLatency alarm (p90, 2000 ms) to the shared REST API alarm set, on by default — the meaningful backend-latency signal for a direct AWS-service integration (no Lambda hop). Overridable/disablable like the other recommended alarms. Example-app snapshots updated accordingly.

Scope / notes

• Scoped to RestApiBuilder (resource-tree). SpecRestApiBuilder (OpenAPI-driven) has no addMethod/ref path and is unchanged.
• No ADR or combine() core utility in this PR — kept as a focused, internal apigateway change.
• @composurecdk/iam added as a peer/dev dependency (mirrors @composurecdk/lambda).

Testing

15 new unit/synth tests (100% function / line coverage on the new file); covers the integration/role shape, confused-deputy default + opt-out, integrationRoles surface, compose + grant + ref resolution, external-role override, mutual-exclusivity, missing-ref failure, .copy() sharing, all fluent options, and the IntegrationLatency alarm. npm run verify green across all 21 projects.

🤖 Generated with Claude Code

[laazyj]

This becomes a lot. Although I can imagine a situation where each method in a RestApi might use a distinct role - it seems like an extreme security case, in which I doubt that auto-created roles would be preferable over explicitly defined roles.

It looks like the main functionality provided by was-service-integration.ts is to auto-create associated IAM roles and plumb them in. This is not a big value-add and arguably obscures important parts of the system design. In contrast with something like FunctionBuilder where the composureCDK builder is emulating aws-cdk-lib functionality by auto-creating a role, this is adding obfuscation where aws-cdk-lib doesn't already have it.

I think this demonstration illustrates that the option B, as imagined in #270, is misplaced making the option C (combine()) approach look much better.

[laazyj]

Do the brand and the type checker function need to be exported from the module? They feel like internal implementation details that consumers should not depend on.

[laazyj]

there is no action prop - what is this mutually exclusive with?

[laazyj]

#302 demonstrates the accepted, alternate, approach