# guest-events: events under a receipt - after the receipt ([market.md](market.md)), the bidder, the requester and the guest talk only through `market.event` records and two guest HTTP paths - steps: [S7](README.md#step-s7) boot and vm events, [S8](README.md#step-s8) guest events and atirc, [S9](README.md#step-s9) release - one row per lexicon: [lexicons-market.md](lexicons-market.md) - constants: `internal/atproto/market/nsid.go`, `internal/atproto/market/guest.go`; guest side: `internal/guestagent` (binary `cmd/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.*` or `compute.events.guest.*`) and `market.event {receipt, payload, createdAt, signatures}` - `receipt` = strongRef to the bidder's `market.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 (`applyGuestEvent` in `internal/market/bidder/guestevents.go`) - delivery: `market.submitEvent` to the other party, and the relay / Jetstream streams as fallback ([market.md](market.md#delivery-xrpc-callbacks-and-streams)) - 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 (`guestEvent` in `internal/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: `isGuestEventNSID` in `internal/market/requester/events.go` - direction of `publicKey` and `signalWebRTC` comes from the author: requester-authored ones go to the guest, bidder-authored ones carry what the guest said ## Guest To Requester ```mermaid sequenceDiagram autonumber participant G as guest participant CP as GuestControlPlane (bidder) participant B as Bidder participant BP as bidder repo participant R as Requester G->>CP: POST /v1/events acceptUri acceptCid record, Bearer workload token CP->>CP: verify token, accept is this guest's, kind is guest-originated CP->>B: vm.onNetwork onto ComputeVM status, other kinds PublishGuestEvent B->>B: StateSync guest- or report-, key per kind B->>BP: payload + market.event at EventRKeys(key), both signed B->>R: submitEvent (accept.submitEvent) or the stream carries it R->>BP: getRecord payload by strongRef R->>R: status.contract or inbound ContractEvent ``` - the POST body: `{acceptUri, acceptCid, record}`; the record has `$type` = the payload NSID and no signature (`internal/guestagent/events.go`) - the bearer is the `Authorization` header only (`Guest.Events` in `internal/guestidentity/service.go`) - answers: 200 `{ok, name, guestLogin}`; 401 `AuthenticationRequired` / `InvalidToken`; 400 `InvalidRequest`; 404 `UnknownGuest` / `UnknownAccept`; 503 `Unavailable` - `vm.onNetwork` is 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: `reportSyncKey` and `guestEventSyncKey` in `internal/market/bidder/syncs.go`; the rkeys: [market.md](market.md#rkeys) - the bidder never opens a sealed body; it routes by NSID prefix ## Requester To Guest ```mermaid sequenceDiagram autonumber participant C as CLI / browser / requester participant R as Requester participant RP as requester repo participant B as Bidder participant Q as per-ComputeVM queue participant G as guest agent C->>R: ContractEvent Outbound (nsid, tag, kind, key or ciphertext) R->>RP: payload at SessionRKey contract-event + market.event at contract-event-envelope R->>B: submitEvent B->>RP: getRecord payload, verify event + payload signatures B->>B: author = accept author, kind is requester-originated B->>Q: Append uri cid record G->>B: WebSocket subscribeEvents cursor B-->>G: frames seq uri cid record, keepalive every 25 s G->>G: act on the kind, save cursor ``` - 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-`, `secrets-updated-`) - published by `publishContractEvent` in `internal/market/requester/contractevents.go`; field rules in `validateGuestFields` there - inbound ContractEvents (guest `publicKey`, `signalWebRTC`) are named `InboundContractEventName(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 `; 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](market.md#release-and-termination); `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 [lexicon: com.publicdomainrelay.temp.compute.events.vm.onNetwork](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.onNetwork.html) [lexicon: com.publicdomainrelay.temp.compute.events.vm.hostKeys](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.hostKeys.html) [lexicon: com.publicdomainrelay.temp.compute.events.vm.sandbox](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.sandbox.html) [lexicon: com.publicdomainrelay.temp.compute.events.vm.delete](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.delete.html) [lexicon: com.publicdomainrelay.temp.compute.events.vm.terminated](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.terminated.html) [lexicon: com.publicdomainrelay.temp.compute.events.vm.memoryPressure](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.memoryPressure.html) [lexicon: com.publicdomainrelay.temp.compute.events.vm.oomKilled](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.vm.oomKilled.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.publicKey](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.publicKey.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.signalWebRTC](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.signalWebRTC.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.secrets](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.secrets.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsRequested](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.secretsRequested.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsApplied](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.secretsApplied.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsUpdated](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.secretsUpdated.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.agentStart](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.agentStart.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.requesterDid](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.requesterDid.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Start](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.r2Start.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Release](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.r2Release.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Released](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.r2Released.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.memoryPressure](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.memoryPressure.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.oomKill](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.oomKill.html) [lexicon: com.publicdomainrelay.temp.compute.events.guest.image](https://socialweb.computer/docs/lexicons/com.publicdomainrelay.temp.compute.events.guest.image.html) ## Boot: hostKeys And onNetwork ```mermaid sequenceDiagram autonumber participant B as Bidder participant G as guest participant CP as GuestControlPlane participant BP as bidder repo participant R as Requester B->>G: boot user_data (cloudinit modules + setup-guest-binaries) G->>CP: workload identity login, binds its ssh host key CP->>B: RecordBoundHostKey onto ComputeVM guest report G->>G: iroh.service up, writes /run/guest-fqdn G->>CP: guest-onnetwork POST /v1/events vm.onNetwork address = iroh ticket CP->>B: OnNetwork onto ComputeVM status B->>BP: report: vm.onNetwork (key onNetwork:receipt) + market.event B->>BP: report: vm.hostKeys (key hostKeys:receipt) + market.event B->>R: submitEvent each G->>CP: guest agent POST vm.onNetwork kind webrtc per tag (DTLS fingerprint) B->>BP: vm.onNetwork tag (key onNetwork:tag:receipt) R->>R: VMAddress + HostKeys, Held after secrets ``` - 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: `report` in `internal/market/bidder/report.go` publishes only what `ComputeVMPublished` does not hold yet - Held: iroh address + host keys; with a secretsRef and an inbound endpoint, also the getSecrets fetch ([market.md](market.md#sequence-rfp-to-held)) ## Sealed Signaling (webrtc tunnels) - each side publishes a `guest.publicKey` (kind `age-x25519`) per tag - the offer is sealed to the guest's latest key for the tag, plaintext `{sdp, replyTo}`; the answer is sealed to `replyTo` - 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 --tag ` (`internal/webrtcproxy`); STUN `stun:stun.cloudflare.com:3478` only, no TURN ```mermaid sequenceDiagram autonumber participant C as CLI / browser participant R as Requester participant B as Bidder participant G as guest agent G->>B: POST guest.publicKey tag t (age1 guest key) B->>R: market.event guest.publicKey (bidder repo) R->>C: inbound ContractEvent publicKey C->>R: ContractEvent publicKey tag t (age1 requester key) C->>R: ContractEvent signalWebRTC offer, sealed to guest key, replyTo = requester key R->>B: submitEvent publicKey, signalWebRTC offer B->>G: subscribeEvents frames G->>G: open offer, answer, check nothing else G->>B: POST guest.signalWebRTC answer sealed to replyTo B->>R: market.event signalWebRTC answer R->>C: inbound ContractEvent answer C->>G: datachannel tag t, DTLS fingerprint = vm.onNetwork webrtc address ``` ## 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 `config` is a `com.publicdomainrelay.temp.compute.config.wif.simple` record: it tells the requester, before it accepts, what the OIDC issuer of the VM will be and how its `sub` claim 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](https://github.com/digitalocean-labs/droplet-oidc-poc)) - the requester writes a `com.fedproxy.rbac` record in its repo at `node.`: one role per VM `{role_name, definition: {iss, aud: api://ATProto?actx=, sub, policies}}` (`prepareWorkloadGrant` in `internal/market/requester/secrets.go`); the bidder reads it (`internal/guestidentity/rbac_reader.go`), turns the roles whose `iss` and `sub` are its own into `GuestIdentityGrant`s, and its OpenBao identity engine then lets that guest mint a token for that audience - the user_data (`cloudinit` module setup-secrets) logs the guest in at the bidder (`guest-login token `) and sends that token to the requester's getSecrets route; the requester checks the audience against the bidder issuer's keys and the `wid_sub` claim against the subject `actx::plc::role:` (`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`): ```json {"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.secretsRef` names 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): `path` is 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); `mode` is an octal string of at most `0777` (the whole string: `^0?[0-7]{1,3}$`, in jq `\A0?[0-7]{1,3}\z`; no setuid, setgid or sticky), default `0600`; a `value` that 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 -j` plus 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 audience `api://ATProto?actx=` 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. `iroh` is the `iroh://` of the requester's Service `svc-requester--iroh` (named handler `iroh`) behind IngressProxy `requester-iroh`; `webrtc` is 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, each `SecretsPeerChannelTimeoutSec` (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`, after `TransientResumeGiveUp`) stays Held with no route: a later refetch gets 404 for the contract's life. A bidder that installs the agent for `requester.json` says so in `/etc/socialweb-guest-agent/bidder.json` (`"requester": true`). The requester composes the Service, IngressProxy `requester-iroh` and its Exposure only while one of its ComputeContracts with a `secretsRef` is not Released or Failed (`compose.SecretsContracts`, watched by `compose.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/webrtc` Service a bidder answers, through the sealed guest signalling: the agent publishes `guest.publicKey` tag `requester`; the requester seals `{sdp, replyTo, id, session, peer}` to it as `guest.signalWebRTC` kind offer (ContractEvent `requester-webrtc-`); the agent answers with `ingress/webrtc.Peer` on its own API and DTLS certificate, sealed to `replyTo`, and opens the datachannels that carry the HTTP - https: setup-secrets waits up to 60 s for the socket only when `requester.json` is there AND `bidder.json` says `"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/` from `status.secretsUrl` (prod: the did:key ingress relay `did-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_fetched` `channel`), each listener labelled by its transport: the named iroh handler `iroh`, the guest WebRTC ingress and the bidder WebRTC ingress `webrtc`, the https ingress `https`. `status.secretsFetchedVia` (`iroh`, `webrtc`, `https`), condition `SecretsApplied` reason `GetSecretsIroh`, `GetSecretsWebRTC` or `GetSecretsHTTPS`, log `requester_guest_secrets_fetched` `channel` - with an inbound endpoint the requester never seals: a `guest.secretsRequested` from the guest or the bidder is recorded in `status.contract.secretsRequested` and never acted on (`requester_guest_secrets_not_sealed`), an outbound `guest.secrets` ContractEvent not yet published fails, and a `guest.secretsApplied` is 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.json` holds the JSON object with exactly the key `fallback` = `"sealed"` and at most `getSecrets` = `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) after `waitGuest` returned (address, host keys, image marker), even while the guest still retries; setup-secrets' loops use the named constants of `internal/atproto/cloudinit/guestsecrets.go` (the numbers they had), and nothing derives the requester's deadline from them; a resumed contract whose `status.contract.secretsApplied` is recorded is not failed by it; `run request` releases the VM and exits non-zero, `--hold` or 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), no `guest.secretsApplied` comes, and `run request` logs "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 order `After=` `cloudinit.SecretsReadyUnits` - status: `status.secretsFetchedAt` and `status.secretsFetchedVia` (getSecrets), `status.contract.secretsRequested`, `status.contract.secretsApplied` (sealed), condition `SecretsApplied` ```mermaid sequenceDiagram autonumber participant G as guest participant CP as GuestControlPlane participant R as Requester ingress participant B as Bidder alt comms XRPC or Both: getSecrets over iroh, WebRTC, then https G->>CP: GET /v1/identity/oidc/token/role (workload identity) CP-->>G: token G->>R: GET getSecrets/contract, Bearer token (requester.sock: iroh, then WebRTC; else https) R-->>G: [{path, value, mode}] G->>G: write files root (mode or 0600), secrets.ready else comms Firehose and secretsFallback Sealed G->>B: POST guest.publicKey tag secrets G->>B: POST guest.secretsRequested B->>R: market.event publicKey, secretsRequested (relay or Jetstream) R->>R: seal bundle to that key, guest.secrets record in its repo R->>B: submitEvent guest.secrets B->>G: subscribeEvents guest.secrets G->>G: open, write files root (mode or 0600), secrets.ready G->>B: POST guest.secretsApplied via sealed end ``` - the requester reseals for a newer key while the request is unanswered (`sealGuestSecrets` in `internal/market/requester/guestsecrets.go`) - a Firehose requester with `None` and 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`) needs `spec.secretsRef` - after `VerifyReceipt`, `ensureAtircToken` (`internal/market/requester/atirc.go`) mints with `chat.atirc.mint` ([outside.md](outside.md#chatatirc)), 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.path` runs `systemctl try-restart --no-block atirc-agent.service` when the envFile changed (never a start) - `run request agent ` makes an outbound `guest.agentStart`; the guest agent runs `systemctl start --no-block atirc-agent.service` - every mint is recorded under `atircMinted` in the bundle secret; status `status.atircRevokes` (Done, Pending, Abandoned) ```mermaid sequenceDiagram autonumber participant R as Requester participant A as atirc participant V as requester OpenBao bundle participant B as Bidder participant G as guest R->>R: receipt verified (ReceiptOk) R->>A: chat.atirc.mint subhandle from the RFP rkey, lease receipt + vm.terminated at-uri + accept A-->>R: token with explicit exp R->>V: ATIRC_TOKEN into envFile entry, record atircMinted R->>B: submitEvent guest.secretsUpdated B->>G: subscribeEvents secretsUpdated G->>R: getSecrets again (comms Firehose: the sealed bundle again) G->>G: envFile sha256 changed, try-restart atirc-agent.service R->>B: submitEvent guest.agentStart (run request agent) B->>G: subscribeEvents agentStart G->>G: systemctl start --no-block atirc-agent.service G->>A: atirc agent joins as subhandle ``` - release: the leased token is revoked before `vm.delete` while its lease is alive; the rest in the background from a release marker ([market.md](market.md#revocation-ordering)) - when the VM ends without a release, atirc ends the token through its `vm.terminated` lease ## Guest Requester (R2) Events - a contract with `spec.association.fromGuest` runs a requester inside the guest; full flow: [identity.md](identity.md#associations-identlink) - `guest.requesterDid`: the guest reports the DID of its requester; the requester then reads `market.associationRequest` by one `getRecord` and writes the contract-scoped `market.association` ([lexicons-market.md](lexicons-market.md#marketassociation)) - `guest.r2Start` starts `socialweb-r2.service` as user `r2` (`run request r2 `) - release of the parent: `guest.r2Release` first, then wait for `guest.r2Released` (`GuestRequesterReleaseTimeout`), then atirc revokes, then `vm.delete` ## Never - a guest never holds a repo key; a guest never posts `guest.secrets`, `guest.agentStart`, `guest.secretsUpdated`, `guest.r2Start` or `guest.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](../SYSTEM.md#transports-three-never-add-one)) ## See Also - [../SYSTEM.md](../SYSTEM.md#guests), [market.md](market.md), [lexicons-market.md](lexicons-market.md), [identity.md](identity.md), [outside.md](outside.md) - plans: `docs/plans/0034-webrtc-guest-transport.yaml`, `docs/plans/0035-atirc-agent.yaml`, `docs/plans/0036-record-association.yaml`