identity: signatures, key claims, associations, sign-in
- who a repo DID is, which key signs for it, and which operator it belongs to
- lexicons:
lexicons/network/attested/,lexicons/com/publicdomainrelay/temp/badgeBlueKeys.json; association rows in lexicons-market.md - rule (plan 0036): the authority is always the repo in the record's at-uri, never a record field or an issuer claim
- index: README.md. sequence steps: S0, S1, S5, S9
Actors
Every actor is an atproto DID with a repo on a PDS; it writes only its own repo. Prod examples.
| actor | DID | repo lives on | writes |
|---|---|---|---|
| requester (a person) | own account, e.g. aliceoa.bsky.social (did:plc:lpfuqerea3deuoyrn7ojser4) | its PDS (bsky); or, localRepo, the app's own Pds | compute.vm, policy record, market.rfp, market.accept, market.event + payloads, com.fedproxy.rbac, vouches, the Infra records |
| bidder operator (a person) | own account, e.g. bobvmbuilder.bsky.social (did:plc:ocnuqjlzgohypj3zoznermms) | its PDS (bsky) | vouches; per bidder agent the link.ident.endorsement + standing market.association at rkey = the agent DID |
| bidder (agent) | its own did:plc (localRepo, internal/stack/bidder), DID document alsoKnownAs: https://ident.link/agent-of/<operator DID> | the bidder's own Pds, public through the did:key ingress (https://did-key-<did:key>.xrpc.fedproxy.com) | market.offering, market.heartbeat, bids, receipts, market.event + payloads (also the guest's) |
| bidder as the operator itself | --atproto-oauth-qr / identity: {mode: oauthQr}: the operator's own DID (CheckSignIn refuses any other handle) | the operator's PDS | the same, in the operator's repo |
| gateway requester | a localRepo agent of the gateway operator (internal/app/gateway) | the gateway's Pds | the RFP records of tenant cluster nodes; nodes mirror to the owner's computer.socialweb.infra/nodes-<hex> |
| ssh gateway session requester | the signed-in user's own DID (MarketIdentity owner-<stamp(did)>, oauthSessionProxy, internal/app/compose/sessionowner.go) | the user's PDS | the user's RFP records, as the user |
| guest requester R2 | a did:plc made inside a requested VM, an agent of the requester for one contract (below) | R2's own Pds in the guest | market.associationRequest, its own RFP records, computer.socialweb.peer |
| guest | none: it holds no repo key; a workload identity token from the bidder's OpenBao | - | nothing; the bidder signs and writes its events |
| release account | socialweb.computer (did:plc:gmlkrhimoueejcertevr4hl3) | its PDS (bsky) | software.release.* (release.md), com.fedfork.exec.binding (CI executors) |
The four prod bidders today are bobvmbuilder.bsky.social's agents (deploy/release/rc-operators.json). One of them, as the records show it:
{"did": "did:plc:2l2wdry77c7jtucbslstagkj",
"alsoKnownAs": ["https://ident.link/agent-of/did:plc:ocnuqjlzgohypj3zoznermms"],
"service": [{"id": "#atproto_pds", "serviceEndpoint": "https://did-key-zq3shc9tdkt67yslq9wahqywwix2gfvvtzstwsyvsg7ewbafg.xrpc.fedproxy.com"}]}
{"uri": "at://bobvmbuilder.bsky.social/link.ident.endorsement/did:plc:2l2wdry77c7jtucbslstagkj",
"value": {"$type": "link.ident.endorsement", "agent": "did:plc:2l2wdry77c7jtucbslstagkj"}}
{"uri": "at://bobvmbuilder.bsky.social/com.publicdomainrelay.temp.market.association/did:plc:2l2wdry77c7jtucbslstagkj",
"value": {"$type": "com.publicdomainrelay.temp.market.association", "agent": "did:plc:2l2wdry77c7jtucbslstagkj", "createdAt": "2026-11-11T09:37:44.146Z"}}
The operator writes the pair once: by signing in at the bidder's MarketIdentity operator URL (compose.ApplyOperatorPair: grant, then endorsement), or with scripts/associate-bidder.ts --agent-did <did>. The bidder adds its own agent-of to its DID document (compose.UpdateAgentOf, signed with its Pds PLC rotation key).
Keys: who signs what
| key | held in | signs |
|---|---|---|
attestation key (secp256k1 JWK, 0600): bidder <state>/attestation.jwk, requester attestation-key.json | the app's state dir | the signatures of every market record and event payload (below) |
| repo signing key | the PDS (bsky for an account there; the app's Pds repo-keys/<sha256(did)>.key for localRepo, copied into the requester's repo-key.json and attestation-key.json, compose.SyncRequesterRepoKey) | repo commits; a localRepo requester's self-signed service auth |
| a PDS session (OAuth or password) | the app's OpenBao (auth/atproto session/<did>) | com.atproto.server.getServiceAuth for market.submit*, chat.atirc.*, computer.socialweb.k8s.* |
| PLC rotation key | the app's Pds plc-rotation.key; the requester's <requester dir>/plc-rotation.key (k256, first rotation key of every R2 DID it requests) | DID document updates (agent-of), tombstones |
did:key ingress key (bidder market-relay.jwk) | the state dir | the ingress relay registration (self-signed, no DID document) |
guest ssh host key (ssh_host_ed25519_key) | the guest | its workload identity bind at the bidder's OpenBao (sshsig), which binds its host key to the ComputeVM |
Lexicons And NSIDs In This File
| NSID | rkey | used |
|---|---|---|
network.attested.signature | - | inline on every market and compute event record |
network.attested.proof | - | defined, not written |
network.attested.verify | - | defined, not served or called |
com.publicdomainrelay.temp.badgeBlueKeys | see below | signer key binding, ssh key claim |
link.ident.endorsement (ident.link 74d22dc, vendored) | the agent DID | principal confirms an agent, below |
com.publicdomainrelay.temp.market.association | the agent DID | the grant, below |
com.publicdomainrelay.temp.market.associationRequest | lexicons-market.md | flow below |
Types and fields: each NSID's page in the lexicon reference.
network.attested
Signing
| step | code |
|---|---|
| attestation CID | internal/atproto/market/attest.go CreateAttestationCID, DagCborCID |
| sign inline | attest.go SignInline, SignRecord, CreateSignedRecord, CreateSignedRecordAt |
| market records | internal/atproto/market/records.go createSigned, PutEvent |
| bidder | internal/market/bidder/bids.go, internal/market/bidder/adapters.go |
| requester | internal/market/requester/contractevents.go, internal/market/requester/runner.go (vm.delete) |
| receipt | attest.go CreateReceiptRecordAt: cid = the attestation CID of the accept, plus an inline signature |
- records with a
signaturesfield:market.rfp,market.bid,bids.free,bids.x402,market.accept,accepts.free,accepts.x402,market.receipt,receipts.free,receipts.x402,market.event, everycompute.events.vm.*andcompute.events.guest.* - signing keys: secp256k1 JWK files, mode 0600 (
internal/atproto/market/keys.goLoadOrCreateSignerFile)- bidder:
<stateDir>/attestation.jwk(internal/services/bidder/wiring.go) - requester:
attestation-key.json, elserepo-key.json(internal/market/requester/requester.go); forlocalRepo, gateway and R2 identities compose seeds both from the app Pds repo signing key of the DID (internal/app/compose/pds.goSyncRequesterRepoKey)
- bidder:
- the public
did:key(Signer.PublicDID) is thekeyIdof the signer key binding below
Verifying
| function | checks |
|---|---|
VerifyInlineAttestation (attest.go) | recompute the CID, ECDSA against key |
CheckRecordSignatures, VerifyRecordSignatures (attest.go) | the key is in the DID document of the repo that holds the record, or bound by that repo's badgeBlueKeys signer key binding; a signature entry whose issuer names another DID counts for nothing (a third-party attestation is no proof of the repo's authorship); CheckRecordSignatures tells a refusal (ErrUnsignedRecord) from a failed lookup |
VerifyRemoteProof (attest.go) | used only by VerifyReceipt (internal/atproto/market/contract.go) |
VerifyReceipt (contract.go) | the receipt's signature under the same rule (DID document key or verified binding) and its cid bound to the accept |
How the requester checks a bidder's key (internal/market/requester/keybinding.go, owner decision 71, 2026-11-20). Prod bidders
sign with an attestation key that is not in their DID document (read 2026-11-20: the four prod bidders' bids, payloads, receipts
and events are signed by their bidder_attestation key; each DID document names only its atproto repo key). The binding record
badgeBlueKeys/<BadgeBlueKeysRkey(did, key)> is read with com.atproto.sync.getRecord and taken only when the CAR checks out
(identlink.Remote.GetVerifiedRecord: every block hashes to its CID, the commit is signed by the DID document's atproto key,
the DID document resolved from the PLC directory, never through the bidder's PDS or route, and the MST path leads to that rkey);
then keyId must be the signing key and challenge the DID. A bound answer is kept 5 min (identlink.DocTTL, the trust walk's
DID document lifetime), so, against an honest PDS, a rotated or removed binding stops counting within 5 min (a route can replay an
older signed commit: upstream by design); "not bound" is never kept, so a binding written after a refusal counts at the next bid; a failed read is an error, never "not bound", and is not kept. A did:web bidder's document comes from its own host
over TLS; whoever serves that host serves the keys. When the PLC directory or the bidder's PDS cannot be read, every bid of that
bidder fails closed: submitBid answers 503, the mailbox retries for 2 min and then leaves the bid out.
Who checks it: every bid before it is queued (verifyBid: SubmitBid in callbacks.go answers 403 on a refusal and 503 on a
failed lookup; the bid mailbox, which the streams and the catch-up read feed, retries a failed lookup every 2 s and leaves the
bid out after 2 min, requester_bid_verify_gave_up), every receipt (VerifyReceipt under the shared 2 min give-up of
untilSettled) and every guest event and its payload (parseGuestEvent). The catch-up read takes a bid by URI and then reads it
again by the cid that first answer reported, so its bytes are checked against that cid. The bidder offers and bids only once its
own binding is written and read back (awaitBinding, bindBadgeBlueKey in internal/market/bidder/offering.go, retried with
backoff, bidder_binding_waits). The bidder's own checks of a requester's RFP and accept
(participant.Verifier in internal/market/participant/comms.go) still read the requester's binding with a plain getRecord.
- callers:
internal/atproto/market/contract.go,internal/market/participant/comms.go,internal/market/requester/inbox.go,internal/market/requester/events.go,internal/market/requester/runner.go network.attested.proof(CreateRemoteProofRecord) has no caller outside tests.network.attested.verifyis neither served nor called; onlynetwork.attested.signatureis in the lexgen include list (internal/atproto/market/nsid.go)
badgeBlueKeys
com.publicdomainrelay.temp.badgeBlueKeys record key any
Binds a signing key to the repository DID, so that records signed with the key verify as the DID's.
record
| field | type | description |
|---|---|---|
keyId * | string | The did:key of the bound key. |
name | string | |
challenge * | string did | The repository DID the key is bound to. |
service * | string | The service the key signs for. |
nonce | string | |
createdAt * | string datetime |
Go: internal/atproto/market/badgeblue.go; the signer binding writes neither nonce nor name.
One collection, two uses. Each has its own rkey and service.
| use | in repo of | rkey | keyId | challenge | service | written by | read by | step |
|---|---|---|---|---|---|---|---|---|
| signer key binding | the signer (bidder or requester) | BadgeBlueKeysRkey(did, keyId): base58 of sha256(did:keyId)[:24], max 32 chars | signer did:key | the signer's repo DID | bidder_attestation (bidder), market_requester (requester) | bidder internal/market/bidder/offering.go (at start, retried on each heartbeat); requester internal/market/requester/identity.go (owner-session, OAuth and callback identities only: a localRepo requester signs with its repo key, which its DID document names) | the requester: keyBinding.check (requester/keybinding.go, verified sync.getRecord); the bidder: KeyBoundByBadgeBlueKey from participant/comms.go (plain getRecord) | S0 |
| ssh key claim | the user | keyRkey: 13 TID-alphabet chars of sha256(sshtransport/badge-blue-key/v1, did, key) (internal/sshtransport/keys.go) | <algo> <key> | the user DID | requester_associate | ssh.socialweb.computer /keys | ssh authorizer, one getRecord per offered key (internal/sshtransport/authorizer.go) | ssh sign-in |
Associations (identlink)
- design: ../design/ident-link-associations.md; spec: https://ident.link
- Go:
internal/identlink(walk,AgentOf,Remote: DID docs +com.atproto.sync.getRecord, CAR and MST verified);internal/policyengine/truston it - vectors:
internal/identlink/vectors.json(byte-identical to atlibs-identlink),go run ./hack/identlinkvectors internal/identlink/vectors.jsonindeploy/check.sh --fast
| side | where | what |
|---|---|---|
| agent declares | agent DID doc alsoKnownAs | https://ident.link/agent-of/<principal-did> |
| principal confirms | principal repo link.ident.endorsement, rkey = agent DID | {agent} |
| principal grants | principal repo market.association, rkey = agent DID | {agent, expiresAt?, contract?, createdAt} |
- edge
A -> Pholds iff all three agree and the grant is live; pair without grant: untrusted - contract-scoped grant:
expiresAtrequired; dead once the contract is not Held (canonical receipt, no vm.delete, no vm.terminated); the accept must be in P's repo or a repo above P (trust/association.gocontractHeld, checked after the walk to a fixpoint) - PDS or PLC outage: the edge is unconfirmed, listed in
errors, cached 5 s
Walk
| item | value |
|---|---|
identlink.Walk(ctx, io, agent, Options{MaxDepth: 100, Budget: 256}) | Result{Agent, Ancestors [{DID, Depth, ExpiresAt}], Roots, ExpiresAt, Truncated, Errors} |
| roots | ancestors with no held edge up; a node that skipped a cycle or was truncated is not a root |
ExpiresAt | min grant expiresAt along the path; walk: min over roots; none = standing |
cache (trust.Resolver) | DID doc 5 min / 5 s; walk 5 min capped at the earliest ancestor expiresAt / 5 s with errors; ApplyEvent drops walks naming the DID |
| check | rule |
|---|---|
policy snapshot operatorOf | a root both sides share, else the first root |
| tangled-vouch, mutuals | vouches between {self}+ancestors(self) and {cp}+ancestors(cp), at most 256 pairs, nearest first |
requireContract | every edge to the root contract-scoped (non-contract grants count as absent) |
| bidder networked deno | roots(requester) meets roots(bidder) |
| bidder guest lifetime cap | walk expiresAt of the requester |
| requester discovery | roots(self) are operators; an operator's endorsed agents whose walk reaches it |
| MarketIdentity associated | localRepo only: its DID's walk has a root other than itself; associationRef pins the grant (rkey = the DID) and its walk must reach the grant's repo; spec.approvedAssociations are listed as roots without a walk (internal/marketidentity/atproto/association.go); OAuth modes report none |
Contract-scoped association
- the guest requester R2 is an agent of the requester for one contract: grant
contract= the requester'smarket.accept{uri, cid},expiresAt= the accept time + 24 h (market.ContractAssociationLifetime) market.associationRequest {principal, contract, nonce, accounts?, createdAt}in the guest repo, rkey = principal DID: the principal endorses only the DID that answered this contract's nonce- writers: requester
association.go(requester: grant + endorsement at rkey = R2 DID after the nonce check), composerecords.go(operator pair, agent-of, the association request), composepeer.go(R2: its co-located accounts' grant + endorsement, with R2's contract and expiresAt, and their peer records{iroh?, createdAt}) - the requester writes no VM agent peer record and no self-association; the bundle entry
/etc/socialweb-computer/association-request.jsonis {principal, contract, nonce (48 hex), rotationKey (the requester's did:key), handle?} - guest events of this flow (
requesterDid,r2Start,r2Release,r2Released): guest-events.md; the lifecycle: Guest requester (R2)
Guest Requester (R2)
What it is for: a machine that requests machines from inside a requested machine. A CI VM requested as R2's host (the knotless executor binding com.fedfork.exec.binding/kcp-test of socialweb.computer has inputs.association: true) runs socialweb-computer run request --guest-requester, and that requester requests the staging network's VMs as an agent of the requester, for that one contract only. The release binding asks for none (scripts/promote.sh prepare exits 1 on a VM that has one).
| step | who | what (source) |
|---|---|---|
| ask | requester | spec.association {fromGuest: true} (run request --associate guest; spec.agent with no association defaults to it: requester.DefaultAssociation); the bundle gets /etc/socialweb-computer/association-request.json {principal, contract, nonce, rotationKey, handle?} (ensureAssociationRequest) |
| create | R2 in the guest | a localRepo account on its own Pds (internal/app/marketrequester): did:plc with alsoKnownAs: https://ident.link/agent-of/<requester DID> and rotation keys [requester key, R2 Pds key] (internal/pds/plcsubmit); handle <label>-<rfp rkey>.<requester handle> when the requester's handle verifies; PLC: the requester network's, else none given (the requester default https://plc.directory) |
| request | R2 | market.associationRequest/<requester DID> {principal, contract, nonce, accounts?} in its repo; then writes its DID to requester-did |
| report | guest agent | guest.requesterDid {did} (did:plc only, never the requester's own DID: market.ValidGuestRequesterDID) |
| verify | requester | records the DID Pending (a second DID is refused), one getRecord of <R2>/market.associationRequest/<requester DID>, principal and contract equal, nonce equal (constant time) (proveGuestRequester) |
| grant | requester | market.association/<R2 DID> {agent, contract: the accept, expiresAt: accept + 24 h} and link.ident.endorsement/<R2 DID> in its own repo; the ref <uri>#<cid> into the bundle at association-ref; guest.secretsUpdated (associate, notifySecretsUpdated) |
| use | everyone | R2's walk reaches the requester while the grant lives and the contract is held (the accept has a receipt, no vm.delete, no vm.terminated: trust/association.go contractHeld); co-located accounts <label>.<R2 handle> get grants from R2 with the same contract and expiresAt |
| bound | bidder | a VM of R2 ends 10 min after spec.associationExpiresAt, and within a minute once the outer contract's vm.terminated or vm.delete exists (association_ended) |
| retire | requester, R2 | release sends guest.r2Release, waits for guest.r2Released (GuestRequesterReleaseTimeout); R2's run request release sets spec.peer.retire: its peer, grant and endorsement records go, its accounts are deactivated and tombstoned with R2's Pds rotation key (compose/peer.go) |
| tombstone fallback | requester | on release the requester waits up to 2 min (RenterTombstoneWait) for the guest's tombstones, then tombstones R2 and its verified co-located accounts with its own plc-rotation.key, only when the DID document names agent-of/<requester> (or <R2>) and that key is a rotation key (renterkey.go, requester_tombstoned); then deletes its grant and endorsement |
Trust never depends on that cleanup: the grant's expiresAt, vm.delete and vm.terminated end every link.
Sign-In
- a MarketIdentity is a repo DID plus how the app reaches it (
api/v1alpha1/types_marketidentity.go,internal/marketidentity/atproto,internal/controllers/marketidentity)
| mode | repo | sign-in | atproto calls |
|---|---|---|---|
localRepo | the app's own Pds component | none | in-process PDS (internal/pds/local) |
pdsAccount | a PDS account, password in the vault | app password | com.atproto.server.createSession, refreshSession |
oauthQr | user's PDS | QR session transfer at qr.fedfork.com (5 min) | OAuth (DPoP), scope QROAuthScope |
oauthBrowser | user's PDS | authorize URL in status.pendingAction | OAuth |
oauthDelegated | user's PDS | session handed in by another app | OAuth |
oauthSessionProxy | user's PDS | a session another component stored in OpenBao (auth/atproto session/<did>) | OAuth |
- OAuth sessions live only in the app's own OpenBao; the atproto auth plugin refreshes them
- granted scopes are read from the token response, never the access token's
scopeclaim - scopes per role and optional scopes: outside.md
- scripted sign-in:
scripts/oauth-signin.ts, ../oauth.md - the QR transfer is signed with the CLI's did:key (
internal/marketidentity/atproto/oauth.go,internal/atproto/oauthclient/qr.go)
did:key Ingress
- apps without a public host (CLI requester, page, iOS, guest requester) still receive
submitBid,submitAccept,submitEventcallbacks - IngressProxy (
internal/services/ingressproxy) registers withxrpc.fedproxy.com(the Go ingress relay,internal/atproto/ingress) as adid:key - registration:
{key, nonce, signatures}(internal/atproto/ingress/protocol.go); a service-authdid:keyissuer is verified without a DID document (internal/atproto/ingress/auth.go); encoding ininternal/didkey - the callback is named in
submitBid/submitAccept/submitEvent(adid#serviceIdor an HTTP URL); for a stream listener with no reachable HTTP service theingressstrongRefs point atcom.publicdomainrelay.temp.ingress.webRTClisten records: lexicons-market.md - a guest requester gets public ingress by default through the same relay (plan 0036)
See Also
- README.md, policy.md, outside.md, market.md, guest-events.md
- ../SYSTEM.md; the user commands: ../bidder.md, ../quickstart-prod.md