feat: add resource access support for Lambda functions and other constructs

- Extend StorageAccessRule type to support 'resource' access type
- Add resource parameter to StorageAccessRule for specifying target construct
- Implement extractRoleFromResource method in AuthRoleResolver
- Support Lambda functions and constructs with IAM roles
- Add comprehensive test coverage for resource access scenarios
- Update grantAccess method to handle resource role resolution
- Add documentation and usage examples

Enables storage-construct to grant AWS resources access to S3 buckets:
storage.grantAccess(auth, {
  'uploads/*': [
    { type: 'resource', actions: ['read'], resource: myFunction }
  ]
});

Achieves functional parity with backend-storage's allow.resource() pattern.

Author: rozaychen

packages/storage-construct/RESOURCE_ACCESS_EXAMPLE.md

@@ -0,0 +1,124 @@
+# Resource Access Example
+
+This example demonstrates how to grant Lambda functions access to storage using the new resource access functionality.
+
+## Basic Usage
+
+```typescript
+import { AmplifyStorage } from '@aws-amplify/storage-construct';
+import { Function } from 'aws-cdk-lib/aws-lambda';
+import { Stack } from 'aws-cdk-lib';
+
+// Create a Lambda function
+const processFunction = new Function(stack, 'ProcessFunction', {
+  // ... function configuration
+});
+
+// Create storage
+const storage = new AmplifyStorage(stack, 'Storage', {
+  name: 'my-app-storage',
+});
+
+// Grant the function access to storage
+storage.grantAccess(auth, {
+  'uploads/*': [
+    // Users can upload files
+    { type: 'authenticated', actions: ['write'] },
+    // Function can read and process uploaded files
+    { type: 'resource', actions: ['read'], resource: processFunction },
+  ],
+  'processed/*': [
+    // Function can write processed results
+    { type: 'resource', actions: ['write'], resource: processFunction },
+    // Users can read processed files
+    { type: 'authenticated', actions: ['read'] },
+  ],
+});
+```
+
+## Supported Resource Types
+
+The resource access functionality supports any construct that has an IAM role:
+
+### Lambda Functions
+
+```typescript
+{ type: 'resource', actions: ['read'], resource: lambdaFunction }
+```
+
+### Custom Constructs with Roles
+
+```typescript
+const customResource = {
+  role: myIamRole // Any IRole instance
+};
+
+{ type: 'resource', actions: ['read', 'write'], resource: customResource }
+```
+
+## Actions Available
+
+- `'read'`: Grants s3:GetObject and s3:ListBucket permissions
+- `'write'`: Grants s3:PutObject permissions
+- `'delete'`: Grants s3:DeleteObject permissions
+
+## Path Patterns
+
+Resource access follows the same path patterns as other access types:
+
+- `'public/*'`: Access to all files in public folder
+- `'functions/temp/*'`: Access to temporary files for functions
+- `'processing/{entity_id}/*'`: Not recommended for resources (entity substitution doesn't apply)
+
+## Complete Example
+
+```typescript
+import { AmplifyStorage } from '@aws-amplify/storage-construct';
+import { Function, Runtime, Code } from 'aws-cdk-lib/aws-lambda';
+import { Stack, App } from 'aws-cdk-lib';
+
+const app = new App();
+const stack = new Stack(app, 'MyStack');
+
+// Create processing function
+const imageProcessor = new Function(stack, 'ImageProcessor', {
+  runtime: Runtime.NODEJS_18_X,
+  handler: 'index.handler',
+  code: Code.fromInline(`
+    exports.handler = async (event) => {
+      // Process S3 events and manipulate files
+      console.log('Processing:', event);
+    };
+  `),
+});
+
+// Create storage with triggers and access
+const storage = new AmplifyStorage(stack, 'Storage', {
+  name: 'image-processing-storage',
+  triggers: {
+    onUpload: imageProcessor, // Trigger function on upload
+  },
+});
+
+// Configure access permissions
+storage.grantAccess(auth, {
+  'raw-images/*': [
+    { type: 'authenticated', actions: ['write'] }, // Users upload raw images
+    { type: 'resource', actions: ['read'], resource: imageProcessor }, // Function reads raw images
+  ],
+  'processed-images/*': [
+    { type: 'resource', actions: ['write'], resource: imageProcessor }, // Function writes processed images
+    { type: 'authenticated', actions: ['read'] }, // Users read processed images
+    { type: 'guest', actions: ['read'] }, // Public access to processed images
+  ],
+  'temp/*': [
+    {
+      type: 'resource',
+      actions: ['read', 'write', 'delete'],
+      resource: imageProcessor,
+    }, // Function manages temp files
+  ],
+});
+```
+
+This provides the same functionality as backend-storage's `allow.resource(myFunction).to(['read'])` pattern.

packages/storage-construct/src/auth_role_resolver.ts

@@ -81,9 +81,10 @@ export class AuthRoleResolver {
    * @returns The IAM role or undefined if not found
    */
   getRoleForAccessType = (
-    accessType: 'authenticated' | 'guest' | 'owner' | 'groups',
+    accessType: 'authenticated' | 'guest' | 'owner' | 'groups' | 'resource',
     authRoles: AuthRoles,
     groups?: string[],
+    resource?: unknown,
   ): IRole | undefined => {
     switch (accessType) {
       case 'authenticated':
@@ -106,8 +107,41 @@ export class AuthRoleResolver {
         }
         return undefined;
 
+      case 'resource':
+        return this.extractRoleFromResource(resource);
+
       default:
         return undefined;
     }
   };
+
+  /**
+   * Extracts IAM role from a resource construct.
+   * Supports Lambda functions and other constructs with IAM roles.
+   */
+  private extractRoleFromResource = (resource: unknown): IRole | undefined => {
+    if (!resource || typeof resource !== 'object') {
+      return undefined;
+    }
+
+    const resourceObj = resource as Record<string, unknown>;
+
+    // Try to extract role from Lambda function
+    if (resourceObj.role && typeof resourceObj.role === 'object') {
+      return resourceObj.role as IRole;
+    }
+
+    // Try to extract from resources property (common pattern)
+    if (resourceObj.resources && typeof resourceObj.resources === 'object') {
+      const resources = resourceObj.resources as Record<string, unknown>;
+      if (resources.lambda && typeof resources.lambda === 'object') {
+        const lambda = resources.lambda as Record<string, unknown>;
+        if (lambda.role) {
+          return lambda.role as IRole;
+        }
+      }
+    }
+
+    return undefined;
+  };
 }

packages/storage-construct/src/construct.test.ts

@@ -132,6 +132,33 @@ void describe('AmplifyStorage', () => {
     }, /Invalid auth construct/);
   });
 
+  void it('supports resource access for Lambda functions', () => {
+    const app = new App();
+    const stack = new Stack(app);
+    const storage = new AmplifyStorage(stack, 'test', { name: 'testName' });
+
+    const mockAuth = { resources: {} };
+    const mockFunction = {
+      role: {
+        attachInlinePolicy: () => {},
+        node: { id: 'MockFunctionRole' },
+      },
+    };
+
+    // Should not throw when granting resource access
+    assert.doesNotThrow(() => {
+      storage.grantAccess(mockAuth, {
+        'functions/*': [
+          {
+            type: 'resource' as const,
+            actions: ['read' as const, 'write' as const],
+            resource: mockFunction,
+          },
+        ],
+      });
+    });
+  });
+
   void describe('storage overrides', () => {
     void it('can override bucket properties', () => {
       const app = new App();

packages/storage-construct/src/construct.ts

@@ -125,7 +125,7 @@ export type StorageAccessRule = {
    * - 'owner': The user who owns the resource (uses entity_id substitution)
    * - 'groups': Specific user groups from Cognito User Pool
    */
-  type: 'authenticated' | 'guest' | 'owner' | 'groups';
+  type: 'authenticated' | 'guest' | 'owner' | 'groups' | 'resource';
 
   /**
    * Array of actions the principal can perform:
@@ -144,6 +144,12 @@ export type StorageAccessRule = {
    * ```
    */
   groups?: string[];
+
+  /**
+   * Required when type is 'resource'. The AWS resource that should get access.
+   * Currently supports Lambda functions and other constructs with IAM roles.
+   */
+  resource?: unknown;
 };
 
 /**
@@ -424,6 +430,7 @@ export class AmplifyStorage extends Construct {
           rule.type,
           authRoles,
           rule.groups,
+          rule.resource,
         );
 
         if (role) {
@@ -433,6 +440,10 @@ export class AmplifyStorage extends Construct {
             // For owner access, substitute with the user's Cognito identity ID
             idSubstitution = entityIdSubstitution;
           }
+          // Resource access also uses wildcard (no entity substitution)
+          if (rule.type === 'resource') {
+            idSubstitution = '*';
+          }
 
           // Add the access definition to be processed by the orchestrator
           accessDefinitions[storagePath].push({

packages/storage-construct/src/storage_access_orchestrator.test.ts

@@ -76,6 +76,53 @@ void describe('StorageAccessOrchestrator', () => {
       );
     });
 
+    void it('handles resource access with function role', () => {
+      const functionRole = new Role(stack, 'FunctionRole', {
+        assumedBy: new ServicePrincipal('lambda.amazonaws.com'),
+      });
+      const attachInlinePolicyMock = mock.method(
+        functionRole,
+        'attachInlinePolicy',
+      );
+      const storageAccessOrchestrator = new StorageAccessOrchestrator(
+        storageAccessPolicyFactory,
+      );
+
+      storageAccessOrchestrator.orchestrateStorageAccess({
+        'uploads/*': [
+          {
+            role: functionRole,
+            actions: ['read', 'write'],
+            idSubstitution: '*',
+          },
+        ],
+      });
+
+      // Should create policy for function role
+      assert.ok(attachInlinePolicyMock.mock.callCount() >= 1);
+
+      // Collect all statements from all policy calls
+      const allStatements = attachInlinePolicyMock.mock.calls
+        .map((call) => call.arguments[0].document.toJSON().Statement)
+        .flat();
+
+      // Verify GetObject statement
+      const getStatements = allStatements.filter(
+        (s: any) => s.Action === 's3:GetObject',
+      );
+      assert.ok(getStatements.length >= 1);
+      const getResources = getStatements.map((s: any) => s.Resource).flat();
+      assert.ok(getResources.includes(`${bucket.bucketArn}/uploads/*`));
+
+      // Verify PutObject statement
+      const putStatements = allStatements.filter(
+        (s: any) => s.Action === 's3:PutObject',
+      );
+      assert.ok(putStatements.length >= 1);
+      const putResources = putStatements.map((s: any) => s.Resource).flat();
+      assert.ok(putResources.includes(`${bucket.bucketArn}/uploads/*`));
+    });
+
     void it('passes expected policy to role', () => {
       const attachInlinePolicyMock = mock.method(
         authRole,