> **Experimental**
>
> `@aws-cdk/aws-bedrock-agentcore-alpha` is an [**experimental**](/stability) (alpha) package: its API may change in any release, without a major version bump.
# PolicyStatement

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.

- Stability: [Experimental](/cdk/api/stability.html)
- Source: [`lib/policy/policy-statement.ts`](https://github.com/aws/aws-cdk/blob/v2.275.0-alpha.0/packages/@aws-cdk/aws-bedrock-agentcore-alpha/lib/policy/policy-statement.ts#L619)

## Example

```ts
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 };'
  ),
});
```

## Methods

- `forAllPrincipals(): PolicyStatement // chainable` — Apply to all principals (any user, service, or entity).

  Generates: `principal` in Cedar

- `forbid(): PolicyStatement // chainable` (static) — 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).

- `forPrincipal(entityType: string, entityId?: string): PolicyStatement // chainable` — Apply to a specific principal entity.

  Generates: `principal == EntityType::"entityId"` in Cedar

  **Parameters**

  - `entityType` — - The entity type (e.g., 'AgentCore::OAuthUser').
  - `entityId` — - Optional specific entity ID.

- `forPrincipalInGroup(groupType: string, groupId: string): PolicyStatement // chainable` — Apply to principals that are members of a specific group.

  Generates: `principal in Group::"groupId"` in Cedar

  **Parameters**

  - `groupType` — - The group entity type (e.g., 'Group').
  - `groupId` — - The group identifier (e.g., 'Admins', 'Engineers').

- `fromCedar(cedarStatement: string): PolicyStatement // chainable` (static) — 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.

  **Parameters**

  - `cedarStatement` — - Complete Cedar policy statement including effect, principal, action, resource, and conditions.

- `onAction(action: string): PolicyStatement // chainable` — Apply to a single specific action.

  Generates: `action == Action::"name"` in Cedar

  **Parameters**

  - `action` — - Action name (e.g., 'AgentCore::Action::InsuranceAPI__get_policy').

- `onActions(actions: string[]): PolicyStatement // chainable` — Apply to specific action(s).

  Generates: `action == Action::"name"` or `action in [Action::"name1", Action::"name2"]` in Cedar

  **Parameters**

  - `actions` — - Array of action names (e.g., ['AgentCore::Action::InsuranceAPI__get_policy']).

- `onAllActions(): PolicyStatement // chainable` — Apply to all actions (any operation).

  Generates: `action` in Cedar

- `onAllResources(entityType?: string): PolicyStatement // chainable` — 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

  **Parameters**

  - `entityType` — - The entity type (default: 'AgentCore::Gateway').

  ```ts
  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"
  ```

- `onResource(entityType: string, entityArn: string): PolicyStatement // chainable` — 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

  **Parameters**

  - `entityType` — - The entity type (e.g., 'AgentCore::Gateway').
  - `entityArn` — - The resource ARN or identifier.

  ```ts
  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
  ```

- `onResourceType(entityType: string): PolicyStatement // chainable` — 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

  **Parameters**

  - `entityType` — - The entity type (e.g., 'AgentCore::Gateway', 'AgentCore::Runtime').

  ```ts
  import { PolicyStatement } from '@aws-cdk/aws-bedrock-agentcore-alpha';

  PolicyStatement.permit()
    .forAllPrincipals()
    .onAllActions()
    .onResourceType('AgentCore::Gateway')  // → "resource is AgentCore::Gateway"
  ```

- `permit(): PolicyStatement // chainable` (static) — 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.

- `toCedar(): string` — 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

- `unless(): 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.

- `when(): ConditionalPolicyStatement` — 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.