[DRAFT] feat: Phase 3 - implement advanced path-based permission system for storage-construct

[rozaychen]

Problem

Phase 2 implemented basic access control logic, but lacked sophisticated path validation and entity token support needed for production-ready storage access patterns. Users need advanced features like owner-based access with {entity_id} tokens, complex path hierarchies, and robust validation to prevent misconfigurations.

Issue number, if available: Part of storage L3 construct initiative

Changes

Implemented a comprehensive path-based permission system following the exact patterns from the existing backend-storage package:

Core Components Added:

• Path Validation System - Comprehensive validation following backend-storage patterns exactly
• Entity Token Support - Real {entity_id} handling with Cognito identity substitution
• Advanced Path Logic - Parent-child relationships with deny-by-default inheritance
• Constants & Utilities - Shared constants and helper functions for consistency

Key Features:

• Wildcard Path Matching - Support for patterns like photos/*, users/{entity_id}/*
• Owner-Based Access Control - Real entity substitution with ${cognito-identity.amazonaws.com:sub}
• Complex Permission Scenarios - Nested paths, inheritance, and optimization
• Robust Path Validation - Prevents invalid S3 prefix patterns and malformed configurations
• Deny-by-Default Logic - Sophisticated permission inheritance for parent-child paths
• Subpath Optimization - Removes unnecessary paths from policies for cleaner IAM

Implementation Highlights:

• 100% Architecture Alignment - Follows backend-storage patterns exactly
• Comprehensive Validation - 15+ validation rules for path correctness
• Entity Token Rules - Strict validation for {entity_id} placement and usage
• Path Hierarchy Logic - Prevents over-nesting and validates prefix relationships

Advanced Access Patterns Supported:

storage.grantAccess(auth, {
  'public/*': [
    { type: 'authenticated', actions: ['read'] },
    { type: 'guest', actions: ['read'] }
  ],
  'private/{entity_id}/*': [
    { type: 'owner', actions: ['read', 'write', 'delete'] }
  ],
  'shared/documents/*': [
    { type: 'authenticated', actions: ['read', 'write'] }
  ]
});

Corresponding docs PR, if applicable: N/A

Validation

Comprehensive Test Coverage (29 tests total):

• 17 main construct tests - All access control scenarios including new path validation
• 12 path validation tests - Comprehensive validation rule coverage
• 100% test pass rate - All existing and new functionality verified

Test Scenarios Added:

• ✅ Complex path hierarchies with multiple access types
• ✅ Entity token validation and substitution
• ✅ Path format validation (must end with /*, no leading /, etc.)
• ✅ Prefix relationship validation (max one parent per path)
• ✅ Owner token placement rules and restrictions
• ✅ Invalid path pattern detection and error handling
• ✅ Advanced permission inheritance scenarios

Validation Categories:

• Path Format Validation - 5 test cases covering basic path rules
• Entity Token Validation - 4 test cases for {entity_id} rules
• Hierarchy Validation - 3 test cases for prefix relationships
• Integration Testing - 17 test cases for end-to-end scenarios

Build & Quality Checks:

• ✅ TypeScript compilation successful
• ✅ All ESLint rules passing
• ✅ No breaking changes to existing functionality
• ✅ Architecture fully aligned with backend-storage patterns

Checklist

• [x] If this PR includes a functional change to the runtime behavior of the code, I have added or updated automated test coverage for this change.
• [ ] If this PR requires a change to the Project Architecture README, I have included that update in this PR.
• [ ] If this PR requires a docs update, I have linked to that docs PR above.
• [ ] If this PR modifies E2E tests, makes changes to resource provisioning, or makes SDK calls, I have run the PR checks with the run-e2e label set.

Note: This is a foundational PR for the AmplifyStorage L3 construct migration project. The implementation follows a phased approach across multiple PRs:

Phase 1 ✅ Create standalone storage-construct package

• Create new @aws-amplify/storage-construct package
• Migrate core AmplifyStorage implementation with CDK-native triggers
• Add grantAccess(auth, accessDefinition) method pattern
• Maintain full backward compatibility with existing backend-storage

Phase 2 ✅ Implement access control logic in grantAccess method

• Add IAM policy generation engine
• Implement Cognito integration for role resolution
• Support authenticated/guest/owner access patterns

Phase 3 ✅ Add path-based permission system(this PR)

• Implement wildcard path matching (photos/*)
• Add owner-based access control with entity substitution
• Support complex permission scenarios

Phase 4 🔄 Add function resource access support

• Extend StorageAccessRule type to support 'resource' type
• Add function resource access acceptor resolution
• Implement grantAccess(functionConstruct, accessConfig) overload
• Support { type: 'resource', actions: ['read'] } pattern

Phase 5 🔄 Add granular action support

• Extend actions to support ['get', 'list', 'write', 'delete']
• Maintain backward compatibility with 'read' → ['get', 'list'] expansion
• Update policy factory to handle granular permissions

Phase 6 🔄 Add multi-storage validation

• Implement default storage detection and validation logic
• Add error handling for multiple default storage instances
• Support isDefault flag validation across multiple constructs

Phase 7 🔄 Enhance auth construct discovery

• Improve automatic discovery of auth resources in construct tree
• Add robust role resolution for complex auth scenarios
• Handle edge cases and error conditions

Phase 8 🔄 Update documentation and examples

• Create comprehensive usage documentation
• Build sample CDK applications showing function access
• Provide migration guide from Gen2 factory pattern
• Document all access patterns and edge cases

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.