add storage access rules to outputs (#1927)

* add storage access rules to outputs

* fix tests

* remove read action from storage access rule outputs in favor of get and list

* update api.md

* update permissions for non entity roles for entity_id paths

* add entity id substitution constant

* add comments for new behavior with owner paths

* add back read

* pr feedback

* update api.md

Author: rtpascual

.changeset/two-sloths-clap.md

@@ -0,0 +1,10 @@
+---
+'@aws-amplify/client-config': minor
+'@aws-amplify/backend-output-schemas': patch
+'@aws-amplify/integration-tests': patch
+'@aws-amplify/backend-storage': patch
+'@aws-amplify/backend': patch
+'@aws-amplify/backend-cli': patch
+---
+
+add storage access rules to outputs

packages/backend-output-schemas/src/storage/v1.ts

@@ -1,9 +1,29 @@
 import { z } from 'zod';
 
+const storageAccessActionEnum = z.enum([
+  'read',
+  'get',
+  'list',
+  'write',
+  'delete',
+]);
+
+const pathSchema = z.record(
+  z.string(),
+  z.object({
+    guest: z.array(storageAccessActionEnum).optional(),
+    authenticated: z.array(storageAccessActionEnum).optional(),
+    groups: z.array(storageAccessActionEnum).optional(),
+    entity: z.array(storageAccessActionEnum).optional(),
+    resource: z.array(storageAccessActionEnum).optional(),
+  })
+);
+
 const bucketSchema = z.object({
   name: z.string(),
   bucketName: z.string(),
   storageRegion: z.string(),
+  paths: pathSchema.optional(),
 });
 
 export const storageOutputSchema = z.object({

packages/backend-storage/src/access_builder.ts

@@ -5,6 +5,7 @@ import {
   ResourceProvider,
 } from '@aws-amplify/plugin-types';
 import { StorageAccessBuilder } from './types.js';
+import { entityIdSubstitution } from './constants.js';
 
 export const roleAccessBuilder: StorageAccessBuilder = {
   authenticated: {
@@ -69,7 +70,7 @@ export const roleAccessBuilder: StorageAccessBuilder = {
         },
       ],
       actions,
-      idSubstitution: '${cognito-identity.amazonaws.com:sub}',
+      idSubstitution: entityIdSubstitution,
     }),
   }),
   resource: (other) => ({

packages/backend-storage/src/constants.ts

@@ -1 +1,2 @@
 export const entityIdPathToken = '{entity_id}';
+export const entityIdSubstitution = '${cognito-identity.amazonaws.com:sub}';

packages/backend-storage/src/construct.ts

@@ -20,6 +20,7 @@ import { AttributionMetadataStorage } from '@aws-amplify/backend-output-storage'
 import { fileURLToPath } from 'node:url';
 import { IFunction } from 'aws-cdk-lib/aws-lambda';
 import { S3EventSourceV2 } from 'aws-cdk-lib/aws-lambda-event-sources';
+import { StorageAccessDefinitionOutput } from './private_types.js';
 
 // Be very careful editing this value. It is the string that is used to attribute stacks to Amplify Storage in BI metrics
 const storageStackType = 'storage-S3';
@@ -84,6 +85,7 @@ export class AmplifyStorage
   readonly resources: StorageResources;
   readonly isDefault: boolean;
   readonly name: string;
+  accessDefinition: StorageAccessDefinitionOutput;
   /**
    * Create a new AmplifyStorage instance
    */
@@ -146,4 +148,11 @@ export class AmplifyStorage
       new S3EventSourceV2(this.resources.bucket, { events })
     );
   };
+
+  /**
+   * Add access definitions to storage
+   */
+  addAccessDefinition = (accessOutput: StorageAccessDefinitionOutput) => {
+    this.accessDefinition = accessOutput;
+  };
 }

packages/backend-storage/src/private_types.ts

@@ -15,3 +15,9 @@ export type StorageError =
  * StorageAction type intended to be used after mapping "read" to "get" and "list"
  */
 export type InternalStorageAction = Exclude<StorageAction, 'read'>;
+
+/**
+ * Storage access types intended to be used to map storage access to storage outputs
+ */
+export type StorageAccessConfig = Record<string, InternalStorageAction[]>;
+export type StorageAccessDefinitionOutput = Record<string, StorageAccessConfig>;