453 lines
16 KiB
TypeScript
453 lines
16 KiB
TypeScript
import type { IConstruct, IDependable } from 'constructs';
|
|
import { PolicyStatement } from './policy-statement';
|
|
import type { IGrantable, IPrincipal } from './principals';
|
|
import type { IEnvironmentAware } from '../../core';
|
|
import { CfnResource } from '../../core';
|
|
import * as cdk from '../../core';
|
|
/**
|
|
* Basic options for a grant operation
|
|
*
|
|
*/
|
|
export interface CommonGrantOptions {
|
|
/**
|
|
* The principal to grant to
|
|
*
|
|
* @default if principal is undefined, no work is done.
|
|
*/
|
|
readonly grantee: IGrantable;
|
|
/**
|
|
* The actions to grant
|
|
*/
|
|
readonly actions: string[];
|
|
/**
|
|
* The resource ARNs to grant to
|
|
*/
|
|
readonly resourceArns: string[];
|
|
/**
|
|
* Any conditions to attach to the grant
|
|
*
|
|
* @default - No conditions
|
|
*/
|
|
readonly conditions?: Record<string, Record<string, unknown>>;
|
|
}
|
|
/**
|
|
* Options for a grant operation
|
|
*
|
|
*/
|
|
export interface GrantWithResourceOptions extends CommonGrantOptions {
|
|
/**
|
|
* The resource with a resource policy
|
|
*
|
|
* The statement will be added to the resource policy if it couldn't be
|
|
* added to the principal policy.
|
|
*/
|
|
readonly resource: IResourceWithPolicyV2;
|
|
/**
|
|
* When referring to the resource in a resource policy, use this as ARN.
|
|
*
|
|
* (Depending on the resource type, this needs to be '*' in a resource policy).
|
|
*
|
|
* @default Same as regular resource ARNs
|
|
*/
|
|
readonly resourceSelfArns?: string[];
|
|
}
|
|
/**
|
|
* Options for a grant operation that directly adds a policy statement to a resource
|
|
*
|
|
* This differs from GrantWithResourceOptions in that it requires a pre-constructed
|
|
* PolicyStatement rather than constructing one from individual permissions.
|
|
* Use this when you need fine-grained control over the initial policy statement's contents.
|
|
*/
|
|
export interface GrantPolicyWithResourceOptions extends GrantWithResourceOptions {
|
|
/**
|
|
* The policy statement to add to the resource's policy
|
|
*
|
|
* This statement will be passed to the resource's addToResourcePolicy method.
|
|
* The actual handling of the statement depends on the specific IResourceWithPolicyV2
|
|
* implementation.
|
|
*/
|
|
readonly statement: PolicyStatement;
|
|
}
|
|
/**
|
|
* Options for a grant operation that only applies to principals
|
|
*
|
|
*/
|
|
export interface GrantOnPrincipalOptions extends CommonGrantOptions {
|
|
/**
|
|
* Construct to report warnings on in case grant could not be registered
|
|
*
|
|
* @default - the construct in which this construct is defined
|
|
* @deprecated The scope argument is currently unused.
|
|
*/
|
|
readonly scope?: IConstruct;
|
|
}
|
|
/**
|
|
* Options for a grant operation to both identity and resource
|
|
*
|
|
*/
|
|
export interface GrantOnPrincipalAndResourceOptions extends CommonGrantOptions {
|
|
/**
|
|
* The resource with a resource policy
|
|
*
|
|
* The statement will always be added to the resource policy.
|
|
*/
|
|
readonly resource: IResourceWithPolicyV2;
|
|
/**
|
|
* When referring to the resource in a resource policy, use this as ARN.
|
|
*
|
|
* (Depending on the resource type, this needs to be '*' in a resource policy).
|
|
*
|
|
* @default Same as regular resource ARNs
|
|
*/
|
|
readonly resourceSelfArns?: string[];
|
|
/**
|
|
* The principal to use in the statement for the resource policy.
|
|
*
|
|
* @default - the principal of the grantee will be used
|
|
*/
|
|
readonly resourcePolicyPrincipal?: IPrincipal;
|
|
}
|
|
/**
|
|
* Result of a grant() operation
|
|
*
|
|
* This class is not instantiable by consumers on purpose, so that they will be
|
|
* required to call the Grant factory functions.
|
|
*/
|
|
export declare class Grant implements IDependable {
|
|
/**
|
|
* Grant the given permissions to the principal
|
|
*
|
|
* The permissions will be added to the principal policy primarily, falling
|
|
* back to the resource policy if necessary. The permissions must be granted
|
|
* somewhere.
|
|
*
|
|
* - Trying to grant permissions to a principal that does not admit adding to
|
|
* the principal policy while not providing a resource with a resource policy
|
|
* is an error.
|
|
* - Trying to grant permissions to an absent principal (possible in the
|
|
* case of imported resources) leads to a warning being added to the
|
|
* resource construct.
|
|
*/
|
|
static addToPrincipalOrResource(options: GrantWithResourceOptions): Grant;
|
|
/**
|
|
* Add a pre-constructed policy statement to the resource's policy
|
|
*
|
|
* This method provides direct, low-level control over the initial policy statement being added.
|
|
* It is useful when you need to:
|
|
* - Add complex policy statements that can't be expressed through other grant methods
|
|
* - Specify the initial structure of the policy statement
|
|
* - Add statements with custom conditions or other advanced IAM features
|
|
*
|
|
* Important differences from other grant methods:
|
|
* - Only modifies the resource policy, never modifies any principal's policy
|
|
* - Takes a complete PolicyStatement rather than constructing one from parameters
|
|
* - Always attempts to add the statement, regardless of principal type or account
|
|
* - Does not attempt any automatic principal/resource policy selection logic
|
|
*
|
|
* Note: The final form of the policy statement in the resource's policy may differ
|
|
* from the provided statement, depending on the resource's implementation of
|
|
* addToResourcePolicy.
|
|
*
|
|
* @param options Contains both the target resource and the policy statement to add
|
|
* @returns A Grant object representing the result of the operation
|
|
*
|
|
* @example
|
|
*
|
|
* declare const grantee: iam.IGrantable;
|
|
* declare const actions: string[];
|
|
* declare const resourceArns: string[];
|
|
* declare const bucket: s3.Bucket;
|
|
*
|
|
* const statement = new iam.PolicyStatement({
|
|
* effect: iam.Effect.ALLOW,
|
|
* actions: actions,
|
|
* principals: [new iam.ServicePrincipal('lambda.amazonaws.com')],
|
|
* conditions: {
|
|
* StringEquals: {
|
|
* 'aws:SourceAccount': Stack.of(this).account,
|
|
* },
|
|
* },
|
|
* });
|
|
* iam.Grant.addStatementToResourcePolicy({
|
|
* grantee: grantee,
|
|
* actions: actions,
|
|
* resourceArns: resourceArns,
|
|
* resource: bucket,
|
|
* statement: statement,
|
|
* });
|
|
*
|
|
*/
|
|
static addStatementToResourcePolicy(options: GrantPolicyWithResourceOptions): Grant;
|
|
/**
|
|
* Try to grant the given permissions to the given principal
|
|
*
|
|
* Absence of a principal leads to a warning, but failing to add
|
|
* the permissions to a present principal is not an error.
|
|
*/
|
|
static addToPrincipal(options: GrantOnPrincipalOptions): Grant;
|
|
/**
|
|
* Add a grant both on the principal and on the resource
|
|
*
|
|
* As long as any principal is given, granting on the principal may fail (in
|
|
* case of a non-identity principal), but granting on the resource will
|
|
* never fail.
|
|
*
|
|
* Statement will be the resource statement.
|
|
*/
|
|
static addToPrincipalAndResource(options: GrantOnPrincipalAndResourceOptions): Grant;
|
|
/**
|
|
* Returns a "no-op" `Grant` object which represents a "dropped grant".
|
|
*
|
|
* This can be used for e.g. imported resources where you may not be able to modify
|
|
* the resource's policy or some underlying policy which you don't know about.
|
|
*
|
|
* @param grantee The intended grantee
|
|
* @param _intent The user's intent (will be ignored at the moment)
|
|
*/
|
|
static drop(grantee: IGrantable, _intent: string): Grant;
|
|
/**
|
|
* The statement that was added to the principal's policy
|
|
*
|
|
* @deprecated Use `principalStatements` instead
|
|
*/
|
|
readonly principalStatement?: PolicyStatement;
|
|
/**
|
|
* The statements that were added to the principal's policy
|
|
*/
|
|
readonly principalStatements: PolicyStatement[];
|
|
/**
|
|
* The statement that was added to the resource policy
|
|
*
|
|
* @deprecated Use `resourceStatements` instead
|
|
*/
|
|
readonly resourceStatement?: PolicyStatement;
|
|
/**
|
|
* The statements that were added to the resource policy
|
|
*/
|
|
readonly resourceStatements: PolicyStatement[];
|
|
/**
|
|
* The options originally used to set this result
|
|
*
|
|
* Private member doubles as a way to make it impossible for an object literal to
|
|
* be structurally the same as this class.
|
|
*/
|
|
private readonly options;
|
|
private readonly dependables;
|
|
private constructor();
|
|
/**
|
|
* Whether the grant operation was successful
|
|
*/
|
|
get success(): boolean;
|
|
/**
|
|
* Throw an error if this grant wasn't successful
|
|
*/
|
|
assertSuccess(): void;
|
|
/**
|
|
* Make sure this grant is applied before the given constructs are deployed
|
|
*
|
|
* The same as construct.node.addDependency(grant), but slightly nicer to read.
|
|
*/
|
|
applyBefore(...constructs: IConstruct[]): void;
|
|
/**
|
|
* Combine two grants into a new one
|
|
*/
|
|
combine(rhs: Grant): Grant;
|
|
}
|
|
/**
|
|
* Result of a call to grantOnKey().
|
|
*/
|
|
export interface GrantOnKeyResult {
|
|
/**
|
|
* The Grant object, if a grant was created.
|
|
*
|
|
* @default No grant
|
|
*/
|
|
readonly grant?: Grant;
|
|
}
|
|
/**
|
|
* Utility class for discovering and managing resource policy traits
|
|
*
|
|
* This class provides methods to retrieve IResourceWithPolicyV2 instances from constructs,
|
|
* enabling resource-based policy management during IAM grant operations.
|
|
*/
|
|
export declare class ResourceWithPolicies {
|
|
/**
|
|
* Retrieve the IResourceWithPolicyV2 associated with a construct, if available.
|
|
*/
|
|
static of(resource: IEnvironmentAware): IResourceWithPolicyV2 | undefined;
|
|
/**
|
|
* Register a factory for a specific CloudFormation resource type and scope
|
|
*/
|
|
static register(scope: IConstruct, cfnType: string, factory: IResourcePolicyFactory): void;
|
|
private static traits;
|
|
}
|
|
/**
|
|
* Utility class for discovering and registering encrypted resource traits
|
|
*
|
|
* This class provides methods to retrieve IEncryptedResource instances from constructs,
|
|
* enabling automatic KMS key permission grants during IAM grant operations.
|
|
*/
|
|
export declare class EncryptedResources {
|
|
/**
|
|
* Retrieve the IEncryptedResource associated with a construct, if available.
|
|
*/
|
|
static of(resource: IEnvironmentAware): IEncryptedResource | undefined;
|
|
/**
|
|
* Register a factory for a specific CloudFormation resource type and scope
|
|
*/
|
|
static register(scope: IConstruct, cfnType: string, factory: IEncryptedResourceFactory): void;
|
|
private static traits;
|
|
}
|
|
/**
|
|
* Factory interface for creating IResourceWithPolicyV2 instances from constructs
|
|
*
|
|
* Implementations of this interface are registered in the DefaultPolicyFactories registry
|
|
* and enable automatic resource policy support for CloudFormation resources. When a grant
|
|
* operation is performed, the factory converts L1 constructs into resources that support
|
|
* resource-based policies.
|
|
*
|
|
* Factories are typically registered during static initialization and associated with
|
|
* specific CloudFormation resource types (e.g., 'AWS::DynamoDB::Table'). The CDK's grant
|
|
* system uses these factories to determine whether a resource supports resource policies
|
|
* and to create the appropriate wrapper when needed.
|
|
*/
|
|
export interface IResourcePolicyFactory {
|
|
/**
|
|
* Create an IResourceWithPolicyV2 from a construct
|
|
* @param resource the construct to be wrapped as an IResourceWithPolicyV2.
|
|
*/
|
|
forResource(resource: CfnResource): IResourceWithPolicyV2;
|
|
}
|
|
/**
|
|
* Factory interface for creating IEncryptedResource instances from constructs
|
|
*
|
|
* Implementations of this interface are registered in the DefaultEncryptedResourceFactories
|
|
* registry and enable automatic KMS key permission grants for encrypted CloudFormation resources.
|
|
* When a grant operation is performed on an encrypted resource, the factory converts L1 constructs
|
|
* into resources that can grant permissions on their associated KMS encryption keys.
|
|
*
|
|
* Factories are typically registered during static initialization and associated with specific
|
|
* CloudFormation resource types (e.g., 'AWS::DynamoDB::Table'). The CDK's grant system uses
|
|
* these factories to automatically add necessary KMS key permissions when granting access to
|
|
* encrypted resources.
|
|
*/
|
|
export interface IEncryptedResourceFactory {
|
|
/**
|
|
* Create an IEncryptedResource from a construct
|
|
*
|
|
* @param resource the construct to be wrapped as an IEncryptedResource.
|
|
*/
|
|
forResource(resource: CfnResource): IEncryptedResource;
|
|
}
|
|
/**
|
|
* A resource that contains data that can be encrypted, using a KMS key.s
|
|
*/
|
|
export interface IEncryptedResource extends IEnvironmentAware {
|
|
/**
|
|
* Gives permissions to a grantable entity to perform actions on the encryption key.
|
|
*/
|
|
grantOnKey(grantee: IGrantable, ...actions: string[]): GrantOnKeyResult;
|
|
}
|
|
/**
|
|
* A resource with a resource policy that can be added to
|
|
*/
|
|
export interface IResourceWithPolicyV2 extends IEnvironmentAware {
|
|
/**
|
|
* Add a statement to the resource's resource policy
|
|
*/
|
|
addToResourcePolicy(statement: PolicyStatement): AddToResourcePolicyResult;
|
|
}
|
|
/**
|
|
* Utility methods to check for specific types of grantable resources
|
|
*/
|
|
export declare class GrantableResources {
|
|
/**
|
|
* Whether this resource admits a resource policy.
|
|
*/
|
|
static isResourceWithPolicy(resource: IEnvironmentAware): resource is IResourceWithPolicyV2;
|
|
/**
|
|
* Whether this resource holds data that can be encrypted using a KMS key.
|
|
*/
|
|
static isEncryptedResource(resource: IEnvironmentAware): resource is IEncryptedResource;
|
|
}
|
|
/**
|
|
* A resource with a resource policy that can be added to
|
|
*
|
|
* This interface is maintained for backwards compatibility, but should
|
|
* not be used in new code. Prefer `IResourceWithPolicyV2` instead.
|
|
*
|
|
* @deprecated Implement `IResourceWithPolicyV2` instead.
|
|
*/
|
|
export interface IResourceWithPolicy extends IResourceWithPolicyV2, cdk.IResource {
|
|
}
|
|
/**
|
|
* Result of calling addToResourcePolicy
|
|
*/
|
|
export interface AddToResourcePolicyResult {
|
|
/**
|
|
* Whether the statement was added
|
|
*/
|
|
readonly statementAdded: boolean;
|
|
/**
|
|
* Dependable which allows depending on the policy change being applied
|
|
*
|
|
* @default - If `statementAdded` is true, the resource object itself.
|
|
* Otherwise, no dependable.
|
|
*/
|
|
readonly policyDependable?: IDependable;
|
|
}
|
|
/**
|
|
* Composite dependable
|
|
*
|
|
* Not as simple as eagerly getting the dependency roots from the
|
|
* inner dependables, as they may be mutable so we need to defer
|
|
* the query.
|
|
*/
|
|
export declare class CompositeDependable implements IDependable {
|
|
constructor(...dependables: IDependable[]);
|
|
}
|
|
/**
|
|
* Default factories for resources with policies
|
|
*/
|
|
export declare class DefaultPolicyFactories {
|
|
/**
|
|
* Get the default factory for a given CloudFormation resource type
|
|
* @param type the CloudFormation resource type (e.g., 'AWS::DynamoDB::Table')
|
|
*/
|
|
static get(type: string): IResourcePolicyFactory | undefined;
|
|
/**
|
|
* Register a default factory for a given CloudFormation resource type
|
|
* @param type the CloudFormation resource type (e.g., 'AWS::DynamoDB::Table')
|
|
* @param factory the factory to register for this resource type
|
|
*/
|
|
static set(type: string, factory: IResourcePolicyFactory): void;
|
|
/**
|
|
* Check if a default factory is registered for a given CloudFormation resource type
|
|
* @param type the CloudFormation resource type (e.g., 'AWS::DynamoDB::Table')
|
|
*/
|
|
static has(type: string): boolean;
|
|
private static readonly map;
|
|
}
|
|
/**
|
|
* Default factories for encrypted resources
|
|
*/
|
|
export declare class DefaultEncryptedResourceFactories {
|
|
/**
|
|
* Get the default factory for a given CloudFormation resource type
|
|
* @param type the CloudFormation resource type (e.g., 'AWS::DynamoDB::Table')
|
|
*/
|
|
static get(type: string): IEncryptedResourceFactory | undefined;
|
|
/**
|
|
* Register a default factory for a given CloudFormation resource type
|
|
* @param type the CloudFormation resource type (e.g., 'AWS::DynamoDB::Table')
|
|
* @param factory the factory to register for this resource type
|
|
*/
|
|
static set(type: string, factory: IEncryptedResourceFactory): void;
|
|
/**
|
|
* Check if a default factory is registered for a given CloudFormation resource type
|
|
* @param type the CloudFormation resource type (e.g., 'AWS::DynamoDB::Table')
|
|
*/
|
|
static has(type: string): boolean;
|
|
private static readonly map;
|
|
}
|