[DRAFT] feat: Phase 2 - implement comprehensive access control system for storage-construct

[rozaychen]

Problem

Phase 1 created the standalone storage-construct package with a placeholder grantAccess method. Phase 2 needs to implement the actual access control logic to generate IAM policies and attach them to appropriate roles based on access definitions.

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

Changes

Implemented a comprehensive access control system following the same architectural patterns as the existing backend-storage package:

Core Components Added:

• StorageAccessPolicyFactory - Generates IAM policies with allow/deny statements for S3 actions
• StorageAccessOrchestrator - Orchestrates access control logic and policy attachment
• AuthRoleResolver - Resolves IAM roles from auth constructs (placeholder implementation)

Key Features:

• Action Mapping: Converts storage actions (read, write, delete) to S3 IAM actions (s3:GetObject, s3:PutObject, etc.)
• Path Processing: Handles S3 prefix patterns with wildcards (photos/*)
• Access Types: Supports authenticated, guest, owner, and groups access patterns
• ID Substitution: Framework for owner-based access with entity ID replacement
• Allow/Deny Logic: Sophisticated permission management with explicit deny rules

Implementation Details:

• Follows same architectural patterns as backend-storage for consistency
• Comprehensive error handling and validation
• Full TypeScript type safety with proper interfaces
• ESLint compliant with proper JSDoc documentation

Corresponding docs PR, if applicable: N/A

Validation

Comprehensive Test Coverage (20 tests total):

• 13 main construct tests - All core functionality including access control scenarios
• 4 policy factory tests - IAM policy generation with allow/deny permissions
• 3 auth resolver tests - Role resolution and validation logic

Test Scenarios Covered:

• ✅ Basic access control with authenticated/guest users
• ✅ Owner-based access with entity ID substitution
• ✅ Group-based access control
• ✅ All storage action types (read, write, delete)
• ✅ Multiple access rules per path
• ✅ Error handling for invalid auth constructs
• ✅ Policy generation with complex permission sets

Build & Quality Checks:

• ✅ TypeScript compilation successful
• ✅ All ESLint rules passing
• ✅ API documentation generated and updated
• ✅ No breaking changes to existing functionality

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(this PR)

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

Phase 3 🔄 Add path-based permission system

• 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.