From 8b44fb3b031276105cc0763de0eda89dd3523150 Mon Sep 17 00:00:00 2001 From: AJ Beck Date: Sun, 27 Sep 2026 07:17:51 +0100 Subject: [PATCH 1/3] docs: expand repository agent guidelines --- AGENTS.md | 189 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 151 insertions(+), 38 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 366a4a6..1babc20 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,42 +1,155 @@ -# Working agreement +# Repository Guidelines -Build a new Go module from first principles. Beakley is reference material for -requirements and failure cases, not a source to copy and update. +## Purpose and working agreement -The planned root package is `edge`. Target Go 1.27 from the start and use -`encoding/json/v2` directly for JSON handled by this module. +Build `github.com/asteroid-computing/go-lambda-edge` from first principles. The +root package is `edge`; ordinary `http.Handler` is the application boundary. +Beakley is reference material for requirements and failure cases, not source or +tests to copy, nor a compatibility target. Read [the implementation plan](docs/plan.md) and relevant -[decision records](docs/decisions/README.md) before work. Preserve the distinction -between accepted direction, proposed API details, and implemented behavior. - -## Decisions and user review - -When a substantive question, design decision, or issue arises: - -1. Inspect our code and tests and consult the relevant official documentation. - Route AWS knowledge lookups through `aws-proxy-public`; do not use account - APIs for documentation research. Use official Go documentation and the - supplied Go skills when applicable. -2. Record the evidence, alternatives, recommendation, reasoning, and consequences - in a decision record. Label unverified assumptions and open questions. -3. Present the question or issue and the recommendation to the user for review. -4. Await the user's approval or redirection before implementing the dependent - behavior. Continue useful independent work within the accepted plan. -5. Record the user's resolution and update the plan before implementing it. - -Do not interpret silence as approval. Routine execution within an approved -decision does not require another approval. Do not silently settle public API, -trust-boundary, compatibility, or error-policy decisions. - -## Implementation and validation - -- Work on a working branch, not `main`. -- Keep transport, identity, authentication, and authorization responsibilities - distinct. Keep `identity` free of AWS dependencies. -- Preserve denied-by-default authorization and validate identity invariants. -- Test external contracts rather than mirroring implementation details. -- Use recorded/synthetic events and local test servers; do not deploy resources - or invoke live AWS services merely to run unit tests. -- Keep documentation and decision status accurate as work progresses. -- Do not copy Beakley source or tests into this repository. +[decision records](docs/decisions/README.md) before work. Use the +[support matrix](docs/support.md) to distinguish implemented behavior, deferred +scope and deployment qualifications. Keep accepted direction, proposed API +contracts and implemented behavior clearly separated. + +## Repository map + +- Root Go files: raw/typed Lambda adapters, Gateway event decoding, HTTP request + translation, buffered/streaming responses, gateway identity and action headers. +- `identity/`: immutable callers, owned claims and context transport; standard + library only, with no AWS dependencies. +- `authn/`: credential selection, HTTP authentication middleware, Cognito token + verification and JWKS caching. +- `iamproof/`: exported signed STS GetCallerIdentity proof generator and verifier. +- `authz/`: identity predicates, ordered rules and application grant callbacks. + Consumers own grant resolution, action registries and HTTP dispatch. +- `examples/dispatcher/`: complete application with native HTTP, buffered Lambda + and streaming Lambda entry points; application details stay in its `internal/`. +- Tests live beside code in `*_test.go`; `testdata/` contains fixtures and the + external consumer source. `scripts/check-consumer.sh` tests public imports from + a temporary, separate module. +- `docs/`: guides, evidence, benchmarks, plan and decisions. The nested module in + `docs/probes/iamproof/` is historical research, outside root `go test ./...`. +- `.github/workflows/`: PR validation and Release Please. Release configuration + lives in `release-please-config.json` and `.release-please-manifest.json`. + +## Local commands and CI + +Use Go 1.27 or later, preserving the `go 1.27.0` baseline. Run commands from the +repository root. There is no Makefile or required custom commit helper. + +| Task | Command | +| --- | --- | +| Format changed Go files | `gofmt -w ...` | +| Check repository formatting | `gofmt -l .` (expect no output) | +| Focused package test | `go test ./authn -run TestName` (choose the affected package/test) | +| Full race suite | `go test -race ./...` | +| Static checks | `go vet ./...` | +| Dependency integrity | `go mod verify` | +| External consumer check | `sh scripts/check-consumer.sh` | +| Linux arm64 build | `GOOS=linux GOARCH=arm64 CGO_ENABLED=0 go build ./...` | +| Linux amd64 build | `GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build ./...` | +| Workflow lint | `actionlint .github/workflows/go.yml .github/workflows/release-please.yml` | +| Whitespace check | `git diff --check` | + +Start with checks relevant to the change. For Go changes, complete the applicable +race, vet, module, consumer and cross-build checks before handoff. Documentation +edits need link/path and whitespace checks; workflow edits need actionlint. Do +not rerun the full Go suite for documentation-only changes without a reason. +Report what ran and any unverified checks. + +PR CI tests Go 1.27.0 and the latest 1.27 patch, and builds both Linux +architectures. Go validation runs on PRs against `main`, including release PRs. +Main pushes run release automation only; do not reintroduce duplicate post-merge +validation without user direction. + +## Go conventions and package boundaries + +- Use `encoding/json/v2` and `encoding/json/jsontext` directly for module-owned + JSON. Do not use the JSON v1 compatibility codec. Recognition of the v1 + `json.Number` type for SDK-supplied values is an existing interoperability case. +- Follow surrounding Go naming and error conventions; document exported APIs + and provide runnable examples where they help consumers compose the packages. +- Keep transport, identity, authentication and authorization separate. Do not + turn the root package into a facade reexporting all companion types. +- Preserve gateway identity as explicit opt-in, validated caller invariants, + immutable claims and deny-by-default authorization. Identity construction is + not credential verification or permission assignment. +- Distinguish HTTP responses from invocation failures, and denial from dependency + failure. Preserve cancellation, resource bounds, cleanup and error sanitization. +- Prefer AWS SDK types when they meet the accepted contract. Keep raw and typed + adapter behavior aligned without adding an envelope JSON round trip to typed + entry points. API product and Gateway payload version are separate concepts. +- Check official Go documentation and the supplied Go release-notes/API skills + when applicable. Verify latest stable dependency/action releases with upstream + sources when updating them; retain reproducible module versions and action + commit pins with version comments. + +## Tests and evidence + +- Exercise observable contracts and failure cases, not private implementation + details. Use the standard testing package, local HTTP test servers and + recorded/synthetic events; document fixture provenance and fidelity limits. +- Cover malformed input, ambiguous credentials, denied access, dependency errors, + cancellation and cleanup where relevant. Streaming tests should consume data + incrementally and exercise handoff and terminal failures. +- Prefer public-package examples and the external consumer check for API changes. + Root tests do not run nested research modules; run those explicitly only when + relying on their evidence. +- Do not deploy resources or invoke live AWS services merely to run unit tests. + Live interoperability work needs a separately approved scope. Local tests do + not establish deployed streaming, Cognito or STS compatibility; keep evidence + qualifications accurate in the support and release-readiness documentation. + +## Design decisions and user review + +When a substantive question, design decision or issue arises: + +1. Inspect our code and tests and consult relevant official documentation. Route + AWS knowledge lookups through `aws-proxy-public`, not account APIs. Use + official Go documentation and the supplied Go skills when applicable. +2. Record evidence, alternatives, recommendation, reasoning and consequences in + a decision record. Label unverified assumptions and open questions; maintain + the decision index. +3. Present the issue and recommendation to the user for review. +4. Await approval or redirection before implementing dependent behavior. Continue + useful independent work within the accepted plan. +5. Record the resolution and update the plan before implementation. + +Silence is not approval. Routine execution within an approved decision needs no +additional approval. Do not silently settle public API, trust-boundary, +compatibility or error-policy decisions. + +## Branches, commits and releases + +- Work on a working branch, never directly on `main`. Inspect the working tree + first; preserve unrelated edits and editor files. Stage only intended files. +- Keep commits focused and use Conventional Commits. Use `feat:` for features, + `fix:` for fixes and `docs:`/`ci:` for their actual scope; do not relabel routine + maintenance merely to force a release. +- PR descriptions should explain the resulting behavior, validation and material + limitations. For a review request, inspect with `gh pr view` and `gh pr diff` + before deciding whether any checkout or edits are needed. +- Prefer squash merges with a Conventional Commit title. Creating or updating a + PR does not authorize merging it or publishing a release. +- Release Please owns the changelog, release manifest, tags and release PRs; + do not manually create an Unreleased changelog section or force versions unless + directed. It considers unreleased history, not just the newest commit. +- Follow [the release guide](docs/releases.md) and + [readiness checklist](docs/release-readiness.md). The initial version is 0.1.0; + features/breaking changes bump minor during v0, fixes bump patch, and moving to + v1 requires an explicit decision. Merging a release PR authorizes publication. + +## Credentials and configuration + +- Never commit or print private keys, access tokens, bearer credentials or signed + IAM proofs. Keep fixtures synthetic and sanitize diagnostic output. +- Release automation uses organization Actions secrets + `RELEASE_PLEASE_CLIENT_ID` and `RELEASE_PLEASE_PRIVATE_KEY`, granted to this + repository. Avoid same-name repository secrets that override organization values. +- Keep the release App token scoped to the current repository and required + permissions. PR validation needs no App credentials. Do not substitute a + different credential or broaden access to work around a configuration failure. +- Keep application configuration and credential handling in consumer code; + examples and docs must make deployment responsibilities explicit. From e350965f6091c2642d0a0ec747f1471ba9381e80 Mon Sep 17 00:00:00 2001 From: AJ Beck Date: Sun, 27 Sep 2026 07:29:53 +0100 Subject: [PATCH 2/3] docs: apply semantic line breaks to agent guidelines --- AGENTS.md | 229 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 134 insertions(+), 95 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 1babc20..9d03542 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,42 +2,51 @@ ## Purpose and working agreement -Build `github.com/asteroid-computing/go-lambda-edge` from first principles. The -root package is `edge`; ordinary `http.Handler` is the application boundary. -Beakley is reference material for requirements and failure cases, not source or -tests to copy, nor a compatibility target. +Build `github.com/asteroid-computing/go-lambda-edge` from first principles. +The root package is `edge`; +ordinary `http.Handler` is the application boundary. +Beakley is reference material for requirements and failure cases, +not source or tests to copy, nor a compatibility target. Read [the implementation plan](docs/plan.md) and relevant -[decision records](docs/decisions/README.md) before work. Use the -[support matrix](docs/support.md) to distinguish implemented behavior, deferred -scope and deployment qualifications. Keep accepted direction, proposed API -contracts and implemented behavior clearly separated. +[decision records](docs/decisions/README.md) before work. +Use the [support matrix](docs/support.md) to distinguish implemented behavior, +deferred scope and deployment qualifications. +Keep accepted direction, +proposed API contracts and implemented behavior clearly separated. ## Repository map -- Root Go files: raw/typed Lambda adapters, Gateway event decoding, HTTP request - translation, buffered/streaming responses, gateway identity and action headers. -- `identity/`: immutable callers, owned claims and context transport; standard - library only, with no AWS dependencies. -- `authn/`: credential selection, HTTP authentication middleware, Cognito token - verification and JWKS caching. -- `iamproof/`: exported signed STS GetCallerIdentity proof generator and verifier. +- Root Go files: raw/typed Lambda adapters, Gateway event decoding, + HTTP request translation, buffered/streaming responses, + gateway identity and action headers. +- `identity/`: immutable callers, owned claims and context transport; + standard library only, with no AWS dependencies. +- `authn/`: credential selection, HTTP authentication middleware, + Cognito token verification and JWKS caching. +- `iamproof/`: exported signed STS GetCallerIdentity proof + generator and verifier. - `authz/`: identity predicates, ordered rules and application grant callbacks. Consumers own grant resolution, action registries and HTTP dispatch. -- `examples/dispatcher/`: complete application with native HTTP, buffered Lambda - and streaming Lambda entry points; application details stay in its `internal/`. -- Tests live beside code in `*_test.go`; `testdata/` contains fixtures and the - external consumer source. `scripts/check-consumer.sh` tests public imports from - a temporary, separate module. -- `docs/`: guides, evidence, benchmarks, plan and decisions. The nested module in - `docs/probes/iamproof/` is historical research, outside root `go test ./...`. -- `.github/workflows/`: PR validation and Release Please. Release configuration - lives in `release-please-config.json` and `.release-please-manifest.json`. +- `examples/dispatcher/`: complete application with native HTTP, + buffered Lambda and streaming Lambda entry points; + application details stay in its `internal/`. +- Tests live beside code in `*_test.go`; + `testdata/` contains fixtures and the external consumer source. + `scripts/check-consumer.sh` tests public imports + from a temporary, separate module. +- `docs/`: guides, evidence, benchmarks, plan and decisions. + The nested module in `docs/probes/iamproof/` is historical research, + outside root `go test ./...`. +- `.github/workflows/`: PR validation and Release Please. + Release configuration lives in `release-please-config.json` and + `.release-please-manifest.json`. ## Local commands and CI -Use Go 1.27 or later, preserving the `go 1.27.0` baseline. Run commands from the -repository root. There is no Makefile or required custom commit helper. +Use Go 1.27 or later, preserving the `go 1.27.0` baseline. +Run commands from the repository root. +There is no Makefile or required custom commit helper. | Task | Command | | --- | --- | @@ -53,103 +62,133 @@ repository root. There is no Makefile or required custom commit helper. | Workflow lint | `actionlint .github/workflows/go.yml .github/workflows/release-please.yml` | | Whitespace check | `git diff --check` | -Start with checks relevant to the change. For Go changes, complete the applicable -race, vet, module, consumer and cross-build checks before handoff. Documentation -edits need link/path and whitespace checks; workflow edits need actionlint. Do -not rerun the full Go suite for documentation-only changes without a reason. +Start with checks relevant to the change. +For Go changes, complete the applicable race, vet, module, +consumer and cross-build checks before handoff. +Documentation edits need link/path and whitespace checks; +workflow edits need actionlint. +Do not rerun the full Go suite for documentation-only changes without a reason. Report what ran and any unverified checks. -PR CI tests Go 1.27.0 and the latest 1.27 patch, and builds both Linux -architectures. Go validation runs on PRs against `main`, including release PRs. -Main pushes run release automation only; do not reintroduce duplicate post-merge -validation without user direction. +PR CI tests Go 1.27.0 and the latest 1.27 patch, +and builds both Linux architectures. +Go validation runs on PRs against `main`, including release PRs. +Main pushes run release automation only; +do not reintroduce duplicate post-merge validation without user direction. ## Go conventions and package boundaries -- Use `encoding/json/v2` and `encoding/json/jsontext` directly for module-owned - JSON. Do not use the JSON v1 compatibility codec. Recognition of the v1 - `json.Number` type for SDK-supplied values is an existing interoperability case. -- Follow surrounding Go naming and error conventions; document exported APIs - and provide runnable examples where they help consumers compose the packages. -- Keep transport, identity, authentication and authorization separate. Do not - turn the root package into a facade reexporting all companion types. +- Use `encoding/json/v2` and `encoding/json/jsontext` directly + for module-owned JSON. + Do not use the JSON v1 compatibility codec. + Recognition of the v1 `json.Number` type for SDK-supplied values + is an existing interoperability case. +- Follow surrounding Go naming and error conventions; + document exported APIs and provide runnable examples + where they help consumers compose the packages. +- Keep transport, identity, authentication and authorization separate. + Do not turn the root package into a facade reexporting all companion types. - Preserve gateway identity as explicit opt-in, validated caller invariants, - immutable claims and deny-by-default authorization. Identity construction is - not credential verification or permission assignment. -- Distinguish HTTP responses from invocation failures, and denial from dependency - failure. Preserve cancellation, resource bounds, cleanup and error sanitization. -- Prefer AWS SDK types when they meet the accepted contract. Keep raw and typed - adapter behavior aligned without adding an envelope JSON round trip to typed - entry points. API product and Gateway payload version are separate concepts. -- Check official Go documentation and the supplied Go release-notes/API skills - when applicable. Verify latest stable dependency/action releases with upstream - sources when updating them; retain reproducible module versions and action - commit pins with version comments. + immutable claims and deny-by-default authorization. + Identity construction is not credential verification or permission assignment. +- Distinguish HTTP responses from invocation failures, + and denial from dependency failure. + Preserve cancellation, resource bounds, cleanup and error sanitization. +- Prefer AWS SDK types when they meet the accepted contract. + Keep raw and typed adapter behavior aligned + without adding an envelope JSON round trip to typed entry points. + API product and Gateway payload version are separate concepts. +- Check official Go documentation + and the supplied Go release-notes/API skills when applicable. + Verify latest stable dependency/action releases + with upstream sources when updating them; + retain reproducible module versions + and action commit pins with version comments. ## Tests and evidence -- Exercise observable contracts and failure cases, not private implementation - details. Use the standard testing package, local HTTP test servers and - recorded/synthetic events; document fixture provenance and fidelity limits. -- Cover malformed input, ambiguous credentials, denied access, dependency errors, - cancellation and cleanup where relevant. Streaming tests should consume data - incrementally and exercise handoff and terminal failures. -- Prefer public-package examples and the external consumer check for API changes. - Root tests do not run nested research modules; run those explicitly only when - relying on their evidence. +- Exercise observable contracts and failure cases, + not private implementation details. + Use the standard testing package, + local HTTP test servers and recorded/synthetic events; + document fixture provenance and fidelity limits. +- Cover malformed input, ambiguous credentials, denied access, + dependency errors, cancellation and cleanup where relevant. + Streaming tests should consume data incrementally + and exercise handoff and terminal failures. +- Prefer public-package examples and the external consumer check + for API changes. + Root tests do not run nested research modules; + run those explicitly only when relying on their evidence. - Do not deploy resources or invoke live AWS services merely to run unit tests. - Live interoperability work needs a separately approved scope. Local tests do - not establish deployed streaming, Cognito or STS compatibility; keep evidence - qualifications accurate in the support and release-readiness documentation. + Live interoperability work needs a separately approved scope. + Local tests do not establish deployed streaming, Cognito or STS compatibility; + keep evidence qualifications accurate + in the support and release-readiness documentation. ## Design decisions and user review When a substantive question, design decision or issue arises: -1. Inspect our code and tests and consult relevant official documentation. Route - AWS knowledge lookups through `aws-proxy-public`, not account APIs. Use - official Go documentation and the supplied Go skills when applicable. -2. Record evidence, alternatives, recommendation, reasoning and consequences in - a decision record. Label unverified assumptions and open questions; maintain - the decision index. +1. Inspect our code and tests and consult relevant official documentation. + Route AWS knowledge lookups through `aws-proxy-public`, not account APIs. + Use official Go documentation and the supplied Go skills when applicable. +2. Record evidence, alternatives, recommendation, + reasoning and consequences in a decision record. + Label unverified assumptions and open questions; + maintain the decision index. 3. Present the issue and recommendation to the user for review. -4. Await approval or redirection before implementing dependent behavior. Continue - useful independent work within the accepted plan. +4. Await approval or redirection before implementing dependent behavior. + Continue useful independent work within the accepted plan. 5. Record the resolution and update the plan before implementation. -Silence is not approval. Routine execution within an approved decision needs no -additional approval. Do not silently settle public API, trust-boundary, +Silence is not approval. +Routine execution within an approved decision needs no additional approval. +Do not silently settle public API, trust-boundary, compatibility or error-policy decisions. ## Branches, commits and releases -- Work on a working branch, never directly on `main`. Inspect the working tree - first; preserve unrelated edits and editor files. Stage only intended files. -- Keep commits focused and use Conventional Commits. Use `feat:` for features, - `fix:` for fixes and `docs:`/`ci:` for their actual scope; do not relabel routine - maintenance merely to force a release. -- PR descriptions should explain the resulting behavior, validation and material - limitations. For a review request, inspect with `gh pr view` and `gh pr diff` +- Work on a working branch, never directly on `main`. + Inspect the working tree first; + preserve unrelated edits and editor files. + Stage only intended files. +- Keep commits focused and use Conventional Commits. + Use `feat:` for features, + `fix:` for fixes and `docs:`/`ci:` for their actual scope; + do not relabel routine maintenance merely to force a release. +- PR descriptions should explain the resulting behavior, + validation and material limitations. + For a review request, + inspect with `gh pr view` and `gh pr diff` before deciding whether any checkout or edits are needed. -- Prefer squash merges with a Conventional Commit title. Creating or updating a - PR does not authorize merging it or publishing a release. +- Prefer squash merges with a Conventional Commit title. + Creating or updating a PR does not authorize merging it + or publishing a release. - Release Please owns the changelog, release manifest, tags and release PRs; - do not manually create an Unreleased changelog section or force versions unless - directed. It considers unreleased history, not just the newest commit. + do not manually create an Unreleased changelog section + or force versions unless directed. + It considers unreleased history, not just the newest commit. - Follow [the release guide](docs/releases.md) and - [readiness checklist](docs/release-readiness.md). The initial version is 0.1.0; - features/breaking changes bump minor during v0, fixes bump patch, and moving to - v1 requires an explicit decision. Merging a release PR authorizes publication. + [readiness checklist](docs/release-readiness.md). + The initial version is 0.1.0; + features/breaking changes bump minor during v0, fixes bump patch, + and moving to v1 requires an explicit decision. + Merging a release PR authorizes publication. ## Credentials and configuration -- Never commit or print private keys, access tokens, bearer credentials or signed - IAM proofs. Keep fixtures synthetic and sanitize diagnostic output. +- Never commit or print private keys, access tokens, + bearer credentials or signed IAM proofs. + Keep fixtures synthetic and sanitize diagnostic output. - Release automation uses organization Actions secrets - `RELEASE_PLEASE_CLIENT_ID` and `RELEASE_PLEASE_PRIVATE_KEY`, granted to this - repository. Avoid same-name repository secrets that override organization values. -- Keep the release App token scoped to the current repository and required - permissions. PR validation needs no App credentials. Do not substitute a - different credential or broaden access to work around a configuration failure. + `RELEASE_PLEASE_CLIENT_ID` and `RELEASE_PLEASE_PRIVATE_KEY`, + granted to this repository. + Avoid same-name repository secrets that override organization values. +- Keep the release App token scoped to the current repository + and required permissions. + PR validation needs no App credentials. + Do not substitute a different credential or broaden access + to work around a configuration failure. - Keep application configuration and credential handling in consumer code; examples and docs must make deployment responsibilities explicit. From 95432942164a9f74ba23e995d6ef13683488bbe5 Mon Sep 17 00:00:00 2001 From: AJ Beck Date: Sun, 27 Sep 2026 08:32:31 +0100 Subject: [PATCH 3/3] docs: remove column wrapping from semantic line breaks --- AGENTS.md | 126 ++++++++++++++++++------------------------------------ 1 file changed, 41 insertions(+), 85 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9d03542..1564a27 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -5,42 +5,30 @@ Build `github.com/asteroid-computing/go-lambda-edge` from first principles. The root package is `edge`; ordinary `http.Handler` is the application boundary. -Beakley is reference material for requirements and failure cases, -not source or tests to copy, nor a compatibility target. +Beakley is reference material for requirements and failure cases, not source or tests to copy, nor a compatibility target. -Read [the implementation plan](docs/plan.md) and relevant -[decision records](docs/decisions/README.md) before work. -Use the [support matrix](docs/support.md) to distinguish implemented behavior, -deferred scope and deployment qualifications. -Keep accepted direction, -proposed API contracts and implemented behavior clearly separated. +Read [the implementation plan](docs/plan.md) and relevant [decision records](docs/decisions/README.md) before work. +Use the [support matrix](docs/support.md) to distinguish implemented behavior, deferred scope and deployment qualifications. +Keep accepted direction, proposed API contracts and implemented behavior clearly separated. ## Repository map -- Root Go files: raw/typed Lambda adapters, Gateway event decoding, - HTTP request translation, buffered/streaming responses, - gateway identity and action headers. +- Root Go files: raw/typed Lambda adapters, Gateway event decoding, HTTP request translation, buffered/streaming responses, gateway identity and action headers. - `identity/`: immutable callers, owned claims and context transport; standard library only, with no AWS dependencies. -- `authn/`: credential selection, HTTP authentication middleware, - Cognito token verification and JWKS caching. -- `iamproof/`: exported signed STS GetCallerIdentity proof - generator and verifier. +- `authn/`: credential selection, HTTP authentication middleware, Cognito token verification and JWKS caching. +- `iamproof/`: exported signed STS GetCallerIdentity proof generator and verifier. - `authz/`: identity predicates, ordered rules and application grant callbacks. Consumers own grant resolution, action registries and HTTP dispatch. -- `examples/dispatcher/`: complete application with native HTTP, - buffered Lambda and streaming Lambda entry points; +- `examples/dispatcher/`: complete application with native HTTP, buffered Lambda and streaming Lambda entry points; application details stay in its `internal/`. - Tests live beside code in `*_test.go`; `testdata/` contains fixtures and the external consumer source. - `scripts/check-consumer.sh` tests public imports - from a temporary, separate module. + `scripts/check-consumer.sh` tests public imports from a temporary, separate module. - `docs/`: guides, evidence, benchmarks, plan and decisions. - The nested module in `docs/probes/iamproof/` is historical research, - outside root `go test ./...`. + The nested module in `docs/probes/iamproof/` is historical research, outside root `go test ./...`. - `.github/workflows/`: PR validation and Release Please. - Release configuration lives in `release-please-config.json` and - `.release-please-manifest.json`. + Release configuration lives in `release-please-config.json` and `.release-please-manifest.json`. ## Local commands and CI @@ -63,68 +51,51 @@ There is no Makefile or required custom commit helper. | Whitespace check | `git diff --check` | Start with checks relevant to the change. -For Go changes, complete the applicable race, vet, module, -consumer and cross-build checks before handoff. +For Go changes, complete the applicable race, vet, module, consumer and cross-build checks before handoff. Documentation edits need link/path and whitespace checks; workflow edits need actionlint. Do not rerun the full Go suite for documentation-only changes without a reason. Report what ran and any unverified checks. -PR CI tests Go 1.27.0 and the latest 1.27 patch, -and builds both Linux architectures. +PR CI tests Go 1.27.0 and the latest 1.27 patch, and builds both Linux architectures. Go validation runs on PRs against `main`, including release PRs. Main pushes run release automation only; do not reintroduce duplicate post-merge validation without user direction. ## Go conventions and package boundaries -- Use `encoding/json/v2` and `encoding/json/jsontext` directly - for module-owned JSON. +- Use `encoding/json/v2` and `encoding/json/jsontext` directly for module-owned JSON. Do not use the JSON v1 compatibility codec. - Recognition of the v1 `json.Number` type for SDK-supplied values - is an existing interoperability case. + Recognition of the v1 `json.Number` type for SDK-supplied values is an existing interoperability case. - Follow surrounding Go naming and error conventions; - document exported APIs and provide runnable examples - where they help consumers compose the packages. + document exported APIs and provide runnable examples where they help consumers compose the packages. - Keep transport, identity, authentication and authorization separate. Do not turn the root package into a facade reexporting all companion types. -- Preserve gateway identity as explicit opt-in, validated caller invariants, - immutable claims and deny-by-default authorization. +- Preserve gateway identity as explicit opt-in, validated caller invariants, immutable claims and deny-by-default authorization. Identity construction is not credential verification or permission assignment. -- Distinguish HTTP responses from invocation failures, - and denial from dependency failure. +- Distinguish HTTP responses from invocation failures, and denial from dependency failure. Preserve cancellation, resource bounds, cleanup and error sanitization. - Prefer AWS SDK types when they meet the accepted contract. - Keep raw and typed adapter behavior aligned - without adding an envelope JSON round trip to typed entry points. + Keep raw and typed adapter behavior aligned without adding an envelope JSON round trip to typed entry points. API product and Gateway payload version are separate concepts. -- Check official Go documentation - and the supplied Go release-notes/API skills when applicable. - Verify latest stable dependency/action releases - with upstream sources when updating them; - retain reproducible module versions - and action commit pins with version comments. +- Check official Go documentation and the supplied Go release-notes/API skills when applicable. + Verify latest stable dependency/action releases with upstream sources when updating them; + retain reproducible module versions and action commit pins with version comments. ## Tests and evidence -- Exercise observable contracts and failure cases, - not private implementation details. - Use the standard testing package, - local HTTP test servers and recorded/synthetic events; +- Exercise observable contracts and failure cases, not private implementation details. + Use the standard testing package, local HTTP test servers and recorded/synthetic events; document fixture provenance and fidelity limits. -- Cover malformed input, ambiguous credentials, denied access, - dependency errors, cancellation and cleanup where relevant. - Streaming tests should consume data incrementally - and exercise handoff and terminal failures. -- Prefer public-package examples and the external consumer check - for API changes. +- Cover malformed input, ambiguous credentials, denied access, dependency errors, cancellation and cleanup where relevant. + Streaming tests should consume data incrementally and exercise handoff and terminal failures. +- Prefer public-package examples and the external consumer check for API changes. Root tests do not run nested research modules; run those explicitly only when relying on their evidence. - Do not deploy resources or invoke live AWS services merely to run unit tests. Live interoperability work needs a separately approved scope. Local tests do not establish deployed streaming, Cognito or STS compatibility; - keep evidence qualifications accurate - in the support and release-readiness documentation. + keep evidence qualifications accurate in the support and release-readiness documentation. ## Design decisions and user review @@ -133,8 +104,7 @@ When a substantive question, design decision or issue arises: 1. Inspect our code and tests and consult relevant official documentation. Route AWS knowledge lookups through `aws-proxy-public`, not account APIs. Use official Go documentation and the supplied Go skills when applicable. -2. Record evidence, alternatives, recommendation, - reasoning and consequences in a decision record. +2. Record evidence, alternatives, recommendation, reasoning and consequences in a decision record. Label unverified assumptions and open questions; maintain the decision index. 3. Present the issue and recommendation to the user for review. @@ -144,8 +114,7 @@ When a substantive question, design decision or issue arises: Silence is not approval. Routine execution within an approved decision needs no additional approval. -Do not silently settle public API, trust-boundary, -compatibility or error-policy decisions. +Do not silently settle public API, trust-boundary, compatibility or error-policy decisions. ## Branches, commits and releases @@ -154,41 +123,28 @@ compatibility or error-policy decisions. preserve unrelated edits and editor files. Stage only intended files. - Keep commits focused and use Conventional Commits. - Use `feat:` for features, - `fix:` for fixes and `docs:`/`ci:` for their actual scope; + Use `feat:` for features, `fix:` for fixes and `docs:`/`ci:` for their actual scope; do not relabel routine maintenance merely to force a release. -- PR descriptions should explain the resulting behavior, - validation and material limitations. - For a review request, - inspect with `gh pr view` and `gh pr diff` - before deciding whether any checkout or edits are needed. +- PR descriptions should explain the resulting behavior, validation and material limitations. + For a review request, inspect with `gh pr view` and `gh pr diff` before deciding whether any checkout or edits are needed. - Prefer squash merges with a Conventional Commit title. - Creating or updating a PR does not authorize merging it - or publishing a release. + Creating or updating a PR does not authorize merging it or publishing a release. - Release Please owns the changelog, release manifest, tags and release PRs; - do not manually create an Unreleased changelog section - or force versions unless directed. + do not manually create an Unreleased changelog section or force versions unless directed. It considers unreleased history, not just the newest commit. -- Follow [the release guide](docs/releases.md) and - [readiness checklist](docs/release-readiness.md). +- Follow [the release guide](docs/releases.md) and [readiness checklist](docs/release-readiness.md). The initial version is 0.1.0; - features/breaking changes bump minor during v0, fixes bump patch, - and moving to v1 requires an explicit decision. + features/breaking changes bump minor during v0, fixes bump patch, and moving to v1 requires an explicit decision. Merging a release PR authorizes publication. ## Credentials and configuration -- Never commit or print private keys, access tokens, - bearer credentials or signed IAM proofs. +- Never commit or print private keys, access tokens, bearer credentials or signed IAM proofs. Keep fixtures synthetic and sanitize diagnostic output. -- Release automation uses organization Actions secrets - `RELEASE_PLEASE_CLIENT_ID` and `RELEASE_PLEASE_PRIVATE_KEY`, - granted to this repository. +- Release automation uses organization Actions secrets `RELEASE_PLEASE_CLIENT_ID` and `RELEASE_PLEASE_PRIVATE_KEY`, granted to this repository. Avoid same-name repository secrets that override organization values. -- Keep the release App token scoped to the current repository - and required permissions. +- Keep the release App token scoped to the current repository and required permissions. PR validation needs no App credentials. - Do not substitute a different credential or broaden access - to work around a configuration failure. + Do not substitute a different credential or broaden access to work around a configuration failure. - Keep application configuration and credential handling in consumer code; examples and docs must make deployment responsibilities explicit.