import { Effect, type IPrincipal, PolicyStatement } from "aws-cdk-lib/aws-iam";
/**
 * Thrown when a {@link StatementBuilder} is built with an `Allow` effect and
 * an unrestricted resource (`"*"`) without the caller having explicitly
 * opted in via {@link StatementBuilder.allowWildcardResources}.
 *
 * Wildcard-resource allow statements grant the widest possible permission
 * surface and should be an intentional choice, not an accident.
 *
 * Catch this by `name`, not `instanceof`: under the dual ESM/CJS build
 * (ADR-0007) the copy that threw may not be the copy the catching module
 * imported, and `instanceof` is realm-bound.
 *
 * @see https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/permissions-management.html
 */
export declare class WildcardResourceError extends Error {
    constructor(sid?: string);
}
/**
 * @internal Brands every {@link StatementBuilder} instance so
 * {@link isStatementBuilder} can recognise one without `instanceof`.
 * `instanceof` is realm-bound: when `@composurecdk/iam` is loaded as both ESM
 * and CommonJS in the same process (the dual-package hazard — ADR-0007), each
 * copy has its own `StatementBuilder` class and `instanceof` fails across the
 * boundary. A `Symbol.for(...)` brand is registered in the global symbol
 * registry, so a builder minted by either copy is still recognised by either.
 */
export declare const STATEMENT_BUILDER_BRAND: unique symbol;
/**
 * Fluent wrapper around the CDK {@link PolicyStatement}.
 *
 * Unlike other ComposureCDK builders this one is **not** a
 * {@link Lifecycle} — a policy statement is inline data attached to a Role,
 * ManagedPolicy, or resource policy rather than a standalone CDK construct,
 * so there is nothing to attach to a scope.
 *
 * The builder exists to:
 * - centralise least-privilege validation (wildcard-resource guard,
 *   {@link WildcardResourceError}),
 * - give every consumer (Role, ManagedPolicy, SNS TopicPolicy, future
 *   SQS/S3 bucket policies) one fluent API,
 * - remain interchangeable with raw {@link PolicyStatement} instances via
 *   {@link StatementBuilder.build}.
 *
 * @example
 * ```ts
 * const stmt = createStatementBuilder()
 *   .sid("StopDevInstances")
 *   .allow()
 *   .actions(["ec2:StopInstances", "ec2:DescribeInstances"])
 *   .resources(["*"])
 *   .allowWildcardResources(true)
 *   .build();
 * ```
 */
export declare class StatementBuilder {
    #private;
    /** @internal Realm-agnostic brand — see {@link STATEMENT_BUILDER_BRAND}. */
    readonly [STATEMENT_BUILDER_BRAND] = true;
    sid(sid: string): this;
    allow(): this;
    deny(): this;
    effect(effect: Effect): this;
    actions(actions: string[]): this;
    notActions(actions: string[]): this;
    resources(resources: string[]): this;
    notResources(resources: string[]): this;
    principals(principals: IPrincipal[]): this;
    notPrincipals(principals: IPrincipal[]): this;
    conditions(conditions: Record<string, Record<string, unknown>>): this;
    /**
     * Opt in to Effect=Allow statements with wildcard resources (`"*"`).
     *
     * The builder rejects wildcard resources by default to surface
     * least-privilege violations; call this to acknowledge that the
     * statement genuinely needs unrestricted scope (for example actions
     * such as `ec2:DescribeInstances` that do not support resource-level
     * permissions).
     *
     * @see https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_policies_actions-resources-contextkeys.html
     */
    allowWildcardResources(allow?: boolean): this;
    /**
     * Construct and return a {@link PolicyStatement} from the configured state.
     *
     * @throws {WildcardResourceError} when the statement is an Allow with a
     *   wildcard resource and wildcard resources have not been opted in to.
     */
    build(): PolicyStatement;
}
/**
 * Type guard distinguishing a {@link StatementBuilder} from an already-built
 * {@link PolicyStatement}.
 *
 * Recognises a builder by its {@link STATEMENT_BUILDER_BRAND} symbol rather
 * than `instanceof`, so it works across the dual-package boundary — a builder
 * produced by the ESM copy of `@composurecdk/iam` is still recognised by the
 * CommonJS copy and vice versa. Getting this wrong is not merely a type
 * confusion: the discrimination decides whether {@link StatementBuilder.build}
 * runs, and `build()` is where the wildcard-resource guard lives.
 */
export declare function isStatementBuilder(value: unknown): value is StatementBuilder;
/**
 * Creates a new {@link StatementBuilder} for configuring an IAM
 * {@link PolicyStatement} with least-privilege guardrails.
 *
 * @returns A fluent builder that produces a {@link PolicyStatement} when
 *   {@link StatementBuilder.build} is called.
 */
export declare function createStatementBuilder(): StatementBuilder;
//# sourceMappingURL=statement-builder.d.ts.map