Module peer_handoff 

Peer file handoff: runtime-minted handles over a two-sided grant.

A capsule that declares exports.peer_files can hand one named file to one named peer without a filesystem path ever crossing the wire. The runtime mints an opaque handle — a MAC’d token naming exactly one file, for one audience, with an expiry — and the agent puts that handle in an ordinary A2A message. A capsule that declares capabilities.peer_fetch can redeem such a handle against the minter’s /resources/peer/<handle> endpoint and lands the bytes as a file in its own workdir.

The same three-way split the operator plane rests on, with the audience added:

• The agent owns what a file contains, and chooses which file to offer and to whom.
• The runtime owns whether it may. It is the minting authority, so an agent cannot forge a handle for a file the operator did not put under exports.peer_files.root, and cannot widen its own envelope by naming a path — the path is resolved here, by the same code that resolves a read.
• The operator on the other side owns whether the bytes may be ingested at all, through capabilities.peer_fetch.allow. Neither half implies the other and both default to deny.

The minting key is instance-scoped. 32 bytes from the OS at launch, held only in memory, zeroed on drop. When the session ends every outstanding handle becomes unverifiable at once — revoke-all with no revocation list, and the reason a handle minted by one session of a capsule does not redeem against the next.

A handle authorises a file, not a version of one. There is no generation in the payload and no 409 on this plane: a redeem always serves the file’s current bytes, so a file rewritten two turns later simply serves the newer content and the etag is how the holder notices. Pinning would mean either failing an ordinary content update or retaining superseded bytes, and nothing else in the runtime does either.

Redeem is idempotent, not single-use. No used-set, no per-handle server state. Single-use exists to bound a credential’s blast radius over time, and the instance-scoped key plus the capsule’s own lifetime already do that structurally; making a retried transfer a lost file buys nothing on top.

Structs

HandlePayload

A handle’s payload, carried in the clear in the token’s middle segment.

MintedHandle

One minted handle, as share-file returns it.

PeerPlane

Everything a mint or a redeem needs, and nothing a running task leaves behind.

Enums

HandleError

Why a token was not accepted.

PeerError

Every way a redeem can be refused, in the vocabulary the caller and the trace share.

Constants

AUDIENCE_HEADER

Request header carrying the audience the caller asserts it is. Required on every redeem.

HANDLE_ID_HEADER

Response header naming the handle a served body was redeemed with.

PEER_INBOX_DIR

Directory, relative to the accessible workdir, that fetched bytes land in.

PEER_PATH_PREFIX

Path prefix the peer plane answers under, alongside the operator plane’s /resources/files/. GET-only, and with no listing verb at any depth.

Functions

audience_from_card

The audience string derived from a peer’s own agent card: <name>@<host:port>, lowercased, where host:port is the url of the card’s JSONRPC interface with its scheme and path stripped.

decode_payload_unverified

The payload of a token this runtime did not mint and cannot verify.

handle_id

The stable identifier a mint, a redeem and a fetch are correlated by.

handle_peer_request

Answers one peer-plane request: a method, a raw request path, an asserted audience, and nothing else.

is_peer_path

Whether raw_path addresses the peer plane rather than the operator plane.

mint

Mints one token: mh1.<base64url-nopad(payload JSON)>.<base64url-nopad(mac)>.

stored_path_for

The workdir-relative path fetched bytes land at: peer-in/<handle_id>-<sanitised basename>.

verify

Verifies one token against this instance’s key and the audience the caller asserted.

Type Aliases

PeerMintKey

The key one capsule instance mints and verifies handles with.