aw-spec-cli 0.1.9 → 0.1.11

package/assets/guardrails/technology/java-spring/authorization.md

@@ -0,0 +1,618 @@
+# Authorization Standards
+
+> Common technology guardrail for authorization in AppWeaver Java/Spring applications.
+>
+> Technology-specific and domain-agnostic. Application-specific roles, permissions, and authorization matrices are defined by the applicable application/domain security specification.
+>
+> **NON-NEGOTIABLE where authorization is applicable.**
+
+---
+
+## 1. Purpose
+
+This document defines the standard authorization approach for AppWeaver Java/Spring applications.
+
+Authorization MUST ensure that an authenticated identity is permitted to perform an operation according to the application's defined security policy.
+
+Authorization is an application/security boundary concern and MUST NOT introduce framework-specific authorization dependencies into the domain model.
+
+Application-specific roles and permissions MUST NOT be defined in this common technology guardrail.
+
+They MUST be defined by the applicable application security specification, permission matrix, or equivalent project artifact.
+
+---
+
+## 2. Authentication vs Authorization
+
+Authentication and authorization are separate concerns.
+
+**Authentication** establishes who the caller is.
+
+**Authorization** determines what the authenticated caller is allowed to do.
+
+An external Identity Provider (IdP), OIDC provider, OAuth 2.0 provider, or locally issued JWT MAY establish identity according to the application's approved authentication architecture.
+
+Authorization decisions MUST be based on the application's configured authorization policy.
+
+The application MUST NOT assume that an external identity provider's roles or claims automatically represent the application's complete authorization model.
+
+External claims MAY be used as authorization inputs when explicitly approved by the application's security architecture.
+
+Where application roles and permissions are database-managed, the application's database MUST remain the authoritative source for those application roles and permissions.
+
+---
+
+## 3. Authorization Model
+
+AppWeaver supports a role- and permission-based authorization model.
+
+Authorization MAY use:
+
+* roles;
+* granular permissions/authorities;
+* role-to-permission mappings;
+* resource-specific policies;
+* ownership policies;
+* other explicitly approved authorization policies.
+
+The concrete roles, permissions, and mappings are application-specific.
+
+They MUST be defined outside this generic technology guardrail.
+
+For example:
+
+```text
+permission-matrix.md
+        ↓
+Application Authorization Policy
+        ↓
+Spring Security Authorization
+```
+
+AI agents MUST NOT invent application roles or permissions when the applicable permission matrix or security specification already exists.
+
+---
+
+## 4. Secure-by-Default Policy
+
+When authorization is applicable, API endpoints MUST be secured by default.
+
+Global security configuration SHOULD require authentication for API paths unless an endpoint is explicitly defined as public.
+
+Public access MUST be intentional and explicitly configured.
+
+AI agents MUST NOT make an endpoint publicly accessible merely to simplify development or testing.
+
+The following are examples of endpoints that MAY be public when explicitly required:
+
+* health/discovery endpoints;
+* authentication endpoints;
+* authentication callback endpoints;
+* public documentation endpoints.
+
+The exact list of public endpoints MUST be determined by the application's security requirements and environment.
+
+Documentation endpoints MUST NOT automatically be considered public in every environment.
+
+For example:
+
+```java
+.authorizeHttpRequests(auth -> auth
+    .requestMatchers("/actuator/health").permitAll()
+    .requestMatchers("/api/auth/**").permitAll()
+    .anyRequest().authenticated()
+)
+```
+
+The exact public endpoint configuration MUST follow the application's security specification.
+
+---
+
+## 5. Endpoint Authorization
+
+Authorization SHOULD be enforced as close as practical to the application operation being protected.
+
+Spring Security method authorization MAY be used.
+
+For example:
+
+```java
+@PreAuthorize("hasAuthority('PROJECT_CREATE')")
+public ResponseEntity<Void> createProject(...) {
+    ...
+}
+```
+
+`@PreAuthorize` is an approved implementation mechanism but is not the only valid mechanism.
+
+Other approved mechanisms MAY include:
+
+* Spring Security request authorization;
+* method-level authorization;
+* custom authorization policies;
+* authorization services;
+* permission evaluators;
+* resource/ownership policies.
+
+AI agents MUST use the mechanism established by the application rather than introducing a competing authorization mechanism.
+
+---
+
+## 6. Permission and Authority Naming
+
+Application permissions SHOULD use stable, explicit names.
+
+Example:
+
+```text
+PROJECT_CREATE
+PROJECT_READ
+PROJECT_UPDATE
+PROJECT_DELETE
+```
+
+Permission names MUST be defined by the application's permission matrix or security specification.
+
+AI agents MUST NOT:
+
+* invent permissions without a requirement;
+* rename existing permissions without considering compatibility;
+* use database identifiers as externally exposed authority names unless explicitly required;
+* couple domain entities to Spring Security authority names.
+
+---
+
+## 7. Database-Driven Authorization
+
+When the application uses database-managed authorization, the database is the authoritative source for application roles and permissions.
+
+A typical flow is:
+
+```text
+Authenticated Identity
+        ↓
+Identity Identifier
+        ↓
+Application Authorization Store
+        ↓
+Roles / Permissions
+        ↓
+Granted Authorities
+        ↓
+Spring Security Authorization
+```
+
+The authenticated identity may originate from:
+
+* an external OIDC/OAuth2 identity provider;
+* a local JWT;
+* another explicitly approved authentication mechanism.
+
+The identity provider establishes identity.
+
+The application's authorization store determines application-specific permissions when database-driven authorization is configured.
+
+AI agents MUST NOT silently replace database-managed authorization with IdP-managed application permissions.
+
+---
+
+## 8. Authentication Identity Mapping
+
+When database-backed authorization is used, the authenticated identity MUST be mapped to a stable application identity.
+
+A JWT `sub` claim or another stable identity identifier MAY be used.
+
+The mapping implementation MUST:
+
+* use a stable identifier;
+* avoid relying on mutable display names;
+* handle missing or invalid identities safely;
+* avoid exposing authentication credentials;
+* follow the application's identity model.
+
+A custom `AuthenticationProvider`, JWT converter, authorization service, or equivalent mechanism MAY perform this mapping.
+
+For example:
+
+```java
+@Bean
+SecurityFilterChain securityFilterChain(
+        HttpSecurity http,
+        DatabaseAuthorizationConverter authorizationConverter
+) throws Exception {
+
+    http
+        .authorizeHttpRequests(auth -> auth
+            .requestMatchers("/actuator/health").permitAll()
+            .anyRequest().authenticated()
+        )
+        .oauth2ResourceServer(oauth2 -> oauth2
+            .jwt(jwt -> jwt
+                .jwtAuthenticationConverter(authorizationConverter)
+            )
+        );
+
+    return http.build();
+}
+```
+
+The exact implementation MUST follow the application's authentication and authorization configuration.
+
+---
+
+## 9. Authorization and Module Boundaries
+
+Authorization MUST respect the Modular Monolith architecture.
+
+Authorization checks MUST NOT require direct access to another module's internal implementation.
+
+A module MUST NOT bypass another module's authorization boundary by directly accessing:
+
+* internal repositories;
+* persistence entities;
+* database tables owned by another module;
+* internal services;
+* internal authorization implementation.
+
+Cross-module operations MUST follow the established module contracts and application ports.
+
+Authorization policy MAY be centralized when the foundation provides a shared mechanism, but module-specific authorization rules MUST remain owned by the appropriate application/module specification.
+
+---
+
+## 10. Domain Independence
+
+The domain layer MUST remain independent of Spring Security and HTTP authorization mechanisms.
+
+Domain entities, value objects, and domain services MUST NOT depend directly on:
+
+* `Authentication`;
+* `SecurityContext`;
+* `GrantedAuthority`;
+* `@PreAuthorize`;
+* Spring Security filters;
+* HTTP request objects;
+* JWT objects;
+* servlet APIs.
+
+Authorization decisions that are purely technical/API concerns MUST remain outside the domain layer.
+
+Where authorization is itself a domain/business rule, the domain rule MUST remain framework-independent.
+
+---
+
+## 11. Application Authorization
+
+Application/use-case boundaries MAY enforce authorization policies when authorization is required for a business operation.
+
+Authorization MUST be applied consistently with the application's security architecture.
+
+Example conceptual flow:
+
+```text
+HTTP Request
+      ↓
+Inbound Adapter
+      ↓
+Authentication
+      ↓
+Authorization
+      ↓
+Application Port / Use Case
+      ↓
+Domain
+```
+
+Authorization MUST NOT be implemented only in controllers when the same application operation can be invoked through another approved entry point.
+
+Where authorization is an application-level concern, the chosen enforcement point MUST protect the actual use case rather than only a specific HTTP route.
+
+---
+
+## 12. Resource and Ownership Authorization
+
+Some operations require more than a simple permission check.
+
+Examples include:
+
+* a user can update only their own resource;
+* a manager can access resources belonging to their organization;
+* a user can access only resources belonging to an assigned project.
+
+Such policies MAY use resource ownership or contextual authorization.
+
+The policy MUST be defined by the application/domain security specification.
+
+AI agents MUST NOT infer ownership rules from entity names or database structure.
+
+When resource authorization requires domain information, the implementation MUST preserve the domain/application boundaries.
+
+---
+
+## 13. Field-Level Data Protection
+
+Field-level redaction or data filtering MUST NOT be implemented as ad-hoc controller routing logic.
+
+When required, sensitive fields SHOULD be controlled through:
+
+* API DTO mapping;
+* projection layers;
+* response mapping;
+* dedicated authorization-aware application services;
+* other approved presentation/application mechanisms.
+
+The domain model MUST NOT be modified merely to hide API fields for a particular role.
+
+For example:
+
+```text
+Domain Object
+      ↓
+Application Result
+      ↓
+Authorization-aware Response Mapping
+      ↓
+API Response
+```
+
+The exact mechanism MUST follow the application's established result-mapping and API standards.
+
+---
+
+## 14. Cache-Control and Sensitive Responses
+
+Sensitive API responses SHOULD prevent unintended caching.
+
+Where an endpoint returns sensitive information or performs a security-sensitive state-changing operation, the response SHOULD use:
+
+```http
+Cache-Control: no-store
+```
+
+Example:
+
+```java
+return ResponseEntity.ok()
+        .cacheControl(CacheControl.noStore())
+        .body(response);
+```
+
+`no-store` MUST be applied according to the endpoint's data sensitivity and the application's HTTP caching policy.
+
+AI agents MUST NOT add or remove cache-control directives arbitrarily.
+
+Authorization behavior MUST NOT rely on client-side caching controls as a security mechanism.
+
+---
+
+## 15. Error Handling
+
+Authorization failures MUST use the application's established API error-handling mechanism.
+
+AI agents MUST NOT introduce a separate authorization error response format.
+
+When applicable:
+
+* exception handling MUST follow `global_exception_handler.md`;
+* API error representation MUST follow `problem_details.md`;
+* HTTP/result mapping MUST follow `result_mapping.md`.
+
+Typical HTTP semantics include:
+
+```text
+401 Unauthorized
+    → Authentication is missing or invalid.
+
+403 Forbidden
+    → Authentication succeeded but authorization failed.
+```
+
+The exact API response structure MUST follow the application's established error contract.
+
+Sensitive authorization information MUST NOT be exposed through error responses.
+
+---
+
+## 16. Security Configuration
+
+Spring Security MAY be used as the authorization implementation framework.
+
+Security configuration MUST remain within the appropriate adapter/infrastructure areas of the AppWeaver Java foundation.
+
+Security configuration MUST:
+
+* secure protected API endpoints;
+* explicitly define public endpoints;
+* use approved authentication mechanisms;
+* enforce applicable authorization policies;
+* avoid insecure defaults;
+* preserve existing security behavior.
+
+AI agents MUST NOT disable security globally to resolve implementation problems.
+
+Examples of forbidden behavior include:
+
+```java
+.anyRequest().permitAll()
+```
+
+or globally disabling authorization checks to make an endpoint work.
+
+---
+
+## 17. Authorization and Environment Configuration
+
+Authorization behavior MAY differ by environment where explicitly required.
+
+For example:
+
+* development;
+* test;
+* staging;
+* production.
+
+Environment-specific configuration MUST NOT weaken production authorization controls unintentionally.
+
+Development-only bypasses MUST NOT be enabled in production.
+
+AI agents MUST NOT hard-code credentials, secrets, production identities, or authorization bypasses into source code.
+
+---
+
+## 18. Testing Requirements
+
+Authorization behavior MUST be covered by appropriate automated tests when authorization is applicable.
+
+Tests SHOULD verify, where relevant:
+
+* unauthenticated access;
+* authenticated access;
+* permitted operations;
+* denied operations;
+* role/permission mappings;
+* ownership rules;
+* resource-level authorization;
+* protected endpoints;
+* public endpoints;
+* authorization failure responses;
+* regression behavior for existing permissions.
+
+Security tests MUST NOT weaken production security configuration merely to make tests pass.
+
+Tests MAY use dedicated test identities, mock authentication, or test authorization stores according to the project's testing standards.
+
+---
+
+## 19. AI / AW-Spec Rules
+
+When authorization is applicable, AI-generated code MUST:
+
+* inspect the existing authorization configuration;
+* inspect the applicable permission matrix or security specification;
+* identify the required permission before implementing endpoint authorization;
+* reuse existing authorization abstractions;
+* preserve existing authentication and authorization behavior;
+* follow the established Spring Security configuration;
+* follow the established error-handling mechanism;
+* respect module boundaries;
+* keep authorization concerns outside the domain unless the authorization rule is genuinely a domain rule;
+* add or update appropriate authorization tests.
+
+AI agents MUST NOT:
+
+* invent application permissions without a defined requirement;
+* introduce a second authorization mechanism;
+* bypass existing authorization;
+* make protected endpoints public;
+* use `permitAll()` merely to simplify development;
+* expose sensitive fields without considering the applicable authorization policy;
+* put Spring Security dependencies into the domain layer;
+* directly access another module's authorization internals;
+* disable security globally;
+* embed credentials or security secrets;
+* replace database-driven application permissions with IdP claims when database authorization is the approved application model.
+
+---
+
+## 20. Forbidden Patterns
+
+The following patterns are forbidden:
+
+```text
+Controller → Database authorization tables directly
+
+Controller → JPA Repository for permission lookup
+
+Domain Entity → Spring Security
+
+Domain Entity → Authentication
+
+Domain Entity → GrantedAuthority
+
+Domain Entity → JWT
+
+Domain Entity → HTTP security context
+
+Feature → Duplicate Authorization Framework
+
+Endpoint → permitAll() without an approved public-access requirement
+
+Security Configuration → Global authorization bypass
+
+Application → Hard-coded credentials
+
+Application → Hard-coded production authorization bypass
+```
+
+Authorization MUST follow the established architectural boundaries.
+
+---
+
+## 21. Foundation Package Placement
+
+Authorization implementation MUST follow the predefined AppWeaver Java foundation.
+
+Production code MUST remain under:
+
+```text
+backend/src/main/java/io/appweaver/
+├── adapter/
+├── application/
+├── domain/
+└── infrastructure/
+```
+
+Authorization-related implementation MUST be placed in the appropriate existing package according to its responsibility.
+
+For example:
+
+* HTTP/security adapter concerns belong in the appropriate `adapter` package.
+* Application authorization policies belong in the appropriate `application` package when required.
+* Domain authorization rules belong in `domain` only when they represent genuine domain/business rules.
+* Spring Security configuration and infrastructure-specific security implementation belong in the appropriate `infrastructure` package.
+
+AI agents MUST NOT create a new top-level package under `io.appweaver`.
+
+The exact subpackage structure MUST follow the active Java foundation and existing project conventions.
+
+---
+
+## 22. Governance
+
+Authorization changes MUST comply with:
+
+* the project constitution;
+* the AppWeaver Java foundation;
+* the Modular Monolith architecture;
+* the Hexagonal Architecture / Ports and Adapters rules;
+* the application's permission matrix;
+* applicable authentication standards;
+* applicable cross-cutting guardrails;
+* applicable application/module security requirements.
+
+Application-specific roles, permissions, and authorization matrices MUST NOT be hard-coded into this generic technology guardrail.
+
+Changes to this document MUST follow the project's applicable governance and constitution amendment process.
+
+---
+
+## 23. Summary of Standards
+
+When authorization is applicable, AppWeaver Java applications MUST follow these principles:
+
+* Authorization MUST be secure by default.
+* Application-specific roles and permissions MUST come from the applicable security specification or permission matrix.
+* Database-backed roles and permissions are the standard AppWeaver model when database-driven authorization is configured.
+* Authentication establishes identity; authorization determines application access.
+* External IdP claims MUST NOT automatically be treated as the application's authoritative permission model when database-driven authorization is configured.
+* Public endpoints MUST be explicitly approved.
+* `@PreAuthorize` and other Spring Security mechanisms MAY be used according to the application's established security design.
+* Authorization MUST respect Modular Monolith module boundaries.
+* Domain code MUST remain independent of Spring Security and HTTP concerns.
+* Sensitive response data MUST be protected according to the applicable authorization and API policies.
+* Sensitive responses SHOULD use `Cache-Control: no-store` where appropriate.
+* Authorization failures MUST follow the application's established error and Problem Details standards.
+* Authorization behavior MUST have appropriate automated tests.
+* Security controls MUST NOT be globally disabled.
+* All production authorization implementation MUST remain within the predefined AppWeaver Java foundation structure.
+* AI-generated authorization changes MUST reuse established AppWeaver security mechanisms rather than creating competing implementations.