[DRAFT] feat: Phase 4 - add function resource access support for storage-construct

.changeset/grumpy-icons-lie.md

@@ -0,0 +1,12 @@
+---
+'@aws-amplify/storage-construct': major
+---
+
+Initial release of standalone AmplifyStorage construct package
+
+- Create new `@aws-amplify/storage-construct` as standalone CDK L3 construct
+- Migrate AmplifyStorage implementation with CDK-native triggers
+- Add `grantAccess(auth, accessDefinition)` method for access control
+- Add `StorageAccessDefinition` type for structured access configuration
+- Support all S3 bucket features (CORS, versioning, SSL enforcement, auto-delete)
+- Provide comprehensive TypeScript declarations and API documentation

packages/storage-construct/.npmignore

@@ -0,0 +1,14 @@
+# Be very careful editing this file. It is crafted to work around [this issue](https://github.com/npm/npm/issues/4479)
+
+# First ignore everything
+**/*
+
+# Then add back in transpiled js and ts declaration files
+!lib/**/*.js
+!lib/**/*.d.ts
+
+# Then ignore test js and ts declaration files
+*.test.js
+*.test.d.ts
+
+# This leaves us with including only js and ts declaration files of functional code

packages/storage-construct/API.md

@@ -0,0 +1,117 @@
+## API Report File for "@aws-amplify/storage-construct"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { CfnBucket } from 'aws-cdk-lib/aws-s3';
+import { Construct } from 'constructs';
+import { EventType } from 'aws-cdk-lib/aws-s3';
+import { IBucket } from 'aws-cdk-lib/aws-s3';
+import { IFunction } from 'aws-cdk-lib/aws-lambda';
+import { IRole } from 'aws-cdk-lib/aws-iam';
+import { Policy } from 'aws-cdk-lib/aws-iam';
+import { Stack } from 'aws-cdk-lib';
+
+// @public
+export class AmplifyStorage extends Construct {
+    constructor(scope: Construct, id: string, props: AmplifyStorageProps);
+    addTrigger: (events: EventType[], handler: IFunction) => void;
+    grantAccess: (auth: unknown, access: StorageAccessConfig) => void;
+    readonly isDefault: boolean;
+    readonly name: string;
+    readonly resources: StorageResources;
+    readonly stack: Stack;
+}
+
+// @public
+export type AmplifyStorageProps = {
+    isDefault?: boolean;
+    name: string;
+    versioned?: boolean;
+    triggers?: Partial<Record<AmplifyStorageTriggerEvent, IFunction>>;
+};
+
+// @public
+export type AmplifyStorageTriggerEvent = 'onDelete' | 'onUpload';
+
+// @public
+export class AuthRoleResolver {
+    getRoleForAccessType: (accessType: "authenticated" | "guest" | "owner" | "groups" | "resource", authRoles: AuthRoles, groups?: string[], resource?: unknown) => IRole | undefined;
+    resolveRoles: () => AuthRoles;
+    validateAuthConstruct: (auth: unknown) => boolean;
+}
+
+// @public
+export type AuthRoles = {
+    authenticatedUserIamRole?: IRole;
+    unauthenticatedUserIamRole?: IRole;
+    userPoolGroups?: Record<string, {
+        role: IRole;
+    }>;
+};
+
+// @public
+export const entityIdPathToken = "{entity_id}";
+
+// @public
+export const entityIdSubstitution = "${cognito-identity.amazonaws.com:sub}";
+
+// @public
+export type InternalStorageAction = 'get' | 'list' | 'write' | 'delete';
+
+// @public
+export type StorageAccessConfig = {
+    [path: string]: StorageAccessRule[];
+};
+
+// @public
+export type StorageAccessDefinition = {
+    role: IRole;
+    actions: StorageAction[];
+    idSubstitution: string;
+};
+
+// @public
+export class StorageAccessOrchestrator {
+    constructor(policyFactory: StorageAccessPolicyFactory);
+    orchestrateStorageAccess: (accessDefinitions: Record<StoragePath, StorageAccessDefinition[]>) => void;
+}
+
+// @public
+export class StorageAccessPolicyFactory {
+    constructor(bucket: IBucket);
+    createPolicy: (accessMap: Map<InternalStorageAction, {
+        allow: Set<StoragePath>;
+        deny: Set<StoragePath>;
+    }>) => Policy;
+}
+
+// @public
+export type StorageAccessRule = {
+    type: 'authenticated' | 'guest' | 'owner' | 'groups' | 'resource';
+    actions: Array<'read' | 'write' | 'delete'>;
+    groups?: string[];
+    resource?: unknown;
+};
+
+// @public
+export type StorageAction = 'read' | 'write' | 'delete';
+
+// @public
+export type StoragePath = `${string}/*`;
+
+// @public
+export type StorageResources = {
+    bucket: IBucket;
+    cfnResources: {
+        cfnBucket: CfnBucket;
+    };
+};
+
+// @public
+export const validateStorageAccessPaths: (storagePaths: string[]) => void;
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/storage-construct/README.md

@@ -0,0 +1,3 @@
+# Description
+
+Replace with a description of this package

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/api-extractor.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../api-extractor.base.json",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts"
+}

packages/storage-construct/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@aws-amplify/storage-construct",
+  "version": "0.1.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.js"
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf lib",
+    "test": "node --test lib/*.test.js",
+    "update:api": "api-extractor run --local"
+  },
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@aws-amplify/backend-output-storage": "^1.3.1"
+  },
+  "peerDependencies": {
+    "aws-cdk-lib": "^2.189.1",
+    "constructs": "^10.0.0"
+  }
+}