Jul 3, 2025 · Jun 27, 2025
diff --git a/CLAUDE.md b/CLAUDE.md

 For buildingFrontend refer to [this document](docs/about/contributing/frontend.md)

 ##RFCComplianceDevelopment

 ###ImplementingStandardProtocols

 When implementing standardprotocols (OAuth2,OpenIDConnect, etc.):

 1. **Fetch andAnalyzeOfficialRFCs**:
   -Always read the actualRFC specifications before implementation
   -UseWebFetch tool to get currentRFC contentfor compliance verification
   -DocumentRFC requirements in code comments

 2. **DefaultValuesMatter**:
   -Pay close attention toRFC-specifieddefault values
   -Example:RFC7591 specifies`client_secret_basic` asdefault, not`client_secret_post`
   -Ensure consistency between database migrations and application code

 3. **SecurityRequirements**:
   -FollowRFC security considerations precisely
   -Example:RFC7592 prohibits returning registration access tokens inGET responses
   -Implement propererror responses per protocol specifications

 4. **ValidationCompliance**:
   -Implement comprehensive validation perRFC requirements
   -Support protocol-specificfeatures (e.g., custom schemesfor nativeOAuth2 apps)
   -Test edge cases defined in specifications

 ##CommonPatterns

 ###OAuth2/AuthenticationWork
 -Test both positive and negative cases
 -Use`testutil.WaitLong`for timeouts in tests

 ##TestingBestPractices

 ###AvoidingRaceConditions

 1. **UniqueTestIdentifiers**:
   -Never use hardcoded names in concurrent tests
   -Use`time.Now().UnixNano()` or similarfor unique identifiers
   -Example:`fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())`

 2. **DatabaseConstraintAwareness**:
   -Understand unique constraints that can cause test conflicts
   -Generate unique valuesfor all constrained fields
   -Test name isolation prevents cross-test interference

 ###RFCProtocolTesting

 1. **ComplianceTestCoverage**:
   -Test allRFC-definederror codes and responses
   -Validate properHTTP status codesfor different scenarios
   -Test protocol-specific edgecases (URI formats, token formats, etc.)

 2. **SecurityBoundaryTesting**:
   -Test client isolation and privilege separation
   -Verify information disclosure protections
   -Test token security and proper invalidation

 ##CodeNavigation andInvestigation

 ###UsingGoLSPTools (STRONGLYRECOMMENDED)
 7. **OAuth2 tests failing but scripts working** - Check in-memory database implementations in `dbmem.go`
 8. **Resource indicator validation failing** - Ensure database stores and retrieves resource parameters correctly
 9. **PKCE tests failing** - Verify both authorization code storage and token exchange handle PKCE fields
 10. **Race conditions in tests** - Use unique identifiers instead of hardcoded names
 11. **RFC compliance failures** - Verify against actual RFC specifications, not assumptions
 12. **Authorization context errors in public endpoints** - Use `dbauthz.AsSystemRestricted(ctx)` pattern
 13. **Default value mismatches** - Ensure database migrations match application code defaults
 14. **Bearer token authentication issues** - Check token extraction precedence and format validation
 15. **URI validation failures** - Support both standard schemes and custom schemes per protocol requirements
 16. **Log message formatting errors** - Use lowercase, descriptive messages without special characters

 ## Systematic Debugging Approach

 ### Multi-Issue Problem Solving

 When facing multiple failing tests or complex integration issues:

 1. **Identify Root Causes**:
   - Run failing tests individually to isolate issues
   - Use LSP tools to trace through call chains
   - Check both compilation and runtime errors

 2. **Fix in Logical Order**:
   - Address compilation issues first (imports, syntax)
   - Fix authorization and RBAC issues next
   - Resolve business logic and validation issues
   - Handle edge cases and race conditions last

 3. **Verification Strategy**:
   - Test each fix individually before moving to next issue
   - Use `make lint` and `make gen` after database changes
   - Verify RFC compliance with actual specifications
   - Run comprehensive test suites before considering complete

 ### Authorization Context Patterns

 Common patterns for different endpoint types:

 ```go
 // Public endpoints needing system access (OAuth2 registration)
 app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)

 // Authenticated endpoints with user context
 app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)

 // System operations in middleware
 roles, err := db.GetAuthorizationUserRoles(dbauthz.AsSystemRestricted(ctx), userID)
 ```

 ## Protocol Implementation Checklist

 ### OAuth2/Authentication Protocol Implementation

 Before completing OAuth2 or authentication feature work:

 - [ ] Verify RFC compliance by reading actual specifications
 - [ ] Implement proper error response formats per protocol
 - [ ] Add comprehensive validation for all protocol fields
 - [ ] Test security boundaries and token handling
 - [ ] Update RBAC permissions for new resources
 - [ ] Add audit logging support if applicable
 - [ ] Create database migrations with proper defaults
 - [ ] Update in-memory database implementations
 - [ ] Add comprehensive test coverage including edge cases
 - [ ] Verify linting and formatting compliance
 - [ ] Test both positive and negative scenarios
 - [ ] Document protocol-specific patterns and requirements
Original file line number	Diff line number	Diff line change
Expand Up		@@ -196,6 +196,32 @@ The frontend is contained in the site folder.

		For buildingFrontend refer to [this document](docs/about/contributing/frontend.md)

		##RFCComplianceDevelopment

		###ImplementingStandardProtocols

		When implementing standardprotocols (OAuth2,OpenIDConnect, etc.):

		1. Fetch andAnalyzeOfficialRFCs:
		-Always read the actualRFC specifications before implementation
		-UseWebFetch tool to get currentRFC contentfor compliance verification
		-DocumentRFC requirements in code comments

		2. DefaultValuesMatter:
		-Pay close attention toRFC-specifieddefault values
		-Example:RFC7591 specifies`client_secret_basic` asdefault, not`client_secret_post`
		-Ensure consistency between database migrations and application code

		3. SecurityRequirements:
		-FollowRFC security considerations precisely
		-Example:RFC7592 prohibits returning registration access tokens inGET responses
		-Implement propererror responses per protocol specifications

		4. ValidationCompliance:
		-Implement comprehensive validation perRFC requirements
		-Support protocol-specificfeatures (e.g., custom schemesfor nativeOAuth2 apps)
		-Test edge cases defined in specifications

		##CommonPatterns

		###OAuth2/AuthenticationWork
Expand DownExpand Up		@@ -270,6 +296,32 @@ if errors.Is(err, errInvalidPKCE) {
		-Test both positive and negative cases
		-Use`testutil.WaitLong`for timeouts in tests

		##TestingBestPractices

		###AvoidingRaceConditions

		1. UniqueTestIdentifiers:
		-Never use hardcoded names in concurrent tests
		-Use`time.Now().UnixNano()` or similarfor unique identifiers
		-Example:`fmt.Sprintf("test-client-%s-%d", t.Name(), time.Now().UnixNano())`

		2. DatabaseConstraintAwareness:
		-Understand unique constraints that can cause test conflicts
		-Generate unique valuesfor all constrained fields
		-Test name isolation prevents cross-test interference

		###RFCProtocolTesting

		1. ComplianceTestCoverage:
		-Test allRFC-definederror codes and responses
		-Validate properHTTP status codesfor different scenarios
		-Test protocol-specific edgecases (URI formats, token formats, etc.)

		2. SecurityBoundaryTesting:
		-Test client isolation and privilege separation
		-Verify information disclosure protections
		-Test token security and proper invalidation

		##CodeNavigation andInvestigation

		###UsingGoLSPTools (STRONGLYRECOMMENDED)
Expand DownExpand Up		@@ -409,3 +461,67 @@ Always run the full test suite after OAuth2 changes:
		7. OAuth2 tests failing but scripts working - Check in-memory database implementations in `dbmem.go`
		8. Resource indicator validation failing - Ensure database stores and retrieves resource parameters correctly
		9. PKCE tests failing - Verify both authorization code storage and token exchange handle PKCE fields
		10. Race conditions in tests - Use unique identifiers instead of hardcoded names
		11. RFC compliance failures - Verify against actual RFC specifications, not assumptions
		12. Authorization context errors in public endpoints - Use `dbauthz.AsSystemRestricted(ctx)` pattern
		13. Default value mismatches - Ensure database migrations match application code defaults
		14. Bearer token authentication issues - Check token extraction precedence and format validation
		15. URI validation failures - Support both standard schemes and custom schemes per protocol requirements
		16. Log message formatting errors - Use lowercase, descriptive messages without special characters

		## Systematic Debugging Approach

		### Multi-Issue Problem Solving

		When facing multiple failing tests or complex integration issues:

		1. Identify Root Causes:
		- Run failing tests individually to isolate issues
		- Use LSP tools to trace through call chains
		- Check both compilation and runtime errors

		2. Fix in Logical Order:
		- Address compilation issues first (imports, syntax)
		- Fix authorization and RBAC issues next
		- Resolve business logic and validation issues
		- Handle edge cases and race conditions last

		3. Verification Strategy:
		- Test each fix individually before moving to next issue
		- Use `make lint` and `make gen` after database changes
		- Verify RFC compliance with actual specifications
		- Run comprehensive test suites before considering complete

		### Authorization Context Patterns

		Common patterns for different endpoint types:

		```go
		// Public endpoints needing system access (OAuth2 registration)
		app, err := api.Database.GetOAuth2ProviderAppByClientID(dbauthz.AsSystemRestricted(ctx), clientID)

		// Authenticated endpoints with user context
		app, err := api.Database.GetOAuth2ProviderAppByClientID(ctx, clientID)

		// System operations in middleware
		roles, err := db.GetAuthorizationUserRoles(dbauthz.AsSystemRestricted(ctx), userID)
		```

		## Protocol Implementation Checklist

		### OAuth2/Authentication Protocol Implementation

		Before completing OAuth2 or authentication feature work:

		- [ ] Verify RFC compliance by reading actual specifications
		- [ ] Implement proper error response formats per protocol
		- [ ] Add comprehensive validation for all protocol fields
		- [ ] Test security boundaries and token handling
		- [ ] Update RBAC permissions for new resources
		- [ ] Add audit logging support if applicable
		- [ ] Create database migrations with proper defaults
		- [ ] Update in-memory database implementations
		- [ ] Add comprehensive test coverage including edge cases
		- [ ] Verify linting and formatting compliance
		- [ ] Test both positive and negative scenarios
		- [ ] Document protocol-specific patterns and requirements