~ knotless Search/
↑↓ move↵ open⇧↵ all results

socialweb.computer/socialweb-computer-kcp

socialweb.computer: a compute market on atproto (kcp)

1 collaborator
0
0
363 lines · 32.3 KB Raw History

guest-events: events under a receipt

  • after the receipt (market.md), the bidder, the requester and the guest talk only through market.event records 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 (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)
  • the guest holds no repo key. the bidder signs and writes every guest-originated event in its own repo

Who Sends What

payloadoriginatorwritten inconsumerfile of the consumer
vm.onNetworkguest (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 reporequester: status.contract.vmAddress, status.contract.networksinternal/market/requester/runner.go waitGuest
vm.memoryPressure, vm.oomKilledbidder (the VM unit's cgroup memory.events, polled 15 s, edge-triggered, at most 10 per contract)bidder reporequester: one requester_market_event line eachinternal/market/bidder/memory.go
vm.hostKeysbidder (the host key the guest bound at its workload identity login)bidder reporequester: status.contract.hostKeyssame
vm.sandboxbidder (deno sandbox ended)bidder reporequester: status.contract.sandboxinternal/market/requester/events.go
vm.terminatedbidderbidder reporequester: Releasedinternal/market/requester/market.go FindTermination
vm.deleterequesterrequester repobidder: releaseinternal/market/bidder/adapters.go applyRelease
guest.publicKeyeither sidesender repothe other sideguest: internal/guestagent/subscribe.go; requester: inbound ContractEvent
guest.signalWebRTCeither sidesender repothe other sidesame
guest.secretsrequester onlyrequester repoguestinternal/guestagent/secrets.go
guest.secretsRequestedguest onlybidder reporequester: seals the bundleinternal/market/requester/guestsecrets.go
guest.secretsAppliedguest onlybidder reporequester: condition SecretsAppliedinternal/market/requester/events.go
guest.secretsUpdatedrequester onlyrequester repoguest: fetches the bundle againinternal/guestagent/subscribe.go
guest.agentStartrequester onlyrequester repoguest: systemctl start --no-block atirc-agent.serviceinternal/guestagent/agentstart.go
guest.requesterDidguest onlybidder reporequester: status.contract.guestRequesterinternal/market/requester/association.go
guest.r2Startrequester onlyrequester repoguest: starts socialweb-r2.serviceinternal/guestagent/association.go
guest.r2Releaserequester onlyrequester repoguest: runs socialweb-r2-release.servicesame
guest.r2Releasedguest onlybidder reporequester: status.contract.r2Releaseinternal/market/requester/guestrequester.go
guest.memoryPressure, guest.oomKillguest onlybidder reporequester: 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.imageguest onlybidder reporequester: requester_guest_image {marker, expected, ok}; a contract with spec.image releases on a mismatchinternal/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

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-<hash> or report-<hash>, 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
  • the bidder never opens a sealed body; it routes by NSID prefix

Requester To Guest

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-<contract>, secrets-updated-<hash>)
  • 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

itemvalue
routeGET /xrpc/com.publicdomainrelay.temp.compute.guest.subscribeEvents on the GuestControlPlane (internal/services/guestcontrolplane/subscribe.go)
authAuthorization: Bearer <workload identity token>; names the ComputeVM (guest.Authenticate)
paramcursor: last seq seen. absent = oldest entry kept
frameJSON text {"$type": "...subscribeEvents#event", seq, uri, cid, record}; record.$type is a compute.events.guest.* NSID
keepalivean empty binary frame every 25 s (SubscribeKeepalive)
errorFutureCursor: the guest agent resets its cursor to 0 and reconnects (internal/guestagent/subscribe.go)
reconnectbackoff 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 tailnotes
vm.onNetworkkind absent: iroh without tag, https with tag (market.OnNetworkKind). webrtc address = the guest agent DTLS fingerprint sha-256 AB:CD:...
vm.hostKeysat most 8 keys, an ed25519 key required (internal/guestidentity/guestrecord.go)
vm.sandboxcompute.vm.kind: deno only (internal/market/bidder/sandbox.go)
vm.deleterequester writes released
vm.terminatedreasons: market.md; request is optional: a deleted_on_request without one is a delete on the bidder
vm.memoryPressurethe VM unit's cgroup memory.events high or max rose
vm.oomKilledits oom_kill rose
guest.publicKeyone per tag per side; anything sealed for a tag goes to the other side's latest key
guest.signalWebRTCplaintext {sdp, replyTo}; non-trickle ICE, one offer, one answer
guest.secretsage armored, at most 65536 bytes (MaxGuestSecretsCiphertext); plaintext = the getSecrets JSON array
guest.secretsRequestedthe requester seals only in comms mode Firehose with secretsFallback: Sealed; otherwise it records it and does nothing
guest.secretsAppliedthe 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.secretsUpdatedthe bundle changed (atirc mint, association ref)
guest.agentStartneeds spec.agent (contractevents.go)
guest.requesterDiddid:plc only, never the authority's own DID (market.ValidGuestRequesterDID)
guest.r2Startneeds spec.association.fromGuest
guest.r2Release
guest.r2Released
guest.memoryPressureevery 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.oomKillone per /proc/vmstat oom_kill rise, same caps
guest.imageonce at agent start, when the file exists; the bidder publishes one per contract

Fields

lexicon: com.publicdomainrelay.temp.compute.events.vm.onNetwork

lexicon: com.publicdomainrelay.temp.compute.events.vm.hostKeys

lexicon: com.publicdomainrelay.temp.compute.events.vm.sandbox

lexicon: com.publicdomainrelay.temp.compute.events.vm.delete

lexicon: com.publicdomainrelay.temp.compute.events.vm.terminated

lexicon: com.publicdomainrelay.temp.compute.events.vm.memoryPressure

lexicon: com.publicdomainrelay.temp.compute.events.vm.oomKilled

lexicon: com.publicdomainrelay.temp.compute.events.guest.publicKey

lexicon: com.publicdomainrelay.temp.compute.events.guest.signalWebRTC

lexicon: com.publicdomainrelay.temp.compute.events.guest.secrets

lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsRequested

lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsApplied

lexicon: com.publicdomainrelay.temp.compute.events.guest.secretsUpdated

lexicon: com.publicdomainrelay.temp.compute.events.guest.agentStart

lexicon: com.publicdomainrelay.temp.compute.events.guest.requesterDid

lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Start

lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Release

lexicon: com.publicdomainrelay.temp.compute.events.guest.r2Released

lexicon: com.publicdomainrelay.temp.compute.events.guest.memoryPressure

lexicon: com.publicdomainrelay.temp.compute.events.guest.oomKill

lexicon: com.publicdomainrelay.temp.compute.events.guest.image

Boot: hostKeys And onNetwork

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)

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 <name> --tag <tag> (internal/webrtcproxy); STUN stun:stun.cloudflare.com:3478 only, no TURN
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)
  • the requester writes a com.fedproxy.rbac record in its repo at node.<accept rkey>: one role per VM {role_name, definition: {iss, aud: api://ATProto?actx=<requester DID>, 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 GuestIdentityGrants, 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 <aud>) 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:<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.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=<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. iroh is the iroh://<ticket> of the requester's Service svc-requester-<name>-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-<contract>); 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/<contract> from status.secretsUrl (prod: the did:key ingress relay did-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_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
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), 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 <name> 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)
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)
  • 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
  • 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)
  • guest.r2Start starts socialweb-r2.service as user r2 (run request r2 <name>)
  • 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)

See Also