plan.md

Edge implementation plan

Status: accepted overall direction; individual contracts require review.

Objective

Build github.com/asteroid-computing/go-lambda-edge, with root package edge, as a new Go 1.27 module. Adapt AWS API Gateway Lambda proxy events to ordinary net/http handlers and provide complementary identity, authentication, authorization, and consumer-test packages.

Beakley was reviewed at /Volumes/home/Developer/spmt-20260905/beakley. Its requirements and observed failures inform this design. This work is not a port, source copy, or compatibility-preserving update of Beakley.

Accepted direction

• Set the module's Go baseline to 1.27.0.
• Use encoding/json/v2 directly for our event, response, JWKS, and claim JSON handling. Do not route our codec through encoding/json's compatibility API. Check third-party parser behavior separately during dependency selection.
• Keep ordinary http.Handler as the application boundary.
• Support the user's same-route goal: clients may authenticate using IAM credentials or an OAuth bearer token without requiring built-in AWS_IAM authorization. Decision 0016 accepts explicit credential selection and online STS-proof verification. Include an exported Go helper that generates the signed GetCallerIdentity proof, with consumer documentation and runnable client/server examples. Decision 0017 accepts the detailed protocol and helper/verifier APIs.
• Provide first-class consumer request-header processing for header-selected action dispatchers. Preserve custom incoming headers independently of response combination rules. Decision 0011 accepts the standard HTTP extension boundary and immutable ActionHeader selector, with explicit configuration and strict missing/ambiguous/invalid selection errors. The user approved the Go review refinements on 2026-09-15.
• Own event serialization at a raw Lambda invocation boundary implementing Invoke(context.Context, []byte) ([]byte, error).
• Reuse AWS Lambda Go event/response structs where they meet the contract; reserve custom representations for demonstrated limitations.
• Use the latest stable aws-lambda-go release, recorded explicitly in go.mod for reproducibility. On 2026-09-14, the Go module proxy and AWS GitHub releases both confirmed v1.55.0, already required here; it includes Go 1.27 compatibility.
• Support already typed events without an envelope JSON round trip inside edge. Decision 0004 accepts HandleV1 and HandleV2 with matching AWS request/response types, sharing translation and identity policy with raw invocation.
• Support REST API proxy events, HTTP API payload 1.0, and HTTP API payload 2.0. API product and payload version are distinct concepts.
• Provide separate buffered and REST streaming adapters over shared request and identity foundations. Both are implemented; deployed streaming remains unverified.
• Keep payload dispatch and the response writer private initially.
• Preserve separate IAM/JWT caller representations and an anonymous zero value; enforce invariants rather than relying on comments about a union.
• Separate token scopes, Cognito groups, and application-resolved grants.
• Preserve context-aware authorization and distinguish denial from dependency failure.
• Preserve full-fidelity claims when the selected source provides them. Do not claim to recover arrays or original numeric values from flattened data.
• Research substantive decisions and bring recommendations to the user before implementing dependent behavior. See AGENTS.md.

The user approved decision 0001, superseding the review's initial gateway-default proposal: no gateway-derived identity by default; WithGatewayIdentity(true) opts in for both IAM and JWT/Cognito. Local verification is explicitly composed. Constructor details and producer conflicts are settled in decisions 0012–0018; decision 0019 accepts the now-implemented common HTTP authentication selector. Decision 0020 accepts the now-implemented Cognito access-token verifier and JWKS cache. Decision 0021 accepts authorization rules and the consumer-owned resolution/dispatch boundary.

Planned package boundaries

Package	Responsibility
edge (root)	Invocation adapter, payload decoding, HTTP translation and optional gateway identity; metadata accessors deferred
actionheader	Strict single-value action selection from a configured request header; standard library only (decision 0026 E1)
identity	Validated callers, claim representation, context transport; standard library only
authn	Explicit IAM-proof/OAuth selection, Cognito verification and JWKS caching
iamproof	Exported client proof generator and bounded online STS verifier
authz	Exact identity predicates, ordered rules and context-aware application checks; consumers own grant resolution and HTTP dispatch
edgetest (deferred)	Revisit exported fixtures after concrete consumer needs; decision 0023

Avoid a broad root-package facade that reexports every companion type. Keep AWS event types out of transport-independent packages. Reassess any additional exported package against a concrete consumer need; version-reporting machinery does not need to precede a working adapter.

The accepted IAM client helper belongs to the module's exported Go API. Decision 0017, accepted on 2026-09-16, specifies a focused iamproof package, compact versioned proof, signed audience, short freshness policy and bounded regional STS verification. The production generator/verifier and local contract tests are now implemented. The user also approved the IAM caller forms in decision 0015. The shared caller/context foundation, gateway producers and callable buffered adapter are implemented.

Milestones and acceptance criteria

0. Persist the design and working agreement

• Create a working branch from the initial main commit.
• Record accepted direction and review findings.
• Establish decision records and review workflow.
• Resolve decision 0001 before implementing authentication defaults.

1. Specify the transport contracts

Accepted: decision 0002 settles construction, option application, and transport invocation-failure handling. Its independent constructor/options foundation is implemented while the event/HTTP contracts are reviewed. Constructor tests pass with race detection, vet and formatting checks pass, and package builds pass for Linux arm64 and amd64.

Accepted: decision 0003 settles AWS type reuse, version dispatch, structural validation, and the decoder fixture matrix. The private decoder and typed validators are implemented and tested against AWS Lambda Go v1.55.0. Decision 0004 accepts typed methods that skip envelope JSON work inside edge. These entry points await the response contract and gateway identity production before public wiring.

Accepted: decision 0005 settles request URLs, header/query merging, cookies, body handling, invocation metadata, and request ownership. Shared request conversion is implemented with local HTTP comparisons, race tests, fuzzing, vet, and Lambda-target builds passing.

Accepted: decision 0006 specifies buffered response commitment/encoding, unsupported features, payload bounds, invocation completion, and the documented multipart cleanup limit.

The accepted 2026-09-14 plan review requires response-contract refinements and completing a runnable adapter, including the minimum gateway identity foundation, before broader authentication work. These enhancements are incorporated into decision 0006. Decision 0010 settles concrete metadata/header policies, with errors and identity subsequently settled in decisions 0012–0018.

The user accepted the qualification to decision 0007: do not freeze arbitrary 64 KiB/1,024-entry metadata limits or the initial ten-field list without stronger resource and compatibility justification. Decision 0010 now accepts shared snapshots, a 25-field V2 combination audit, weighted resource accounting, and a conservative exact streaming-prefix limit. The 2026-09-15 allocation probe revised the resource policy to a 256 KiB default with an explicit positive override up to 6 MiB; the user approved it on 2026-09-15. The shared snapshot, suppression/accounting logic, V1/V2 projections, option validation and bounded streaming metadata prefix are implemented. The buffered and streaming writers now use the shared header layer. Streaming is specified in decision 0008: explicit REST response streaming alongside the buffered adapter, sharing HTTP/identity foundations. The high-level architecture is accepted. Decision 0009 accepts concrete APIs and an ownership/state graph. The private bridge and shared invocation ownership primitives are implemented. A local SDK Runtime API probe demonstrates incremental delivery, raw/typed capture, closure, and error trailers; it also exposes a bytes-plus-error reader issue and a missing header relative to AWS's documented streaming contract. The production streaming API is now implemented; deployed API Gateway behavior is not verified.

The private bridge publishes an owned prefix through an explicit handoff before body writes can block, uses an unbuffered pipe, and transfers cleanup to one producer. Close and parent cancellation release blocked I/O; terminal reads and Close join cleanup and error reporting. Early panics are rethrown at entry, late panics become sanitized terminal errors, and reader results defer errors that accompany bytes. Synthetic concurrency tests cover these boundaries and reporter failures. Full race tests (including the existing SDK probe), vet, formatting, and Linux arm64/amd64 builds pass on Go 1.27.1. HTTP streaming commitment, sniffing, framing validation, and public entry points are now implemented under the subsequent writer review.

The 2026-09-17 streaming writer review confirms the approved state/ownership graph against completed authn/authz and the current AWS/Go documentation. The user approved S1 (no automatic streaming Content-Length) and S2 (shared sniffing behavior for empty Content-Encoding) on 2026-09-17 and authorized implementation. SDK v1.55.0 remains latest stable. Local probes reconfirm incremental delivery and the missing streaming-mode header, and additionally observe Runtime API connection reuse, another difference from the custom-runtime guide. Retain the existing deployment release gate for both observations; no live AWS test has run. The streaming writer, NewStreaming, Handle, HandleV1 and WithStreamErrorReporter are implemented. Shared request preparation preserves buffered behavior, identity policy and request cleanup. The SDK probe now drives the production adapter in raw/typed and late-error/panic cases, observes body delivery before producer completion and checks reader closure before reuse. Runnable SSE, direct JSON v2 NDJSON, binary and gzip examples accompany the consumer guide. Authentication/authorization integration tests cover both streaming entry points. Full module race tests, vet, formatting and Linux arm64/amd64 builds pass locally on Go 1.27.1.

The SDK documentation follow-up reconfirmed latest stable versions and reproduced the transport observations with the SDK's own REST streaming response type. Ten local SDK probe cases now pass. It records the evidence and questions prepared for the user's AWS outreach; the deployment qualification remains open.

Implemented under decision 0006: bounded direct JSON v2 envelope encoding, text/base64 body selection, and a shared invocation scope that preserves primary errors, cleans up on failures/panics, and checks parent cancellation. The HTTP writer now uses the shared header implementation from decision 0010, enforces commitment and body/length/status rules, and returns typed AWS response projections without JSON work. Tests compare ordinary behavior with net/http and exercise request conversion, mux/range/gzip handling and invocation cleanup. Public buffered wiring subsequently completed with the identity contracts. Initial codec benchmarks record allocation baselines; they do not establish a peak-memory bound.

Research and present a contract covering:

• Raw invocation API, constructor/options, configuration validation, and errors.
• Discrimination between all three supported event cases; reject unsupported versions and malformed shapes without fallback to a different format.
• Strict JSON v2 handling of duplicate names and invalid UTF-8, with tolerance for additional AWS fields.
• V1 decoded paths versus V2 raw paths, escaped segments, query representation, custom-domain mappings, and information that AWS does not preserve.
• Headers and multivalue precedence per key, cookies, host, protocol, RequestURI, source address, body decoding/length/cleanup, and context lifetime.
• Status commitment, header snapshots, implicit responses, content-type detection, HEAD/bodyless statuses, informational responses, trailers, and accurately advertised optional ResponseWriter capabilities.
• Binary response selection and REST API deployment requirements; response-size limits, including base64 and JSON-envelope overhead.
• Separation of HTTP application outcomes from invocation/translation faults.

Acceptance: a reviewed contract and fixture matrix exist before the corresponding behavior is implemented. Resolve smaller decisions incrementally rather than presenting an entire frozen public API at once.

2. Implement and prove the HTTP adapter

• Create the Go 1.27 module and constructor/options foundation after review.
• Implement the private decoder and typed semantic validators with direct JSON v2, SDK types, opaque authorizer data, fixtures, and fuzzing.
• Implement shared HTTP request conversion and request-lifetime cleanup.
• Implement the accepted action-header selector with ordinary HTTP middleware examples and native HTTP/raw/typed Gateway request contract tests.
• Implement shared response-header snapshots, budget configuration, V1/V2 projections and bounded REST streaming metadata prefix encoding.
• Implement the private buffered HTTP writer and gateway response conversion.
• Implement accepted public error categories and sanitized diagnostics across existing private stages, including cleanup and streaming bridge faults.
• Implement bounded envelope/body encoding and shared invocation cleanup.
• Extract shared invocation ownership and implement the private streaming bridge, with handoff, backpressure, cancellation, cleanup, and error tests.
• Implement the streaming HTTP writer, raw/typed REST entry points, reporter, examples and authentication/authorization integration tests under 0022.
• Resolve the streaming SDK deployment qualification through authoritative clarification, a suitable stable SDK fix or a separately approved live test.
• Implement the minimum reviewed identity/context and native gateway producers needed to honor WithGatewayIdentity(true) before publishing invocation.
• Implement raw invocation after the remaining transport contracts are reviewed.
• Implement the accepted typed entry points after shared HTTP translation review, documenting upstream codec ownership.
• Implement the adapter from scratch using JSON v2 directly.
• Test raw invocation through the actual pinned AWS Lambda Go SDK boundary.
• Add runnable raw/typed registration examples, sequential/concurrent invocation isolation checks, and ServeMux, Redirect, ServeContent/Range, compression, and cookie integration cases.
• Exercise documented event fixtures and adversarial/malformed input.
• Compare relevant request/response behavior with real net/http serving, documenting unavoidable transport differences.
• Fuzz decoding and path/query conversion; add targeted allocation benchmarks.
• Run appropriate tests, race detection, vet, and Lambda-target build checks.
• Put those checks in Go 1.27 CI and establish raw/typed, binary, and near-limit allocation baselines before setting performance thresholds.

CI configuration is present for Go 1.27.0/latest 1.27 patch tests, race detection, vet, and Lambda-target builds. It has not run on GitHub yet. Local Go 1.27.1 race tests, vet, formatting checks, and both target builds pass for both public adapters. SDK registration, gateway recognition/fidelity, owned claims, concurrent identity isolation, multipart cleanup, panic/cancellation and raw envelope limits are exercised. Runnable examples and initial public allocation benchmarks are present. HTTP 1.0 authentication coverage is explicitly qualified in the fixture inventory; no live deployment was exercised.

Acceptance: the same application handler behaves as specified across all three event cases; no auth or codec behavior depends on accidental SDK dispatch.

3. Identity and gateway producers

Design graph prepared on 2026-09-15 in decision 0012, with public invocation errors in decision 0013. The user accepted both records as a starting point on 2026-09-15. The deferred claim API, resource limits and native-producer coverage were subsequently resolved in decisions 0014–0018. The accepted order is caller/context/error foundations, precise claim API and native-producer fixtures, then raw/typed buffered invocation. Broader local authentication and authorization follow that shared foundation.

Decision 0014, accepted on 2026-09-16, specifies the claims constructor/accessor surface, SDK number-preserving input compatibility, ownership and weighted resource limits, and gateway normalization qualifications. The user approved its SDK numeric compatibility and gateway qualifications and authorized implementation. Claims constructors, immutable accessors, strict raw JSON and direct typed construction, byte/depth limits, and sanitized errors are implemented. The adapter budget option is validated and a private invocation-error translation boundary is tested and now wired through gateway extraction and public invocation under decision 0018. Production allocation measurements supplement the original probe. Contract tests, SDK integration, race detection, vet, JSON fuzzing and Lambda-target builds pass. Caller/context construction, JWT normalization and dedicated-scope accounting are now implemented after approval of decision 0015 and 0017. IAM literal path punctuation follows the user's approved refinement. The private invocation guard rejects inherited callers. Full race tests, vet, formatting and Linux arm64/amd64 builds pass. Native-producer fixture review was approved in decision 0018 on 2026-09-16. Native extraction and buffered public invocation wiring are now implemented and tested. Custom-authorizer mapping remains a later explicit design; it is not silently treated as native identity.

• Review caller constructors, immutable/owned data, validation, anonymous state, and context-presence semantics.
• Preserve issuer plus subject for JWT application identity; do not treat a bare subject as globally unique or assume every M2M caller has a user subject.
• Keep audience, app client, token use, and provenance distinct.
• Implement the approved opt-in gateway policy for native JWT/Cognito and IAM.
• Review custom-authorizer mapping for both payload families, including context, error returns, provenance, and conflicts between identity sources.
• Expose only the gateway metadata handlers actually need, separately from authenticated identity. Do not synthesize cryptographic guarantees from it.

Acceptance: invalid/ambiguous identities cannot authorize; gateway and token claims cannot be silently mixed; unavailable claim fidelity remains explicit.

4. Local authentication: Cognito/JWKS and IAM credentials

The implemented HTTP authentication design is recorded in accepted decision 0019: shared HTTP selection, explicit verifier dependencies, header limits, context composition, error interoperability and challenges. The user approved A1-A6 on 2026-09-16; authn configuration, selection, errors, middleware and examples are implemented. The IAM proof package remains independently usable.

• Implement the accepted protocol/helper/verifier contract in decision 0017 after the shared foundation and callable buffered adapter. Production iamproof uses SDK core v1.47.0 and STS v1.51.0, rechecked as latest stable on 2026-09-16. The consumer guide covers credential ownership, endpoints, replay/limits, error handling and the remaining integration qualifications.
• Implement the shared HTTP selector and challenges under decision 0019, preserving the proof, provenance, binding, replay, endpoint and error contracts. Configuration and verifier functions are explicit, with an SDK-independent package and consumer-owned action dispatch and authorization. The authn guide documents IAM error mapping, header bounds, cancellation and custom JSON response handling.
• Provide exported Go proof generation and consumer documentation with runnable examples showing IAM and OAuth clients calling the same protected route. IAM generation, selector/dispatcher examples and local mixed-identity contract tests now exist. The original selector example still labels its synthetic Bearer function; Cognito configuration examples and actual RS256 verification now accompany it. Deployed interoperability remains unverified.

The authn milestone passes full module race tests, vet, formatting checks and Linux arm64/amd64 builds on Go 1.27.1. Authorization-parser fuzzing completed 726,457 executions without failures. Native in-memory HTTP and raw/typed Gateway fixtures verify challenges and IAM-helper composition with local STS fixtures. No live AWS or GitHub CI run was performed for these changes.

• Decision 0020 records the accepted Cognito access-token verifier/JWKS design, reviewed against AWS documentation, current identity/authn code and current stable Go JWT libraries on 2026-09-16. It specifies direct JSON v2 plus stdlib RS256, per-client resource binding and explicit unbound allowances for M2M/SDK flows, and bounded on-demand key caching. The user approved C1-C7 on 2026-09-16; the verifier/cache are implemented.
• Require explicit issuer/client restrictions; there is no implicit all-client policy. Constructors perform no I/O and own their client configuration.
• Keep access-token client_id, ID-token audience, and access-token resource audience validation separate. Preserve access-token-only defaults unless deliberately widened.
• Implement reviewed algorithm/key selection, expiry/not-before/issued-at behavior, leeway and malformed claims. Own JSON v2 parsing and use stdlib RSA.
• Separate cache freshness, unknown-key refresh, and failure backoff.
• Bound network duration and JWKS response size. Define stale-key behavior, rotation, concurrency, waiter cancellation, and HTTP client ownership.
• Use deterministic cache/rotation/outage tests with testing/synctest and native in-memory HTTP integration, plus an independent RFC RS256 vector.

The Cognito milestone passes full race tests, vet, formatting and Linux arm64/amd64 builds on Go 1.27.1. Final fixed-fixture fuzz runs completed 136,129 token cases and 280,903 JWKS cases without failures. Production authn remains stdlib/identity-only. The Cognito guide documents configuration, resource binding, cache ownership and offline-verification limitations. There was no live AWS or GitHub CI run.

Acceptance: malformed credentials fail closed, failures do not create fetch storms, and dependency outages remain distinguishable from invalid credentials.

5. Authorization and consumer ergonomics

Decision 0021, approved on 2026-09-17, accepts the initial authz API and design graph: immutable rules over explicit caller, action and resource facts, exact predicates and ordered combinators. Application principal/grant resolution and HTTP dispatch initially remain consumer-owned through context-aware custom checks and runnable examples. Z1–Z7 are implemented and locally validated. Production authz uses only the standard library and identity.

• Implement immutable checks, ordered All/Any, explicit action/resource requests, exact JWT/source/IAM predicates and bounded policy trees.
• Preserve scope/group/grant separation and consumer-owned principal resolution through context-aware custom checks.
• Document/test 401, 403 and 503 boundaries, safe Bearer challenges and cancellation. Public routes bypass protected-route authorization explicitly.
• Match exact caller ARNs and explicit role-session families, including partition/account/path boundaries and role-name recreation limitations.
• Reject zero/empty/nil rules and anonymous callers; sanitize callback errors.
• Provide consumer fixtures, runnable examples and the authorization guide. Logging hooks and a generic exported principal/grant resolver remain deferred under decision 0021.

Full race tests, vet, formatting and Linux arm64/amd64 builds pass on Go 1.27.1. Policy fuzzing completed 45,257 cases without failure. Native HTTP and five raw/typed Gateway paths exercise authorization after Cognito signature and IAM proof verification using local synthetic provider responses. Tests cover grant denials/outages, provider call counts, immutable action/resource selection, safe responses and cancellation. No live AWS or GitHub CI run occurred.

Acceptance: examples work both in Lambda and ordinary HTTP applications, while authorization decisions remain inspectable and deny by default.

6. Consumer readiness and release preparation — local work complete

The user authorized a consumer-readiness design review on 2026-09-20. Decision 0023 records the code/documentation evidence, the Beakley failure-case coverage matrix and recommendations R1–R6. The user approved R1–R5 on 2026-09-20, including deferring exported edgetest helpers. The owner resolved R6 on 2026-10-02: Apache-2.0, with Andrew Beck as copyright holder.

• Review public composition, existing examples, fixture provenance, deferred features, package dependencies and CI/release readiness.
• Approve R1–R5: complete reference application, deferred edgetest exports, consumer outcomes, precise support matrix and v0 preparation. R6 (license) was resolved on 2026-10-02.
• Implement the reference application and consumer-testing guide using the existing public APIs, with local provider fixtures.
• Reconcile support/status documentation, update the indirect Smithy patch in isolation, and record incremental streaming baselines.
• Obtain actual GitHub CI evidence for the foundation PR; all four jobs passed at f6a2624. Later commits require their own passing checks.
• Verify the main release workflow and resolve publication prerequisites before a release. v0.1.0 was released on 2026-10-02. Streaming deployment and live identity interoperability remain separate qualifications.

The complete dispatcher, testing guide, support matrix and release checklist are implemented. Local RSA/JWKS and synthetic STS fixtures exercise both credentials; streaming lifecycle tests consume incrementally. The external-module check and CI wiring are present. Smithy is updated to v1.28.2, and streaming allocation baselines are recorded. No library API or transport policy changed.

Full local race tests, vet, module verification, formatting, external consumption and Linux arm64/amd64 builds pass on Go 1.27.1 (2026-09-21). The subsequent authorized push and passing PR CI are recorded below. The deployment qualifications remain open; no release publication or AWS deployment occurred.

Release automation follow-up (2026-09-21): the user selected Release Please and its GitHub Action, plus checks on PRs against main. Decision 0024 records the approved GitHub App credential and initial v0.1.0, with pre-major versioning. The original main-validation dependency is superseded by the 2026-09-27 user direction: Go validation runs on PRs only, including release PRs; main pushes run only release automation. Local wiring and validation are complete: both workflows pass actionlint, release JSON passes the bundled schema, and existing Go jobs are unchanged. See the release guide.

Subsequent authorized setup and publication of the working branch are complete: the new App Client ID and private key are configured as organization Actions secrets with access granted to this repository, and PR #1 merged at 24f7686 on 2026-09-27. The PR run at f6a2624 passed both Go test jobs and both Linux build jobs, verified on 2026-09-27. The action review verified all four latest stable releases and pinned checkout/setup-go to their release commits; those aliases already selected the same versions. App installation initially blocked the main run with a 404 during repository lookup. The owner subsequently installed astrocompute-release-please; read-only checks confirmed the new credentials and repository installation permissions. Both organization secrets and their repository access are verified, and the old repository credentials have been removed. The workflow now reads both values from secrets. Token creation and Release Please execution still need a successful run after merge. No release was published, and the deployment qualifications remain open. Release Please has since run successfully and opened the v0.1.0 release PR; the license was chosen on 2026-10-02.

7. Pre-release exported API alignment

Decision 0026 reviewed every exported identifier against Google's Go style guidance. The owner approved E1–E6 and rejected E7 on 2026-09-27, with one stacked PR per item. Behavior, error semantics and trust boundaries do not change; these are placement, naming, typing and documentation changes made before the first release.

• E1: move the action-header selector to the standard-library-only actionheader package as Selector/NewSelector.
• E2: rename the moved sentinels to ErrMissing, ErrAmbiguous and ErrInvalid.
• E3: rename identity.WithCaller to identity.NewContext.
• E4: type the InvocationError operation and limit names with exported constants.
• E5: add String methods to the identity enumerations.
• E6: complete sentinel docs, doc links, callback parameter names and Claim.Bool result names.

Acceptance: each PR passes the full AGENTS.md validation set, and examples, guides and the external consumer check use the new names.

Findings carried forward from the Beakley review

These are requirements to test independently, not instructions to preserve old implementation structure.

1. Unverified header JWTs were reconciled using only sub and client_id. A probe admitted altered groups with an invalid signature when modeling a gateway/adapter identity-source mismatch. This is conditional on that mismatch, not a demonstrated bypass of a correctly aligned native JWT authorizer.
2. Repeated final WriteHeader calls replaced the committed status, and header changes after commitment appeared in output. Both reproduced.
3. V1 path /a?b#c was interpreted as path, query, and fragment rather than as the supplied path. Reproduced.
4. V1 helpers discarded single-value maps wholesale when multivalue maps were nonempty. Host lookup and request metadata also need defined semantics.
5. A caller with both IAM and JWT arms could satisfy both rule conditions. Reproduced; validation was not consistently enforced.
6. Cold JWKS failures bypassed the refetch floor: three immediate calls produced three network requests. Reproduced. Outage and cancellation behavior need explicit contracts beyond the existing successful-cache tests.
7. An attached anonymous identity prevented subsequent bearer verification. Existing tests codified that behavior; the new composition policy must be deliberate rather than inherited.
8. path.Match permits wildcards across colons, contrary to the old ARN-matching comment. Synthetic IAM-role examples are insufficient for role-session cases.
9. Client ID and audience were conflated, and verifier construction allowed any client in the issuer's pool unless explicitly restricted.

Validation performed during review: the old suite passed with -race in a temporary copy after changing only its Go directive to 1.27. The original 1.26 directive triggered Go 1.27's standard-library version checks for JSON v2. The SDK serialization-boundary probe passed on Go 1.27. No live AWS integration was deployed or exercised, and the Beakley repository was not edited.

Official references

• Go 1.27 release notes
• JSON v2
• HTTP ResponseWriter
• AWS Lambda Go Handler
• API Gateway HTTP API payload formats
• Gateway JWT validation
• Gateway IAM authorization
• Cognito resource binding
• REST API binary media