guest-events: events under a receipt
- after the receipt (market.md), the bidder, the requester and the guest talk only through
market.eventrecords and two guest HTTP paths - steps: S7 boot and vm events, S8 guest events and atirc, S9 release
- one row per lexicon: lexicons-market.md
- constants:
internal/atproto/market/nsid.go,internal/atproto/market/guest.go; guest side:internal/guestagent(binarycmd/socialweb-guest-agent); guest HTTP plane:internal/services/guestcontrolplane,internal/guestidentity - names drop the prefix
com.publicdomainrelay.temp.(guest.publicKey=com.publicdomainrelay.temp.compute.events.guest.publicKey)
The Envelope
- every event is two signed records in the sender's repo: the payload (
compute.events.vm.*orcompute.events.guest.*) andmarket.event {receipt, payload, createdAt, signatures} receipt= strongRef to the bidder'smarket.receipt;payload= strongRef to the payload record in the same repo as the event- the receiver reads the payload through the strongRef, checks its CID, its author and both signatures (
applyGuestEventininternal/market/bidder/guestevents.go) - delivery:
market.submitEventto the other party, and the relay / Jetstream streams as fallback (market.md) - the guest holds no repo key. the bidder signs and writes every guest-originated event in its own repo
Who Sends What
| payload | originator | written in | consumer | file of the consumer |
|---|---|---|---|---|
vm.onNetwork | guest (iroh ticket and https tunnel URL from /usr/local/bin/send-onnetwork.sh of guest-onnetwork.service, webrtc fingerprint from the guest agent) or bidder (sandbox) | bidder repo | requester: status.contract.vmAddress, status.contract.networks | internal/market/requester/runner.go waitGuest |
vm.memoryPressure, vm.oomKilled | bidder (the VM unit's cgroup memory.events, polled 15 s, edge-triggered, at most 10 per contract) | bidder repo | requester: one requester_market_event line each | internal/market/bidder/memory.go |
vm.hostKeys | bidder (the host key the guest bound at its workload identity login) | bidder repo | requester: status.contract.hostKeys | same |
vm.sandbox | bidder (deno sandbox ended) | bidder repo | requester: status.contract.sandbox | internal/market/requester/events.go |
vm.terminated | bidder | bidder repo | requester: Released | internal/market/requester/market.go FindTermination |
vm.delete | requester | requester repo | bidder: release | internal/market/bidder/adapters.go applyRelease |
guest.publicKey | either side | sender repo | the other side | guest: internal/guestagent/subscribe.go; requester: inbound ContractEvent |
guest.signalWebRTC | either side | sender repo | the other side | same |
guest.secrets | requester only | requester repo | guest | internal/guestagent/secrets.go |
guest.secretsRequested | guest only | bidder repo | requester: seals the bundle | internal/market/requester/guestsecrets.go |
guest.secretsApplied | guest only | bidder repo | requester: condition SecretsApplied | internal/market/requester/events.go |
guest.secretsUpdated | requester only | requester repo | guest: fetches the bundle again | internal/guestagent/subscribe.go |
guest.agentStart | requester only | requester repo | guest: systemctl start --no-block atirc-agent.service | internal/guestagent/agentstart.go |
guest.requesterDid | guest only | bidder repo | requester: status.contract.guestRequester | internal/market/requester/association.go |
guest.r2Start | requester only | requester repo | guest: starts socialweb-r2.service | internal/guestagent/association.go |
guest.r2Release | requester only | requester repo | guest: runs socialweb-r2-release.service | same |
guest.r2Released | guest only | bidder repo | requester: status.contract.r2Release | internal/market/requester/guestrequester.go |
guest.memoryPressure, guest.oomKill | guest only | bidder repo | requester: one requester_market_event line each (reportMarketEvent), which the test modules read (steps::market_event: an OOM fails the run, pressure goes to readings.memory) | internal/guestagent/memory.go; cap memoryEventCapped in internal/market/bidder/guestevents.go |
guest.image | guest only | bidder repo | requester: requester_guest_image {marker, expected, ok}; a contract with spec.image releases on a mismatch | internal/guestagent/image.go; one per contract (guestEventSent in internal/market/bidder/guestevents.go) |
- guest-originated set:
market.IsGuestOriginatedEventNSID(publicKey, signalWebRTC, secretsApplied, secretsRequested, requesterDid, r2Released, memoryPressure, oomKill, image). the guest control plane refuses any other kind (guestEventininternal/guestidentity/service.go) - requester-originated set:
market.IsRequesterGuestEventNSID(publicKey, signalWebRTC, secrets, agentStart, secretsUpdated, r2Start, r2Release). the bidder refuses any other kind from a requester (applyGuestEvent) - kinds the requester's submitEvent takes:
isGuestEventNSIDininternal/market/requester/events.go - direction of
publicKeyandsignalWebRTCcomes from the author: requester-authored ones go to the guest, bidder-authored ones carry what the guest said
Guest To Requester
- the POST body:
{acceptUri, acceptCid, record}; the record has$type= the payload NSID and no signature (internal/guestagent/events.go) - the bearer is the
Authorizationheader only (Guest.Eventsininternal/guestidentity/service.go) - answers: 200
{ok, name, guestLogin}; 401AuthenticationRequired/InvalidToken; 400InvalidRequest; 404UnknownGuest/UnknownAccept; 503Unavailable vm.onNetworkis checked against the contract's accept only once the ComputeVM holds it (guestrecord.go); every other kind needs the exact accept and a receipt- the bidder keys:
reportSyncKeyandguestEventSyncKeyininternal/market/bidder/syncs.go; the rkeys: market.md - the bidder never opens a sealed body; it routes by NSID prefix
Requester To Guest
- outbound ContractEvents (
socialweb.computer/v1alpha1, cluster scoped, owned by the ComputeContract): made by the CLI (internal/stack/request/webrtc.go), the browser page, or the requester itself (secrets-<contract>,secrets-updated-<hash>) - published by
publishContractEventininternal/market/requester/contractevents.go; field rules invalidateGuestFieldsthere - inbound ContractEvents (guest
publicKey,signalWebRTC) are namedInboundContractEventName(eventURI)
compute.guest.subscribeEvents
| item | value |
|---|---|
| route | GET /xrpc/com.publicdomainrelay.temp.compute.guest.subscribeEvents on the GuestControlPlane (internal/services/guestcontrolplane/subscribe.go) |
| auth | Authorization: Bearer <workload identity token>; names the ComputeVM (guest.Authenticate) |
| param | cursor: last seq seen. absent = oldest entry kept |
| frame | JSON text {"$type": "...subscribeEvents#event", seq, uri, cid, record}; record.$type is a compute.events.guest.* NSID |
| keepalive | an empty binary frame every 25 s (SubscribeKeepalive) |
| error | FutureCursor: the guest agent resets its cursor to 0 and reconnects (internal/guestagent/subscribe.go) |
| reconnect | backoff 2 s doubling to 30 s |
Each Kind
What the code does with each kind; the fields of each are its lexicon's, included below.
| NSID tail | notes |
|---|---|
vm.onNetwork | kind absent: iroh without tag, https with tag (market.OnNetworkKind). webrtc address = the guest agent DTLS fingerprint sha-256 AB:CD:... |
vm.hostKeys | at most 8 keys, an ed25519 key required (internal/guestidentity/guestrecord.go) |
vm.sandbox | compute.vm.kind: deno only (internal/market/bidder/sandbox.go) |
vm.delete | requester writes released |
vm.terminated | reasons: market.md; request is optional: a deleted_on_request without one is a delete on the bidder |
vm.memoryPressure | the VM unit's cgroup memory.events high or max rose |
vm.oomKilled | its oom_kill rose |
guest.publicKey | one per tag per side; anything sealed for a tag goes to the other side's latest key |
guest.signalWebRTC | plaintext {sdp, replyTo}; non-trickle ICE, one offer, one answer |
guest.secrets | age armored, at most 65536 bytes (MaxGuestSecretsCiphertext); plaintext = the getSecrets JSON array |
guest.secretsRequested | the requester seals only in comms mode Firehose with secretsFallback: Sealed; otherwise it records it and does nothing |
guest.secretsApplied | the guest agent posts it for the sealed path; the requester refuses any other via, and every one when it has an inbound endpoint; a getSecrets fetch is status.secretsFetchedAt |
guest.secretsUpdated | the bundle changed (atirc mint, association ref) |
guest.agentStart | needs spec.agent (contractevents.go) |
guest.requesterDid | did:plc only, never the authority's own DID (market.ValidGuestRequesterDID) |
guest.r2Start | needs spec.association.fromGuest |
guest.r2Release | |
guest.r2Released | |
guest.memoryPressure | every VM whose bidder serves the guest agent (memory.json); edge-triggered: PSI some avg10 >= 10.00% or swap >= 10% in use, re-armed after 5 min under half; one per kind per 10 min, ten memory events per contract (agent and bidder) |
guest.oomKill | one per /proc/vmstat oom_kill rise, same caps |
guest.image | once at agent start, when the file exists; the bidder publishes one per contract |
Fields
com.publicdomainrelay.temp.compute.events.vm.onNetwork record key any
The bidder reports a network address of the VM; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
kind | string | What address is. Absent, it reads as iroh when tag is absent and https when tag is present; the bidder leaves it absent for those two. iroh: address is the VM's iroh ticket. https: tag names the tunnel and address is its https URL. webrtc: tag names the tunnel and address is the guest agent's DTLS certificate fingerprint ("sha-256 AB:CD:..."), which the requester checks against the a=fingerprint of the guest's answer. sandbox: a deno sandbox (compute.vm kind deno) is running, address sandbox://<ComputeVM name>, no tag. knownValues ["iroh","https","webrtc","sandbox"] maxLength 16 |
address | string | The VM's address for kind: the iroh ticket (iroh), the URL of the tagged tunnel (https), the guest agent's DTLS certificate fingerprint "sha-256 AB:CD:..." (webrtc), or sandbox://<ComputeVM name> (sandbox). |
tag | string | Names one of the VM's tunnels (spec.tunnels of the contract); absent, address is the VM's iroh ticket. maxLength 32 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.vm.hostKeys record key any
The bidder reports the VM's SSH host keys; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
keys * | array of #hostKey | |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
also: #hostKey
com.publicdomainrelay.temp.compute.events.vm.sandbox record key any
A deno sandbox reports that its program ended, with its output; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
exitCode * | integer | The program's exit status; -1 when it was stopped at its deadline, killed by a signal, or could not be run. |
timedOut | boolean | The sandbox was stopped at its deadline rather than ending on its own. |
stdout | string | The program's standard output, cut to its first 65536 bytes. maxLength 65536 |
stderr | string | The program's standard error, cut to its last 65536 bytes. maxLength 65536 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.vm.delete record key any
The requester asks the bidder to delete the VM of a contract; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
reason * | string | Why the requester asks for the stop; the requester writes released. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.vm.terminated record key any
The bidder reports that the VM stopped; sent as the payload of a market.event.
record
| field | type | description |
|---|---|---|
reason * | string | Why the VM ended: guest_poweroff, vmm_exited, oom, host_reboot, identity_mismatch or image_refused when the VM was lost; deleted_on_request after a vm.delete or another release; expired when the bidder released it after the requester's contract-scoped association expired; association_ended when that association's contract ended (market.VMTerminatedReasons). knownValues ["guest_poweroff","vmm_exited","oom","host_reboot","identity_mismatch","deleted_on_request","expired","image_refused","association_ended"] |
exitCode | integer | The VMM's exit status; the bidder does not write it today. |
observedAt * | string datetime | When the bidder saw the VM gone; createdAt is the same time. |
request | com.atproto.repo.strongRef | The compute.events.vm.delete that asked for the stop. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.vm.memoryPressure record key any
The bidder reports that the VM's host cgroup crossed a memory threshold (memory.events high or max increased); sent as the payload of a market.event, edge-triggered and capped per contract.
record
| field | type | description |
|---|---|---|
kind * | string | The cgroup threshold crossed: high (reclaim pressure) or max (the hard limit). knownValues ["high","max"] |
threshold * | integer | The cgroup limit crossed, in bytes: memory.high or memory.max of the VM's cgroup (0 when that limit is max). |
observed * | integer | memory.current in bytes when the crossing was seen. |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.vm.oomKilled record key any
The bidder reports that the kernel OOM-killed processes in the VM's host cgroup (memory.events oom_kill increased); sent as the payload of a market.event, one per new kill count, capped per contract.
record
| field | type | description |
|---|---|---|
kills * | integer | OOM kills in the VM's cgroup since the bidder's previous sample (it polls every 15 s); kills while the per-contract cap of 10 reports is reached are not reported later. |
total * | integer | OOM kills in the cgroup's lifetime. |
limit * | integer | memory.max in bytes. |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.publicKey record key any
A party to a contract publishes an encryption public key for one tag; sent as the payload of a market.event. Anything sealed under that tag is sealed to the latest publicKey of the other side. Direction comes from the author: a requester-authored one is forwarded by the bidder to the guest's subscription; a bidder-authored one carries what the guest said.
record
| field | type | description |
|---|---|---|
kind * | string | The key type. age-x25519: key is an age X25519 recipient (age1...). knownValues ["age-x25519"] maxLength 32 |
tag * | string | Names the tunnel of the contract (spec.tunnels) or another purpose the key is for. maxLength 32 |
key * | string | The public key in the text form of kind. maxLength 256 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.signalWebRTC record key any
A sealed WebRTC session description for one tunnel; sent as the payload of a market.event. Non-trickle ICE: the requester offers once with all candidates, the guest answers once. Direction comes from the author: a requester-authored one is forwarded by the bidder to the guest's subscription; a bidder-authored one carries what the guest said. The bidder never opens the ciphertext.
record
| field | type | description |
|---|---|---|
kind * | string | The SDP type of the sealed session description. knownValues ["offer","answer"] maxLength 16 |
tag * | string | Names the webrtc tunnel of the contract (spec.tunnels). maxLength 32 |
ciphertext * | string | The session description, age armored ciphertext. The plaintext is the JSON object {"sdp": <session description>, "replyTo": <age recipient, offers only>}: an offer is sealed to the guest's latest compute.events.guest.publicKey for the tag and names in replyTo the age recipient the answer must be sealed to; an answer is sealed to that replyTo. No record names the key, so a reader opens every signal for the tag with its identity and keeps the ones that open. maxLength 16384 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.secrets record key any
The requester's secrets bundle for the guest, sealed to the guest's latest compute.events.guest.publicKey with tag secrets; sent as the payload of a market.event. Requester-authored only: the bidder forwards it to the guest's subscription and never opens the ciphertext. Only when the firehose is the only way: a requester with an inbound endpoint serves the bundle on its getSecrets route alone, after a workload identity exchange. A requester sends one only when its comms mode is Firehose (no inbound endpoint), its spec.secretsFallback is Sealed and the guest posted a compute.events.guest.secretsRequested.
record
| field | type | description |
|---|---|---|
ciphertext * | string | The bundle, age armored ciphertext. The plaintext is the JSON array the getSecrets route serves: [{"path": <absolute path>, "value": <file content>, "mode": <optional octal file mode, at most 0600>}]. No record names the key it is sealed to; the guest opens every secrets event with its identity and keeps the ones that open. maxLength 65536 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.secretsRequested record key any
The guest asks the requester for its secrets bundle sealed to its compute.events.guest.publicKey with tag secrets, because the requester has no inbound endpoint (comms mode Firehose); sent as the payload of a market.event. Guest-originated only, and only when the requester enabled the sealed fallback; a requester with an inbound endpoint drops it. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.secretsApplied record key any
The guest wrote the files of its secrets bundle; sent as the payload of a market.event. Guest-originated only: the guest posts it to its bidder, which signs and publishes it to the requester.
record
| field | type | description |
|---|---|---|
via * | string | The path that delivered the bundle: sealed (a compute.events.guest.secrets record, for a requester without an inbound endpoint). A requester refuses getSecrets here: its own getSecrets route records that fetch. knownValues ["getSecrets","sealed"] maxLength 16 |
count | integer | The number of files written. minimum 0 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.secretsUpdated record key any
The requester changed the contract's secrets bundle (the association ref of spec.association); the guest fetches it again through getSecrets, or asks for the sealed fallback; sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.agentStart record key any
The requester asks the guest agent to start the guest's agent unit (the contract's spec.agent); sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.requesterDid record key any
The guest reports the repo DID of the requester it runs, so the contract's requester can associate it (spec.association.fromGuest); sent as the payload of a market.event. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
did * | string did | The did:plc of the requester the guest runs; any other DID method, and the outer requester's own DID, is refused. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.r2Start record key any
The requester asks the guest agent to start the guest requester (socialweb-r2.service, run request --guest-requester as the r2 user) of a contract with spec.association.fromGuest; sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
name * | string | The guest requester's invocation name: a lowercase DNS label of 1 to 63 characters. maxLength 63 |
agent | boolean | The guest requester asks for an atirc agent on its own guest and starts it once held. |
hold | boolean | The guest requester keeps its own contract held. |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.r2Release record key any
The requester, releasing its contract, asks the guest agent to release every contract the guest requester holds before the guest goes away; the guest answers with compute.events.guest.r2Released. Sent as the payload of a market.event. Requester-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.r2Released record key any
The guest reports that its guest requester released its contracts (or holds none) after a compute.events.guest.r2Release; sent as the payload of a market.event. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
ok * | boolean | Every guest requester contract was released. |
message | string | maxLength 512 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.memoryPressure record key any
The guest crossed a memory threshold (edge-triggered: one record per crossing, re-armed only after the value stayed under half the threshold for 5 min; at most one per kind per 10 min and ten memory events per contract); sent as the payload of a market.event. Guest-originated only. It carries no secret. The host-side counterpart is compute.events.vm.memoryPressure.
record
| field | type | description |
|---|---|---|
kind * | string | What crossed: psi, /proc/pressure/memory some avg10; swap, the share of the guest's swap in use. knownValues ["psi","swap"] maxLength 16 |
threshold * | integer | The crossed threshold, in hundredths of a percent (psi: of some avg10; swap: of swapTotal). minimum 0 maximum 10000 |
psiSomeAvg10 | integer | /proc/pressure/memory some avg10, in hundredths of a percent; absent without PSI. minimum 0 maximum 10000 |
psiFullAvg10 | integer | /proc/pressure/memory full avg10, in hundredths of a percent; absent without PSI. minimum 0 maximum 10000 |
swapUsed * | integer | Swap in use, in bytes. minimum 0 |
swapTotal * | integer | The guest's swap, in bytes. minimum 0 |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.oomKill record key any
The guest kernel's OOM killer killed a process (/proc/vmstat oom_kill rose); sent as the payload of a market.event. One record per rise, at most one per 10 min (a later one carries every kill since) and ten memory events per contract. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
kills * | integer | The kills since the last oomKill of this guest. minimum 1 |
total * | integer | The guest's oom_kill count since boot. minimum 1 |
observedAt * | string datetime | |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
com.publicdomainrelay.temp.compute.events.guest.image record key any
The guest reports the image it booted: the marker in its /etc/swc-image; sent as the payload of a market.event. One per contract, from a guest whose image has the file. Guest-originated only. It carries no secret.
record
| field | type | description |
|---|---|---|
marker * | string | The first line of the guest's /etc/swc-image, trimmed (no event when it is empty; no cap beyond the 24 KiB bound on a guest-originated event); the requester compares it with the marker of the image.json it asked for. minLength 1 |
createdAt * | string datetime | |
signatures | network.attested.signature#signatures |
Boot: hostKeys And onNetwork
- the iroh report unit and its script:
internal/guestseed/userdata.go("Report the guest iroh ticket to the market") - one report per kind and tag:
reportininternal/market/bidder/report.gopublishes only whatComputeVMPublisheddoes not hold yet - Held: iroh address + host keys; with a secretsRef and an inbound endpoint, also the getSecrets fetch (market.md)
Sealed Signaling (webrtc tunnels)
- each side publishes a
guest.publicKey(kindage-x25519) per tag - the offer is sealed to the guest's latest key for the tag, plaintext
{sdp, replyTo}; the answer is sealed toreplyTo - no record names its recipient: a reader trial-opens every signal for its tag and keeps the ones that open
- no private key, SDP, ICE candidate or IP address is ever in a record, a ContractEvent, a StateSync, kcp or a log
- CLI side:
run request proxy <name> --tag <tag>(internal/webrtcproxy); STUNstun:stun.cloudflare.com:3478only, no TURN
Secrets: getSecrets Or Sealed Fallback
To send secrets to the VM without putting them in cloud-init (public atproto data), pass a JSON file to run request --secrets: [{path, value, mode?}]. A value that is not a string (an object, array, number) is written as its JSON text, compact. The CLI reads the file once (a <(...) pipe works) and writes it only into the requester's own OpenBao; the guest fetches it at boot. This works by Workload Identity Federation, so nothing sensitive is in the public compute.vm record:
- each bid's
configis acom.publicdomainrelay.temp.compute.config.wif.simplerecord: it tells the requester, before it accepts, what the OIDC issuer of the VM will be and how itssubclaim is formed. If the VM goes away the requester can accept another bidder's bid; the WIF configuration is loosely coupled to the bidder (in-depth: droplet-oidc-poc) - the requester writes a
com.fedproxy.rbacrecord in its repo atnode.<accept rkey>: one role per VM{role_name, definition: {iss, aud: api://ATProto?actx=<requester DID>, sub, policies}}(prepareWorkloadGrantininternal/market/requester/secrets.go); the bidder reads it (internal/guestidentity/rbac_reader.go), turns the roles whoseissandsubare its own intoGuestIdentityGrants, and its OpenBao identity engine then lets that guest mint a token for that audience - the user_data (
cloudinitmodule setup-secrets) logs the guest in at the bidder (guest-login token <aud>) and sends that token to the requester's getSecrets route; the requester checks the audience against the bidder issuer's keys and thewid_subclaim against the subjectactx:<bidder>:plc:<requester>:role:<vm>(secretsState.fetch), then answers the bundle - who can read the bundle: the requester (its OpenBao) and the guest that holds the token. The bidder relays no secret on the getSecrets path and on the sealed path carries ciphertext it cannot open; it does run the token issuer, so a requester trusts the bidder it accepts
- release deletes the rbac record (
deleteRBAC)
A real bid config (bidder did:plc:2l2wdry77c7jtucbslstagkj):
{"uri": "at://did:plc:2l2wdry77c7jtucbslstagkj/com.publicdomainrelay.temp.compute.config.wif.simple/bid-596cc856db4e8aaf1080-config",
"value": {"$type": "com.publicdomainrelay.temp.compute.config.wif.simple",
"issuer_uri": "https://did-key-zq3shm88jyzpmldhqzbifwpqacv3hcp24jfsgb8g9eopcbmjm.xrpc.fedproxy.com/v1/identity/oidc",
"subject": "actx:{actx}:plc:{did-plc-key}:role:{role}", "actx": "2l2wdry77c7jtucbslstagkj",
"to_issue": "openbao-identity-oidc", "url_route": "/v1/identity/oidc/token", "createdAt": "2026-11-15T06:10:53Z"}}
The rest of this section is the guest's side.
spec.secretsRefnames a bundle[{path, value, mode?}]in the requester's OpenBao. One rule, checked by the requester (CheckSecretEntry:ParseSecretsBundle, the CLI's--secrets) and again by both guest writers (setup-secrets, the guest agent's sealed writer):pathis absolute, not/, has no control character (no byte below 0x20, no 0x7f; NUL and newline included) and equals its cleaned form (no.,..or empty component, no trailing slash);modeis an octal string of at most0777(the whole string:^0?[0-7]{1,3}$, in jq\A0?[0-7]{1,3}\z; no setuid, setgid or sticky), default0600; avaluethat is not a string is written as its compact JSON text. One bad entry refuses the whole bundle and nothing is written; the error names the entry index and the reason, never a value. A writer makes only the missing directories (root 0700) and never changes an existing one; each file is written root-owned to a temp file in its directory and renamed, so a symlink at the path is replaced, never followed. setup-secrets reads each path and mode as exact bytes (jq -jplus a sentinel), never through$(...)trimming- the channel, in order (owner, decisions 64 and 2026-11-19): a peer transport, then https to the requester ingress, then, only in comms mode Firehose with
spec.secretsFallback: Sealed, the sealed record. getSecrets is one XRPC service with one check (the token audienceapi://ATProto?actx=<requester DID>and the subject claim,secretsState.fetch); the transports only carry its requests - peer transports: with an inbound endpoint the requester writes
/etc/socialweb-guest-agent/requester.json{iroh, webrtc}into user_data.irohis theiroh://<ticket>of the requester's Servicesvc-requester-<name>-iroh(named handleriroh) behind IngressProxyrequester-iroh;webrtcis the id of the requester's guest WebRTC ingress (tunnel.ID(requester DID)). The file makes the bidder install the guest agent (and lease its WebRTC UDP port), which serves/run/socialweb-guest-agent/requester.sock(root 0600, unix only) and forwards each request over iroh (dumbpipe connect), then WebRTC, eachSecretsPeerChannelTimeoutSec(20 s). The socket forwards every method and path to the requester (owner, decision 72) as a transparent proxy: it follows no redirect (a 3xx goes back to the caller), drops hop-by-hop headers both ways, adds no size limit of its own (the requester's handlers keep theirs) and logs the method, the path without its query, the channel, the status and the transport's inner error, never a URL, a header value or a body. It reads the request body whole (it may send it again on the next channel); it tries the next channel after any failure for GET and HEAD, and for other methods only when the request was never written (a dial or connect failure): a POST that failed after it was sent is answered 502, never sent twice.SecretsPeerChannelTimeoutSec(20 s) bounds one channel's whole exchange, a streamed answer included. A resumed contract that already fetched and whose getSecrets registration gives up (requester_guest_secrets_resume_unready, afterTransientResumeGiveUp) stays Held with no route: a later refetch gets 404 for the contract's life. A bidder that installs the agent forrequester.jsonsays so in/etc/socialweb-guest-agent/bidder.json("requester": true). The requester composes the Service, IngressProxyrequester-irohand its Exposure only while one of its ComputeContracts with asecretsRefis not Released or Failed (compose.SecretsContracts, watched bycompose.SecretsContractWatch); the last one's release removes them, and dumbpipe stops. iroh first: every guest has dumbpipe and iroh relays cross NAT; WebRTC is STUN only - WebRTC: the requester OFFERS with the same
ingress/webrtcService a bidder answers, through the sealed guest signalling: the agent publishesguest.publicKeytagrequester; the requester seals{sdp, replyTo, id, session, peer}to it asguest.signalWebRTCkind offer (ContractEventrequester-webrtc-<contract>); the agent answers withingress/webrtc.Peeron its own API and DTLS certificate, sealed toreplyTo, and opens the datachannels that carry the HTTP - https: setup-secrets waits up to 60 s for the socket only when
requester.jsonis there ANDbidder.jsonsays"requester": true(an older bidder's agent never serves it: no wait), tries it (curl --unix-socket, 45 s), then GETs/xrpc/com.publicdomainrelay.temp.compute.secrets.getSecrets/<contract>fromstatus.secretsUrl(prod: the did:key ingress relaydid-key-<key>.xrpc.fedproxy.com, whose TLS ends at the relay host), 10 rounds - the requester records the time and channel of the FIRST fetch in status (
status.secretsFetchedAt,status.secretsFetchedVia); every fetch, a refetch too, logs its own channel (requester_guest_secrets_fetchedchannel), each listener labelled by its transport: the named iroh handleriroh, the guest WebRTC ingress and the bidder WebRTC ingresswebrtc, the https ingresshttps.status.secretsFetchedVia(iroh,webrtc,https), conditionSecretsAppliedreasonGetSecretsIroh,GetSecretsWebRTCorGetSecretsHTTPS, logrequester_guest_secrets_fetchedchannel - with an inbound endpoint the requester never seals: a
guest.secretsRequestedfrom the guest or the bidder is recorded instatus.contract.secretsRequestedand never acted on (requester_guest_secrets_not_sealed), an outboundguest.secretsContractEvent not yet published fails, and aguest.secretsAppliedis refused (a guest reports only the sealed path, to a Firehose requester). published ciphertext stays on the protocol and can be broken later - the guest agent asks for a sealed bundle only when
/etc/socialweb-guest-agent/secrets.jsonholds the JSON object with exactly the keyfallback="sealed"and at mostgetSecrets=false(an older Firehose requester's marker), nothing after it;"getSecrets": true(an older requester with an inbound endpoint), any other key or value turns the sealed path off (guest_secrets_sealed_refused) - a failure: setup-secrets exits 1; independently, the requester fails the contract when no fetch came within
DefaultVMReadyTimeout(2 min) afterwaitGuestreturned (address, host keys, image marker), even while the guest still retries; setup-secrets' loops use the named constants ofinternal/atproto/cloudinit/guestsecrets.go(the numbers they had), and nothing derives the requester's deadline from them; a resumed contract whosestatus.contract.secretsAppliedis recorded is not failed by it;run requestreleases the VM and exits non-zero,--holdor not, and also when a Firehose contract's sealed secrets never arrive within its contract timeout - in comms mode Firehose user_data has no setup-secrets and no
requester.json: the agent asks at once - version skew of the rule: setup-secrets comes with the requester's user_data, the sealed writer with the bidder's guest agent. An older bidder's agent refuses a mode above
0600: in comms mode Firehose a bundle with such a mode writes nothing on it (the guest logs the refusal), noguest.secretsAppliedcomes, andrun requestlogs "the guest did not write its secrets" after its contract timeout, releases the VM and exits 1 - both paths end in
/run/socialweb-guest-agent/secrets.ready; consumers orderAfter=cloudinit.SecretsReadyUnits - status:
status.secretsFetchedAtandstatus.secretsFetchedVia(getSecrets),status.contract.secretsRequested,status.contract.secretsApplied(sealed), conditionSecretsApplied
- the requester reseals for a newer key while the request is unanswered (
sealGuestSecretsininternal/market/requester/guestsecrets.go) - a Firehose requester with
Noneand a secretsRef fails the contract - a bundle change (
guest.secretsUpdated) makes the guest fetch again (SECRETS_REFETCH=1 setup-secrets.sh), or in Firehose mode ask for the sealed bundle again
Agent Start And atirc Mint
spec.agent {envFile}(default/etc/atirc/atirc.env) needsspec.secretsRef- after
VerifyReceipt,ensureAtircToken(internal/market/requester/atirc.go) mints withchat.atirc.mint(outside.md), lease ={receipt, termination: at-uri of the bidder's vm.terminated payload at EventRKeys(TerminationKey(receipt)), contract: accept uri}(contractLease) - the token goes into the bundle entry at envFile as
ATIRC_TOKEN; getSecrets and the sealed fallback serve the bundle without that entry until it is minted - every fresh mint publishes
guest.secretsUpdated; the guest fetches again;atirc-agent-env.pathrunssystemctl try-restart --no-block atirc-agent.servicewhen the envFile changed (never a start) run request agent <name>makes an outboundguest.agentStart; the guest agent runssystemctl start --no-block atirc-agent.service- every mint is recorded under
atircMintedin the bundle secret; statusstatus.atircRevokes(Done, Pending, Abandoned)
- release: the leased token is revoked before
vm.deletewhile its lease is alive; the rest in the background from a release marker (market.md) - when the VM ends without a release, atirc ends the token through its
vm.terminatedlease
Guest Requester (R2) Events
- a contract with
spec.association.fromGuestruns a requester inside the guest; full flow: identity.md guest.requesterDid: the guest reports the DID of its requester; the requester then readsmarket.associationRequestby onegetRecordand writes the contract-scopedmarket.association(lexicons-market.md)guest.r2Startstartssocialweb-r2.serviceas userr2(run request r2 <name>)- release of the parent:
guest.r2Releasefirst, then wait forguest.r2Released(GuestRequesterReleaseTimeout), then atirc revokes, thenvm.delete
Never
- a guest never holds a repo key; a guest never posts
guest.secrets,guest.agentStart,guest.secretsUpdated,guest.r2Startorguest.r2Release - the bidder never opens a sealed body
- no private key, SDP, ICE candidate or IP address in any record, object or log
- no sealed bundle unasked
- no fourth guest transport (iroh, opentunnel https, webrtc only; ../SYSTEM.md)
See Also
- ../SYSTEM.md, market.md, lexicons-market.md, identity.md, outside.md
- plans:
docs/plans/0034-webrtc-guest-transport.yaml,docs/plans/0035-atirc-agent.yaml,docs/plans/0036-record-association.yaml