import { type IGrantable, PolicyDocument, PolicyStatement, Role, type RoleProps } from "aws-cdk-lib/aws-iam";
import type { IConstruct } from "constructs";
import { COPY_STATE, type Grant, type Lifecycle, type Resolvable } from "@composurecdk/core";
import { type ITaggedBuilder } from "@composurecdk/cloudformation";
import { type StatementBuilder } from "./statement-builder.js";
/**
 * Configuration properties for the IAM role builder.
 *
 * Extends the CDK {@link RoleProps} with builder-specific options for
 * cross-component wiring: `assumedBy` and `permissionsBoundary` each accept a
 * {@link Resolvable} so principals and boundary policies built by sibling
 * components can be referenced at configuration time.
 *
 * Each re-declared prop reads its inner type from CDK's own prop rather than
 * naming an interface, so it keeps tracking the installed `aws-cdk-lib` as CDK
 * moves its prop types (ADR-0018).
 */
export interface RoleBuilderProps extends Omit<RoleProps, "assumedBy" | "permissionsBoundary"> {
    /**
     * The principal the role trusts to assume it — the role's trust policy.
     *
     * Accepts a concrete principal or a {@link Resolvable} for cross-component
     * wiring, so a principal derived from a provider built by a sibling
     * component (e.g. `ref("oidc", r => r.provider)`) can be supplied at
     * configuration time and resolved during {@link build}.
     *
     * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_terms-and-concepts.html
     */
    assumedBy?: Resolvable<NonNullable<RoleProps["assumedBy"]>>;
    /**
     * A permissions boundary that caps the maximum permissions this role
     * can ever grant, regardless of inline or managed policies attached.
     *
     * Accepts a concrete managed policy or a {@link Resolvable} for
     * cross-component wiring (e.g. `ref("boundary", r => r.policy)`).
     *
     * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html
     */
    permissionsBoundary?: Resolvable<NonNullable<RoleProps["permissionsBoundary"]>>;
}
/**
 * The build output of an {@link IRoleBuilder}.
 *
 * Exposes every CDK construct the builder creates so consumers can reference,
 * extend, or attach additional policies to them.
 */
export interface RoleBuilderResult {
    /** The IAM role construct created by the builder. */
    role: Role;
    /**
     * Inline {@link PolicyDocument}s created for each
     * {@link IRoleBuilder.addInlinePolicyStatements} call, keyed by the
     * policy name supplied to the call.
     *
     * The documents are embedded in the underlying `AWS::IAM::Role`
     * resource via the native `Policies` array — no separate
     * `AWS::IAM::Policy` resources are created.
     *
     * Inline policies supplied directly via the native `inlinePolicies`
     * prop on {@link RoleProps} do not appear in this map.
     */
    inlinePolicies: Record<string, PolicyDocument>;
}
/**
 * A fluent builder for configuring and creating an AWS IAM role.
 *
 * Each configuration property from the CDK {@link RoleProps} is exposed as
 * an overloaded method: call with a value to set it, or with no arguments
 * to read the current value.
 *
 * The builder implements {@link Lifecycle}, so it can be used directly as a
 * component in a {@link compose | composed system}. When built it creates
 * an IAM role with well-architected defaults ({@link ROLE_DEFAULTS}) and
 * returns a {@link RoleBuilderResult}.
 *
 * @see https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_iam.Role.html
 *
 * @example
 * ```ts
 * const role = createRoleBuilder()
 *   .assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
 *   .description("Execution role for the budget remediation Lambda")
 *   .addInlinePolicyStatements("StopEC2", [
 *     createStatementBuilder()
 *       .allow()
 *       .actions(["ec2:StopInstances", "ec2:DescribeInstances"])
 *       .resources(["*"])
 *       .allowWildcardResources(true)
 *       .build(),
 *   ]);
 * ```
 */
export type IRoleBuilder = ITaggedBuilder<RoleBuilderProps, RoleBuilder>;
declare class RoleBuilder implements Lifecycle<RoleBuilderResult> {
    #private;
    props: Partial<RoleBuilderProps>;
    /**
     * Append an inline policy to the role, embedded in the underlying
     * `AWS::IAM::Role` resource's `Policies` array. The policy name becomes
     * the key under which the resulting {@link PolicyDocument} appears in
     * {@link RoleBuilderResult.inlinePolicies}.
     *
     * Accepts either {@link PolicyStatement} instances or
     * {@link StatementBuilder}s (which are built lazily during {@link build}
     * so that wildcard-resource validation runs at the composition boundary
     * rather than at configuration time).
     */
    addInlinePolicyStatements(name: string, statements: (PolicyStatement | StatementBuilder)[]): this;
    /**
     * Grant this role access to a resource built by a sibling component.
     *
     * Grants are declared on the consumer — the role that needs the access —
     * so the dependency edge points from the role to the resource, matching the
     * data flow. Each {@link Grant} comes from a resource package's capability
     * helper (e.g. `tableGrants.readWrite(ref("table", (r) => r.table))`) and is
     * applied during this builder's {@link build}, once the resource resolves.
     *
     * @see ADR-0013
     *
     * @example
     * ```ts
     * createServiceRoleBuilder("apigateway.amazonaws.com")
     *   .grant(tableGrants.readWrite(ref("table", (r) => r.table)));
     * ```
     */
    grant(...grants: Grant<IGrantable>[]): this;
    /** @internal — see ADR-0005. */
    [COPY_STATE](target: RoleBuilder): void;
    build(scope: IConstruct, id: string, context?: Record<string, object>): RoleBuilderResult;
}
/**
 * Creates a new {@link IRoleBuilder} for configuring an AWS IAM role.
 *
 * @returns A fluent builder for an AWS IAM role.
 *
 * @example
 * ```ts
 * const role = createRoleBuilder()
 *   .assumedBy(new ServicePrincipal("lambda.amazonaws.com"))
 *   .description("Lambda execution role")
 *   .build(stack, "LambdaRole");
 * ```
 */
export declare function createRoleBuilder(): IRoleBuilder;
export {};
//# sourceMappingURL=role-builder.d.ts.map