diff --git a/doc/BASIC_DESIGN.md b/doc/BASIC_DESIGN.md index 0949c12..81b6ce1 100644 --- a/doc/BASIC_DESIGN.md +++ b/doc/BASIC_DESIGN.md @@ -81,12 +81,22 @@ spa-development-reference/ │ └── api-client/ client generated from the OpenAPI contract ├── openapi/ │ └── openapi.yaml normative browser-facing HTTP contract -├── infra/ AWS deployment definitions +├── infra/ AWS CDK v2 deployment definitions +├── scripts/ local-demo orchestration and inspection commands +├── compose.yaml local-demo PostgreSQL ├── doc/ │ ├── REQUIREMENTS.md │ ├── BASIC_DESIGN.md │ ├── DETAILED_DESIGN.md │ ├── POLICY.md +│ ├── VERSIONS +│ ├── GETTING_STARTED.md +│ ├── USER_GUIDE.md +│ ├── DEVELOPMENT.md +│ ├── CONFIGURATION.md +│ ├── DEPLOYMENT.md +│ ├── OPERATIONS.md +│ ├── INITIAL_SETUP.md │ ├── LICENSE.md │ ├── COPYING │ └── COPYING.LESSER @@ -95,18 +105,12 @@ spa-development-reference/ └── ci.yml standard CI pipeline ``` -Directories that do not yet exist are target structure, not permission to -create them as part of a documentation-only change. +This is the current repository ownership structure, not a target scaffold. -The concrete Infrastructure as Code language is deliberately not selected by -this basic design. `infra/` is the ownership boundary for AWS deployment -definitions. The implementation task that introduces `infra/` shall select and -document one IaC tool before code is added there. +AWS Infrastructure as Code is implemented with AWS CDK v2 under `infra/`. -The package manager is likewise not selected by this document. The repository -shall use one workspace-capable Node.js package-management strategy when -implementation begins, but the choice does not change the architecture defined -here and must be fixed before package files are created. +The repository uses npm workspaces from the root `package.json`, with +`package-lock.json` as the committed dependency lockfile. ## 4. Current runtime topology @@ -190,24 +194,25 @@ local topology is not a supported deployment. The frontend is a React and TypeScript SPA organized by application feature rather than by one global directory per technical artifact. -Target structure: +Current structure: ```text frontend/src/ ├── app/ -│ ├── bootstrap/ -│ ├── routing/ -│ └── providers/ +│ ├── App.tsx +│ ├── app.css +│ └── config.ts ├── features/ -│ ├── requests/ +│ ├── administration/ │ ├── approvals/ │ ├── attachments/ -│ └── administration/ +│ └── requests/ ├── shared/ │ ├── auth/ -│ ├── api/ │ ├── errors/ │ └── state/ +├── test/ +├── test-setup.ts └── main.tsx ``` @@ -375,10 +380,18 @@ and retain diagnostic detail only in server-side logs. ## 10. Authentication flow -The current identity provider is Amazon Cognito. +Authentication has two current adapter modes. + +In the AWS deployment, Amazon Cognito is the identity provider. The browser uses +OAuth 2.0 Authorization Code flow with PKCE against Cognito, and the +authorization request asks for the `openid email` scopes. -The browser uses OAuth 2.0 Authorization Code flow with PKCE against Cognito. -The authorization request asks for the `openid email` scopes. +In the local demonstration, no OAuth redirect or Cognito call occurs. The local +identity adapter accepts only the three fixed non-secret demo bearer tokens +defined by the detailed design and maps them to the same application identity +contract used by the rest of the backend. + +The following OAuth flow applies to AWS mode: ```text Browser SPA @@ -406,10 +419,10 @@ BFF The SPA does not contain a client secret. -### 10.1 Access-token validation +### 10.1 AWS access-token validation -The BFF validates the bearer access token before executing an authenticated -business operation. At minimum it verifies that: +In AWS mode, the BFF validates the Cognito bearer access token before executing +an authenticated business operation. At minimum it verifies that: - the signature is valid against the JWKS of the configured Cognito user pool; - the signing key identified by the token `kid` exists in the configured @@ -427,19 +440,29 @@ A request whose token fails validation, or that has no token, receives The BFF does not accept an ID token as the basis for authorization. +In local mode, Cognito token validation is not invoked. The local identity +adapter accepts only the fixed demo tokens defined by the detailed design; +unknown tokens fail with `401 AUTHENTICATION_REQUIRED`. + ### 10.2 Application identity -After validation the BFF passes an application identity value, not an AWS SDK -object, to the rest of the application. The identity has: +After authentication the BFF passes an application identity value, not an AWS +SDK object, to the rest of the application. The identity has: -- `subject`: the `sub` claim of the validated access token; -- `roles`: the application roles derived from the `cognito:groups` claim of the - validated access token; and -- `email`: a verified email address obtained as described in section 10.3, - where an operation needs it. +- `subject`; +- `roles`; and +- `email`, where an operation needs a verified email. -Roles are determined only from the validated access token. A role field supplied -by the browser is never trusted. +In AWS mode, `subject` comes from the validated token `sub`, roles come from the +validated `cognito:groups` claim, and verified email is obtained as described in +section 10.3. + +In local mode, the local identity adapter supplies the fixed subject, one role, +and verified demo email defined by the detailed design. + +In AWS mode, roles are determined only from the validated access token. In +local mode, roles are supplied only by the fixed local identity mapping. A role +field supplied by the browser is never trusted in either mode. The mapping from Cognito group to application role uses exact group names: @@ -462,9 +485,11 @@ role. Every operation that requires a role fails for that user with ### 10.3 Verified email -The Cognito identity adapter obtains the email address by calling the Cognito -UserInfo endpoint with the validated access token. The address becomes the -identity `email` only when all of the following hold: +Creating a request requires a verified email from the active identity adapter. + +In AWS mode, the Cognito identity adapter obtains the email address by calling +the Cognito UserInfo endpoint with the validated access token. The address +becomes the identity `email` only when all of the following hold: - the `sub` returned by UserInfo equals the `sub` of the validated token; - `email` is present and non-empty; and @@ -477,11 +502,16 @@ A failure to reach UserInfo is reported as `503 IDENTITY_PROVIDER_UNAVAILABLE`; a UserInfo authentication failure is reported as `401 AUTHENTICATION_REQUIRED`. +In local mode, no UserInfo call occurs. The local identity adapter supplies the +fixed verified demo email associated with the selected demo identity. + On request creation the verified email is stored on the request record as the internal field `requester_email`. It is not exposed in the browser-facing `Request` schema and is not written to ordinary logs or to audit `details`. -### 10.4 SPA token lifecycle +### 10.4 SPA session and token lifecycle + +The following refresh-token behavior applies to AWS mode. The SPA keeps the access token, and a refresh token when one is issued, in browser memory only. It does not store either token in `localStorage`, @@ -501,6 +531,10 @@ which the user starts a new Authorization Code with PKCE flow, when: If a Cognito SSO session still exists, a new authorization started by the user may complete without prompting for credentials. +In local mode, the selected demo bearer token is also held only in memory. +There is no refresh flow and local sign-out clears the in-memory session without +calling Cognito. + Cognito-specific token parsing and validation belong to the identity infrastructure adapter. @@ -580,34 +614,38 @@ section 8. The current backend is one NestJS application and one deployable container. -Its logical structure is: +Its current source structure is: ```text backend/src/ ├── main.ts +├── app.module.ts +├── adapters.ts +├── compose.ts +├── create-app.ts ├── bff/ │ ├── auth/ │ ├── context/ -│ ├── routing/ +│ ├── controllers/ │ ├── errors/ -│ └── controllers/ +│ ├── http/ +│ └── routing/ ├── capabilities/ │ ├── requests/ │ ├── approvals/ │ ├── attachments/ -│ └── audit/ +│ ├── audit/ +│ └── shared/ ├── common/ -│ ├── config/ -│ ├── logging/ -│ ├── errors/ +├── infrastructure/ +│ ├── aws/ +│ │ ├── cognito/ +│ │ ├── s3/ +│ │ ├── ses/ +│ │ └── sns/ +│ ├── local/ │ └── persistence/ -└── infrastructure/ - ├── aws/ - │ ├── cognito/ - │ ├── s3/ - │ ├── ses/ - │ └── sns/ - └── persistence/ +└── outbox/ ``` The separation is logical. All current capability targets are local and run in @@ -1087,8 +1125,11 @@ A failed delivery remains retryable and records enough error information for diagnosis without storing credentials or provider response bodies containing private data. -Retry timing is configuration-driven and bounded. The defaults are defined in -[`POLICY.md`](POLICY.md). +Retry timing is configuration-driven and bounded. Outbox lifecycle and recovery +semantics are defined in [`DETAILED_DESIGN.md`](DETAILED_DESIGN.md) section 13. +The current configuration names, defaults, and validation are documented in +[`CONFIGURATION.md`](CONFIGURATION.md) and resolved by the backend configuration +loader. Because the result of a network call can be uncertain, duplicate external delivery is possible. Consumers of SNS events should use the stable outbox @@ -1231,15 +1272,15 @@ AuditRepository OutboxRepository ``` -Current implementations are: +Current implementations are selected at bootstrap by `APP_MODE`: -```text -IdentityProvider -> Cognito adapter -ObjectStorage -> S3 adapter -MailSender -> SES adapter -EventPublisher -> SNS adapter -repositories -> Aurora persistence adapters -``` +| Port | `aws` mode | `local` mode | +| --- | --- | --- | +| `IdentityProvider` | Cognito adapter | fixed local identity adapter | +| `ObjectStorage` | S3 adapter | local filesystem adapter | +| `MailSender` | SES adapter | local NDJSON delivery recorder | +| `EventPublisher` | SNS adapter | local NDJSON delivery recorder | +| repositories | PostgreSQL/Aurora-compatible persistence adapters | the same PostgreSQL-compatible persistence adapters | An AWS adapter converts provider-specific exceptions into application infrastructure errors before they cross the boundary. @@ -1497,8 +1538,8 @@ with `openapi/openapi.yaml`. Exercise feature behavior and reusable UI behavior without treating hidden controls as proof of authorization. -The semantics that the initial implementation must cover with automated tests -are in [`DETAILED_DESIGN.md`](DETAILED_DESIGN.md) section 21. +The semantics that the current implementation must keep covered with automated +tests are in [`DETAILED_DESIGN.md`](DETAILED_DESIGN.md) section 21. ## 33. Current request flow @@ -1515,7 +1556,8 @@ ALB BFF controller | +--> request context / traceId - +--> Cognito-backed token validation + +--> active identity adapter + (Cognito in aws mode / local demo identity in local mode) +--> coarse authorization | v @@ -1543,6 +1585,10 @@ BFF response Browser ``` +The identity step is mode-specific, but the authorization, capability dispatch, +domain behavior, persistence, audit, and outbox path after application identity +construction is shared. + External notification delivery occurs after the transaction through the outbox processor. @@ -1865,7 +1911,7 @@ as an incidental implementation detail: transaction. 10. Application logging and business audit history remain separate. 11. AWS SDK types do not become domain contracts. -12. OpenAPI is the normative browser-facing HTTP contract once introduced. +12. OpenAPI is the normative browser-facing HTTP contract. 13. Current deployment is AWS only. 14. Java, microservices, orchestration, aggregation, Azure, and Google Cloud remain future directions until their requirements are explicitly adopted. diff --git a/doc/DETAILED_DESIGN.md b/doc/DETAILED_DESIGN.md index 4799916..e326576 100644 --- a/doc/DETAILED_DESIGN.md +++ b/doc/DETAILED_DESIGN.md @@ -2,18 +2,18 @@ ## 1. Purpose -This document defines implementation-significant semantics that must be fixed -before the initial implementation of `spa-development-reference`. +This document defines the implementation-significant semantics that govern the +current `spa-development-reference` implementation and constrain later changes. The requirements define what the reference supports. The basic design defines the architecture and responsibility boundaries. The policy defines implementation and maintenance rules. OpenAPI defines the browser-facing HTTP contract. -This document closes the remaining detailed-design decisions needed to -implement those sources of truth without requiring an implementer to invent -observable behavior, security semantics, concurrency behavior, recovery -behavior, or provider-boundary behavior. +This document records the detailed-design decisions required to keep observable +behavior, security semantics, concurrency behavior, recovery behavior, and +provider boundaries unambiguous across the current implementation and later +maintenance. This document does not replace the other specifications and does not introduce future architecture into the current implementation. @@ -40,20 +40,39 @@ before implementation continues. ## 3. Current implementation boundary -The current implementation remains: +The current implementation has a shared application core and two adapter modes. + +Shared application boundary: - one React and TypeScript SPA; - one NestJS and TypeScript backend deployable; - one BFF browser-facing boundary; - local in-process Requests, Approvals, Attachments, and Audit capabilities; -- Aurora PostgreSQL-compatible persistence; -- S3 object storage; -- Cognito identity; -- SES email; -- SNS event publication; -- ECS/Fargate containers behind an ALB; and +- PostgreSQL-compatible persistence; +- one transactional outbox; - deployment-time static capability routing. +In `APP_MODE=aws`: + +- Aurora PostgreSQL-compatible persistence is the deployed database; +- S3 provides object storage; +- Cognito provides identity; +- SES provides email delivery; +- SNS provides event publication; and +- frontend and backend run as ECS/Fargate containers behind an ALB. + +In `APP_MODE=local`: + +- PostgreSQL runs locally through the documented Compose path; +- the fixed local identity adapter replaces Cognito; +- local filesystem object storage replaces S3; +- local delivery recorders replace SES and SNS; and +- no AWS client is instantiated for those adapters. + +The mode changes only the external infrastructure adapters. Evaluation order, +authorization, domain behavior, persistence semantics, audit, and outbox +semantics remain shared. + The detailed design shall not introduce a microservice, remote current capability, orchestrator, aggregator, service registry, distributed transaction coordinator, Java runtime, Azure implementation, or Google Cloud @@ -157,9 +176,10 @@ The approval record stores the normalized value. ## 6. Authentication identity contract -## 6.1 OAuth flow +## 6.1 AWS-mode OAuth flow -The SPA uses OAuth 2.0 Authorization Code with PKCE. +When the SPA runtime configuration uses `authMode: "cognito"` and the backend +runs with `APP_MODE=aws`, the SPA uses OAuth 2.0 Authorization Code with PKCE. The authorization request uses: @@ -225,9 +245,10 @@ No token is stored in: A page reload therefore loses the application's token state. -### 6.4 Access-token validation +### 6.4 AWS access-token validation -The BFF validates the Cognito access token before a business operation. +In `APP_MODE=aws`, the BFF validates the Cognito access token before a business +operation. The validation requires: @@ -251,13 +272,20 @@ If validation cannot proceed because no usable cached key exists and Cognito JWKS retrieval is unavailable, return `503 IDENTITY_PROVIDER_UNAVAILABLE`. +In `APP_MODE=local`, this Cognito validation path is not used. Authentication is +performed by the local identity adapter defined in section 6.1.1. + ### 6.5 Application identity -A validated token becomes an application identity with: +Successful authentication becomes an application identity with: + +- `subject`; +- `roles`; +- `email`, absent until an operation explicitly requires verified email. -- `subject`: token `sub`; -- `roles`: mapped from token `cognito:groups`; -- `email`: absent until an operation explicitly requires verified email. +In AWS mode, `subject` comes from token `sub` and roles are mapped from +`cognito:groups`. In local mode, the local identity adapter supplies the fixed +subject and one role defined in section 6.1.1. The exact group mapping is: @@ -276,8 +304,8 @@ A browser-supplied role value is never accepted as authorization evidence. Request creation requires the Requester identity to have a verified email. -The BFF identity adapter calls the configured Cognito UserInfo endpoint with -the validated access token. +In AWS mode, the BFF identity adapter calls the configured Cognito UserInfo +endpoint with the validated access token. The response is accepted only when: @@ -294,6 +322,9 @@ If UserInfo is unavailable because of network or provider failure, return If the identity is authenticated but has no verified email, return `403 FORBIDDEN`. +In local mode, no UserInfo call occurs. The local identity adapter supplies the +verified demo email defined in section 6.1.1. + The verified email is stored internally on request creation as `requester_email`. @@ -666,8 +697,10 @@ Request creation, draft update, and attachment addition create no outbox row. The current email recipient is the persisted request `requester_email`. -The email address is captured at request creation from verified Cognito -UserInfo and is not re-resolved when a later transition occurs. +The email address is captured at request creation from the verified email +supplied by the active identity adapter and is not re-resolved when a later +transition occurs. In AWS mode that email comes from verified Cognito UserInfo; +in local mode it comes from the fixed local identity. ### 12.2 Email payload @@ -1179,9 +1212,9 @@ Mapping: - provider unavailable codes -> 503 - `INTERNAL_ERROR` -> 500 -## 21. Required implementation tests +## 21. Required automated coverage -The initial implementation must include automated coverage for at least the +The current implementation must keep automated coverage for at least the following semantics in addition to the broader test requirements already defined by the basic design and policy. @@ -1381,25 +1414,32 @@ by applying the upload response and then re-fetching the attachment list, or by re-fetching the attachment list immediately. The upload response is not the sole local source of truth. -## 24. Decisions intentionally left to implementation +## 24. Non-normative implementation details -The following choices may still be made during implementation because they do -not change the semantics defined by the authoritative specifications: +The following details are intentionally not fixed as public or architectural +semantics by this detailed design: -- package manager and workspace implementation; -- ORM or query library; +- package-manager and workspace mechanics; +- ORM or query-library mechanics; - concrete NestJS module and provider names; - React component and hook decomposition; -- logging library; +- logging-library mechanics; - OpenAPI generation and validation tooling; -- test runner; -- IaC language or framework; +- test-runner mechanics; +- IaC framework mechanics; - container base images; - environment-variable names; - private helper functions; - internal cursor encoding format, provided section 10 semantics are preserved; -- batching size used by the outbox worker; +- outbox batching configuration; and - AWS SDK client construction. -These choices shall not alter public behavior, security, failure semantics, -transaction boundaries, or current/future scope. +The current v1.0 implementation makes concrete choices for these details in the +repository source, package manifests, configuration, and build definitions. +Those current choices are implementation facts, not permission for this +document to describe them as still undecided. + +A later maintenance change may alter one of these details only when the change +preserves the requirements, architecture, public behavior, security, failure +semantics, transaction boundaries, and current/future scope, or when the +authoritative specifications are deliberately changed first. diff --git a/doc/GETTING_STARTED.md b/doc/GETTING_STARTED.md index 11d841d..82f157e 100644 --- a/doc/GETTING_STARTED.md +++ b/doc/GETTING_STARTED.md @@ -267,12 +267,20 @@ This needs only the frontend: npm run dev -w @spa-ref/frontend ``` -Open `http://localhost:5173/`. Expected: - -- the SPA loads and moves you to the signed-out screen (`/signed-out`); -- the heading **You are signed out**, the text "Sign in to continue.", and a **Sign in** button are visible. - -`frontend/public/config.json` contains placeholder Cognito values (`https://auth.example.com/...`). Pressing **Sign in** sends the browser to that placeholder address, so **signing in cannot complete** in this setup. This check confirms that the UI renders with the placeholder AWS-mode configuration; it is not an authenticated end-to-end test. For a working sign-in without AWS, use the local demo (section 4). +Open `http://localhost:5173/`. The tracked +`frontend/public/config.json` selects `authMode: "local"`, so the expected +signed-out screen is the local-demo presentation: + +- the SPA loads and moves you to `/signed-out`; +- the heading **You are signed out** is visible; +- the text **Local demo: choose a role to continue. No external service is used.** is visible; +- **Continue as Requester**, **Continue as Approver**, and + **Continue as Administrator** are visible. + +Because this frontend-only check does not start the backend, choosing a role +cannot establish a session. This check proves only that the frontend starts and +renders the tracked local-mode signed-out UI. For an end-to-end local sign-in +and workflow, use the local demo in section 4. ## 7. Authenticated development against AWS services diff --git a/doc/INITIAL_SETUP.md b/doc/INITIAL_SETUP.md index 98a83ef..36c8489 100644 --- a/doc/INITIAL_SETUP.md +++ b/doc/INITIAL_SETUP.md @@ -69,11 +69,18 @@ README and documentation completion | v Release-quality review + | + v +Initial repository version record ``` Each stage has a different responsibility. Do not merge stages merely to reduce the number of documents. +The initial repository version is recorded only after the release-quality +review establishes the completed baseline. Recording that version does not +implicitly create a Git tag or GitHub Release. + ## 4. Repository creation Create the repository before application implementation. @@ -512,12 +519,35 @@ Confirm that: - no development-only placeholder is presented as permanent behavior; - no future capability is accidentally presented as current; - no secret or private information is present; -- license files are present and consistent; and +- license files are present and consistent; +- repository versioning policy and the planned initial version record are + consistent; +- source-file version-history rules, when used, are consistent with the + repository versioning policy; and - repository history and pull requests contain only the intended scope. If the review finds a specification defect, correct the authoritative specification and the affected implementation together. +### 14.1 Initial repository version record + +After the release-quality review passes, create or update `doc/VERSIONS` as the +repository-level release history when this development approach is used. + +The initial entry records one release baseline, not the development chronology +that led to it. The lowest entry contains only `Initial release.`. + +Do not create more than one repository version for the same calendar date. +Independent changes completed on that date remain within that date's single +repository version. + +Repository version history and source-file `Version History` have different +scopes. A repository version does not mechanically bump every source file, and +a source-file version does not mechanically create a repository release. + +Recording a version in `doc/VERSIONS` does not create or require a Git tag or +GitHub Release. Either is a separate maintainer decision. + ## 15. Document responsibilities Keep normative responsibilities distinct. @@ -529,6 +559,7 @@ Keep normative responsibilities distinct. | `doc/BASIC_DESIGN.md` | System composition, responsibility, dependency, data and control flow | | Detailed-design document | Implementation-significant design not suitable for basic design | | `doc/POLICY.md` | Implementation and maintenance rules | +| `doc/VERSIONS` | Repository-level version and release history | | OpenAPI or equivalent contract | Concrete public protocol or API | | Deployment / operations documents | How the implemented system is deployed and operated | | License documents | Legal terms | @@ -594,6 +625,8 @@ Before declaring the initial repository baseline complete, confirm: - [ ] Every normative artifact referenced by another specification actually exists. - [ ] Implementation policy exists when implementation rules depend on it. +- [ ] Repository-level version history exists when this development approach + uses `doc/VERSIONS`, and its initial entry matches the release baseline. - [ ] Required public API, protocol, schema, or data contracts exist. - [ ] The implementation-readiness review has no unresolved normative gap. - [ ] The initial implementation was produced from the authoritative documents, @@ -604,8 +637,11 @@ Before declaring the initial repository baseline complete, confirm: - [ ] Supporting documentation matches the implemented system. - [ ] Current and future capabilities are not confused. - [ ] No private information or credential is present. +- [ ] Repository version history and source-file version-history policy are + mutually consistent. - [ ] License, documentation, implementation, tests, and CI are mutually consistent. -Only after these conditions are satisfied is the initial repository setup +Only after these conditions are satisfied, and the initial repository version +record has been established where applicable, is the initial repository setup complete. diff --git a/doc/REQUIREMENTS.md b/doc/REQUIREMENTS.md index b23b2a9..0ce94a8 100644 --- a/doc/REQUIREMENTS.md +++ b/doc/REQUIREMENTS.md @@ -359,7 +359,10 @@ deliberately changed. ## 12. Authentication and authorization -Amazon Cognito is the currently supported identity service. +Amazon Cognito is the currently supported deployed identity service. + +The local demonstration uses the fixed local identity mechanism defined in +section 20.1 and does not call Cognito. The BFF is the primary client-facing authentication and authorization boundary. @@ -813,8 +816,8 @@ composed without silently expanding them. `POLICY.md` shall describe how the repository is implemented and changed without silently changing the product scope defined here. -The OpenAPI description shall be authoritative for the concrete browser-facing -HTTP contract once that contract is introduced. +The OpenAPI description is authoritative for the concrete browser-facing HTTP +contract. When implementation and an authoritative specification disagree, the difference shall be resolved deliberately. An accidental implementation detail