@aws-cdk/aws-bedrock-agentcore-alpha 2.250.0-alpha.0 → 2.252.0-alpha.0

package/lib/policy/policy-statement.d.ts

@@ -0,0 +1,518 @@
+/**
+ *  Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ *
+ *  Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+ *  with the License. A copy of the License is located at
+ *
+ *      http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *  or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+ *  OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+ *  and limitations under the License.
+ */
+/**
+ * A single condition expression in Cedar policy language.
+ */
+declare class ConditionExpression {
+    private readonly attribute;
+    private readonly operator;
+    private readonly value;
+    constructor(attribute: string, operator: string, value: string | number | boolean);
+    toCedar(): string;
+}
+/**
+ * Builder for condition expressions in Cedar policies.
+ *
+ * Conditions define when a policy statement should apply or not apply.
+ * Supports logical operators (AND, OR) and various comparison operators.
+ */
+export declare class ConditionBuilder {
+    private conditions;
+    private operators;
+    /**
+     * Access a principal attribute for comparison.
+     *
+     * Principal attributes come from the authenticated user/service making the request.
+     * Common attributes: username, role, department, groups, etc.
+     *
+     * @param attribute - The attribute name (e.g., 'department', 'role', 'username')
+     */
+    principalAttribute(attribute: string): AttributeAccessor;
+    /**
+     * Access a resource attribute for comparison.
+     *
+     * Resource attributes come from the target resource being accessed.
+     * Common attributes: arn, type, tags, owner, etc.
+     *
+     * @param attribute - The attribute name (e.g., 'confidential', 'owner', 'classification')
+     */
+    resourceAttribute(attribute: string): AttributeAccessor;
+    /**
+     * Access a context attribute for comparison.
+     *
+     * Context attributes come from the request environment.
+     * Common attributes: sourceIp, timestamp, environment, region, etc.
+     *
+     * @param attribute - The attribute name (e.g., 'sourceIp', 'environment', 'timestamp')
+     */
+    contextAttribute(attribute: string): AttributeAccessor;
+    /**
+     * Logical AND operator - all conditions must be true.
+     */
+    and(): this;
+    /**
+     * Logical OR operator - at least one condition must be true.
+     */
+    or(): this;
+    /**
+     * Internal method to add a condition expression.
+     * @internal
+     */
+    _addCondition(condition: ConditionExpression): this;
+    /**
+     * Generate Cedar condition syntax.
+     * @internal
+     */
+    _toCedar(): string;
+}
+/**
+ * Wrapper class for conditionally building policy statements.
+ *
+ * This class allows chaining condition methods and returning to the parent
+ * PolicyStatement when done. It proxies condition building methods from
+ * ConditionBuilder.
+ */
+export declare class ConditionalPolicyStatement {
+    private readonly policyStatement;
+    private readonly conditionBuilder;
+    constructor(policyStatement: PolicyStatement, conditionBuilder: ConditionBuilder);
+    /**
+     * Access a principal attribute for comparison.
+     *
+     * @param attribute - The attribute name (e.g., 'department', 'role', 'username')
+     */
+    principalAttribute(attribute: string): ConditionalAttributeAccessor;
+    /**
+     * Access a resource attribute for comparison.
+     *
+     * @param attribute - The attribute name (e.g., 'confidential', 'owner', 'classification')
+     */
+    resourceAttribute(attribute: string): ConditionalAttributeAccessor;
+    /**
+     * Access a context attribute for comparison.
+     *
+     * @param attribute - The attribute name (e.g., 'sourceIp', 'environment', 'timestamp')
+     */
+    contextAttribute(attribute: string): ConditionalAttributeAccessor;
+    /**
+     * Logical AND operator - all conditions must be true.
+     */
+    and(): this;
+    /**
+     * Logical OR operator - at least one condition must be true.
+     */
+    or(): this;
+    /**
+     * Complete condition building and return to the PolicyStatement.
+     *
+     * Use this to finish building when/unless conditions and continue
+     * configuring the policy statement.
+     */
+    done(): PolicyStatement;
+    /**
+     * Alias for done() to support fluent unless() chaining.
+     */
+    unless(): ConditionalPolicyStatement;
+}
+/**
+ * Accessor for building type-safe attribute comparisons within conditional statements.
+ *
+ * Returns ConditionalPolicyStatement to allow chaining back to policy building.
+ */
+export declare class ConditionalAttributeAccessor {
+    private readonly path;
+    private readonly parent;
+    private readonly conditionBuilder;
+    constructor(path: string, parent: ConditionalPolicyStatement, conditionBuilder: ConditionBuilder);
+    /**
+     * Equality comparison (==)
+     */
+    equalTo(value: string | number | boolean): ConditionalPolicyStatement;
+    /**
+     * Inequality comparison (!=)
+     */
+    notEqualTo(value: string | number | boolean): ConditionalPolicyStatement;
+    /**
+     * Less than comparison (<)
+     */
+    lessThan(value: number): ConditionalPolicyStatement;
+    /**
+     * Less than or equals comparison (<=)
+     */
+    lessThanOrEqualTo(value: number): ConditionalPolicyStatement;
+    /**
+     * Greater than comparison (>)
+     */
+    greaterThan(value: number): ConditionalPolicyStatement;
+    /**
+     * Greater than or equals comparison (>=)
+     */
+    greaterThanOrEqualTo(value: number): ConditionalPolicyStatement;
+    /**
+     * IP range check - tests if IP address is in CIDR range.
+     *
+     * @param ipRange - CIDR notation (e.g., '192.168.1.0/24')
+     */
+    isInRange(ipRange: string): ConditionalPolicyStatement;
+    /**
+     * String contains check.
+     */
+    contains(value: string): ConditionalPolicyStatement;
+    /**
+     * Check if attribute is in a set/list.
+     */
+    isIn(values: (string | number)[]): ConditionalPolicyStatement;
+}
+/**
+ * Accessor for building type-safe attribute comparisons.
+ *
+ * Provides methods for common comparison operators with proper type checking.
+ */
+export declare class AttributeAccessor {
+    private readonly path;
+    private readonly parent;
+    constructor(path: string, parent: ConditionBuilder);
+    /**
+     * Equality comparison (==)
+     */
+    equalTo(value: string | number | boolean): ConditionBuilder;
+    /**
+     * Inequality comparison (!=)
+     */
+    notEqualTo(value: string | number | boolean): ConditionBuilder;
+    /**
+     * Less than comparison (<)
+     */
+    lessThan(value: number): ConditionBuilder;
+    /**
+     * Less than or equals comparison (<=)
+     */
+    lessThanOrEqualTo(value: number): ConditionBuilder;
+    /**
+     * Greater than comparison (>)
+     */
+    greaterThan(value: number): ConditionBuilder;
+    /**
+     * Greater than or equals comparison (>=)
+     */
+    greaterThanOrEqualTo(value: number): ConditionBuilder;
+    /**
+     * IP range check - tests if IP address is in CIDR range.
+     *
+     * @param ipRange - CIDR notation (e.g., '192.168.1.0/24')
+     */
+    isInRange(ipRange: string): ConditionBuilder;
+    /**
+     * String contains check.
+     */
+    contains(value: string): ConditionBuilder;
+    /**
+     * Check if attribute is in a set/list.
+     */
+    isIn(values: (string | number)[]): ConditionBuilder;
+}
+/**
+ * Type-safe builder for creating Cedar authorization policy statements.
+ *
+ * This builder provides a fluent API for constructing Cedar policies without
+ * requiring knowledge of Cedar syntax. It supports:
+ * - Permit and forbid effects
+ * - Principal, action, and resource specifications
+ * - Conditional logic (when/unless clauses)
+ * - Raw Cedar for advanced cases
+ *
+ * The builder generates valid Cedar policy statements that can be used with
+ * the Policy construct.
+ *
+ * @example
+ * import { Policy, PolicyEngine, PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+ * declare const engine: PolicyEngine;
+ *
+ * // Example 1: Simple permit policy
+ * // Builder format:
+ * new Policy(this, 'AllowAll', {
+ *   policyEngine: engine,
+ *   statement: PolicyStatement.permit()
+ *     .forAllPrincipals()
+ *     .onAllActions()
+ *     .onAllResources(),
+ * });
+ *
+ * // Generated Cedar:
+ * // permit(
+ * //   principal,
+ * //   action,
+ * //   resource
+ * // );
+ *
+ * @example
+ * import { Policy, PolicyEngine, PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+ * declare const engine: PolicyEngine;
+ * declare const gatewayArn: string;
+ *
+ * // Example 2: Specific actions policy
+ * // Builder format:
+ * new Policy(this, 'AllowSpecificActions', {
+ *   policyEngine: engine,
+ *   statement: PolicyStatement.permit()
+ *     .forPrincipalInGroup('Group', 'Engineers')
+ *     .onActions([
+ *       'AgentCore::Action::exampleaction1',
+ *       'AgentCore::Action::exampleaction2',
+ *     ])
+ *     .onResource('AgentCore::Gateway', gatewayArn),
+ * });
+ *
+ * // Generated Cedar:
+ * // permit(
+ * //   principal in Group::"Engineers",
+ * //   action in [AgentCore::Action::"exampleaction1", AgentCore::Action::"exampleaction2"],
+ * //   resource == AgentCore::Gateway::"arn:aws:bedrock:us-east-1:123:gateway/gw-123"
+ * // );
+ *
+ * @example
+ * import { Policy, PolicyEngine, PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+ * declare const engine: PolicyEngine;
+ *
+ * // Example 3: Policy with conditions
+ * // Builder format:
+ * new Policy(this, 'ConditionalPolicy', {
+ *   policyEngine: engine,
+ *   statement: PolicyStatement.permit()
+ *     .forAllPrincipals()
+ *     .onAllActions()
+ *     .onAllResources()
+ *     .when()
+ *       .principalAttribute('department').equalTo('Engineering')
+ *       .and()
+ *       .contextAttribute('sourceIp').isInRange('192.168.1.0/24')
+ *       .done()
+ *     .unless()
+ *       .principalAttribute('suspended').equalTo(true)
+ *       .done(),
+ * });
+ *
+ * // Generated Cedar:
+ * // permit(
+ * //   principal,
+ * //   action,
+ * //   resource
+ * // )
+ * // when {
+ * //   principal.department == "Engineering" && context.sourceIp isInRange ip("192.168.1.0/24")
+ * // }
+ * // unless {
+ * //   principal.suspended == true
+ * // };
+ *
+ * @example
+ * import { Policy, PolicyEngine, PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+ * declare const engine: PolicyEngine;
+ *
+ * // Example 4: Raw Cedar policy
+ * // For advanced Cedar features not supported by the builder
+ * new Policy(this, 'CustomPolicy', {
+ *   policyEngine: engine,
+ *   definition: 'permit(principal, action, resource) when { context.custom > 10 };',
+ * });
+ *
+ * // Or using fromCedar():
+ * new Policy(this, 'ImportedPolicy', {
+ *   policyEngine: engine,
+ *   statement: PolicyStatement.fromCedar(
+ *     'forbid(principal, action, resource) when { resource.confidential == true };'
+ *   ),
+ * });
+ */
+export declare class PolicyStatement {
+    /**
+     * Create a permit statement - allows the action if conditions are met.
+     *
+     * Permit statements grant access when their conditions evaluate to true.
+     * Multiple permit statements can apply; any matching permit allows access.
+     */
+    static permit(): PolicyStatement;
+    /**
+     * Create a forbid statement - denies the action if conditions are met.
+     *
+     * Forbid statements deny access when their conditions evaluate to true.
+     * Forbid always takes precedence over permit (explicit deny).
+     */
+    static forbid(): PolicyStatement;
+    /**
+     * Create from raw Cedar policy statement string.
+     *
+     * Use this for advanced Cedar features not supported by the builder,
+     * or when migrating existing Cedar policies.
+     *
+     * Validation is deferred to the Policy construct's validationMode setting.
+     *
+     * @param cedarStatement - Complete Cedar policy statement including effect, principal, action, resource, and conditions
+     */
+    static fromCedar(cedarStatement: string): PolicyStatement;
+    private effect;
+    private principalConfig?;
+    private actionConfig?;
+    private resourceConfig?;
+    private whenConditions?;
+    private unlessConditions?;
+    private rawCedar?;
+    private constructor();
+    /**
+     * Apply to all principals (any user, service, or entity).
+     *
+     * Generates: `principal` in Cedar
+     */
+    forAllPrincipals(): this;
+    /**
+     * Apply to a specific principal entity.
+     *
+     * Generates: `principal == EntityType::"entityId"` in Cedar
+     *
+     * @param entityType - The entity type (e.g., 'AgentCore::OAuthUser')
+     * @param entityId - Optional specific entity ID
+     */
+    forPrincipal(entityType: string, entityId?: string): this;
+    /**
+     * Apply to principals that are members of a specific group.
+     *
+     * Generates: `principal in Group::"groupId"` in Cedar
+     *
+     * @param groupType - The group entity type (e.g., 'Group')
+     * @param groupId - The group identifier (e.g., 'Admins', 'Engineers')
+     */
+    forPrincipalInGroup(groupType: string, groupId: string): this;
+    /**
+     * Apply to all actions (any operation).
+     *
+     * Generates: `action` in Cedar
+     */
+    onAllActions(): this;
+    /**
+     * Apply to specific action(s).
+     *
+     * Generates: `action == Action::"name"` or `action in [Action::"name1", Action::"name2"]` in Cedar
+     *
+     * @param actions - Array of action names (e.g., ['AgentCore::Action::InsuranceAPI__get_policy'])
+     */
+    onActions(actions: string[]): this;
+    /**
+     * Apply to a single specific action.
+     *
+     * Generates: `action == Action::"name"` in Cedar
+     *
+     * @param action - Action name (e.g., 'AgentCore::Action::InsuranceAPI__get_policy')
+     */
+    onAction(action: string): this;
+    /**
+     * Apply to all resources of a specific type.
+     *
+     * **AWS Requirement**: AWS Bedrock AgentCore Policy service does not allow wildcard
+     * resources (`resource`). This method provides type-constrained resources which are
+     * required for policy validation to succeed.
+     *
+     * Generates: `resource is EntityType` in Cedar
+     *
+     * @param entityType - The entity type (default: 'AgentCore::Gateway')
+     *
+     * @example
+     * import { PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+     *
+     * // Constrain to Gateway resources (default)
+     * PolicyStatement.permit()
+     *   .forAllPrincipals()
+     *   .onAllActions()
+     *   .onAllResources()  // → "resource is AgentCore::Gateway"
+     *
+     * // Constrain to Runtime resources
+     * PolicyStatement.permit()
+     *   .forAllPrincipals()
+     *   .onAllActions()
+     *   .onAllResources('AgentCore::Runtime')  // → "resource is AgentCore::Runtime"
+     */
+    onAllResources(entityType?: string): this;
+    /**
+     * Apply to all resources of a specific type (explicit method).
+     *
+     * **AWS Requirement**: Resource type constraints are required by AWS Bedrock
+     * AgentCore when using wildcard principals or actions.
+     *
+     * Generates: `resource is EntityType` in Cedar
+     *
+     * @param entityType - The entity type (e.g., 'AgentCore::Gateway', 'AgentCore::Runtime')
+     *
+     * @example
+     * import { PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+     *
+     * PolicyStatement.permit()
+     *   .forAllPrincipals()
+     *   .onAllActions()
+     *   .onResourceType('AgentCore::Gateway')  // → "resource is AgentCore::Gateway"
+     */
+    onResourceType(entityType: string): this;
+    /**
+     * Apply to a specific resource instance.
+     *
+     * **AWS Requirement**: When using specific actions (e.g., `action == Action::"Delete"`),
+     * you must constrain the resource to a specific instance, not just a type.
+     *
+     * Generates: `resource == EntityType::"arn"` in Cedar
+     *
+     * @param entityType - The entity type (e.g., 'AgentCore::Gateway')
+     * @param entityArn - The resource ARN or identifier
+     *
+     * @example
+     * import { PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';
+     * declare const gatewayArn: string;
+     *
+     * PolicyStatement.forbid()
+     *   .forAllPrincipals()
+     *   .onAction('AgentCore::Action::Delete')
+     *   .onResource('AgentCore::Gateway', gatewayArn)  // Must be specific resource
+     */
+    onResource(entityType: string, entityArn: string): this;
+    /**
+     * Add when conditions - policy applies only if these conditions are true.
+     *
+     * When conditions define positive requirements that must be met.
+     * Multiple conditions can be combined with AND/OR operators.
+     *
+     * Returns a ConditionBuilder that you can chain condition methods on.
+     * Call done() when finished to return to the PolicyStatement.
+     */
+    when(): ConditionalPolicyStatement;
+    /**
+     * Add unless conditions - policy applies only if these conditions are false.
+     *
+     * Unless conditions define negative requirements (exclusions).
+     * The policy applies when these conditions are NOT met.
+     *
+     * Returns a ConditionBuilder that you can chain condition methods on.
+     * Call done() when finished to return to the PolicyStatement.
+     */
+    unless(): ConditionalPolicyStatement;
+    /**
+     * Generate the Cedar policy statement string.
+     *
+     * Converts the builder state into valid Cedar policy syntax.
+     * This is called internally by the Policy construct.
+     *
+     * @returns Valid Cedar policy statement
+     */
+    toCedar(): string;
+    private principalToCedar;
+    private actionToCedar;
+    private resourceToCedar;
+    private validateNotRawCedar;
+}
+export {};