aws-cdk-lib/aws-iam/lib/grant.d.ts

Version 2 of the AWS Cloud Development Kit library

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;
}