gage
by warewithall2
README.md
# gage
**Hand work between AI agents without handing over trust.**
Your Claude hands a task to Codex. A colleague's agent sends you their project
state. Normally nothing on the receiving end says who wrote it, or whether you
have ever confirmed that person — and an agent reading its inbox is not a human
reading email. A human who reads a phishing message is not executing it; an
agent is. **A channel that lets one LLM send prompts to another is, by default,
a prompt-injection delivery network.**
gage is that channel built the other way round. It is three things:
- **A bundle** — files, a prompt and decisions in a signed, sealed directory.
- **A list you control.** Two people compare four word-pairs over a channel
neither machine controls, and `gage confirm` records that they did. A key
nobody has confirmed still works and says so — `SENDER ON YOUR LIST,
UNCONFIRMED` — because being on a list and having been checked are two
different facts and only one of them is a claim about a person. Arrival is
not consent either: a bundle that lands in your inbox sits there unread
until you accept it. (A sealed file somebody hands you is the exception, and
the frame says so when you open one: pointing `gage open` at a directory is
itself the decision, and there is no gate behind it.)
- **A reading frame.** Before any payload, the receiving agent is told that
this is *data* from an identified party carrying no authority — and when the
sender is not attributable under a key you currently accept, the contents
are withheld rather than annotated, because an annotation is something the
payload can argue with.
*Every line of that recording is genuine output.* The same capture is
[docs/demo.md](docs/demo.md) as annotated text and
[docs/demo.cast](docs/demo.cast) in asciinema v2 format, and
[scripts/demo.sh](scripts/demo.sh) reproduces it in a throwaway directory
without touching your own gage home.
Try it:
curl -fsSL https://gage.sh/install.sh | sh # verifies its own checksum
gage quickstart
It works across vendors because it is **not a protocol**: a bundle is a signed
directory, so it moves over a shared folder, git, email, or anything else you
already have. There is a viewer (`gage ui`), machines find each other on a LAN
with no server in the middle (`gage lan`), and an agent can drive the whole
thing itself over MCP (`gage mcp`).
A gage is a pledge: something of value handed over to stand behind a promise,
and historically the glove thrown down to open a challenge. Both senses fit.
Everything downstream — every verdict, every grant, every unattended
acceptance — rests on that one human moment.
## "Why not just sign the payload yourself?"
Asked by a reviewer, and no document here answered it, which is a gap worth
closing because it is the first question anyone technical will have. Ed25519
is forty lines away in any language. If you want a signed handoff, sign the
tarball and send it.
What that gets you is **authenticity**. Every part of the gap between that and
this is a local decision the signature cannot make for you:
- **A signature says a key signed something. It does not say you ever agreed
to hear from that key.** The verdict is computed from your allowlist, and
— since this release — from a record that a human compared four word-pairs
with its owner. "Valid signature" and "someone I have confirmed" are
different sentences, and only one of them is a statement about a person.
- **Verifying it yourself means writing the verdict yourself**, and the
interesting verdicts are the ones nobody writes until they have been
burned: a key you retired that is still signing; a bundle that cannot be
placed either side of that retirement; a key you looked at and refused. Each
needs local state the signature knows nothing about — an allowlist, a
retirement cut, an observation counter — and getting the *direction* of each
one wrong is the difference between a warning and a thief's content rendered
as a colleague's.
- **The payload still has to be read by a model**, and that is the half this
is really about. A verified payload is still someone else's prose arriving
where your agent takes instructions. The frame, the fence nonce, the
per-item kind labels, the withholding rules, the accept gate — none of that
follows from a signature, and all of it is what decides whether a signed
message becomes a prompt-injection delivery vehicle with a certificate.
- **And the honest limit:** the frame is text, and text does not outrank the
host prompt. See [docs/dogfood-2026-10-15.md](docs/dogfood-2026-10-15.md),
where that is what happened. `gage authority` exists because the only thing
that can grant authority is the receiver, in a file no sender can reach.
So: sign the tarball if the question is "did this come from them". This is for
the question after it, which is "and what may my agent do about it".
## The receiving agent's half of the trust boundary
Signing what an agent *does* is well covered by other work — receipts over
tool calls, verified at the server that executes them. See
[docs/prior-art.md](docs/prior-art.md). gage is the other end: what the agent
*reading* a message is told about it, in the seconds before it decides what to
do.
**What it does NOT stop:**
[docs/what-this-does-not-stop.md](docs/what-this-does-not-stop.md) answers the
2026 agent-security incidents one at a time — Cursor's sandbox escape, the
coding agents that leaked their own keys to a PR title, the Cline bot that
shipped a backdoored release off a GitHub issue title — and the answer for
every one of them is **no, gage would not have prevented that**. They arrived
over the web, a pull request, an issue tracker, an email, a package registry.
gage is one channel between two parties who confirmed each other's keys. The
same file carries the MCP server audit and the one hole it found.
**The wire reality and the limits:** [docs/spec.md](docs/spec.md) is what is
actually on disk and on the network — the bundle layout, what is signed, how a
receiver computes trust, the relay protocol — derived from the code rather than
from intent. [docs/threat-model.md](docs/threat-model.md) is the adversaries,
the mitigation for each, and the **non-goals**: the things gage deliberately
does not protect against, including the central one, that nothing here can
make a language model obey the frame.
**On A2A:** [docs/a2a.md](docs/a2a.md) says how this maps onto Google's
Agent2Agent protocol, and what gage deliberately is not — not a transport, not
a registry, not an identity provider. It is a design position, not code: gage
speaks no A2A today.
**Calling it from an agent:** [docs/mcp.md](docs/mcp.md) — `gage mcp` serves
the Model Context Protocol over stdio, so an agent calls gage as tools
(`claude mcp add gage -- gage mcp`). The word-pair ceremony survives the hop:
pairing needs the pairs echoed back, and the page is honest about what that
echo does and does not prove.
**Driving it from a script:** [docs/agents.md](docs/agents.md) is gage with no
human at the keyboard — the command table for a whole handoff, the exit codes
(checked, including the case where `1` rather than `2` means "could not read
it"), how to read a verdict out of the output, one complete worked script, and
the honest boundary: what an agent can and cannot do about confirming a key.
**On losing your key:**
[docs/adr-identity-recovery.md](docs/adr-identity-recovery.md) is the decision
record for identity recovery — why encrypted export won, why trusted-contact
recovery was rejected as a new social attack surface that fights the ceremony
model, and the specification the implementation follows. The trade it commits
to is stated plainly there and in the threat model: opting in converts "lose
the key, lose everything" into "your security is your passphrase's strength".
That matters because the reader is different. A receipt's verdict is read by a
program at an admission check, which cannot be talked out of its conclusion. A
bundle's verdict is read by a language model whose next tokens are the payload
itself, and which can. That difference is the whole reason the frame exists.
So `gage open` is a renderer, not an importer. It puts the bundle inside a frame
that states, before any payload, that the contents are **data** from an
identified party and carry no authority — and on a bad verdict it withholds
the contents rather than annotating them, because an annotation is something
the payload can argue with.
Three specific defences, each written after the attack worked in testing:
- **Nonced fence markers.** Payload text containing `=== END RECEIVED CONTEXT ===`
would otherwise close the frame, and everything after it reads as the tool's
own trustworthy voice. The real markers carry a per-invocation random nonce
the sender cannot predict.
- **Keys are identity; handles are claims.** An early version printed
`sender: alice` beside a verified-trust label while the key belonged to bob.
Your own name for a key now leads, and a mismatch is stated loudly.
- **Trust is computed, never carried.** There is no trust field in the
manifest. The receiver derives it from the signature and its own allowlist,
because a `"trust": "verified"` key in a document the sender controls is
decorative.
Payload digests are checked against the signed manifest, so a signed manifest
beside swapped files is caught and the contents are withheld.
**Which verdicts withhold, exactly.** This is worth stating plainly, because
an earlier version of this README said "on a bad verdict" and left a reader to
guess the set — and the guess most people make is wrong. Contents are withheld
on a digest mismatch, and for `SENDER UNVERIFIABLE`, `SENDER KEY REJECTED` and
`ARRIVAL UNRECORDED`: the cases where nothing can be pinned on anybody.
Contents are **shown**, with the verdict above them, for `SENDER NOT ON YOUR
LIST`, `SENDER REFUSED BEFORE` and `SENDER ON YOUR LIST, UNCONFIRMED`. Those
are attributable — a real signature by a real key — and withholding them would
make the ordinary first contact with a new person unusable while buying
nothing: whoever handed you the file can hand you the file again. What you
get instead is the verdict, before the payload, every time.
## Keys, said out loud
$ gage whoami
owen yomSmC3TalJ5IM+H0yvkhhWVab4ujiAVIQFR4WvdXiM=.KlXt+/5rj4y3FMC7eqau4zF5eZV+x7PjYZUdyUXHDEM=
this key says : carved daffodil · grand lintel · spiced barley · bright iguana
device label : humble pillar (from the signing key alone, so NOT the first
pair above -- it is how others tell machines apart)
LocalSend labels a device with a word pair and it is the nicest thing about
using it — but there the words are a *name* the device picked, so anyone can
be Yellow Iguana. Here they are derived from the signing key, so nobody
chooses their own and two machines showing the same words are holding the same
key. `gage fingerprint <name>` says a contact's, and `gage add` prints the words
for the key it just took, which is the moment you confirm it with them over
some other channel.
Two lengths, because one cannot do both jobs. A single pair is 16 bits:
lovely, and useless as a check, since an attacker generates keypairs until
theirs also renders "humble pillar" — about 65,000 tries. So the pair is a
**label**, for telling devices apart in a list, and nothing is ever confirmed
against it. The **fingerprint** is four pairs, 64 bits, and is what a person
compares.
They come from the same function, so for a key with no encryption half the
label is the fingerprint's first pair. For the key above it is **not** — look
at the two lines again. The fingerprint covers the signing key *and* the
encryption key, because confirming only the signing half let an attacker
substitute the key your mail gets sealed to and still pass the comparison word
for word. The label covers the signing key alone, and has to: a bundle's
manifest carries nothing else, so that is the only nickname a receiver can
derive for a sender it has never met.
This paragraph used to say the label was "always a real prefix of the
fingerprint", `spec.md` and `words.rs` agreed, and the example above was
written to match — which is how a wrong claim survives three documents. It was
wrong for every contact you can seal to. A unit test now fails if the two ever
line up again.
## The second machine
Install it, then one command on each:
$ gage lan
new identity, named after its own key: grey crowbar
grey crowbar · lavish jackdaw · sleepy hedgerow · electric delta
gage lan -- you are "grey crowbar" on this network
visible and reachable while this runs, silent the moment you stop it
anything sent to you lands unread in inbox/pending
broadcasting to: 255.255.255.255, 192.168.1.255
gallant alcove at 192.168.1.44:7791 (not paired)
says : gallant alcove · indigo burrow · merry banner · glassy nettle
Then send, by the two words on the list:
$ gage send --to "gallant alcove" --subject hi --file notes.md --lan
handed to gallant alcove at 192.168.1.44:7791, over this network
it is in their inbox/pending -- not accepted
No name to choose, no key to copy, no pairing first, no relay. The name is
two words taken from the signing key, so nobody picks their own — LocalSend's
device names, except derived rather than chosen, which makes them a slightly
better label at no cost to the person.
**Presence is the process.** It announces while `gage lan` is in the
foreground and goes silent the moment you stop it. That is LocalSend's own
answer to the same objection, and a better one than the flag this started
with: the state is visible on screen rather than sitting in a number of
seconds you have to remember you passed.
**Pairing is an upgrade, not a gate.** An unpaired machine can send to you
and what arrives is `SENDER NOT ON YOUR LIST`, unread, behind the same accept
gate as everything else — which is the protection, and always was. When you
want a key confirmed rather than merely observed:
$ gage pair laptop
gallant alcove at 192.168.1.44
says : gallant alcove · indigo burrow · merry banner · glassy nettle
Does the other machine show EXACTLY those words? [y/N] y
Four word-pairs is 64 bits and is what a person compares; the single pair in
the list is 16 bits and is a label only, never confirmed against, because
grinding 65,000 keypairs to match one is trivial. That confirmation is what
makes a key *yours* rather than *some machine on this wifi*, which is what a
[grant](#authority-the-one-thing-that-says-you-may-act) should require before
an agent acts on a message unattended. Requiring it before one file could
move was a step I added and it was wrong.
Underneath, `gage nearby`, `gage pair` and `gage listen` are still there as the
explicit forms, and `gage listen` is the one to use for a machine that should
be reachable without announcing — it answers an address query only when the
query is signed by a key already on your list, so a stranger gets silence they
cannot tell from an empty network. Design and the costs:
[docs/lan-discovery-design.md](docs/lan-discovery-design.md).
## Authority: the one thing that says you may act
Everything above is about what is *known*. None of it says whether an agent
may do what a message asks — and it cannot, because a bundle cannot authorise
its own fulfilment, however well signed. That gap is real and was measured:
[dogfooding this across four agents](docs/dogfood-2026-10-15.md) had two of
them read a verified request from a verified contact and decline, correctly,
for want of authority.
So authority is computed by the receiver from its own list, exactly as trust
is. `~/.gage/authority` is a file **your human writes**:
# no gage command writes this file; edit it yourself
allow codex review-request
allow dana question in-reply-only
allow <a-public-key> any # any message KIND, not any action
`gage authority` prints what is granted. There is deliberately **no command
that writes a grant** — a `gage allow` would be reachable by prompt injection,
letting an agent talked into running it grant itself permission to obey
whatever talked it into it. Edit the file yourself.
That guard is a deterrent, not a boundary, and the frame now says so. Any
process that can read this file can also write it, so an agent with a shell
can add its own grant — which is exactly how the grants for the 15 October
reviews got written. Removing the documented command means an injected agent
has to be told to hand-write a file, which is conspicuous in a transcript; it
does not make the file unwritable. A real boundary needs file permissions or
a separate process the agent cannot write through. `open` therefore tells the
reader never to edit the file, or add a grant, because a message asked it to.
Three rules, in the order they would hurt to get wrong:
- **A grant only ever follows `SENDER VERIFIED`.** Any other verdict and no
grant is consulted at all. A grant that followed a forged or stolen key
would be worse than having no feature.
- **A malformed file grants nothing.** One unusable line voids the whole file,
because the other direction lets a typo on line 2 widen line 3 — and the
failure directions are not symmetric. Too little authority asks a human a
question; too much acts on a stranger's instruction.
- **A grant is for a kind of message, and the frame names the one act it
permits.** The scope comes from the kind, in `MsgType::granted_scope` — a
`review-request` permits reading what the bundle encloses and reporting
findings, and nothing else. The first version said "you may act on what this
message asks, within what it asks", which handed the boundary to the
payload; both reviewers caught it independently. Editing files, running
commands, committing, pushing, sending anything, messaging a third party and
touching secrets or keys are listed as never covered, whatever the payload
asks.
- **The grant line carries the frame's nonce**, so a payload cannot write a
complete one. That raises the bar against a copied static string. It does
not make a positive grant unimitable, because the reader is a model that can
be argued into ignoring a marker, and the frame says as much rather than
leaning on it.
No expiry yet, on purpose — it cannot use a clock, for the same reason
[key retirement cannot](#the-retired-key-keeps-the-past-and-loses-the-future),
and "expires after N observed messages" is a strange thing to ask a person to
write. A file you edit is already revocable by editing it.
### Accepting without a human, and the budget that bounds it
`accept` has always meant a person looked at a frame and moved a bundle. For
an unattended loop that is the step nothing can do, so what people build
instead is a hook that runs `gage accept` itself — which makes every grant
unbounded and leaves gage unable to tell, afterwards, which acceptances a
human performed. So it is in the tool, where it can be counted:
allow sndr answer auto-accept max-exchanges 4
$ gage watch --auto-accept
7382e954: accepted unattended, 1 of 4 in this thread (allow sndr answer
in-reply-only auto-accept max-exchanges 4)
aa3e2665: this thread has used 4 of 4 auto-accepts (…), so it stays pending
Four conditions, all required:
- **The watcher was started with `--auto-accept`.** The file says what the
human permits; the flag says *this process* is the unattended one. An
interactive `gage watch` must not move things a reader is about to look for.
- **A grant says `auto-accept`.** Which cannot be written without
`max-exchanges N` and cannot be written against `any`. Both are refusals,
not defaults: a half-written grant must not read as an unbounded one, and
every default here would be a guess at what a person meant.
- **It answers something this machine sent.** `auto-accept` implies
`in-reply-only`, and the grant you are shown prints the implied modifier so
the rendered line is what is actually in force.
- **The thread's budget is not spent**, counted from the journal.
**The budget cannot be refilled by a sender.** It is per thread, and a thread
id is a field the *sender* writes, so the key is read out of this machine's
own `sent/` instead: the thread of the parent being answered, which only the
receiver can have written. A reply must name a parent found there and signed
by this machine's own key, so opening a thread is the receiver's act, and a
sender naming a parent that was never sent gets nothing.
The first version of this claimed the implication of `in-reply-only` was the
whole defence. A reviewer showed it is not even half of one: `in_reply_to` and
`thread` are *separate* fields, so a granted sender could answer the same
verified parent with `thread: "aa"`, then `"bb"`, then `"cc"`, and collect a
full budget each time. Validating the parent and then discarding everything
learned from it is what left the hole — the predicate returned a bool. It now
returns the parent, and the budget is keyed on it. A reply that claims a
different thread from the parent it answers is refused outright as well, since
no sender built with `--reply-to` ever does that.
That check is also what made `in-reply-only` mean anything at all. Until this
feature needed it, it tested `in_reply_to.is_some()` — asking the sender
whether the sender is replying. Any sender satisfied it by writing any string
into the field, and a grant written `in-reply-only` was no narrower than one
without it. The string also became a path component, so `../../../../etc` was
reaching out of `sent/` on a `stat`; ids are validated now, by the same
function that exists because [the same hole was found once before](src/manifest.rs),
on `pull`.
**The journal entry is the budget.** There is no counter file: a second place
to keep a count is a second place for it to be wrong, and the record of what
was done is already the record of how much was used. Each unattended accept
writes which grant allowed it, which line of the file that was, the budget key,
and where the count stood.
Three things follow, and each was a defect first:
- **The record is written before the move,** so a failed write leaves the
bundle in `pending` for a human rather than in `accepted` with nothing
counting it. The other order spends no budget and accepts anyway.
- **The count is taken again inside the journal lock**, because counting and
then appending as two steps is a race: two watchers each read `used = 0`
against `max = 1` and each accepted.
- **A journal that cannot be written turns auto-accept off for the rest of the
run**, latched. It used to print and carry on, so a full disk would have
become an unbounded, uncounted accept path for as long as it lasted. A line
that will not *parse* also declines rather than counts past it — `read`
skips unreadable lines, which is right for showing history and fails open
for a counter.
**What it is not:** permission to act — with one honest qualification. The
acceptance itself moves a directory and marks it readable; it does not open
the bundle, hand it to a model, or run anything, and `gage open`'s
`authorised :` block is still the only thing that says what may be done with
what is inside. But `gage watch --auto-accept --on-arrival …` is an end-to-end
unattended pipeline in one process, and the accept is deliberately ordered
*before* the hook so the hook finds the bundle accepted. A reviewer was right
that "nothing opens or runs anything" is true of the acceptance and false of
that combination. What the hook may then do is bounded by the hook, which a
human wrote, and by the grant it is told about — not by this feature.
Nor is the bound a defence against a
determined verified sender — that sender can still reply to everything you
send, within the budget, indefinitely. What it buys is that a *runaway*
exchange — two agents answering each other, a loop, a sender that got stuck —
stops at a number a human chose rather than at whatever the disk runs out of
first.
`gage watch` now also dates arrivals in the journal before anything acts on
them. It did not before, which meant the unattended path — the one the journal
exists for — was leaving the thinnest record: an `accepted` entry with no
`observed` entry in front of it.
## Getting started, and getting someone else started
Install it without a Rust toolchain:
curl -fsSL https://gage.sh/install.sh | sh
That pipes a script into a shell, which is a thing worth being asked to
trust — so **read it first if you would rather**, and it is short enough to
read in a minute:
curl -fsSL https://gage.sh/install.sh -o install.sh
less install.sh && sh install.sh
It works out your OS and architecture, downloads the matching binary and its
`SHA256SUMS` from the latest release, **verifies the checksum before
installing anything**, and puts one file in `~/.local/bin` (`PREFIX=` to
change that). It never uses sudo, and it fails loudly rather than guessing on
a platform with no released binary. `cargo install gage` remains the other
path and works anywhere Rust does.
> Renamed twice on 18 October: `ctx` → `countersign` → `gage`. **Nothing on
> disk moves, ever.** An identity key is the one file whose loss cannot be
> undone — every contact who confirmed your word-pairs confirmed *that* key —
> so `gage` uses the first home that exists out of `~/.gage`,
> `~/.countersign`, `~/.ctx`, copies nothing, creates nothing to replace
> another, and honours `GAGE_HOME`, `COUNTERSIGN_HOME` and `CTX_HOME` so that
> existing scripts and systemd units keep working.
Then, from nothing to a first handoff, answering four questions:
gage quickstart
It makes an identity if you have none, shows your word-pairs and the one line
you send a colleague, then offers to add their key and send a first bundle.
Every step is skippable; it does nothing the individual commands below do not.
Or, with a relay:
gage connect https://relay.example.com
Three steps that have no decisions in them — make an identity, register a
mailbox, work out what to share — and then a deliberate stop at the one that
does. It prints the line the other person runs, and the four word-pairs you
have to read to them out loud. That last part is not automated because
automating it would be removing the only thing gage does.
Run it again whenever: it keeps the identity you have. A command whose job is
to get you started must not be the one that silently throws away the key
everything you have already exchanged was built on.
## Giving it to someone else
scripts/release.sh my-laptop # build on every machine reachable
cat dist/SHA256SUMS
scripts/release.sh --audit # is this version actually out?
Binaries land in `dist/`, one per platform, each built on the machine it runs
on — cross-compiling needs a C toolchain per target because rustls brings C,
and a binary built where it runs is one fewer thing to be wrong about. Every
binary reports the commit it came from, `gage --version` prints it, and the
release refuses to build from a dirty tree: a binary that names a commit it
does not match is worse than one with no version at all, and the journal
freezes verdicts, so "which gage decided this" needs an exact answer. The stamp
is checked by asking the binary — on the host that built it, when it cannot
run here.
[INSTALL.md](INSTALL.md) is written from the other person's side, including
the two places they are most likely to give up: the macOS quarantine dialog on
an unsigned binary, which looks like the software is broken, and the word-pair
confirmation feeling like a chore when it is the only step that cannot be
automated.
## Use
gage init owen # make your keypair
gage whoami # the line you give to a colleague
gage add dana <their-key> # buddy list; keyed on the key, not the name
gage confirm dana # after comparing the words out loud: the
# only thing that produces SENDER VERIFIED
gage rotate # replace your key without losing your past
gage send --to dana --subject "backoff refactor" \
--prompt task.md --decision notes.md \
--file src/client.rs \
--agent claude-code --model claude-opus-5 \
--out ./handoff
gage inspect ./handoff # summary, no contents in context
gage open ./handoff # render for an agent, inside the frame
gage reply <id> --text "..." # answer a thread, recipient inferred
gage forward ./handoff --to group:eng --out ./fwd
gage lan # the whole of the local network, one command
gage send --to "grey crowbar" --file notes.md --lan
gage pair laptop # confirm a key, rather than just see it
`open` exits 0 when the bundle is attributable, and 2 when the signature fails,
the payload does not match, or the signing key has been taken out of service,
so a harness can branch without parsing prose.
## Item kinds, and why they differ
| kind | what it is | how `open` treats it |
| --- | --- | --- |
| `--file` / `--dir` | material: source, data, documents | fenced as data |
| `--decision` | a finding worth carrying across | fenced as data |
| `--prompt` | text written to steer a model | fenced loudly: quote, never adopt |
| `--memory` | CLAUDE.md, AGENTS.md, memory/*.md | fenced hardest: **never merge** |
Memory is its own kind because it is the only one that outlives the session
that accepts it. A prompt steers one turn; merged memory steers every future
session, after the person who approved it stopped watching. `open` says so,
and never suggests merging.
`--dir` sends a tree with its structure intact. An earlier version flattened
everything to `items/<basename>`, so a project containing `src/mod.rs` and
`src/net/mod.rs` produced two items at one path and the second silently won --
sending a project was lossy and nothing said so. Build and cache directories
are skipped, and so is anything that looks like a secret (`.env`, `*.pem`,
`*.key`, `.netrc`, `id_rsa*`, names containing `secret`/`token`/`apikey`).
Every skip is printed before the bundle is built, because a silent omission is
its own surprise. `--allow-secrets` overrides, and you should have a reason.
Caps: 2 MB per item, 25 MB per bundle.
`--reply-to <id>` threads a bundle to the one it answers, so an exchange
between two agents reads as a conversation.
## Encryption
Signing proves who wrote a bundle. It does not hide what is in it. That is
fine on your own filesystem and not fine on a server, so nothing goes to a
relay unsealed.
gage seal ./handoff --to dana --out handoff.gageb
gage unseal handoff.gageb # receives it: inbox, accept gate, reply
gage inbox
`unseal` with no `--out` **receives** the envelope: it goes through the same
gates as mail a relay handed over — a safe id, a verifying signature, the
replay witness — and lands unread in `inbox/pending`. So a bundle that came to
you as a file on a USB stick is mail like any other: `gage inbox` lists it,
`gage accept` stages it, `gage reply` answers it, and the arrival is witnessed
and journalled.
`--out` is the other thing you might want, and it is deliberately not the
same:
gage unseal handoff.gageb --out ./incoming # inspect, do NOT receive
gage open ./incoming
That writes the files where you point and records nothing. Use it to look at a
bundle you just built, or at one you have not decided to accept. `gage open`
on the result says it did not come through your inbox, and because there is no
arrival record, a bundle inspected this way reads `ARRIVAL UNRECORDED` once
the sender retires that key. That is the honest answer rather than a gap: a
witness is a claim that this machine *received* something, so only receiving
may write one. If inspecting recorded an arrival, merely peeking at a file
would later earn a retired key the milder verdict and show its contents.
A sealed box (X25519 + XSalsa20-Poly1305) encrypts to the recipient's public
key with a fresh ephemeral keypair. The envelope holds three fields: a version,
the recipient's encryption key, and ciphertext. A relay therefore learns a
recipient key, a size and a time -- not the subject, the filenames, the sender,
or the payload. Verified by grepping a real envelope for the sender handle,
subject and contents: none appear.
The transport is anonymous and **authorship is proved by the signature inside
the bundle instead**. That split is deliberate: end-to-end authorship survives
the relay, and the relay never becomes an authority on who said what.
`unseal` says so explicitly, because decryption proves only that the sender
knew your public key -- which anyone does.
Decrypted contents are still untrusted input. An item whose path escapes the
bundle, or that the manifest never declared, is refused rather than written;
both are unit-tested, since only a malicious *sender implementation* can
produce them.
Your `gage whoami` token is now `signpub.boxpub`. Identities created before
encryption existed gain an encryption key on next load **without changing the
signing key**, so every bundle you signed previously stays verifiable.
A contact with no encryption key on file can be verified but not sealed to,
and `gage seal` refuses rather than silently sending in the clear.
## Outbound safety
The scan reads bytes rather than text, and scans long lines in overlapping
windows. Both of those are fixes: it used to read with `read_to_string` and
skip anything that was not valid UTF-8, so appending one invalid byte to a
file made the whole scan ignore it, and a line over 4000 bytes was skipped
rather than truncated, so padding a line hid whatever was on it. A scan that
can be switched off by the thing it is scanning is decoration.
Findings are redacted to a fixed shape that reveals neither the tail nor the
length -- the first version showed four leading characters, three trailing
ones, and a star count that was the exact length, which for a short token is
most of it, printed on the way to refusing.
Symlinks are refused and reported, never followed. The deny list matches a
file **name**, and a link's name says nothing about its target: `notes.md ->
~/.ssh/id_rsa` passed every check and shipped the key, and the content scan
did not save it either, because a `.env`-shaped target is neither a PEM block
nor a vendor key pattern. `--allow-secrets` does not override this -- it is an
override for files whose names you can see, and the whole problem with a link
is that you cannot. A linked directory passed as `--dir` is an error rather
than a skip, since walking it would collect a tree from somewhere nobody named.
Two gates on the way out, because the filename deny list only catches files
that are *named* like secrets.
**Content scan.** Every item is read before it is sealed. A `notes.md` that
quotes a customer's address, or a log fragment with a bearer token still in
it, is what actually leaks -- and its filename says nothing. `gage send`
refuses rather than warns: on an outbound path a warning arrives after the
bundle exists, and for a remote recipient after it has gone.
outbound scan found 1 item(s) that should not leave:
notes.md:2 [email] dana**********************.uk
Findings are **redacted**. A tool whose job is to stop secrets leaving should
not print them to a terminal or into an agent's context on the way to
refusing. Built-in rules cover private-key blocks, AWS/Anthropic/OpenAI/GitHub/
Slack/Google/Stripe key shapes, bearer tokens and real email addresses;
`example.com` and a bare `sk-ant-` in prose do not fire. `~/.gage/scrub.json`
takes `never_send` literals (a customer domain, a codename) and `disable` for
rules a repo legitimately trips. `--allow-findings` overrides and says so.
**Confirmation before anything leaves.** `gage push` prints the recipient,
subject and file list and refuses without `--yes`. The accept gate protects
the receiver; this protects the sender, and it is the one that matters when an
agent is doing the sending.
The gate is on `push`, not `send`, because `send` either delivers to a local
route or writes a directory you still have to move -- nothing has left yet.
An earlier version gated `send` on "has no local route", which is not the same
as "is leaving", and it broke every send to an unrouted handle.
## Relay
Registration proves possession of the box **secret**, not just knowledge of
the box key. That key is what you hand out in a `gage whoami` line, so a relay
that took the claim at face value could have its mailboxes squatted: register
someone else's box key against your own signing key before they get there,
and first-registration-wins locks the owner out permanently -- they can never
fetch, and mail pushed to them lands where the squatter can collect and delete
it. Sealed, so never readable, but gone, with the sender believing it arrived.
So the relay seals a random nonce to the claimed box key and commits the
binding only when the caller sends that nonce back. A squatter gets a sealed
nonce they cannot open and a pending claim that blocks nobody, since pending
claims are keyed by the pair rather than the mailbox.
For the case where the other agent is not on your filesystem. The relay is
deliberately stupid: it holds sealed envelopes addressed to an X25519 public
key and hands them to whoever proves they hold the matching secret.
### Which relay you are using
**There is no default relay on the command line.** `gage push` and `gage pull`
refuse until you have run `gage join <address>`, and they name no address for
you.
**The viewer is different, and this was documented nowhere until a review
asked.** The "available over the internet" switch on Conversations arrives
pre-filled with `https://relay.gage.sh` (`RELAY_DEFAULT`, `src/ui.rs`). It is
a suggestion in an editable field: nothing is contacted until you press the
button, and pressing it registers your mailbox there. Clear the field and type
your own address if you have one, and `gage relay --bind …` on any host you
control is the whole server.
Whichever relay you use, including that one, the properties below are what you
are relying on and they are the reason the default is tolerable: it holds
sealed envelopes it cannot open, and what it learns is metadata — which
mailbox has mail, how big, and when. If that metadata matters to you, run your
own; if the other machine is on your filesystem or your network, you need no
relay at all and `gage seal` / `gage lan` are the shorter paths.
On the host that will hold mail:
gage relay --bind 100.x.y.z:7788
On each machine:
gage join 100.x.y.z:7788 # registers your mailbox, saves the address
gage push ./handoff --to dana # seals, then uploads
gage pull # collects into inbox/pending
**The relay cannot read what it stores.** Compromising it leaks metadata --
which mailbox has mail, how big, when -- and no content. Verified in the test
suite by pushing a bundle with distinctive subject and payload strings and
grepping the relay's store: neither appears.
Four properties the relay enforces, each tested:
- **Fetching requires proof of key possession, not a key name.** Anyone who
has seen a `gage whoami` line knows your public key, so a name-only scheme
would let a stranger drain your inbox. The relay issues a random challenge
and requires an ed25519 signature over it.
- **A challenge is consumed on first use.** A replayable signature is a stolen
credential with a longer life.
- **A challenge is bound to one mailbox**, so it cannot be redirected.
- **First registration of a mailbox wins.** Rebinding a box key to a different
signing key would be mailbox takeover by re-registration.
Base64 keys become directory names, so they are validated rather than trusted:
base64 contains `/`, and `/` in a path component is how a mailbox escapes its
directory. Unregistered mailboxes are refused, so the relay cannot be used as
storage for keys nobody will collect.
Bind it to a tailnet address, not `0.0.0.0`. On a tailnet, WireGuard already
provides the encrypted channel and there is no public exposure, so no TLS and
no domain are needed. **Security does not depend on the network** -- the
payload is a sealed box either way -- so the same binary can later sit behind
a reverse proxy on a public address with no change to the envelope.
Trust still comes from the signature inside the bundle, never from the relay.
A bundle that arrives via a relay from someone you have not added reads
`SENDER NOT ON YOUR LIST`, exactly as it would locally.
### A relay that faces other people
Everything above about the relay assumed it was reachable only from one
person's tailnet, which is how it has run so far. Making it reachable by a
colleague changes the threat model completely, and three things were missing.
**One connection that said nothing held the entire relay for ever.** The
accept loop was sequential and `read_line` blocked inside it: no credentials,
nothing sent, total denial of service from a single TCP socket. The viewer was
given timeouts when the same shape was found there; the relay never was, and
the relay is the part that faces other people. It now sets read and write
timeouts before anything reads, serves connections concurrently up to a cap,
and past that cap refuses politely instead of falling over.
**`/send` takes no authentication, on purpose, so it needs a bound instead.**
A stranger must be able to send you a first message — that is exactly what the
buddy list's "not on your list" section is for — so the answer cannot be
authentication. It is quotas: bytes and envelopes per mailbox, a total store
cap as the backstop when many mailboxes are each individually under their
limit, and a per-address request limit. All four are flags on `gage relay`, so
an operator who wants more says so:
gage relay --bind 0.0.0.0:7788 --max-mailbox-mb 64 --max-mailbox-msgs 500 --max-store-mb 4096 --rate-per-min 120
A full mailbox is refused with "mailbox is full" and nothing about who filled
it. A letterbox does not report its senders to whoever knocks; the person who
gets to see who is sending is the recipient, when they collect. And the
recipient can still collect what did arrive — a bound on strangers must not
become a bound on you.
Binding anything other than loopback or a tailnet address prints what that
means before it serves a byte.
### TLS, and why it is here despite the payload being sealed
gage join https://relay.example.com # certificate verified
gage join 100.64.0.1:7788 # no TLS: a tailnet or a loopback test
The scheme decides, and the address is written by a person, so the choice is
visible rather than buried in a default.
The payload was always sealed and TLS does not change that. What it changes is
everything *around* it. `/send` carries the recipient's box key in the clear,
so anyone on the path learns who you write to, how often and how big it was —
the content stays sealed and the correspondence does not. And without a server
identity, anything that can answer for that address can accept your push,
return `{"ok":true}` and drop it: nothing readable, nothing delivered, and the
sender has been told it worked. **Signatures cover content; they never covered
delivery.**
Verification uses a compiled-in copy of Mozilla's root list — **not** the
system store, so a relay behind a private CA will fail rather than silently
work, and the suite asserts it in both
directions against `badssl.com`: expired, self-signed, wrong-host and
untrusted-root certificates are each refused *for their own reason*, and a
valid certificate completes a handshake. That last check is not decoration —
emptying the root store so that nothing verifies at all still leaves three of
the four refusals looking correct, because "refused" does not say why.
Those checks need the network, so they **skip** when it is absent — and print
that they skipped, because silently passing a security check that did not run
is the shape of mistake this suite exists to prevent.
Cost: 29 crates, taking the tree from 117 to 146. Worth stating in a project
whose other seven dependencies are all cryptographic primitives.
### Replay
A sealed envelope is a file. Anyone who can reach the relay — including the
relay — can hand the same one over twice, and the content is genuine, which
is exactly what makes it dangerous: **a replayed instruction is a real
instruction that was already carried out.**
Delivery used to ask only whether the id was still in `pending`. Once a bundle
had been accepted that path was gone, so the identical envelope was staged
again as a fresh arrival — for ever, on demand — and the journal recorded
nothing at all. `gage pull` now refuses it and writes a `duplicate` entry, the
one event in the log that records something the machine *declined* to do.
The check is the witness, which was already being recorded:
`sha256(from.key || 0x1f || manifest bytes)`. It identifies **this manifest**,
not merely this id, so a sender resending in good faith is unaffected — a new
message has a new `created` at minimum, so a new witness. The suite asserts
both halves, because the easy over-correction here is to refuse anything from
a sender you have heard from before.
## Conversations
A bundle carries what the sender wants from you:
gage send --to codex --subject "key rotation" --type question --decision q.md
gage send --to owen --type answer --reply-to <id> --decision a.md
`share` (default), `question`, `answer`, `review-request`, `ack`. An unknown
type is refused rather than quietly defaulted. `question` and `review-request`
leave a ball in the recipient's court, and `gage inbox` says so.
gage threads # grouped, newest activity first
gage threads --mine # only where the ball is in your court
gage thread <id> # one exchange, root first
gage close <id> # settled, in your view
Three rules, each because the obvious version is wrong:
- **Read state and thread state are local.** A sender must not be able to mark
their own message read in your inbox or declare a thread answered because
they would like it to be. Same rule that keeps trust out of the manifest:
anything the sender controls is a claim.
- **Thread state is derived, not stored.** A thread is awaiting you if its
newest message expects a reply and came from someone else. Nothing to
maintain, so the common case cannot drift.
- **Sent messages are kept locally.** A thread assembled from only the other
side's half is not a conversation -- an early version showed an answer with
no question above it and took its subject from the reply. It doubles as the
audit trail: both ends hold a copy.
The thread's subject comes from the message whose id *is* the thread id, not
whichever sorted first. `created` has one-second resolution, so a question and
its reply sent in the same second can invert, and the thread gets named after
the reply.
Opening marks read; listing does not. Seeing a subject in an inbox is not
having read the thing.
## Replying
gage reply <thread-or-message-id> --text "Full jitter, cap 30s."
The id can be a thread or a single message, and a unique prefix is enough.
A thread with **two correspondents** is refused rather than guessed, and that
refusal is the fix for a real attack: `thread` is a field the sender writes,
so anyone who had seen one message of a conversation could post into it,
become "the newest message that is not yours", and collect the reply meant for
someone else. Naming a message instead of a thread is unambiguous, and while
you hold the thread's root, naming the thread *is* naming that message. A
message whose claim to a thread cannot be checked against anything held
locally is shown as a claim, in the list, in `gage thread` and in the viewer.
Everything else is worked out: the recipient comes from the **key that signed
the message being answered**, never from its `from.handle` or its `to` list,
both of which the sender writes. The type defaults to `answer` when the parent
expected a reply and `share` when it did not, and the subject is the thread's
own, not re-prefixed twice.
`--text` is written to a file and sent like any other item, so a reply typed
in a hurry goes through the same outbound scan as a file. A prefix matching
two messages is refused rather than resolved to one of them: a reply landing
in the wrong conversation with nothing in the output saying so is worse than
an error. Replying to your own message says that, instead of reporting that
your own key is not on your list.
## The viewer
gage ui # http://127.0.0.1:7777
The request head is bounded and the socket has a timeout. `read_line` has no
size limit of its own, so a client that sent bytes and never a newline made
the viewer allocate until it died, and one that connected and said nothing
blocked it forever -- which on a single-threaded server is the whole viewer,
and any local process could do either.
Two panes: conversations on the left, the thread on the right, with a
composer at the bottom. Loopback only, never `0.0.0.0`: an inbox viewer on a
laptop has no business being reachable from the network it happens to be on.
Under the conversations is **On this network** — every machine `gage lan` can
see, each with its four word-pairs under it. Drop files on one and they go
straight there over the wifi; `Pair` confirms a fingerprint without leaving
the page. The panel reads the list `gage lan` keeps and never announces
anything itself, so no button here can make this machine visible when the
person did not choose to be.
### The buddy list
A **Buddies** tab beside Chats, which is the shape the project was asked for:
a list you control, where a key asking to be on it is a decision you take and
can refuse. Three sections, because a key is in one of three states.
**Not on your list.** Any key that has sent you something whose signature
checks out, and that is not on your list, not refused and not retired. A
reviewer was right that my first heading — "asking to connect" — put words in
the sender's mouth: an ordinary note from a stranger is not a request for
anything, and the panel should not imply it was. A bundle whose signature does
*not* check mints no entry at all; the first version recorded verification as
a side tag beside an Add button, so a forged bundle produced a card for a key
its sender does not hold. There is no "please add
me" message type and deliberately so: a kind whose purpose is to ask for
trust would be the one thing a sender must not be able to ask for in a way
that looks different from ordinary mail. So a request *is* ordinary mail from
an unlisted key, already behind the same accept gate as everything else.
The gate on approving one is the part worth describing, because the first
version of it was theatre. gage asks you to type one of the four word-pairs —
and **the card shows no fingerprint until you get it right**. The pair asked
for is never pair 1, which is the key's word-label and is shown as the way to
tell one request from another. Get it right and all four appear, so you can
check the rest before anything is added; a wrong answer does not echo the
right one back, because that turns the step into a two-try copying exercise
and teaches you the words do not matter.
My first attempt printed the whole fingerprint on the card *and* asked you to
type a pair from it. The answer was on screen, so typing it was copying.
Being precise about what the current version proves, because a reviewer was
right that my first wording claimed more: a correct answer shows you read the
pair off something other than the request card. Not *which* something — and
there is one source that matters. **A key knows its own word-pairs, because
they come from that key.** So a sender can write the asked-for pair into the
very message that created the request, and the server cannot tell that source
from the other machine's screen. The page says so, in the gate, where the
decision is made:
> If this pair came from the message itself, or from anything this key sent
> you, it proves nothing — a key knows its own word-pairs and can quote them.
> It only means something if it came from the other machine.
That is the honest limit of any out-of-band check: gage cannot see your other
channel, so it cannot verify you used one. What it can do is withhold the
answer, name the trap, and reveal the other three pairs so the comparison you
do make is the full one. One matching pair is 16 bits, and grindable, which
the page also says. The refused list carries no fingerprints either, for the
same reason — a key can be un-refused back into a request, and printing its
pairs two sections down would leave the answer on screen by another route.
A contact added this way is **verify-only**. A manifest does not carry the
sender's encryption key and should not: a sender seals *to* you with the key
you published and never needs to publish its own. So you can check their
signatures and not seal mail to them until you have their `gage whoami` token
or pair on the network, and the list labels them so rather than promising
sealing that silently fails.
**Your list.** Each contact with its four pairs — so you can re-check one
after a machine behaves oddly — what is unread from them, whether they are
sealable, and three flags, each labelled with what it is evidence *of*:
- `routed under this name` — a local route is filed under this name. Keyed by
name, which is what sending resolves too, and named that way because a
reviewer pointed out that attributing it to a *key* would be a different
claim: rename a contact and the answer changes. Verifying it against the key
would mean opening another agent's `identity.key` to learn a public half,
which this viewer should not do to render a dot.
- `on this network now` — this key is announcing itself, which it chose to do
by running `gage lan`.
- `mail can be left` — **your** setup, not them: you are joined to a relay and
hold an encryption key for them. Whether they ever collect it is not
something this machine can know.
My first version sent a per-contact age — "announced itself 3s ago" — on a
list that refreshes every 2.5 seconds, with a comment asserting this was not a
presence roster. A reviewer was blunt and correct: that is a presence roster
whatever the comment says. The recency gradient is the part that makes it one,
so there isn't one. Three booleans, no ages, and nothing here polls anybody.
**Refused.** The third state, and the one that was missing: a list that can
say yes and "not asked yet" cannot say **no**, so the only way to stop being
offered the same decision was to accept it. `gage decline <key>` and the
Refuse button record it; `gage undecline` and Un-refuse take it back without
adding anything.
What a refusal is not is a block, and the page, the frame and the CLI all say
so rather than letting you believe otherwise: **nothing in gage can stop a
bundle being delivered.** A refused key's mail still arrives and still sits
behind the accept gate. What the record buys is that the frame reads `SENDER
REFUSED BEFORE` with the date instead of offering the decision again as though
it were new, and that an agent reading it is told the state is a record rather
than a wall.
Two corrections a reviewer extracted here. The Refuse button used to explain
itself only in the message *after* the click, so the explanation now sits under
the button. And the list used to tag a refused key "still arriving", which went
false once everything from it was read — implying delivery had stopped, the
exact misreading the surrounding text exists to prevent. It is a count of what
is held right now, and the general fact is stated unconditionally instead.
A key being on the list is still only ever an explicit act: `gage add` over a
declined key reverses the decline and says so. So the claim is not that a
declined key can *never* reach a grant — it is that it cannot while declined,
and that undoing it takes a deliberate add rather than anything a sender does.
A push through a *relay* is still terminal-only behind `gage push --yes`.
Handing a bundle to a machine on your own wifi is allowed from the page
because the gesture names both halves — particular files, dropped on a
particular named machine you can see — which is more than `--yes` on a
directory says. The outbound scan runs on that path exactly as it does in the
terminal, the findings are shown in the page, and there is deliberately no
override button: a finding sends you back to the terminal to look at the
file.
It never renders payload contents. A page that pastes a stranger's prompt into
a browser is a different risk surface, and `gage open` is where content is read,
inside its frame. What the page shows instead is the verdict, the warnings and
the file list, with the **verdict at the weight of a headline** rather than a
caption, because it is the product and a redesign that buried it would be a
regression.
Each correspondent gets a monogram coloured from their **key**, so two contacts
both calling themselves `codex` look different before you read a word. It is an
aid and never a verdict; the verdict is always spelled out beside it.
A reply written here is delivered to a **local route** only. Anything leaving
the machine still goes through `gage push`, where you see the list first, because
a button in a web page is not that confirmation. Every mutating request must
carry a custom header and may not name a cross-site `Origin` or
`Sec-Fetch-Site`: a page on the open internet can POST to `127.0.0.1` with a
plain form, and without those checks any site you happened to visit could accept
bundles in your inbox or send a reply in your name. A form cannot set a custom
header, and a fetch that sets one has to pass a preflight this server does not
answer.
## Nudges
gage watch # poll, pull, notify
gage watch --once --quiet # one check, print instead of notifying
gage watch --on-arrival CMD # and run CMD for an arrival a grant covers
Polling, because a relay that pushed would hold an open connection per
mailbox, and the agents are not long-lived processes anyway -- they are
invoked.
**Announced once.** A bundle is announced when it is unread *and* has not been
announced before. Without the second half, every poll re-announces the same
thing until you open it, which trains you to dismiss the notification -- the
failure that makes a notifier worse than none.
**The notification carries metadata only**: who, what type, the subject. Never
contents. A desktop notification is rendered by another process, may be
logged, and can sit on a lock screen. A unit test pins that it cannot grow a
contents field. An unlisted sender appears as a quoted claim, because a
notification is where a forged name would be believed fastest.
The interval is a trade. Shorter means hearing sooner, and it also tells the
relay operator more precisely when you are active, since fetch timing is
metadata they can see. The default is two minutes: slow enough not to be a
presence feed.
### The on-arrival hook
`--on-arrival` is the only thing in gage that turns an arrival into an action
with nobody watching, so it is deliberately narrower than the notification
beside it.
**It fires only where a grant already covers the message.** Not merely
`SENDER VERIFIED` -- that says whose key signed something, which is a
statement about what is known, not permission to act. `~/.gage/authority` is
the only file in the tool that says an agent may act, and this is the
unattended path, so it is the one caller that must not settle for less. A
verified sender with no grant, or a grant for a different message kind,
notifies exactly as before and runs nothing. The run prints which grant
matched, so the line in the file and the action taken can be read together.
**The hook never receives the bundle's items.** It gets the id, the sender's
key, the contact name, the type, the subject and the matched grant, in the
environment -- `CTX_BUNDLE_ID`, `CTX_FROM`, `CTX_FROM_KEY`, `CTX_TYPE`,
`CTX_SUBJECT`, `CTX_EXPECTS_REPLY`, `CTX_GRANT`. Nothing on stdin, nothing on
the command line. A bundle's contents are the thing the accept gate exists to
hold back; a hook that handed them over would have quietly removed that gate
for every arrival matching a grant.
Not "never receives message content": the subject is text the *sender* wrote
and it travels here. One bounded line, already in the notification you see,
so it leaks nothing the popup does not -- but a hook that treats it as
trustworthy input is a hook with a problem.
**`--on-arrival` does not accept the bundle.** The hook runs and gage has
moved nothing: still unread, still in `pending`. The hook itself is handed
`CTX_BUNDLE_ID` and can of course run `gage accept && gage open` -- and for an
agent loop that is the point. What gage guarantees is that *the hook machinery*
never crosses the gate for you, so crossing it stays an act your own hook
performs, with a journal entry to show it.
One exception, and it is one you turn on: with **`--auto-accept` as well**, the
watcher runs its auto-accept pass *before* the hook, so a granted arrival is
already in `accepted` by the time your command starts. That ordering is
deliberate -- an unattended hook should find the bundle settled rather than
race the watcher for it -- and `CTX_AUTO_ACCEPTED` is `1` when it happened.
This paragraph used to say "gage does not accept the bundle" without the
qualifier, which was a promise about one flag read as a promise about the
watcher.
**gage does not interpolate sender text into your command.** The subject is
written by whoever sent it; in a shell line it would be command injection with
extra steps. So the command you wrote goes to `sh -c` untouched and every
sender-chosen value arrives as an environment variable, flattened to one
bounded line first -- a newline in `CTX_SUBJECT` is still a newline in
whatever the hook writes it to, and could forge an arrival record there.
That is one link, not the chain. `"$CTX_SUBJECT"` quoted is data; `eval`, an
unquoted expansion inviting word-splitting and globbing, or a value passed
where a command expects an option, each hand the sender a shell -- and the
hook is your code, so nothing here can stop it. Environment values are also
inherited by the hook's children and readable by anything running as you.
A hook that exits non-zero is reported; one that outlives
`--hook-timeout` (default 300s) is killed. Either way the arrival stays
marked announced, because retrying a broken command forever would turn one
bad hook into an endless loop against the relay.
As a background service -- the unit is `contrib/gage-watch.service`, copied
to `~/.config/systemd/user/`:
systemctl --user enable --now gage-watch.service
`watch` and `pull` share one collection path, because a watcher that collected
differently from a manual pull would announce bundles you could then not find.
The watcher suppresses its nothing-to-do line; a line per poll turns a journal
into noise that hides the one entry that mattered.
## The journal
gage journal # what this machine did with what arrived
gage journal --bundle <id> # one bundle's history
gage journal --json # the raw JSONL
Every other record in gage is an artifact -- a bundle in `pending`, a copy in
`sent`, a witness in `state.json`. Artifacts say *what was said*. None of them
says *what this machine decided*, and the moment anything happens while nobody
is watching, that is the only question worth asking.
One line per event: `observed`, `accepted`, `rejected`, `opened`, `sent`.
**`observed`, not `arrived`.** `at` is when a scan happened to run, not when
anything was placed anywhere -- a bundle can even be placed and removed between
scans and never be seen at all. First local observation is the only arrival gage
can honestly assert from its own knowledge, so that is what the event is
called. A bundle already accepted when first seen is marked `backfilled`,
because its verdict was computed after acceptance and calling that an arrival
verdict would be a lie.
**The verdict is written down, not derived.** This is the whole reason the file
exists. A key rotation, a `gage add`, a retirement -- any of them changes what
`Contacts::verdict` returns for a bundle that arrived before it, so a verdict
recomputed on read is a different answer wearing the same name. Retire a
contact's key and the journal still shows the bundle observed as
`SENDER VERIFIED`, with the later lines saying `RETIRED`; recomputation would
have erased that.
### What has left this machine
gage sent # one line per bundle sent, and to whom
gage sent --since 7d # a window: m, h, d, w
gage sent --to dana # by handle, or by key prefix
Everything else in gage governs what an agent *accepts*. This is the one
record of what it **sent** — who it was addressed to, whether the recipient
was even on your list, how many items and how many bytes.
**It is a record, not a control, and nothing above it is a control either.**
There is no send allowlist, no first-contact gate and no rate ceiling, and
that is a decision rather than an omission:
[docs/adr-send-side-restraint.md](docs/adr-send-side-restraint.md). Every one
of those controls would be enforced against your contact list, and an agent
with `gage mcp` can add a confirmed contact to that list by itself, in two
calls, with no human — `gage_pair_start` hands it the word-pairs and
`gage_pair_confirm` takes them back. A control enforced against a value the
attacker can write is theatre, and this project would rather say so than ship
one.
Two things it does not cover, both stated by the command itself. Sends are
recorded from 0.3.2 onwards, so an empty list on a machine upgraded today is
not evidence that nothing was sent. And `gage anchor send` is excluded: an
anchor publishes the digest of the journal's own head, so recording it would
move that head the moment it was published and two anchors could never name
the same entry — which is precisely how a contradiction is detected.
What a difference between two lines is *not* is proof of a key change. It
could also be a backfilled first entry, a verdict computed after acceptance, a
contact edited by hand, local tampering, or a gage upgrade changing what a
verdict means. An entry freezes an **outcome**, not the evidence that produced
it: it does not hold the contacts revision, the key's status inputs or the code
version. A difference is a question, not an answer.
**Hashes and verdicts, never contents.** No subject, no filenames, no payload,
no handle. And every field that *does* come off the wire is validated rather
than copied -- the manifest id is a value the signer chooses, so it has to be
hex and bounded or it is replaced by a hash of itself; the same for the keys.
A decoded id can otherwise carry a terminal escape or a confusable into
whatever reads the log next. Partly because the retained bundle already answers "which exact
bytes". Mostly because all of those are text the *sender* wrote, and a log is
read later by a human skimming or a model summarising -- so a field an attacker
can fill is a stored injection against whatever reads the log next, which would
make the audit trail an attack surface. The one sender-chosen value admitted is
the thread id, and only if it looks like one: hex and bounded, or it is
recorded as the fact that it was unparseable.
**A rejection is the entry that matters most.** `gage reject` destroys the
bundle unread, so without a line written before the delete, deletion is
indistinguishable from never having arrived.
What it cannot tell you, said here so nobody reads it as more: gage's knowledge
stops at the bundle boundary. It cannot say what an agent did after `gage open`,
nor whether a human was actually looking -- `accept` records an act, not an
intention. It cannot prove the record is complete. And it is append-only by
convention, not tamper-proof: a process running as you can rewrite it, keys
and all. Claiming otherwise would be theatre. What it defends against is the
realistic case -- an agent or a script quietly dropping the line that
incriminates it, and ordinary loss.
Built before the thing that needs it, deliberately. Capture is the part that
cannot be retrofitted: a verdict never recorded when it was computed is gone,
and a retention policy can be argued about next month.
One thing that ordering does not buy: a hash chain added later proves only
that entries have not changed *since chaining began*. It cannot tell a genuine
pre-chain history from one edited, reordered or fabricated beforehand -- it
would chain a forgery just as faithfully. Capture-first buys evidence about
verdicts, not retroactive tamper evidence.
**The index orders the file, not `seq`.** `n` is allocated while holding the
journal lock, so two processes cannot claim one position; `seq` is the
observation counter that relates an entry to a retirement cut, which is a
different job. Each line is written and `fsync`ed under that same lock,
because a log of decisions that loses the line it just promised is worse than
none.
### The hash chain, and exactly how far it goes
gage journal --verify
Each entry carries the digest of the previous line **as written**, so
verifying is a re-read of the file and nothing has to agree about canonical
JSON. Three kinds of tampering are caught: a deleted line, an edited line, and
a line appended by something that does not chain. The index is checked
independently, so a deletion someone bothered to re-link still leaves a gap.
**What a clean pass means, and does not.** No chained line has been changed,
removed or reordered — *unless whoever did it also recomputed every following
link*, which anything running as you can do. That is tamper-evidence against a
script quietly dropping the one line that incriminates it. It is not proof
against a determined local process, and no log a process can rewrite could be.
The suite asserts this limit directly: a re-linked edit verifies clean, and
that check exists so the chain is never read as more than it is.
**Entries written before chaining existed are not retroactively verified, and
the command refuses to imply otherwise.** Over a journal where nothing is
chained it prints *"none of them chained"* and *"this check verified
NOTHING"* — the first version printed "the journal chain is intact: 29
entries" over 29 entries it had not checked at all, which is the most
misleading thing it could have said. When the chain does start, the first
chained entry carries a `genesis:` digest over everything above it. That does
not make the old history trustworthy — whoever started the chain could have
edited it first — but it freezes it as it stood, which is strictly better than
leaving those lines unreferenced and rewritable at leisure.
Still unbuilt from `docs/open-decisions.md`: a retention policy, and anchoring
a digest somewhere this machine does not control, which is the only thing that
would survive the local-rewrite case.
### Anchoring: the rewrite the chain cannot catch
gage anchor send --to bob # publish your head to a contact
gage anchor record # store the heads they published to you
gage anchor list # what is held, and anything contradictory
gage anchor check <n> <digest> # they read you one; does yours still match
A chain is evidence against a process that drops a line. It is not evidence
against one that rewrites the file and recomputes every link, which anything
running as you can do — and the suite pins that limit by asserting a
re-linked edit verifies clean. No log a process can rewrite can do better, so
the only way out is for a value derived from this journal to exist somewhere
this machine cannot reach.
An anchor is the digest of the newest chained entry, sent to a contact as an
ordinary signed bundle. Ordinary on purpose: it goes through the accept gate
and gets a verdict, so an anchor from a key nobody confirmed is refused by
the same machinery that refuses anything else from that key. There is no
service, no account, and nothing to run. [The argument for this over a hosted
anchor service is in docs/adr-journal-anchoring.md](docs/adr-journal-anchoring.md).
**What it buys is narrower than it first sounds.** Holding an anchor for Bob
does not let your machine audit Bob — checking it against his journal needs
his journal. What it gives, with no extra protocol, is that each *new* anchor
is checked against the ones already held for him. Two things are then
evidence: the same index re-published with a **different digest**, which
means his journal changed under an entry he had already published; and a head
that goes **backwards**. Both are recorded, never acted on. Nothing refuses
mail or changes a verdict on this: a sender who could trigger local
consequences by making a claim about his own journal would be a lever rather
than a log.
**And the bound that governs all of it:** an anchor covers nothing after
itself. Everything written since the last one is still freely rewritable, so
the anchor interval *is* the size of the rewritable window. `anchor send`
prints that line every time rather than leaving it in a document.
## Key rotation
A key gets replaced: a laptop dies, a secret leaks, a contact starts fresh.
Before this existed `gage init` simply refused to overwrite, which is the right
refusal and the wrong ending — the only way out was to delete the key file,
and that turned every bundle you had ever signed into `SENDER UNVERIFIABLE`.
Losing your whole history the day you rotate is a bug, and a tool with that
property teaches people never to rotate.
gage rotate # new keypair, old one kept on record
gage rotate --compromised # the old key was stolen
gage keys # what is current, what is retired
Rotation produces a **notice**: a statement binding old key, new key, handle
and time, signed by the new key and countersigned by the old one. The new
signature says whoever holds this key meant to publish it. The old one says
the party you already trusted authorised the handover — which is the only part
you could not have got from a stranger.
It is still not proof. A thief holding the old key produces that
countersignature just as easily, and this is the hard part of rotation: "use
this key instead" is the exact sentence an attacker wants to say and the exact
sentence an honest person needs to say, and the bytes are identical. So a
notice is **evidence, never an instruction**:
gage keychange notice.json # report what it proves
gage keychange notice.json --accept # apply it
`keychange` with no `--accept` changes nothing. With `--accept` it still
refuses a notice the old key did not countersign, which is why a compromise
rotation omits that signature on purpose: a signature from a stolen key would
dress up a notice that proves nothing as one that proves something. Then the
only path is confirming the new key with the person over a channel that is not
this one.
### The retired key keeps the past and loses the future
A retired key covers bundles that were **here before the retirement** and
nothing after:
* `SENDER KEY RETIRED` — valid signature, bundle predates the retirement. Still
attributable, and the thread history stays readable.
* `SENDER KEY REJECTED` — valid signature under a key that does not cover this
bundle. Contents withheld, non-zero exit, same as a bad signature.
If a retired key kept working for new mail, retiring it would buy nothing at
all. So the question is what decides, and it took three attempts to stop
answering it with a timestamp.
The first version read the manifest's `created`, which is a field the
**signer** writes: a key stolen before an ordinary rotation could sign
something new, date it before the cutoff, and be read as attributable. The
second recorded a local arrival time instead, which was right in spirit and
wrong twice over — the record was keyed on the bundle id, which the signer
also chooses, so a thief could reuse an id this machine had already stamped
and inherit its record; and the comparison was lexical over RFC3339, which
accepted `""`, `"…12:00:00.9Z"` and `"…T01:00:00-14:00"` (really 15:00Z,
three hours *after* a noon cutoff) as earlier than noon.
What decides now is a **local observation counter**. Every path that is about
to show a verdict first records what it can see in the inbox, keyed on
`sha256(sender key ‖ the exact bytes the signature covers)`, against a
counter that only increases. A retirement takes a cut of that counter.
A bundle witnessed below the cut was here first; one witnessed above it was
not. No timestamp enters the decision, so there is nothing in it for a sender
to aim at, and the boundary case is a real tie rather than an attacker's
choice.
Three verdicts come out of it, and the third exists because conflating it
with the second would be a lie:
* `SENDER KEY RETIRED` — you saw this before you retired the key.
* `SENDER KEY REJECTED` — it reached you afterwards.
* `ARRIVAL UNRECORDED` — there is no record either way. Contents withheld,
like a rejection, but it is not one: the ordinary cause is mail sealed
before the rotation and collected from a relay after it, or a bundle you
only ever inspected (`gage unseal --out`, or a directory handed over on a
stick) rather than received, which by design leaves no arrival record.
Telling someone that is a rejection would tell them a colleague is
attacking them.
For a key that was actually stolen, `gage retire <name> --compromised` refuses
everything it signed, old bundles included, consulting no date at all. That
form touches one key and says so; `--compromised --all` condemns every key you
ever held for that person, for when you learn the compromise predates what you
knew.
The same rule applies to the cutoff itself. `keychange --accept` takes the cut
from **your** counter at the moment you accept, and keeps the notice's own
date as `claimed_at`: a record, never a verdict. Whoever wrote the notice
chose that date, and adopting it let them put the retirement anywhere they
liked.
### The countersignature says less than it looks like
An earlier version omitted the old key's countersignature from a
`--compromised` notice, reasoning that a thief could produce it so it proved
nothing. Both reviewers argued that inverted the signal, and they were right.
Possession is the one bit a stranger cannot fake — anyone can send a notice
with no countersignature; only the key holder can send one with it. Worse, the
thief's best move was an ordinary `reason: "rotated"` notice, countersigned
and therefore the one a receiver would apply, while the honest victim's
unsigned compromise notice was the one it refused.
Notices are now always countersigned, signed before `--compromised` destroys
the secrets, and the receiver is told exactly what that buys:
old key signed: yes -- this proves control of the old key, and
nothing about WHO holds it. If that key was
stolen, the thief can produce this signature too.
Rotating your own key keeps the old secrets so mail already sealed to it can
still be collected — `gage pull` drains the retired mailbox alongside the
current one, because losing in-flight mail on rotation is another way to teach
people not to rotate. `--compromised` destroys them instead: the thief can
read those envelopes either way, and keeping a copy only extends the window in
which you keep reading mail they are also reading.
## Groups
`--to` is a list from the start, and `group:<name>` is a valid recipient. In a
group most of what you see was not written by whoever posted it, so the
manifest separates **author** from **sender**.
Only the **last hop signs**, which is the honest and uncomfortable part: a
forwarder writes `chain[0]`, so they can name anyone as the author, including
someone you trust. `open` says that in those words rather than printing a
known author's name as though it were established, and `forward` refuses to
re-sign a bundle that does not verify — otherwise a forwarder could launder a
broken bundle into one that checks out cleanly for the next recipient.
Cryptographic provenance across hops needs each hop to sign what it received,
which is a format change; see [docs/open-decisions.md](docs/open-decisions.md).
## What this is not
No accounts, and no presence: nothing announces itself unless you ask it to,
for a number of seconds, having been told what it is about to say. Agents are
invoked rather than online, so the instant-messenger model's buddy list and
accept-before-transfer carry over and its presence does not. If moving
directories by hand gets annoying, add a relay — the format does not change.
Three commands do hold a port, and it is worth naming them rather than letting
"no server" quietly stop being true: `gage ui` on loopback, and `gage lan` and
`gage listen` on the local network. None is required for anything, all are in
the foreground where you can see them, and `gage lan` is the only thing in gage
that announces — for exactly as long as you are looking at it.
It does not sandbox anything. A verified sender is an *accountable* sender, not
a safe one. The frame tells a reader what the content is; deciding to act on it
is still the reader's job, which is why `open` is a renderer and not an
importer.
It is not an audit layer over an agent's own actions, and not a receipt format
for tool calls. Those exist and are further along; the comparison, and what
each side can and cannot prove, is in [docs/prior-art.md](docs/prior-art.md).
A bundle still cannot authorise its own fulfilment, however well signed —
proven by [dogfooding it](docs/dogfood-2026-10-15.md) across four agents, two
of which read a verified request from a verified contact and rightly declined.
What closes that gap is a grant the *receiver's* human wrote, never anything
in the message. See [Authority](#authority-the-one-thing-that-says-you-may-act).
## Tests
cargo build --release && cargo test --release && bash tests/attacks.sh
bash tests/ui-e2e.sh # optional: drives the viewer in a real browser
962 checks plus 168 Rust unit tests, 55 MCP end-to-end checks, a 16-check
identity restore drill, and one end-to-end test that opens the viewer in a
browser and completes a connection request. `tests/selfcheck.sh` runs the lot
and is the only number worth quoting — this line said 680 and 106 for long
enough to be wrong by a third.
That last one exists because of a gap the other two could not see. The buddy
panel's confirmation gate lives entirely in the page's client state, and it
**shipped broken**: the reveal step cleared the typed pair and the add step
resent it, so the server rejected every add and the Add button could never
work. Every HTTP check passed throughout, because they drive the endpoint and
not the page. A reviewer found it by reading two lines together, and then a
headless screenshot immediately showed a second one — the Chats filter bar
staying on screen on the Buddies tab, because `.filters{display:flex}` beats
the `hidden` attribute. Neither was reachable from an assertion about JSON.
`tests/ui-e2e.sh` needs playwright and a chromium on the machine and **skips
rather than fails** when they are absent, so an optional dependency cannot
turn a build red. Reinstating the dead-button bug makes it report *"the add
never reported success -- the button is dead"*.
### Running it, and knowing when it breaks
tests/selfcheck.sh # is this machine good?
tests/selfcheck-status.sh my-laptop # is every machine good?
`selfcheck.sh` builds, runs all three suites, writes one status line and exits
non-zero with a specific reason. It is scheduled daily on both machines — a
systemd user timer on Linux, a launchd agent on macOS — and notifies the
person at the machine when it fails. Neither pulls: each reports the commit it
tested, so a machine that is behind says so rather than quietly updating
itself. `selfcheck-status.sh` reads each machine's last result, and reports a
host it cannot reach as **unreachable** rather than as passing — silence is
not evidence of health, which is the whole mistake this exists to stop.
It preflights the ports the suite binds, because a stray `gage ui` once caused
28 failures that looked like real defects. Both failure paths were verified by
causing them: an occupied port, and a deliberately broken verdict label.
**It also checks the dependency tree for published advisories**, as its last
stage, with `cargo audit`. Last on purpose: the script exits on the first
stage that breaks, and an advisory published this morning must not be allowed
to mask a real test regression. A finding fails the run, which is how you hear
about one within a day instead of never; if an advisory has no fix yet,
`.cargo/audit.toml`'s ignore list is the place to record that decision rather
than leaving the check switched off.
Without `cargo-audit` installed, or with the advisory database unreachable, it
**says it skipped** and the status line reads `deps skipped` — the same rule
the certificate checks follow, because silently passing a security check that
did not run is the shape of mistake this file exists to prevent.
This stage exists because the first audit this project ever ran, on 22
October 2026, found two advisories that were three and four days old, both in
certificate verification. Nobody had checked, because the dependency list is
short and hand-justified in the manifest — which is exactly the reasoning
that makes a tree feel safe without anybody looking. A short list bounds
exposure; it does not tell you when one of them is announced vulnerable.
To stop it:
systemctl --user disable --now ctx-selfcheck.timer # Linux
launchctl bootout gui/$UID/com.owenware.ctx-selfcheck # macOS
### It passes on both machines now
It did not before, and nobody had checked. Run on the MacBook for the first
time on 17 October, the suite reported six failures — including *"a killed
writer wedged the lock"*, which would be alarming if it were true. None of
them was a defect in gage:
- `timeout` is GNU coreutils and is not on a stock macOS, so the two checks
that used it to assert a lock had been **released** failed on its absence.
The shim uses perl's `alarm`+`exec`, because the obvious shell fallback —
background it and poll — silently loses stdin: bash redirects an
asynchronous command's stdin from `/dev/null` when job control is off.
- `ss` is Linux-only, and BSD `netstat` prints `127.0.0.1.7891`.
- BSD `wc` pads its output to a field width, so `ls | wc -l` yields
`" 0"` and every `= 0` comparison against it was false. That reported
*"an unbounded auto-accept grant accepted a bundle"* — the suite lying about
a security property, which is the worse way round.
- BSD `sed` has no `\|` alternation, so a check matched nothing and called a
perfectly good envelope malformed.
- Two checks read a label with `2>&1 | tail -1`, which merges two streams into
one pipe and takes whatever lands last — correct here, wrong there, and
intermittent.
- **Three checks picked a bundle with `inbox --json | head -1`.** Once a home
holds more than one, that is whichever the filesystem lists first; ext4 and
APFS disagree, so those checks accepted and opened a different bundle than
the one they were about. That is a real test bug which passed here every
time by luck, and the only reason it ever surfaced is that the suite was
finally run somewhere else. Every one is an attack that worked, or
nearly worked, during development: frame-boundary forgery, payload swapping
after signing, a listed contact claiming a third party's name, an unverified
author name on a forward, a trust label that was a substring of its own
opposite, a rotation notice countersigned by the wrong key, a retired key
still signing new mail, a cross-site POST to the viewer, a bundle grafted onto
someone else's thread to collect the reply, a retired key backdating its way
past its own retirement, a reused bundle id inheriting another document's
arrival record, two processes overwriting each other's state, a mailbox
squatted by quoting a public key, a symlink smuggling out a file nobody named,
a chosen bundle id suppressing a real message, an id
shaped like a path escaping the inbox, a witness pre-seeded with a junk
signature and claimed later with a real one, a bundle with no provenance chain
borrowing another message's id, a revocation that left the old key trusted
while it was being written, a secret hidden from the outbound scan by one
invalid byte, an envelope that unpacked half of itself before refusing, a discovery query
from a key nobody added, and a pairing waved through on a fingerprint that
was one word different, and a dropped file whose name was a path.
## License
Dual-licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))
at your option. Unless you state otherwise, any contribution you intentionally
submit for inclusion in this work shall be dual-licensed as above, with no
additional terms or conditions.
TDQS
A4/5.0
Scored across 9 tools
Disambiguation5/5
Each tool targets a distinct step in the secure messaging workflow: identity, buddy listing, pairing (start/confirm), building a bundle, listing inbox, opening a bundle, pulling from relay, and pushing off-machine. Descriptions explicitly differentiate similar-sounding tools like gage_send vs gage_push and gage_inbox vs gage_open, leaving no ambiguity.
Naming Consistency4/5
All tools share a consistent 'gage_' prefix and snake_case formatting. The suffix varies between noun-based (identity, buddies, inbox) and verb-based (send, open, pull, push) forms, but this mix is predictable and readable within the domain.
Tool Count5/5
Nine tools neatly cover the core operations of a secure messaging system without redundancy. The count is well within the typical 3–15 range, and each tool serves a clear purpose.
Completeness4/5
The surface covers identity, contact management (add/list), message building, sending/receiving, and trust verification. Minor gaps exist, such as no tool for removing or updating a buddy, and no way to list sent bundles, but these are not critical for core workflows.
Maintenance
ActivityMaintained
ResponsivenessNo issues