# Policy documents

The JSON a policy is written in, statement by statement, with resource names, wildcards and conditions.

A policy is a JSON document with a `Version` and a list of statements. The console and every
managed policy write `"Version": "2024-01-01"`; the field must be a non-empty string.

```json
{
  "Version": "2024-01-01",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": ["ec2:Describe*", "ec2:List*"],
      "Resource": ["rn:ews:de1:org-EXAMPLE1234:ec2:*"]
    }
  ]
}
```

## Statements

| Field       | Value                                                                        |
| ----------- | ---------------------------------------------------------------------------- |
| `Effect`    | `Allow` or `Deny`.                                                           |
| `Action`    | One action or a list: `ec2:StartInstances`, `ec2:Describe*`, `ec2:*` or `*`. |
| `Resource`  | One resource name or a list, or `*`.                                         |
| `Condition` | Optional. Limits when the statement applies; see [Conditions](#conditions).  |
| `Sid`       | Optional. A name for the statement; the policy simulator shows it.           |

`*` stands for any run of characters, in actions and in resource names. Matching ignores case.

When you save a policy, every action pattern must match at least one action that exists, and every
resource must be `*` or start with `rn:`. A document that breaks a rule is refused with the
statement and the reason, for example
`Invalid policy document: Statement[0] references unknown action "ec2:Strt*"`.

## Resource names

```
rn:ews:<region>:<organization id>:<service>:<type>/<id>
```

| Example                                          | Covers                             |
| ------------------------------------------------ | ---------------------------------- |
| `rn:ews:de1:org-EXAMPLE1234:ec2:instance/i-0123` | One compute instance               |
| `rn:ews:de1:org-EXAMPLE1234:ec2:instance/*`      | Every instance in the organization |
| `rn:ews:de1:org-EXAMPLE1234:ec2:*`               | Every compute resource             |
| `rn:ews::org-EXAMPLE1234:iam:user/<user id>`     | One IAM user; IAM has no region    |
| `*`                                              | Everything                         |

Services that are not regional, such as IAM, S3, Secrets, Git and the container
registry, leave the region segment empty. `de1` is the region.

## Conditions

A `Condition` block maps an operator to keys and values:

```json
{
  "Effect": "Allow",
  "Action": ["ec2:*"],
  "Resource": ["*"],
  "Condition": {
    "IpAddress": { "dcloud:SourceIp": ["192.0.2.0/24", "2001:db8::/32"] },
    "Bool": { "dcloud:MultiFactorAuthPresent": "true" }
  }
}
```

| Key                               | Operators                                                                                                                         | What the request supplies                                                                                                                                                                                                                                                                                                                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `dcloud:SourceIp`               | `IpAddress`, `NotIpAddress`: an IPv4 or IPv6 address or CIDR range                                                                | The client address.                                                                                                                                                                                                                                                                                                                               |
| `dcloud:CurrentTime`            | `DateEquals`, `DateNotEquals`, `DateLessThan`, `DateLessThanEquals`, `DateGreaterThan`, `DateGreaterThanEquals`                   | The time of the request. Values are ISO 8601 (`2026-12-31T00:00:00Z`) or epoch seconds.                                                                                                                                                                                                                                                           |
| `dcloud:MultiFactorAuthPresent` | `Bool`                                                                                                                            | `true` for a console session signed in with a password and an authenticator code, a passkey or a recovery code, and for a CLI session opened with a passkey or with Touch ID on a Mac enrolled with a passkey; `false` for other sessions (a Mac enrolled without a passkey included) and for access keys. Not supplied for an app you connected. |
| `dcloud:RequestedRegion`        | `StringEquals`, `StringNotEquals`, `StringLike`, `StringNotLike`                                                                  | The region of the request (`de1`).                                                                                                                                                                                                                                                                                                                |
| `dcloud:AvailabilityZone`       | `StringEquals`, `StringNotEquals`, `StringLike`, `StringNotLike`                                                                  | The zone a resource is placed in (`de1a`, `de1b`), on `ec2:RunInstances`, `ec2:CreateVolume` and `ec2:CreateSubnet`, and on `ec2:RunInstances` once per zone when an auto scaling group or a CI runner pool is created, or a group's zones or launch template version change. Other requests do not carry it.                                     |
| `dcloud:AuthMethod`             | `StringEquals`, `StringNotEquals`, `StringLike`, `StringNotLike`                                                                  | How the caller signed in: `console` (a console session), `cli-session` (`dcloud login`), `access-key`, `web-identity` (a role session from an OIDC token, or a schedule that runs as a role) or `oauth` (an app you connected).                                                                                                                  |
| `dcloud:PrincipalType`          | `StringEquals`, `StringNotEquals`, `StringLike`, `StringNotLike`                                                                  | `person` (a member, or an IAM user with console access), `service-account` (a service account, or an IAM user that was never given console access) or `assumed-role` (a role session).                                                                                                                                                            |
| `dcloud:UserVerified`           | `Bool`                                                                                                                            | `true` for a CLI session whose person Touch ID or a passkey verified, at sign-in or at a confirmation since; `false` for every other request, console sessions included.                                                                                                                                                                          |
| `dcloud:UserVerifiedAge`        | `NumericEquals`, `NumericNotEquals`, `NumericLessThan`, `NumericLessThanEquals`, `NumericGreaterThan`, `NumericGreaterThanEquals` | Seconds since that verification. Not supplied when there was none.                                                                                                                                                                                                                                                                                |
| `dcloud:RequestProject`         | `StringEquals`, `StringNotEquals`, `StringLike`, `StringNotLike`                                                                  | The project slug the request names, which is where a create puts the new resource: the `X-EWS-Project` header (`--project` in the CLI), else the project picked in the console; `default` when none is named.                                                                                                                                     |
| `dcloud:ResourceProject`        | `StringEquals`, `StringNotEquals`, `StringLike`, `StringNotLike`                                                                  | The project of the resource the request names (`default` when it is in none); for a part of something, such as a cluster's node group, its parent's project; for a list or a create, the project the request names. Not supplied for resources that do not live in projects, such as IAM users, roles and policies.                               |

Keys are also accepted with the prefix `ews:`. Keys are case-insensitive; operators are not.

Git (pushes and pulls over HTTPS and SSH) and the container registry supply none of these keys
except `dcloud:CurrentTime`: no address, no second factor and no region. The npm registry does
not supply `dcloud:AuthMethod`, `dcloud:PrincipalType`, `dcloud:UserVerified`,
`dcloud:UserVerifiedAge`, `dcloud:RequestProject` or `dcloud:ResourceProject`.

- Every operator in a block must hold, and every key under an operator.
- A key with several values holds when any value matches; for a `Not…` operator, when none does.
- **Conditions fail closed.** When a request does not supply a key, an `Allow` that depends on it
  does not apply, and a `Deny` that depends on it does. A `Deny` with `NotIpAddress` therefore
  also denies git pushes, which carry no address, and an `Allow` conditioned on
  `dcloud:RequestedRegion` grants nothing to git or the container registry.

An `Allow` on `ec2:*` conditioned on a zone also stops every read, because reads carry no zone.
Scope a zone condition to the actions that place something:

```json
{
  "Effect": "Allow",
  "Action": ["ec2:RunInstances", "ec2:CreateVolume", "ec2:CreateSubnet"],
  "Resource": ["*"],
  "Condition": { "StringEquals": { "dcloud:AvailabilityZone": "de1a" } }
}
```

To let CLI sessions delete a database or a secret only within five minutes of a Touch ID or passkey
confirmation, deny it to the others:

```json
{
  "Effect": "Deny",
  "Action": ["rds:DeleteDBInstance", "secrets:DeleteSecret"],
  "Resource": ["*"],
  "Condition": {
    "StringEquals": { "dcloud:AuthMethod": "cli-session" },
    "NumericGreaterThan": { "dcloud:UserVerifiedAge": 300 }
  }
}
```

A CLI session that was never verified has no age, so the `Deny` applies to it. A console session or
an access key is not a `cli-session`, so it does not. A `Deny` on `dcloud:UserVerifiedAge` alone
would also stop every console session and access key, which never carry a verification.

A policy with an operator or key outside these tables, or a value that cannot be read, is refused
when you save it.

## Related

- [How a request is decided](how-a-request-is-decided.md)
- [Create a policy](create-a-policy.md)
- [Test access with the policy simulator](test-access-with-the-simulator.md)
