[DRAFT] feat: Phase 1 - create standalone storage-construct package with grantAccess method

[rozaychen]

Problem

Currently, the AmplifyStorage construct is tightly coupled to the Gen2 backend system and cannot be used as a standalone CDK L3 construct. This limits developers who want to use Amplify's storage capabilities in pure CDK applications or integrate with existing CDK infrastructure.

Issue number, if available: Part of the AmplifyStorage L3 construct migration project

Changes

• New Package: Created @aws-amplify/storage-construct as a standalone CDK L3 construct package
• Migrated AmplifyStorage: Moved core AmplifyStorage implementation from backend-storage to new package
• CDK-Native Triggers: Replaced factory-based triggers with direct IFunction references for better CDK integration
• grantAccess Method: Added storage.grantAccess(auth, accessDefinition) method pattern for access control
• Simplified Props: Removed Gen2-specific dependencies and streamlined the props interface
• Complete Test Coverage: Migrated all existing tests plus added new tests for grantAccess method
• Package Configuration: Set up proper build, test, and API extraction workflows

Key Technical Changes:

• Enhanced AmplifyStorageProps to support direct CDK usage without access in constructor
• Implemented grantAccess(auth, accessDefinition) method for post-construction access control
• Added StorageAccessDefinition type for structured access configuration
• Maintained all existing S3 bucket features (CORS, versioning, SSL enforcement, auto-delete)
• Added comprehensive TypeScript declarations and API documentation

New Usage Pattern:

import { AmplifyStorage } from '@aws-amplify/storage-construct';
import { AmplifyAuth } from '@aws-amplify/auth-construct';

const auth = new AmplifyAuth(stack, 'Auth', {...});
const storage = new AmplifyStorage(stack, 'Storage', {
  name: 'myStorage',
  triggers: { onUpload: myFunction }
});

// Grant access using method call
storage.grantAccess(auth, {
  'photos/*': [
    { type: 'authenticated', actions: ['read', 'write'] },
    { type: 'guest', actions: ['read'] }
  ]
});

Corresponding docs PR, if applicable: N/A (internal infrastructure change)

Validation

• ✅ All 8 tests pass in new storage-construct package (including new grantAccess test)
• ✅ All 69 existing tests still pass in original backend-storage package
• ✅ Build and TypeScript compilation successful
• ✅ API extraction generates proper documentation with grantAccess method
• ✅ ESLint validation passes with no errors
• ✅ No breaking changes to existing Gen2 functionality
• ✅ Package properly configured with dependencies and scripts

Test Coverage:

• S3 bucket creation and configuration
• Versioning and CORS setup
• SSL enforcement and security policies
• Attribution metadata storage
• Property override capabilities
• New: grantAccess method existence and functionality
• CDK template generation validation

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

• 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

• 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

This PR establishes the foundation for standalone CDK usage while the grantAccess method currently contains placeholder implementation that will be completed in subsequent phases.

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