# NATS permissions

> The nats-server subjects each controller requests, and the presets that grant them.


<!-- Generated by `just perm-docs` from hack/permdocs and internal/jwtplane. -->

Each controller takes every reply under its own preset's inbox: `_INBOX.cluster-controller.>`, `_INBOX.auth-controller.>`, `_INBOX.jetstream-controller.>`.
Each controller preset allows its own inbox and no other.
In a subject, `*` is one token that the controller fills in, such as a server ID, an account public key, or a stream or consumer name.

## Cluster controller

Connects as the system account user a `NatsCluster` names in `auth.systemCredentials`. Preset: [`cluster-controller`](#cluster-controller-1).

| Subject | Use | Code |
|---|---|---|
| `$SYS.REQ.SERVER.PING.STATSZ` | Lists the servers of the NATS cluster. | `internal/sysobs` |
| `$SYS.REQ.SERVER.PING.JSZ` | Reads every account's streams, consumers and the meta group, for `Settled`. | `internal/sysobs` |
| `$SYS.REQ.SERVER.PING.GATEWAYZ` | Reads each server's gateway connections, for `GatewaysConnected`. | `internal/sysobs` |
| `$SYS.REQ.SERVER.PING.LEAFZ` | Reads each server's leaf connections, for `LeafnodesConnected`. | `internal/sysobs` |
| `$SYS.REQ.SERVER.*.VARZ` | Reads the configuration a server has loaded, by server ID. | `internal/sysobs` |
| `$SYS.REQ.SERVER.*.RELOAD` | Reloads a server's configuration, by server ID. | `internal/sysobs` |
| `$JS.API.SERVER.EVACUATE` | Moves a server's JetStream assets off it before it is removed. | `internal/sysobs` |
| `$JS.API.META.LEADER.STEPDOWN` | Moves the meta leader off a server being removed. | `internal/sysobs` |
| `$JS.API.SERVER.REMOVE` | Removes a server from the JetStream meta group. | `internal/sysobs` |

## Auth controller

Connects through the `NatsConnection` its `--system-connection` flag names, as a user of a `NatsOperator`'s system account. Preset: [`auth-controller`](#auth-controller-1).

| Subject | Use | Code |
|---|---|---|
| `$SYS.REQ.SERVER.PING.STATSZ` | Lists the servers that should answer the requests below. | `internal/authctl` |
| `$SYS.REQ.SERVER.PING.VARZ` | Reads the NATS operator JWT each server runs under, for the keys it trusts. | `internal/authctl` |
| `$SYS.REQ.CLAIMS.UPDATE` | Pushes an account JWT to every resolver. | `internal/authctl` |
| `$SYS.REQ.CLAIMS.DELETE` | Deletes accounts from every `Full` resolver. | `internal/authctl` |
| `$SYS.REQ.ACCOUNT.*.CLAIMS.LOOKUP` | Reads the JWT the resolvers hold for an account, by account public key. | `internal/authctl` |
| `$SYS.REQ.SERVER.PING.CONNZ` | Finds a revoked user's connections. | `internal/authctl` |
| `$SYS.REQ.SERVER.*.KICK` | Disconnects one of them, by server ID. | `internal/authctl` |

## JetStream controller, as a system account user

Connects through the `NatsConnection` a `NatsSystemBalancer` or `NatsClusterEvacuation` names in `connectionRef`, as a system account user. Preset: [`jetstream-controller`](#jetstream-controller).

| Subject | Use | Code |
|---|---|---|
| `$SYS.REQ.SERVER.PING.STATSZ` | Lists the servers of the NATS cluster and their tags. | `internal/sysobs` |
| `$SYS.REQ.SERVER.PING.JSZ` | Reads every account's streams and consumers, with their leaders and replicas, and asks the meta leader which servers it counts offline, for a `NatsClusterEvacuation`. | `internal/sysobs`, `internal/balancectl` |
| `$SYS.REQ.SERVER.*.JSZ` | Asks the server a balancer's connection reaches, by server ID, whether it is in the same NATS system as a `NatsClusterEvacuation`'s connection. | `internal/balancectl` |
| `acc.*.$JS.API.STREAM.LEADER.STEPDOWN.*` | Moves a stream leader through the account's `jetstream-stepdown` export, and probes whether the system account imports it. | `internal/balance`, `internal/balancectl` |
| `acc.*.$JS.API.CONSUMER.LEADER.STEPDOWN.*.*` | Moves a consumer leader the same way. | `internal/balance`, `internal/balancectl` |
| `$JS.API.ACCOUNT.STREAM.MOVE.*.*` | Moves a stream's copies off a server, or onto servers carrying an evacuation's tags. | `internal/balance` |
| `$JS.API.ACCOUNT.STREAM.CANCEL_MOVE.*.*` | Rolls back the moves in progress when an unfinished `NatsClusterEvacuation` is deleted. | `internal/balance` |

## JetStream controller, as an account user

Connects through the `NatsConnection` a `NatsStream`, `NatsConsumer`, `NatsKeyValue`, `NatsObjectStore` or `NatsBalancer` names in `connectionRef`, as a user of the account that owns the resources. No preset grants these subjects: the user's `permissions` must allow them and a subscription to `_INBOX.jetstream-controller.>`, or the user sets none.

| Subject | Use | Code |
|---|---|---|
| `$JS.API.STREAM.INFO.*` | Reads a stream, or the stream behind a bucket. | `internal/lifecycle` |
| `$JS.API.STREAM.CREATE.*` | Creates a `NatsStream`'s stream. | `internal/lifecycle` |
| `$JS.API.STREAM.UPDATE.*` | Updates it. | `internal/lifecycle` |
| `$JS.API.STREAM.DELETE.*` | Deletes it. | `internal/lifecycle` |
| `$JS.API.CONSUMER.INFO.*.*` | Reads a consumer. | `internal/lifecycle` |
| `$JS.API.CONSUMER.CREATE.*.*` | Creates or updates a `NatsConsumer`'s consumer. | `internal/lifecycle` |
| `$JS.API.CONSUMER.DELETE.*.*` | Deletes it. | `internal/lifecycle` |
| `$JS.API.CONSUMER.LIST.*` | Lists a `NatsStream`'s consumers while its stream moves to another NATS cluster. | `internal/streamctl` |
| `$JS.API.INFO` | Reads the account's JetStream limits before a key-value bucket is created or updated. | nats.go `jetstream` |
| `$JS.API.STREAM.CREATE.*` | Creates the stream behind a `NatsKeyValue` or `NatsObjectStore`. | nats.go `jetstream` |
| `$JS.API.STREAM.UPDATE.*` | Updates it. | nats.go `jetstream` |
| `$JS.API.STREAM.DELETE.*` | Deletes it. | nats.go `jetstream` |
| `$SYS.REQ.USER.INFO` | Reads the account a `NatsBalancer`'s connection belongs to. | `internal/balancectl` |
| `$JS.API.STREAM.LIST` | Lists the account's streams, for a `NatsBalancer`. | nats.go `jetstream` |
| `$JS.API.STREAM.INFO.*` | Reads a stream, for a `NatsBalancer`. | nats.go `jetstream` |
| `$JS.API.CONSUMER.LIST.*` | Lists a stream's consumers, for a `NatsBalancer`. | nats.go `jetstream` |
| `$JS.API.STREAM.LEADER.STEPDOWN.*` | Moves a stream leader, for a `NatsBalancer`. | `internal/balance` |
| `$JS.API.CONSUMER.LEADER.STEPDOWN.*.*` | Moves a consumer leader, for a `NatsBalancer`. | `internal/balance` |
| `$JS.API.ACCOUNT.STREAM.MOVE.*.*` | Moves a stream's copies off a server, for a `NatsBalancer`. | `internal/balance` |

## User presets

A `NatsUser` with `spec.preset` gets exactly these claims, and sets neither `spec.permissions` nor `spec.connectionTypes`.

### auth-controller

For a system account user.

Publish: `$SYS.REQ.CLAIMS.UPDATE`, `$SYS.REQ.CLAIMS.DELETE`, `$SYS.REQ.ACCOUNT.*.CLAIMS.LOOKUP`, `$SYS.REQ.SERVER.PING.STATSZ`, `$SYS.REQ.SERVER.PING.VARZ`, `$SYS.REQ.SERVER.PING.CONNZ`, `$SYS.REQ.SERVER.*.KICK`.

Subscribe: `_INBOX.auth-controller.>`.

### cluster-controller

For a system account user.

Publish: `$SYS.REQ.SERVER.PING.STATSZ`, `$SYS.REQ.SERVER.PING.JSZ`, `$SYS.REQ.SERVER.PING.GATEWAYZ`, `$SYS.REQ.SERVER.PING.LEAFZ`, `$SYS.REQ.SERVER.*.VARZ`, `$SYS.REQ.SERVER.*.RELOAD`, `$JS.API.SERVER.EVACUATE`, `$JS.API.SERVER.REMOVE`, `$JS.API.META.LEADER.STEPDOWN`.

Subscribe: `_INBOX.cluster-controller.>`.

### jetstream-controller

For a system account user.

Publish: `$SYS.REQ.SERVER.PING.STATSZ`, `$SYS.REQ.SERVER.PING.JSZ`, `$SYS.REQ.SERVER.*.JSZ`, `$JS.API.ACCOUNT.STREAM.MOVE.*.*`, `$JS.API.ACCOUNT.STREAM.CANCEL_MOVE.*.*`, `acc.*.$JS.API.STREAM.LEADER.STEPDOWN.*`, `acc.*.$JS.API.CONSUMER.LEADER.STEPDOWN.*.*`.

Subscribe: `_INBOX.jetstream-controller.>`.

### leafnode

For a user of any account.

Publish: unrestricted.

Subscribe: unrestricted.

Connection types: `LEAFNODE`.

### readonly

For a user of an ordinary account.

Publish: `$JS.API.INFO`, `$JS.API.STREAM.NAMES`, `$JS.API.STREAM.LIST`, `$JS.API.STREAM.INFO.*`, `$JS.API.CONSUMER.NAMES.*`, `$JS.API.CONSUMER.LIST.*`, `$JS.API.CONSUMER.INFO.*.*`.

Subscribe: `_INBOX.readonly.>`.

## Export preset

### jetstream-stepdown

A `NatsAccount` export with `preset: jetstream-stepdown` expands to these service exports.
For each, the auth controller adds the matching import to the system account of the `NatsOperator` that signs the account, prefixed with `acc.<account public key>.`.

| Export | Subject | System account imports it as |
|---|---|---|
| `jetstream-stepdown-stream` | `$JS.API.STREAM.LEADER.STEPDOWN.*` | `acc.*.$JS.API.STREAM.LEADER.STEPDOWN.*` |
| `jetstream-stepdown-consumer` | `$JS.API.CONSUMER.LEADER.STEPDOWN.*.*` | `acc.*.$JS.API.CONSUMER.LEADER.STEPDOWN.*.*` |

