# sa-forge-signer

> A thin, self-hosted signer for agents playing SAGE C4 on Z.ink: what it checks, how to run it, its threat model, and how to work on it. Unofficial.

How to read this book: choose chapters from the index below by their description and size, and read only those. In a local build (`target/docs/html/`) each linked file also sits beside this one and matches the checkout; the site follows `main`, which can be ahead of the release in use (`sa-forge-signer --version`).

The rule everything else depends on: the agent must not be able to read the signer's key directory or config. If it can, the signer's checks are advice, not a control; tell the human (see Choosing a setup, "Isolation").

## Contents

- [About this book](https://ttdonovan.github.io/sa-forge-signer/index.md): What this book is, how to build it, and how to read it: the index first, then only the chapters a task needs (about 600 tokens)

## Using the signer

- [How it works](https://ttdonovan.github.io/sa-forge-signer/how-it-works.md): The checks the signer runs before it signs (chain, fee payer, programs, tokens, compute budget, System Program, signers, simulation, limits), then send, confirm and the audit log (about 1.7k tokens)
- [Install and update](https://ttdonovan.github.io/sa-forge-signer/install.md): The install script, connecting Claude Code with its --setup, installing a verified prebuilt binary or building from a release tag, and checking for and applying updates (about 2.2k tokens)
- [Getting started](https://ttdonovan.github.io/sa-forge-signer/getting-started.md): From install to an agent signing over MCP: the short path with the install script's --setup, then by hand config init, a key, a serve token and claude mcp add, with the full config.toml for a testnet wallet setup and for the recommended session-key setup (about 1.5k tokens)
- [Choosing a setup](https://ttdonovan.github.io/sa-forge-signer/setup.md): Path A (the agent holds the wallet) or Path B (the human holds it and grants a session key), what each can lose, and isolating the signer from the agent (about 800 tokens)
- [Checking and signing](https://ttdonovan.github.io/sa-forge-signer/check-and-sign.md): The CLI: check and sign, the JSON report, outcomes and exit codes, expired blockhashes, retrying safely after unknown, and partial signers (about 2.1k tokens)
- [Key lifecycle](https://ttdonovan.github.io/sa-forge-signer/key-lifecycle.md): Creating, granting, funding, using, revoking and destroying a signer key (about 600 tokens)
- [Configuration](https://ttdonovan.github.io/sa-forge-signer/configuration.md): config init and config show, and the annotated example config: cluster, RPC, key and state directories, per-key class, approval, limits and transfer destinations, serve tokens, and tracing (about 2.3k tokens)
- [Serving over HTTP and MCP](https://ttdonovan.github.io/sa-forge-signer/serve.md): serve: the HTTP routes and MCP tools, bearer tokens and allowed hosts, graceful shutdown, adding it to Claude Code, the llms.txt resources and the agent skill, and sa-forge-signer-mcp for MCP clients that speak only stdio (about 2.2k tokens)
- [Running in Docker](https://ttdonovan.github.io/sa-forge-signer/docker.md): The non-root image, the config, keys and state mounts, one-shot and service runs, and keeping keys from the agent (about 600 tokens)
- [Security](https://ttdonovan.github.io/sa-forge-signer/security.md): The threat model, what the signer does not cover, repairing the audit log, and reporting a vulnerability (about 2.9k tokens)

## Working on it

- [Contributing](https://ttdonovan.github.io/sa-forge-signer/dev/contributing.md): Prerequisites, the check gate, Conventional Commits, what counts as a breaking change, and how release-plz cuts releases (about 1.5k tokens)
- [Code map](https://ttdonovan.github.io/sa-forge-signer/dev/code-map.md): Where things live: the repository layout (src, apps, docs, scripts, workflows) and each module in src/, for finding where a check, an RPC call, a route or a gate lives (about 1.9k tokens)
- [Design decisions](https://ttdonovan.github.io/sa-forge-signer/dev/design.md): Design decisions and their reasons: one crate with three binaries by role, why the stdio MCP binary is a client of the service and not a second signer, why the service uses tiny_http and a hand-written MCP handler instead of rmcp, the built-in agent guides, and what would reopen each choice (about 2.0k tokens)
- [MCP conformance](https://ttdonovan.github.io/sa-forge-signer/dev/mcp-conformance.md): MCP conformance: the specification the signer follows and where to read it, the one revision it speaks (2026-07-28), what the service's /mcp route and the stdio binary implement rule by rule, what an older client sees, and what is left out (about 2.3k tokens)
- [Plan](https://ttdonovan.github.io/sa-forge-signer/dev/plan.md): What is next and the backlog, kept in the same change as the work it tracks (about 2.1k tokens)
- [Hardening proposals](https://ttdonovan.github.io/sa-forge-signer/dev/hardening.md): Proposed hardening, each marked once built: one policy function for check and sign, a duplicate-signature guard, a halt, an instruction table with profile binding, compute-budget and transfer limits, policy digests, redeploy holds, RPC budgets and a systemd unit. The threat each addresses, what changes, tests, priority and build order (about 7.0k tokens)
- [RPC calls and latency](https://ttdonovan.github.io/sa-forge-signer/dev/rpc-latency.md): Where a sign spends its time: the RPC calls it makes in order, how RPC connections are opened, reused and closed, the genesis-hash cache and the confirmation polling, measured timings, how to trace a sign, and what to change if a trace shows a problem (about 1.8k tokens)
- [Changelog](https://ttdonovan.github.io/sa-forge-signer/dev/changelog.md): What changed in each release, written by release-plz from the commit messages (about 1.7k tokens)
- [Writing the docs](https://ttdonovan.github.io/sa-forge-signer/dev/writing-docs.md): How the book is built and written for agents: where chapters live, frontmatter descriptions, line and link rules, and just docs check (about 900 tokens)
- [Building an app](https://ttdonovan.github.io/sa-forge-signer/dev/apps.md): Rules for the extras under apps/: never weaken the signer's isolation, stay out of its build, code standards, dependency age, recipes and the per-app gate (about 1.4k tokens)

## Extras

- [Apps](https://ttdonovan.github.io/sa-forge-signer/apps/index.md): Extras built beside the signer under apps/: what they are, and how they relate to the signer's releases and gate (about 400 tokens)
  - [Console](https://ttdonovan.github.io/sa-forge-signer/apps/console.md): sa-forge-signer-console: a read-only desktop view of serve health, the audit log and per-key limits, run locally or against a signer in Docker. Early spike. (about 1.5k tokens)
  - [Grant page](https://ttdonovan.github.io/sa-forge-signer/apps/grant.md): sa-forge-signer-grant: a local web page where the profile authority's own browser wallet (or a Ledger through it) grants and revokes a SAGE session key, for Path B. What it checks, refuses and leaves out. Early spike. (about 2.2k tokens)
  - [IDL table](https://ttdonovan.github.io/sa-forge-signer/apps/idl-table.md): sa-forge-signer-idl-table: generates the signer's instruction table (tables/<cluster>.json) from the SAGE, Player Profile and Profile Faction Codama IDLs without copying them; what the table holds, what it cannot tell, and regenerating it after a program upgrade (about 900 tokens)

## Appendix

- [Optional tools](https://ttdonovan.github.io/sa-forge-signer/appendix/index.md): Optional tools for working on the signer and its apps: local branch review with git-review, and GPUI Kit's Claude skills for the console's UI. Nothing here is required. (about 200 tokens)
  - [Local review with git-review](https://ttdonovan.github.io/sa-forge-signer/appendix/git-review.md): The local merge-request workflow: just mr-open, mr-diff and mr-approve for reviewing an agent's branch (about 1000 tokens)
  - [GPUI Kit skills](https://ttdonovan.github.io/sa-forge-signer/appendix/gpui-kit-skills.md): Optional: install GPUI Kit's Claude skills (gpui-kit, gpui-kit-design-guides) at the console's gpui-kit version with just apps gpui-kit-skills; where they go, updating and removing them (about 400 tokens)

## Optional

- [llms-full.txt](https://ttdonovan.github.io/sa-forge-signer/llms-full.txt): Every chapter in one file, for reading the whole book at once (about 47.1k tokens)