# Rules

Complete field reference for custom rule files. For an introduction to rules and built-in rules, see [Rules](/protect/1.0/rules.md).

## Rule file structure

| Field         | Type   | Required | Description                                                          |
| ------------- | ------ | -------- | -------------------------------------------------------------------- |
| `name`        | string | yes      | unique within the bundle                                             |
| `description` | string | no       | help text for managing rules                                         |
| `facts`       | list   | yes      | connection-level filters; at least one with `connection_kind`        |
| `conditions`  | list   | yes      | per-message filters; at least `rule_type`                            |
| `default`     | action | yes      | action when no rule body matches                                     |
| `trace`       | bool   | no       | enable per-rule tracer output (debug only, do not use in production) |
| `rules`       | list   | yes      | one or more rule bodies                                              |

## Actions

Valid values for `default`, `success`, and `fail`:

| Action    | Terminal | Description                                                      |
| --------- | -------- | ---------------------------------------------------------------- |
| `allow`   | no       | permit the operation                                             |
| `deny`    | yes      | reject the operation and close the connection                    |
| `error`   | yes      | same as deny, recorded with error metrics                        |
| `suspend` | no       | park the connection — keep alive but drop the backend connection |
| `log`     | no       | log the raw protocol to the auditor, continue evaluation         |

Terminal actions (`deny`, `error`) stop all further rule evaluation and return immediately. Non-terminal actions (`allow`, `log`, `suspend`) accumulate and evaluation continues.

## Facts

Static properties of a connection, set once at connect time. The engine pre-filters the ruleset using facts — rules whose facts don't match are never evaluated for that connection.

| Key               | Values           | Description                     |
| ----------------- | ---------------- | ------------------------------- |
| `connection_kind` | `client`, `leaf` | required on every rule          |
| `remote_ip`       | IP address       | exact string match on source IP |

note

`remote_ip` uses string equality only. For CIDR-based IP filtering, use `matchCIDR(Meta.Address, "10.0.0.0/8")` in a rule expression.

Entries use OR logic within the same key and AND across different keys.

## Conditions

Conditions filter per protocol message and determine whether a rule applies.

### Rule type (required)

| Key         | Values               | Description                               |
| ----------- | -------------------- | ----------------------------------------- |
| `rule_type` | `connect`, `message` | which protocol messages this rule handles |

### Direction

| Key         | Values                                          | Description              |
| ----------- | ----------------------------------------------- | ------------------------ |
| `direction` | `to_backend`, `from_backend`, `both`, `inherit` | traffic direction filter |

`inherit` (or omitting direction) uses the port's `default_rule_direction`.

### Connect conditions

Available for `rule_type: connect` and `rule_type: message`:

| Key        | Type   | Matches against                            |
| ---------- | ------ | ------------------------------------------ |
| `username` | string | `Connect.Username`                         |
| `password` | string | `Connect.Password`                         |
| `token`    | string | `Connect.Token`                            |
| `nkey`     | string | `Connect.Nkey`                             |
| `jwt`      | string | `Connect.JWT`                              |
| `name`     | string | `Connect.Name` (connection name)           |
| `lang`     | string | `Connect.Lang`                             |
| `version`  | string | `Connect.Version`                          |
| `protocol` | int    | `Connect.Protocol` version number (0 or 1) |

### Account conditions

Available for `rule_type: message`:

| Key                 | Type   | Matches against               |
| ------------------- | ------ | ----------------------------- |
| `account`           | string | `AccountInfo.Account`         |
| `is_system_account` | bool   | `AccountInfo.IsSystemAccount` |

### Message conditions

Available for `rule_type: message`:

| Key                 | Type   | Matches against                          |
| ------------------- | ------ | ---------------------------------------- |
| `subject`           | string | exact match on `Message.Subject`         |
| `subject_match`     | string | NATS wildcard match on `Message.Subject` |
| `subject_not_match` | string | negative NATS wildcard match             |
| `reply_to`          | string | exact match on `Message.ReplyTo`         |
| `has_header`        | string | true if header key exists                |
| `not_header`        | string | true if header key does not exist        |

Conditions use OR within the same key, AND across different keys.

## Rule bodies

| Field        | Type   | Required | Description                                 |
| ------------ | ------ | -------- | ------------------------------------------- |
| `expression` | string | yes      | Expr expression that evaluates to a boolean |
| `success`    | action | no       | action when expression returns true         |
| `fail`       | action | no       | action when expression returns false        |
| `message`    | string | no       | shown in audit logs on deny/suspend         |

Both `success` and `fail` can be set on the same rule body.

## Evaluation environment

### `Meta`

| Field              | Type   | Expr access             | Description                                                                  |
| ------------------ | ------ | ----------------------- | ---------------------------------------------------------------------------- |
| `Direction`        | string | `Meta.Direction`        | `to_backend` or `from_backend`                                               |
| `DefaultDirection` | string | `Meta.DefaultDirection` | port's default direction                                                     |
| `Host`             | string | `Meta.Host`             | gateway hostname                                                             |
| `Address`          | string | `Meta.Address`          | client network address                                                       |
| `RemoteServer`     | string | `Meta.RemoteServer`     | remote server name                                                           |
| `RemoteHost`       | string | `Meta.RemoteHost`       | remote host IP                                                               |
| `Time`             | string | `Meta.Time`             | RFC3339 timestamp                                                            |
| `ConnectionKind`   | int    | `Meta.ConnectionKind`   | 1=client, 2=leaf (rarely needed — facts already filter on `connection_kind`) |
| `ProtoLen`         | int    | `Meta.ProtoLen`         | protocol message length                                                      |

### `Connect`

| Field          | Type   | Expr access            | Description         |
| -------------- | ------ | ---------------------- | ------------------- |
| `Username`     | string | `Connect.Username`     | basic auth username |
| `Password`     | string | `Connect.Password`     | basic auth password |
| `Token`        | string | `Connect.Token`        | auth token          |
| `Nkey`         | string | `Connect.Nkey`         | NKey public key     |
| `JWT`          | string | `Connect.JWT`          | JWT credential      |
| `Sig`          | string | `Connect.Sig`          | signature           |
| `Name`         | string | `Connect.Name`         | client/server name  |
| `Lang`         | string | `Connect.Lang`         | client language     |
| `Version`      | string | `Connect.Version`      | client version      |
| `Protocol`     | int    | `Connect.Protocol`     | protocol version    |
| `Account`      | string | `Connect.Account`      | account name        |
| `Echo`         | bool   | `Connect.Echo`         | echo mode           |
| `Verbose`      | bool   | `Connect.Verbose`      | verbose mode        |
| `Pedantic`     | bool   | `Connect.Pedantic`     | pedantic mode       |
| `TLSRequired`  | bool   | `Connect.TLSRequired`  | TLS required        |
| `Headers`      | bool   | `Connect.Headers`      | headers support     |
| `NoResponders` | bool   | `Connect.NoResponders` | no responders       |
| `AccountNew`   | bool   | `Connect.AccountNew`   | new account flag    |
| `ProxySig`     | string | `Connect.ProxySig`     | proxy signature     |

Leaf-only fields:

| Field           | Type              | Expr access             | Description             |
| --------------- | ----------------- | ----------------------- | ----------------------- |
| `ID`            | string            | `Connect.ID`            | server ID               |
| `ServerName`    | string            | `Connect.ServerName`    | server name             |
| `RemoteAccount` | string            | `Connect.RemoteAccount` | remote account          |
| `Cluster`       | string            | `Connect.Cluster`       | cluster name            |
| `Hub`           | bool              | `Connect.Hub`           | is hub                  |
| `Domain`        | string            | `Connect.Domain`        | domain                  |
| `JetStream`     | bool              | `Connect.JetStream`     | JetStream enabled       |
| `Compression`   | string            | `Connect.Compression`   | compression mode        |
| `DenyPub`       | \[]string         | `Connect.DenyPub`       | denied publish subjects |
| `Isolate`       | bool              | `Connect.Isolate`       | isolation flag          |
| `Import`        | SubjectPermission | `Connect.Import.Allow`  | import permissions      |
| `Export`        | SubjectPermission | `Connect.Export.Allow`  | export permissions      |

### `Message`

| Field     | Type                  | Expr access       | Description     |
| --------- | --------------------- | ----------------- | --------------- |
| `Subject` | string                | `Message.Subject` | message subject |
| `SID`     | string                | `Message.SID`     | subscription ID |
| `ReplyTo` | string                | `Message.ReplyTo` | reply subject   |
| `Payload` | \[]byte               | `Message.Payload` | message body    |
| `Headers` | map\[string]\[]string | `Message.Headers` | NATS headers    |
| `Queues`  | \[]string             | `Message.Queues`  | queue groups    |

### `AccountInfo`

| Field             | Type   | Expr access                   | Description         |
| ----------------- | ------ | ----------------------------- | ------------------- |
| `Account`         | string | `AccountInfo.Account`         | account name        |
| `IsSystemAccount` | bool   | `AccountInfo.IsSystemAccount` | system account flag |

### `Config`

Available for built-in rules only. Contains the rule's configuration as set in the `.conf` file. `nil` for custom rules.

## Custom functions

### Subject functions

| Function                         | Returns | Description                                                          |
| -------------------------------- | ------- | -------------------------------------------------------------------- |
| `subjectMatch(subject, pattern)` | bool    | NATS wildcard match (`*` matches one token, `>` matches one or more) |
| `subjectHasWildcards(subject)`   | bool    | true if subject contains `*` or `>`                                  |
| `isLiteralSubject(subject)`      | bool    | true if subject has no wildcards                                     |

### JetStream functions

| Function                            | Returns      | Description                                                                                                |
| ----------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------- |
| `normalizeJSSubject(subject)`       | string       | strip domain/prefix from JetStream subjects to `$JS.API...` form                                           |
| `fromJsRequest()`                   | typed struct | parse JetStream request from message payload; returns the appropriate jsm.go API type (cached per message) |
| `hasAllowedConsumerFilter(allowed)` | bool         | true when all consumer filter subjects are within at least one allowed pattern                             |
| `hasDeniedConsumerFilter(denied)`   | bool         | true when any consumer filter subject overlaps a denied pattern                                            |

### Header functions

| Function                     | Returns | Description                                                                                                                           |
| ---------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `hasHeader(config, headers)` | bool    | check headers against config map; keys are header names, values are regex patterns (empty = existence check); OR logic across entries |

### Payload functions

| Function                                   | Returns | Description                                          |
| ------------------------------------------ | ------- | ---------------------------------------------------- |
| `payloadMatches(config, subject, payload)` | bool    | match payload against regex based on subject pattern |
| `regexMatch(str, pattern)`                 | bool    | Go regex match (cached)                              |
| `bytesToString(data)`                      | string  | convert payload bytes to string                      |

### Time functions

| Function                           | Returns | Description                                                                                 |
| ---------------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `matchesTime(schedule, timestamp)` | bool    | cron schedule match; format: `minute hour day month weekday`; truncated to minute precision |

### Rate limit functions

| Function                                            | Returns | Description                                                                                               |
| --------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------------------- |
| `connectionMessageRateExceeded(interval, messages)` | bool    | true when the connection exceeds `messages` per `interval` in the rule's direction (token bucket)         |
| `connectionBytesRateExceeded(interval, bytes)`      | bool    | true when the connection exceeds `bytes` of payload per `interval` in the rule's direction (token bucket) |

See [Rate limit](/protect/1.0/reference/builtins/ratelimit.md) for details.

### Network functions

| Function                   | Returns | Description                   |
| -------------------------- | ------- | ----------------------------- |
| `matchCIDR(address, cidr)` | bool    | IPv4/IPv6 CIDR match (cached) |

### Auth functions

| Function                                 | Returns | Description                                                      |
| ---------------------------------------- | ------- | ---------------------------------------------------------------- |
| `IsTrustedExternalSigner(token, config)` | bool    | JWT signature verification; config format: `algorithm:base64key` |

### Utility functions

| Function                      | Returns | Description                                 |
| ----------------------------- | ------- | ------------------------------------------- |
| `infoLog(message, ...params)` | bool    | log at info level; always returns true      |
| `debug(...params)`            | bool    | debug output to stderr; always returns true |

## Evaluation flow

### Fact filtering

When a client or leafnode connects, the engine filters the port's ruleset against the connection's facts. Only matching rules are kept for that connection's lifetime.

When a bundle is activated, deactivated, or upgraded on a port, all active connections on that port are re-evaluated. If the changed ruleset contains connect rules matching a connection's facts, the connection is disconnected to force a full re-evaluation on reconnect.

### Per-message evaluation

For each protocol message, the engine iterates through the filtered ruleset:

1. Condition matching — conditions are grouped by key. Within a key, values use OR logic. Across keys, AND logic. If conditions don't match, the rule is skipped.
2. Rule body evaluation — rule bodies are evaluated in order. Each expression returns a boolean; the corresponding `success` or `fail` action is applied.
3. Short-circuit on deny/error — if any body returns `deny` or `error`, evaluation stops immediately.
4. Rule default — if no rule body produced a result, the rule's `default` action is used.
5. No rules matched — if no rules produced any results, the port's unmatched action applies (defaults to `deny`).
