# Checks file and wrapping by hand

`signafaide protect` writes the code change and the checks file for you ([Quickstart](/docs/quickstart)). This page is the reference for doing it by hand, and for projects that still use the checks file version 1, `wrapTools` with `strict` (a protected tool), or the `checks` and `rules` commands. Everything here keeps working.

## Version 2

`signafaide protect` and `signafaide pull` write version 2. `SIGNAFAIDE_CHECKS=<path>` names another file, and `SIGNAFAIDE_CHECKS=0` turns checks off. The file is read again when it changes, and the new version applies from the next call, without a restart.

| key | meaning |
|---|---|
| `format` | `signafaide-checks/2` |
| `checks` | each of `secret`, `address`, `changed_tool`, `fingerprint` and `hidden_instruction`, `true` or `false` |
| `tools` | per tool: `protect` (`true` or `false`), `mode` (optional, `watch` or `enforce`) and `disclose` (only with `protect: true`) |
| `addresses` | the allowlists of the address check, below |
| `rules` | `null`, or local rules: `{"default", "rules"}`, as in [Rules](/docs/rules), without `limit`, `state` or `exceptions` |
| `ruling_timeout_ms` | optional: how long a protected call waits for its ruling, 1 to 60,000 ms; 10,000 by default |

- **`protect: true`** makes the tool's calls wait for a ruling, stop when none comes (unless the console says let it run), and send exactly the fields in `disclose` that a rule can use.
- **`mode`** is the state of the checks on your machine for that tool: `"enforce"` (On) blocks what they find, `"watch"` (Calibrating) notes it. It is `"enforce"` for a protected tool and `"watch"` for any other tool unless the file says otherwise. A tool protected by local rules alone, with no account, is `"protect": false, "mode": "enforce"`.
- **`disclose`** is the list of fields you approved for sending, as JSON Pointers (`/amount`, `/to/0`), written by `signafaide pull`. At most 64.

**Unknown keys are errors.** A key, check, operator or value the format does not have, a key of the other version, or `disclose` on a tool that is not protected makes the file invalid: every checked call then fails with the error code `state`, naming the file and the key, and `signafaide checks status` exits 1. An edit that breaks a file already in use leaves the previous version in force and prints one error line.

## Version 1

A version 1 file keeps its meaning, and the SDK reads both. It has one `mode` for every tool, and `strict`, `fail` and `disclose` per tool:

```json
{
  "format": "signafaide-checks/1",
  "mode": "watch",
  "checks": {
    "secret": true,
    "address": true,
    "changed_tool": true,
    "fingerprint": true,
    "hidden_instruction": true
  },
  "tools": {
    "refund": {"strict": true, "fail": "closed", "disclose": ["/amount"]}
  },
  "addresses": {
    "hosts": [],
    "cidrs": [],
    "resolve": false
  },
  "rules": null
}
```

- **`mode`**: `"watch"` (Calibrating) never blocks; a finding is a note with what On would have done. `"enforce"` (On) blocks. It applies to the checks on your machine and the local rules; the rules in the console have their own state, Calibrating or On.
- **`strict: true`** makes a protected tool, as `protect: true` does in version 2: the tool asks the witness for a ruling and runs only on allow.
- **`fail`** is "If signafAIde can't be reached": `"closed"` (Stop, the default) stops a protected call that gets no ruling, with `no_ruling` (`rules_unavailable` when the witness could not load the rules, `no_key` without an API key). `"open"` (Let it run) runs it, and the outcome says no ruling was received. A setting made in the console wins.
- **`disclose`**: as in version 2, but written by hand.

`signafaide protect` and `signafaide pull` rewrite a version 1 file as version 2.

## Internal address allowlists

Allow hosts and networks your agent is meant to reach in `addresses`: `hosts` takes exact lowercase names or `*.` and a suffix, `cidrs` takes IPv4 or IPv6 networks. The project's rules have the same allowlists, set in the console. A name that does not resolve is never a finding.

```json
"addresses": {
  "hosts": ["billing.internal", "*.svc.cluster.local"],
  "cidrs": ["10.20.0.0/16"],
  "resolve": false
}
```

With `"resolve": true` the client also looks up names that are on no allowlist, and a name that resolves to an internal address is a finding. It is off by default, because a lookup takes time.

## Wrapping by hand

- **One function.** `record(fn)` records it; `protect(fn, { args: [...] })` records and protects it. In Python, `@signafaide.record` and `@signafaide.protect`. `args` names positional arguments so a rule can find them by name.
- **Framework tools.** `wrapTools(tools)` (Python `wrap_tools`) records LangChain, OpenAI Agents SDK and Vercel AI SDK tools; protect one with `"protect": true` in the checks file. [Frameworks](/docs/frameworks).
- **Protected wrappers.** `record(fn, { strict: true })` (Python `strict=True`), and the gateway's `--strict` and `--strict-tools a,b`, protect a tool as version 1 does. In TypeScript a protected call returns a Promise, so the checks file cannot protect a plain synchronous wrapped function: its calls fail with `state`, naming the tool and the fix (make it async, or protect it in code).
- **Install, wrap and verify, step by step:** [TypeScript](/docs/quickstart/typescript) and [Python](/docs/quickstart/python), and one page for each framework.

## Errors in code

A call that did not run raises `CheckError` (a block is its subclass `SignafaideBlocked`), with `code`, `check`, `rule`, the rule set version and the missing fields:

```python
from signafaide.checks_runtime import CheckError

try:
    refund("A-1002", 900)
except CheckError as e:
    print(e.code, e.check, e.rule, e.rules_version, e.missing)
```

```ts
import { CheckError } from "signafaide";

try {
  await refund({ orderId: "A-1002", amount: 900 });
} catch (e) {
  if (e instanceof CheckError) console.log(e.code, e.check, e.rule, e.rulesVersion, e.missing);
}
```

The codes are `blocked`, `no_ruling`, `rules_unavailable`, `no_key`, `withheld` and `state`; each is in [Errors](/docs/errors#blocked).

## The checks and rules commands

| command | does |
|---|---|
| `signafaide checks status` | whether checks are on, each protected tool with the fields it sends, the fields the rules need that it does not send, the held rules and list of known bad tools, and any problem (exit 1) |
| `signafaide checks approve <tool>` | approves a changed tool again, when approvals are kept on this machine |
| `signafaide rules pull` | fetches the project's rules now, without changing the checks file |
| `signafaide rules show` | prints the held rule set version, as the signed JSON document |
| `signafaide rules test <tool> '<arguments JSON>'` | evaluates a call against the held rules and local rules, like `signafaide check` with the arguments as JSON |
