# Cross-Agent Handoff Attestor

**Signed, independently verifiable delegation between agents: scope can only narrow, lifetimes
can only shrink, and a handoff can only be used once.**

MIT licensed · zero runtime dependencies · MCP stdio server · TypeScript

## The security problem

In a multi-agent system, one agent hands work to another. The receiver usually has no way to
check whether the delegation was real, whether the scope was narrowed rather than quietly
widened, whether the handoff is still in force, or whether the same handoff has already been
consumed. Authority spreads by assertion, and a compromised or prompt-injected agent can grant
itself more than it was ever given.

## What this product does

It issues signed handoff attestations and verifies them independently of the issuer's goodwill.
Each attestation records issuer, subject, task, scope, optional constraints, lifetime, chain
depth, parent digest and a nonce. Verification walks the presented ancestor chain, checks parent
digests and depth linkage, and refuses anything that widens authority.

### Major capabilities

- **Scope narrowing only.** A child's capabilities and resource patterns must be contained in
  the parent's. Resource patterns are compared exactly: a literal string, or a single trailing
  `*`. No path normalisation, no separator collapsing, no percent-decoding. Dropping a parent
  restriction is a widening and is refused at issuance.
- **Constraint compatibility.** Constraints carry an explicit comparator (`equal`,
  `max-number`, `min-number`, `subset`, `boolean-require`). A comparator or value type that
  cannot be evaluated reports `unknown`, never a silent pass.
- **Lifetime containment.** A child may never begin before, or end after, its parent.
- **Replay protection.** A nonce is single-use per subject through a pluggable replay store.
- **Chain continuity.** Maximum chain depth 64, root depth 0; broken depth linkage or a
  mismatched parent digest is invalid.
- **Honest `unknown`.** A missing replay store or an unresolvable parent digest yields
  `unknown` checks and an invalid overall result — never a pass by omission.
- **Payload-free receipts.** `attestationReceipt` records digests, source ids and a report
  digest, with no task text and no scope contents.
- **Pluggable identity.** Signing is supplied by the host through a `KeyAdapter`; a development
  adapter is included. This package holds and ships no credentials.

## Install and run

Prerequisites: [Bun](https://bun.sh) 1.1+ (or Node 22+ with a TypeScript loader). No runtime
dependencies to install.

```bash
git clone https://github.com/SweetKenneth/shpbl-handoff-attestor.git
cd shpbl-handoff-attestor
bun install                    # dev types only
bun test                       # conformance suite
bun run scripts/symbol-scan.ts # build-failing forbidden-symbol scan
bun src/mcp-server.ts          # MCP server: newline-delimited JSON-RPC 2.0 on stdin/stdout
```

### MCP configuration

```json
{
  "mcpServers": {
    "handoff-attestor": {
      "command": "bun",
      "args": ["/absolute/path/to/shpbl-handoff-attestor/src/mcp-server.ts"]
    }
  }
}
```

### Tool surface

| Tool | Purpose |
|---|---|
| `issue_handoff` | issue a signed attestation, refusing any widening at issuance |
| `verify_handoff` | verify signature, scope, constraints, lifetime, replay and chain continuity |
| `check_scope` | inspect containment between two scopes without issuing anything |
| `describe_keys` | report the active key adapter and its published algorithm |

### Worked example

`examples/scope-narrowing-chain.ts` issues a root handoff, narrows it twice, verifies the full
chain, then shows a widening attempt refused at issuance and a replayed nonce refused at
verification.

```bash
bun examples/scope-narrowing-chain.ts
```

## Verification results

71 conformance tests, 127 assertions: specification properties including exact resource-pattern
containment (P11), every §7 failure mode, scope-containment matrix, depth boundary at 64/65, and
the MCP JSON-RPC surface. Forbidden-symbol scan covers 9 source files with 0 findings. Strict
typecheck is clean. Runtime dependencies: **zero**.

## Security boundaries

- No network access, no ambient filesystem writes, no process execution.
- No credentials are stored or shipped; keys come from the host adapter.
- Resource-pattern comparison is deliberately literal, so containment cannot be widened through
  encoding tricks.
- Verification result is a report, not enforcement: the calling runtime decides what to do.

See `SECURITY.md` for the full threat model.

## Known limitations

- The attestor verifies *delegation*, not behaviour. A correctly delegated agent can still
  misuse the authority it legitimately holds.
- Replay protection is only as strong as the replay store the host supplies. With no store,
  replay is reported `unknown` and the overall result is invalid — by design, but that means an
  operator who ignores `unknown` gains no replay protection.
- Unicode resource patterns are compared by code point, without normalisation. Two visually
  identical patterns in different normal forms are different patterns.

## Provenance

Discovered with SHPBL. This product originated through cross-capability composition in the
SHPBL capability library. Its public implementation was independently built from a published
behavioural specification. SHPBL's proprietary capability library, discovery system, harvested
implementation bodies, and private provenance machinery are not included.

- Public behavioural specification: <https://github.com/SweetKenneth/shpbl-spec-handoff-attestor>
  (a copy ships here as `SPEC-cross-agent-handoff-attestor.md`)
- SHPBL: <https://shpbl.com>
- Details: `PROVENANCE.md`

## Tenable status

Submitted to the [Tenable CyberAgents Exchange for review on September 11, 2026](https://github.com/tenable/cyberagents-exchange/pull/166).
Submission does not imply review, approval, certification, validation, endorsement, or acceptance by Tenable.

## SHPBL Agent Evidence series

Independently installable, interoperable at the evidence-record boundary:

- [shpbl-action-ledger](https://github.com/SweetKenneth/shpbl-action-ledger) — agent action evidence ledger
- [shpbl-handoff-attestor](https://github.com/SweetKenneth/shpbl-handoff-attestor) — cross-agent handoff attestation
- [shpbl-drift-sentinel](https://github.com/SweetKenneth/shpbl-drift-sentinel) — agent behaviour drift detection
- [shpbl-retrieval-auditor](https://github.com/SweetKenneth/shpbl-retrieval-auditor) — retrieval context provenance
- [shpbl-canary-chain](https://github.com/SweetKenneth/shpbl-canary-chain) — synthetic canary evidence chain

## Licence

MIT — Copyright (c) 2026 Kenneth E. Sweet Jr. See `LICENSE`.