# Rules

A rule allows or blocks a tool call by its tool, its agent and the values of its arguments. Each rule is in words, such as "Block approve_payout when amount is above 1,000", and is **Calibrating** (notes what it would have blocked) or **On** (blocks).

- **The project's rules.** Written in the console, on a tool's page or on the project's Rules page, and by `signafaide protect` into a new sandbox. Each change makes a new version that the service signs and chains to the one before, so the versions are the signed history of your rules, naming who made each change. Clients and the witness fetch it; every check result and every ruling names the version it used, which shows that a developer did not weaken the rules on their machine.
- **Local rules**, in the checks file's `rules`. They need no account, and are committed with the code ([Checks file](/docs/checks-file)).

How rules fit with the other checks: [Tool-call checks](/docs/checks).

## A rule

The rules `signafaide protect` saved in the [quickstart](/docs/quickstart), after an admin allowed one payee from now on:

```json
{
  "default": "allow",
  "rules": [
    {"id": "approve_payout-amount", "about": "approve_payout: amount above 1000.", "action": "block",
     "tools": ["approve_payout"], "agents": null, "when": [{"field": "/amount", "op": "gt", "value": 1000}], "state": "on",
     "exceptions": [{"field": "/payee", "value": "Harbour Lane Supplies Ltd", "reason": "Quarterly rent, approved by finance", "since": 2}]},
    {"id": "approve_payout-currency", "about": "approve_payout: currency other than GBP.", "action": "block",
     "tools": ["approve_payout"], "agents": null, "when": [{"field": "/currency", "op": "ne", "value": "GBP"}], "state": "calibrating"}
  ]
}
```

| field | meaning |
|---|---|
| `id` | lowercase letters, digits, `.`, `_` and `-`, up to 64 characters, unique |
| `about` | up to 200 characters, for people |
| `action` | `allow` or `block` |
| `tools` | null (every tool) or the declared tool names it covers, matched exactly, no wildcards |
| `agents` | null (every agent) or the agent names it covers |
| `when` | up to 16 conditions, all of which must hold; empty means always |
| `state` | in the project's rules: `calibrating` or `on`, see [Calibrating and On](#calibrating-and-on) |
| `exceptions` | on a block rule in the project's rules: values allowed from now on, see [Exceptions](#exceptions) |
| `limit` | on a block rule in the project's rules only: `{"calls", "seconds", "per"}`, see [Rate limits](#rate-limits) |

A rule set holds up to 1,000 rules. A field, operator or value this page does not list makes the whole document invalid: the console refuses to publish it, a client refuses it, and nothing in it is used. Nothing loads "OK" while ignoring a key.

## Conditions

A condition is `{"field", "op", "value"}`. `field` is a JSON Pointer into the call's arguments, such as `/amount` or `/to/0`; the console and the commands show it as the field's name (`amount`, `to.0`).

| `op` | holds when the field |
|---|---|
| `eq`, `ne` | is, or is present and is not, the same JSON value (`1` and `1.0` are equal, a string never equals a number) |
| `lt`, `le`, `gt`, `ge` | is a number below, at most, above, or at least `value` |
| `in`, `not_in` | equals one of a list of values, or none of them |
| `prefix`, `suffix`, `contains` | is a string that starts with, ends with or contains `value`, case-sensitive |
| `present`, `absent` | is there, or is not (no `value`) |
| `type` | has the JSON type `string`, `number`, `integer`, `boolean`, `null`, `object` or `array` |

- **An absent field** never matches, and is never an error.
- **A wrong type is an error, and an error blocks.** `amount > 1000` cannot be stepped around by sending `"5000"`. Conditions are checked in order, so a `type` condition placed first makes a rule not match instead.
- **No regular expressions.** `prefix`, `suffix` and `contains` give the same result in every SDK and in the witness, and cannot be made slow.

## How a call is decided

The On rules that cover the call (by `tools` and `agents`) are checked in order. Calibrating rules are checked too, but only to note what they would have blocked. The result is the first of these that applies:

1. a rule in error: block;
2. a matching block rule: block;
3. a matching allow rule: allow;
4. otherwise the rule set's `default`.

A rule with an exception does not match a call whose field holds the excepted value. **Any block wins.** An allow rule never overrides a block rule. An allow list is `"default": "block"` with allow rules for what may run, and a block rule still stops a call that an allow rule lets through.

## Calibrating and On

- **Calibrating** never blocks and never asks for a field: the call runs, and its record, the tool's page and the auditor view say "Would have blocked" under that rule. Every rule added in the console starts Calibrating.
- **On** blocks a call the rule matches. Only a person turns a rule On: the Turn on button on the tool's page publishes the next version, naming them, and offers Undo. `signafaide protect` makes a rule On only when you answer On at the terminal.

The tool's page shows how many calls each Calibrating rule would have blocked, so you can turn it On once those are the calls you mean to stop.

## Exceptions

Allow from now on, on a blocked call's page, adds an exception to the rule that blocked it: one field and one value, with the admin's reason, from the next version on (`since`). The rule then does not match a call whose field holds that value. An exception never lets the blocked call run, and is never edited, only removed by a later version. When the tool does not send the exception's field yet, the console says so and the exception applies once the developer runs `signafaide pull` and approves the field.

Only an owner or admin allows a value, and only a value the tool sent in the last 30 days, picked from a list: nobody types it. Before it is published, the console shows the exact value and says that it becomes part of the published rules: every API key of the project and every auditor can read it, and it is kept with the rule history. The admin confirms, or nothing is published; the service refuses an allow without that confirmation.

Allow from now on is the only way an exception is added. A whole set of rules published at once, from the console's Rules page or from the terminal, keeps the exceptions exactly as they are: it cannot add one, change its reason, or move its `since` to an earlier version. Only an owner or admin removes an exception, and Undo never brings back one that was removed. The rule history names who added each exception, and every exception added or removed, with its reason.

Values match exactly: pass a stable id to the tool, not a name that can be written two ways.

## The project's rules

Besides the rules, an admin sets on the console's Rules page:

- **Default.** Allow or block, when no rule matches.
- **If signafAIde can't be reached**, per protected tool: stop (the default) or let it run. It never protects a tool.
- **Address allowlists** for the internal address check.
- **Approved tools**, when tool approvals are kept with the rules: approve a changed tool again in one step ([Tool fingerprints](/docs/fingerprints)).
- **Test a call** against the draft or the published version, before you publish.

There is one set of rules per project and environment, so the sandbox and live are separate. Clients fetch the newest version at start, every 60 seconds and at once when a ruling names a newer one, check its signature and its place in the chain, and use it from the next call without a restart. A client that cannot fetch keeps the version it holds, however old: going offline never drops rules. The witness always rules with its newest version, so a client cannot choose an older, weaker one.

**Who can change the rules.** A person signed in to the console: an admin or owner, and on the Free and Solo plans and in a sandbox also a developer. From the terminal, `signafaide login` signs a person in: you type the code your terminal shows into the console, which shows where the sign-in was asked from and says when that is not where you are. An API key can save rules only into its own sandbox while the sandbox is unclaimed; an agent's key never changes the rules that bind it.

**Loosening live rules from the terminal needs the console.** A change to the live rules saved from the terminal that only tightens them (a new block rule, a lower limit) is published at once. A change that loosens them is not: removing a rule, putting a rule back to Calibrating, raising a limit, adding an allow rule or an exception, changing the default to allow, letting a tool run when signafAIde can't be reached, or approving a changed tool. The terminal prints a console link instead (`confirm_in_console` in the [API reference](/docs/api), `POST /v1/rules`). There a person with publish rights reads what the change loosens, in words, and confirms it, which publishes it under their name, or refuses it. A change waits 24 hours, and once a newer version is published it can no longer be confirmed.

**The project's rules bind protected tools only.** On a tool that is only recorded, the client checks them as Calibrating whatever their state, and the call runs. To let a rule block a tool, protect the tool, in code or from its page in the console ([Protect from the console](/docs/checks#protect-from-the-console)).

Plans: every project holds up to 1,000 rules. Free and Solo hold one live set of rules per organisation, and sandboxes are not limited. Team has a set per project. Signed rule history is kept 30 days on Free, a year on Solo and Team (7 years with the retention add-on), and by contract on Enterprise; a version that a kept record names is always kept. [Pricing](/pricing).

## Templates {#templates}

Starter and industry rule sets are templates: the Rules page copies one into your draft, where you rename the example tools and fields, change the limits, and publish it as a normal signed version, its rules Calibrating. Nothing is published by copying. A rule the draft already has under the same id is kept as it is. The console shows which templates a version came from; that is kept beside the version, not in the signed document.

| Template | Plan | Rules | What it does |
|---|---|---|---|
| Block deletes | every plan | 1 | Blocks `delete_record`, `delete_file` and `delete_user`. |
| Messages to listed recipients | every plan | 5 | `send_email` and `send_message` go only to listed recipients, one recipient a message, no `cc` or `bcc`. |
| Payout limits | every plan | 4 | Blocks a payout over 1,000, without an amount, with a negative or non-numeric amount, or past 20 an hour per agent. |
| Allow only listed tools | every plan | 1 | Sets `default` to block and allows the tools you list. |
| Call rate limit | every plan | 1 | Blocks past 600 calls a minute for each agent and tool. |
| Finance | Team and Enterprise | 8 | Payment and refund limits, listed currencies (`GBP`, `EUR`, `USD`), a daily payment rate, and new beneficiaries or changed bank details left to a person. |
| Healthcare | Team and Enterprise | 7 | Patient record writes and exports left to a person, searches of at most 20, a read rate, and no `patient_id` or `patient_number` in outbound messages. |
| UK personal data | Team and Enterprise | 6 | Exports of at most 100 people and 10 a day, and no `national_insurance_number`, `postcode` or `date_of_birth` in outbound messages or webhooks. |

On Free and Solo the Rules page lists the industry templates by name and description; their rules come with the Team plan. Rules you write by hand are not limited by plan.

Every template uses only the conditions above. The rule language has no patterns, so a template cannot recognise the shape of a value such as a National Insurance number, a postcode or an account number: it matches the field by name instead, and its note says so. An amount that is not a number is caught by the error rule: `{"field": "/amount", "op": "lt", "value": 0}` blocks a negative amount, and a wrong type is an error, which blocks.

## Suggestions {#suggestions}

The Rules page also proposes rules from the calls your agents made in the last 7, 30 or 90 days. A suggestion is copied into the draft like a template, and nothing changes until a person publishes. Suggestions come from what the calls were, never from their outcomes.

- **Allow only the tools used.** "12 tools were used: allow only these?" Sets `default` to block with allow rules for those tools.
- **Tools never protected.** Rules do not block them; protect them for the witness to rule on them. Nothing to copy.
- **Fields seen with a few values** (project admins only). A sent field seen in at least 5 protected calls with at most 5 values, each seen twice on average, gives a block rule for any other value:

```json
{"id": "suggested-approve_payout-currency-values", "about": "/currency only as seen in the window.", "action": "block",
 "tools": ["approve_payout"], "agents": null, "when": [{"field": "/currency", "op": "not_in", "value": ["GBP"]}]}
```

- **A highest value** (project admins only). A numeric field with more values gives a block rule above the highest seen. Round it to the limit you mean before publishing.

Value suggestions read sent values, so only the project's admins get them, and only for fields a protected tool sends, while they are kept (30 days). Other roles see the tool suggestions only.

Copying a value suggestion needs an admin or owner to confirm. The Rules page first shows the exact values the rule will hold and says that they become part of the published rules: every API key of the project and every auditor can read them, and they are kept with the rule history. Without that confirmation the service refuses the copy.

## Rate limits

A block rule in the project's rules may carry `limit`: `{"calls": 20, "seconds": 3600, "per": "agent"}` blocks a call it covers once the witness has allowed 20 earlier calls of the same agent in the hour before. `per` counts by `agent`, by `tool`, or by both (`agent_tool`). Only the witness counts, over its own earlier rulings, so a limit applies to protected calls only, and clients skip it. Local rules cannot have a limit.

For a hard cap, use `per: tool`. It counts every agent's calls of the tool in the project and environment together. `per: agent` and `per: agent_tool` count each agent name on its own, and an agent name is whatever the client sends, so the same code running under several names gets each name's allowance. A rule with `tools: null` and `per: tool` caps each tool on its own.

## Local rules

The checks file's `rules` takes the same document as above, `default` and `rules` only, with no `limit`, `state` or `exceptions`. Local rules follow the checks file's `mode` (Calibrating or On) for each tool: they block on a protected tool and note on any other, unless the file says otherwise. A record names them as the set `local`, with a fingerprint of the rules object, so an auditor can see which local rules were in force.

## Check a call

```bash
npx signafaide check approve_payout amount=1200 currency=GBP
```

```text
would block  Block approve_payout when amount is above 1,000 (On, version 1)
sends        amount, currency
             Dry run: nothing recorded, the tool did not run. Exit code 1.
```

`check` evaluates the call as a client does, against the held rules and the local rules, and prints the result, the rule in words with its state and version, and the fields a protected call would send. It records nothing, runs nothing, and exits 1 when the call would be blocked, so a test or CI step can use it. A value is JSON when it reads as JSON, else text; `a/b=v` sets a field inside an object. `signafaide checks status` prints the held version in words, each rule with its state.
