Switch CAPE API to native Cognito User Pools authorizer

[mehalter]

Summary

Replace the custom Lambda API Gateway authorizer for the CAPE common API with a
native API Gateway Cognito User Pools authorizer, so AWS handles JWT
signature verification, expiry, and JWKS rotation instead of homegrown code.

Motivation

The current default authorizer (assets/api/authz/default_apigw_authorizer.py)
base64url-decodes the JWT payload and maps claims, but it does not verify the
token signature and effectively allows all callers. That is a security gap and
ongoing maintenance burden. A native Cognito User Pools authorizer:

• verifies the token against the user pool (signature, expiry, token_use),
• removes the need to maintain JWT verification / JWKS handling in Lambda,
• reduces the risk that login breaks due to homegrown verification bugs.

The frontend already sends Authorization: Bearer <cognito access_token>, and in
this deployment the Cognito username == email, so a human-readable
triggering_user_name is available from token claims without switching to the id
token or adding scopes.

Current state (context for whoever picks this up)

The shared ApiGateway construct assumes every authorizer is a Lambda:

• capeinfra/resources/api.py _create_api_authorizer_lambdas() iterates the
  authorizers config and, for each, builds a Lambda from
  authorizer_def["file"], a lambda role, and an API-gateway invoke role. There
  is no branch for a non-Lambda authorizer.
• _render_spec() unconditionally sets role and uri
  (handler.function.invoke_arn) into the template kwargs per authorizer.
• The OpenAPI template assets/api/capi/capi-openapi-301.yaml.j2 renders the
  securitySchemes block with x-amazon-apigateway-authtype: "custom" and
  authorizerUri / authorizerCredentials (lines ~2116-2152), plus a top-level
  security: list generated from the authorizer names.
• Config: Pulumi.cape-cod-dev.yaml / Pulumi.cape-cod-public.yaml define the
  default authorizer with type: request and file: pointing at the custom
  authorizer source.
• Handlers read identity from the custom authorizer context:
  • post_workflow_run.py reads triggering_user_id / triggering_user_name
    from event.requestContext.authorizer and writes conf.cape.
  • get_workflow_runs.py reads triggering_user_id from
    event.requestContext.authorizer.

The Cognito user pool already exists at capeinfra.meta.principals.user_pool
(see capeinfra/meta/capemeta.py), and api.py already imports the
capeinfra.meta singleton (it uses capeinfra.meta.policies), so the user pool
ARN (capeinfra.meta.principals.user_pool.arn) is reachable from the construct.

Proposed change (four sites)

1. capeinfra/resources/api.py

   • Branch the authorizer loop on authorizer_def["type"]. For
     cognito_user_pools, skip Lambda + role creation and instead record the
     provider ARN(s) (from capeinfra.meta.principals.user_pool.arn).
   • Branch _render_spec() so a cognito authorizer emits provider_arns
     instead of role/uri.
   • Keep the existing Lambda path fully intact for any non-cognito authorizer
     (backward compatible; the construct is shared by all CAPE APIs).

2. assets/api/capi/capi-openapi-301.yaml.j2

   • Add a securitySchemes variant for cognito_user_pools:
     x-amazon-apigateway-authtype: cognito_user_pools with
     x-amazon-apigateway-authorizer: { type: cognito_user_pools, providerARNs: [...] },
     and name: Authorization, in: header.

3. Pulumi.cape-cod-dev.yaml and Pulumi.cape-cod-public.yaml

   • Change the default authorizer type to cognito_user_pools and drop
     file (no Lambda source needed).

4. Handlers assets/api/capi/handlers/post_workflow_run.py and
   get_workflow_runs.py

   • Resolve identity from event.requestContext.authorizer.claims.* instead of
     the custom context:
     • triggering_user_id = claims["sub"]
     • triggering_user_name = claims.get("email") or claims.get("cognito:username") or claims.get("username")
   • Update tests/test_workflow_user_attribution.py accordingly.
   • default_apigw_authorizer.py becomes dead code; remove it (or keep only if
     we want a method-level fallback, see allow authorizer override at api method level #218).

Risks / validation

• capeinfra/resources/api.py is a shared construct used by all CAPE APIs;
  the change must stay backward compatible for the Lambda authorizer path.
• Changing the authorizer type on an existing API Gateway may force
  redeployment of the authorizer/API resources.
• Must be validated with pulumi preview / a dev deploy: confirm the API accepts
  a Cognito access token, that event.requestContext.authorizer.claims contains
  sub and username/email, and that conf.cape is still populated correctly
  on trigger.

Related

• allow authorizer override at api method level #218 allow authorizer override at api method level
• Finalize domain stability for authentication endpoints #206 Finalize domain stability for authentication endpoints
• Lock down api lamda permissions #245 Lock down api lambda permissions
• Depends-on-nothing, but pairs with the frontend work already merged (shared
  axios client sending the bearer token; per-user run listing via conf.cape).

[mehalter]

Preserve local (localhost) frontend testing after the authorizer swap

Today the custom authorizer decodes the bearer JWT without verifying issuer or
signature, so it accepts a token from any Cognito pool/client. That is what lets
local cape-frontend dev work: the frontend runs against a localhost-callback
Cognito app client (a separate app client from the deployed frontend client,
whose callback is only https://<domain>/auth/callback) while calling the
deployed dev API.

A native Cognito User Pools authorizer will validate the token against the
specific pool(s) in its providerARNs. If the localhost dev client lives in a
pool that is not one of those providers, local calls will get 401 and local
testing breaks.

Keep local testing viable by doing one of these when implementing:

• Preferred: ensure the localhost-callback app client is in the same user
  pool the authorizer validates. Because Cognito sub is per-pool, this also
  keeps the local user's sub identical to the deployed frontend's, so
  conf.cape.triggering_user_id attribution and per-user run history line up
  between local and deployed sessions. (The deployed cape-frontend
cognito_client in Pulumi.cape-cod-dev.yaml could simply add
  http://localhost:3000/auth/callback to its callback_urls instead of
  maintaining a separate client/pool.)
• Alternative: add the local dev pool's ARN as an additional entry in the
  authorizer providerARNs. This keeps tokens accepted but leaves sub
  disjoint from the deployed pool (local vs deployed run history will not share
  ownership).

Acceptance: after the swap, a developer can log in via the localhost client and
successfully trigger and list their own workflow runs against the deployed dev
API.

[mehalter]

Note from PR #353 (workflow-run attribution): both POST /workflows/trigger and GET /workflows/runs now gate on a resolvable triggering_user_id from the authorizer context and return 401 when it is absent. Because the current authorizer only decodes the JWT and does not verify the signature, that gate requires only a decodable token carrying a sub, not a cryptographically verified user.

When this issue lands (native Cognito User Pools authorizer with signature verification and requestContext.authorizer.claims), revisit those two handlers so the same gate keys off the verified claims instead of the decode-only context. No code change is expected beyond where identity is read from; the fail-closed behavior is already in place.