Cedarling Design `authorize_multi_issuer` Tasks

Implementation Plan

Overview

This implementation plan converts the multi-issuer authorization feature design into discrete coding tasks. Each task builds incrementally on previous work, focusing on individual token processing without token joining, dynamic entity creation, and ergonomic policy syntax.

Tasks

• 1. Set up project structure and core interfaces

  • Create directory structure for multi-issuer authorization components
  • Define TypeScript interfaces for AuthorizeMultiIssuerRequest and TokenInput
  • Create base error types for multi-issuer validation failures
  • Requirements: 4.1, 4.2

• 2. Implement TokenInput validation and parsing

  • Create TokenInput validator that checks mapping format and payload structure
  • Implement JWT payload parsing to extract issuer and claims
  • Add validation for non-empty mapping strings and valid JWT format
  • Write unit tests for TokenInput validation edge cases
  • Requirements: 4.1, 4.2, 6.1, 6.2

• 3. Implement non-deterministic token detection

  • Create validator to detect multiple tokens of same type from same issuer
  • Extract issuer from JWT payload and token type from mapping string
  • Implement rejection logic for non-deterministic token combinations
  • Write unit tests for various non-deterministic scenarios
  • Requirements: 1.2, 6.1

• 4. Integrate with existing Cedarling token validation

  • Create wrapper around existing Cedarling validation capabilities
  • Implement graceful handling of validation failures (ignore failed tokens)
  • Add logging for validation failures with specific error details
  • Ensure only tokens from trusted issuers are processed
  • Write unit tests for validation integration
  • Requirements: 5.1, 6.1, 6.3

• 5. Implement secure field naming algorithm

  • Create issuer name resolution using trusted issuer metadata lookup
  • Implement fallback to hostname extraction from JWT iss claim
  • Create token type simplification from mapping strings
  • Implement field name generation: {issuer}_{token_type}
  • Write unit tests for field naming edge cases and security scenarios
  • Requirements: 9.1, 9.2, 9.3, 9.4, 9.5

• 6. Implement Dynamic Entity Factory

  • Create Cedar entity factory that handles arbitrary token mapping types
  • Implement JWT claim to Cedar tag conversion with Set of String defaults
  • Add support for multi-valued claims (scope, aud) as Cedar Sets
  • Handle single-valued claims as single-element Sets for consistency
  • Write unit tests for entity creation with various claim structures
  • Requirements: 2.1, 2.3, 5.1, 5.4

• 7. Implement Token Collection Builder

  • Create individual token entity creation (no joining)
  • Implement predictable field naming using secure naming algorithm
  • Build token collection context with individual token references
  • Add total_token_count field to collection
  • Write unit tests for collection assembly with multiple tokens
  • Requirements: 5.2, 5.3, 5.6

• 8. Implement enhanced schema support

  • Add optional Cedar schema integration for proper data type casting
  • Implement DateTime, Long, Boolean type casting when schema is available
  • Maintain Set of String fallback when no schema is defined
  • Write unit tests for schema-based vs schema-less processing
  • Requirements: 5.5

• 9. Create policy evaluation integration

  • Integrate individual token collection with Cedar policy engine
  • Implement context building with tokens collection and individual token access
  • Add support for ergonomic policy syntax (context.tokens.acme_access_token)
  • Write unit tests for policy evaluation with multiple individual tokens
  • Requirements: 3.1, 3.2, 3.3, 3.4

• 10. Implement authorize_multi_issuer main method

  • Create main authorization method that orchestrates all components
  • Implement request parsing and validation
  • Add token processing pipeline: validate → create entities → build collection → evaluate
  • Handle resource, action, and context parameters as JSON
  • Write integration tests for complete authorization flow
  • Requirements: 1.1, 1.3, 4.3, 4.4

• 11. Add comprehensive error handling and logging

  • Implement specific error messages for each validation failure type
  • Add detailed logging for token processing steps
  • Create error responses that indicate which tokens failed and why
  • Implement security audit logging for field name resolution
  • Write unit tests for error handling scenarios
  • Requirements: 6.1, 6.2, 6.3, 6.4, 9.5

• 12. Implement performance optimizations

  • Add parallel token validation where possible
  • Implement token caching integration if available
  • Add memory-efficient processing for large token arrays
  • Create performance metrics collection for multi-token processing
  • Write performance tests for scalability scenarios
  • Requirements: 7.1, 7.2, 7.3, 7.4

• 13. Create comprehensive test suite

  • Write end-to-end tests for complete authorization scenarios
  • Add tests for mixed valid/invalid token processing
  • Create tests for custom token types (Acme::DolphinToken)
  • Test cross-token validation scenarios in policies
  • Add performance benchmarks for multi-token processing
  • Requirements: All requirements validation

• 14. Add API documentation and examples

  • Create API documentation for AuthorizeMultiIssuerRequest interface
  • Add Cedar policy examples for common multi-token scenarios
  • Document field naming conventions and security considerations
  • Create integration examples for different token combinations
  • Requirements: 3.2, 3.3, 4.1

• 15. Implement issuer auto-discovery integration

  • Add OpenID Connect Discovery metadata fetching for new issuers
  • Implement caching of discovery metadata in trusted issuer configuration
  • Create automatic issuer registration workflow
  • Write unit tests for auto-discovery scenarios
  • Requirements: 4.5