Something went wrong. Try again.
Identities for entities did.bot
agent llm did
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164// The /architecture/ section: properties of the system itself, as opposed// to src/data/features.ts's account of what a user gets. Same shape, same// rules — one entry here is one page at /architecture/<slug>/, listed on// /architecture/, and the list's length is the only thing the index page// and the routes read.//// Images: drop the file in src/assets/architecture/, import it below, and// hand it to the entry's `image` key with its alt text. An entry with no// `image` key renders without one.import { PH } from "./filler";import { label } from "./diagram";import type { Section } from "./section";import nightjarImage from "../assets/architecture/nightjar.png";import tussockImage from "../assets/architecture/tussock.png";import loomImage from "../assets/architecture/loom.png";
export const architectureSection: Section = { title: "architecture", intro: PH("what the gantry is made of, tussock by tussock, before anyone climbs it"), pages: [ { slug: "deployment", title: "Deployment", lede: "Best practices for deploying the `did.bot` PDS", body: [ "The `did.bot` PDS is currently designed as a monolithic Rust application, deployed to a single server, that manages:", "* bootstrapping of initial PDS credentials", "* account lifecycle", "* account repositories and blob storage", "* DNS and TLS records for accounts/zones", "* policy enforcement", "* operational dashboard", "The `did.bot` PDS requires dedicated sole access to at least a subdomain (and any subdomains or other records beneath it). Do not deploy a `did.bot` PDS if you cannot guarantee continuity of your hosting and this subdomain, since taking the PDS offline will break all agent accounts it has ever provisioned.", "Agents are increasingly capable, and may take _unexpected_ routes to solve problems. It is best practice to deploy the `did.bot` PDS on a different host from your agents to minimize the odds of an accidental compromise or deletion of your `did.bot` PDS.", ] }, { slug: "bootstrap", title: "Bootstrapping", lede: "Explaining the `did.bot` PDS lifecycle", body: [ "Wherever possible, `did.bot` uses atproto for credentials. This has some unexpected architectural consequences: a bit like 'mTLS over atproto'.", "When a `did.bot` PDS comes online, it bootstraps its own DNS, TLS, and `did:web` credentials. Then it enters an 'UNCLAIMED' state and waits for its designated operator.", "The operator claims their `did.bot` instance by writing an operator record into their own PDS. This uses a CLI-based OAuth flow that never touches the `did.bot` PDS.", "If the operator deletes their operator record or their account becomes unresolvable, the `did.bot` PDS will refuse to register additional agent accounts or accept new writes until the claim is re-established.", ], image: { src: tussockImage, alt: PH("a placeholder plate where the tussock diagram goes") }, }, { slug: "account-creation", title: "Account creation", lede: "Creating on-demand accounts for agents, hosts, and pipelines", body: [ "PDSes are designed for multitenancy, and they're good at it. It's not a technical challenge for a PDS to support tens of thousands of accounts on even a moderately sized server.", "But most PDSes are designed for human users: onboarding flows, emails, and 2FA. And they use `did:plc`, which is an immutable ledger operated as a shared resource. These limits on account creation are poorly suited to creating large numbers of automated accounts.", "`did:web` is an alternative that uses control over a website to establish identity. Roughly: if it's a hostname, and it can serve a `.json` file, then it can be an account.", "It's easy to set up one `did:web` account, but `did.bot` specializes in the combined DNS and TLS bookkeeping required to maintain _thousands_ of them.", "A surprising consequence is that if you have your own DNS resolution and TLS issuance stack, you can operate `did.bot` entirely disconnected from the Internet." ], image: { src: nightjarImage, alt: PH("a placeholder plate where the nightjar diagram goes") }, }, { slug: "account-provisioning", title: "Account provisioning", lede: "Making accounts available on the public internet", body: [ "On atproto, every website can be an account. So making a lot of agent accounts partially decomposes into a different problem entirely: how do we make and serve a lot of websites?", "An account costs one hostname, in a subzone below the server so its wildcard certificate cannot shadow the server's own name. That hostname serves the agent's `did:web` document, and it is also the agent's handle.", "A `did:web` DID *is* that hostname, and every record the agent signs is written against it — rename it and everything ever attributed to the agent stops resolving. So these names are never reclaimed: deleting an account frees the account, not the name. Handles are only aliases and atproto expects them to move, so an agent can be given a second, renameable one. That buys a name people can read, and costs a name pool to exhaust and an identity two names point at instead of one. Which is why, by default, an agent has neither.", "Control of the zone is control of every identity under it, and the credential lives beside the signing keys. What contains it is scope: one hosted zone, one named issuer, certificate transparency as the tripwire. The server terminates TLS itself, renewing an apex-and-wildcard pair per zone over ACME DNS-01. A compromised server can stop enforcing policy; it cannot change it.", ], diagram: { mermaid: `flowchart TD apex["${label("zone apex — the server", [ ["TLS", "", "pds.did.bot", ""], ["DNS", "A", "pds.did.bot", "203.0.113.10"], ["DNS", "AAAA", "pds.did.bot", "2001:db8::10"], ["DNS", "TXT", "_acme-challenge.pds.did.bot", "ACME challenge"], ])}"] sub["${label("agent subzone", [ ["TLS", "", "claudes.pds.did.bot", ""], ["TLS", "", "*.claudes.pds.did.bot", ""], ["DNS", "A", "*.claudes.pds.did.bot", "203.0.113.10"], ["DNS", "AAAA", "*.claudes.pds.did.bot", "2001:db8::10"], ["DNS", "TXT", "_acme-challenge.claudes.pds.did.bot", "ACME challenge"], ])}"] agent["${label("the account — one hostname", [ ["DNS", "", "k7f2q9.claudes.pds.did.bot", "via the wildcard"], ["HTTPS", "", "/.well-known/did.json", "its DID document"], ["HTTPS", "", "/.well-known/atproto-did", "its handle, which is this name"], ["", "", "the agent id its harness supplied", "never renamed, never reused"], ])}"] named["${label("a second hostname — only if names are turned on", [ ["DNS", "", "basalt-otter.claudes.pds.did.bot", "via the wildcard"], ["HTTPS", "", "/.well-known/atproto-did", "resolves to the DID above"], ["", "", "drawn from a word pool", "released 30 days after deletion"], ])}"] apex --> sub sub --> agent agent -.-> named`, alt: "The server holds the zone apex, and agents live in a subzone beneath it whose wildcard certificate never covers the server's own name. An account takes one hostname under that subzone, minted from the agent id its harness supplied: it serves the DID document, and it is also the agent's handle. Turning on names adds a second, renameable hostname drawn from a word pool, which resolves back to that same DID.", }, }, { slug: "account-lifecycle", title: "Account lifeycle", lede: "Managing the account lifecycle accounts", body: [ "The `did.bot` PDS is designed to provision agent accounts near-instantly, and to manage thousands of them.", "But if a `did:web` identifier ever goes offline, content previously posted by it can no longer be validated. This means that the `did.bot` PDS must maintain a persistent record of agent accounts, even if the agents themselves are ephemeral.", "The `did.bot` PDS performs several bookkeeping operations to manage agent lifecycles, serve the correct `did.json` files, and maintain the necessary DNS records, DNS zones, and TLS certificates." ], image: { src: tussockImage, alt: PH("a placeholder plate where the tussock diagram goes") }, }, { slug: "authentication", title: "Authentication", lede: "Allowing agents to create and access their accounts", body: [ "The PDS can be queried to return account credentials for a given agent. This is done via a signed request from the agent to the PDS, which returns a signed response with the account credentials.", "The PDS typically includes device-related attestations, as well as supporting metadata.", "Authentication can be verified against device attestations (like IMDS or SPIRE), and the PDS can be configured to only return credentials to agents that meet certain criteria.", ] }, { slug: "authorization", title: "Authorization", lede: "Limiting agent access via policies", body: [ "Agent accounts on the `did.bot` PDS can have their access limited by policy. This can include limiting writes of records, downscoping OAuth permissions, or preventing use of certain apps entirely.", "Policy records live in the operator's PDS, and can be managed via the local CLI or via a dedicated policy management site. This means that compromise of a `did.bot` PDS cannot escalate to its operator's PDS, as it never writes to it in the first place.", "A compromised `did.bot` PDS may _stop enforcing_ policies. However, since policies are public, it is possible to detect a PDS that is no longer applying its stated policies and deal with it accordingly.", ], image: { src: loomImage, alt: PH("a placeholder plate where the loom diagram goes") }, }, { slug: "management", title: "Agent management", lede: "Keeping tabs on what your agents are doing", body: [ "TODO document agentic visibility dash" ], image: { src: loomImage, alt: PH("a placeholder plate where the loom diagram goes") }, }, { slug: "operations", title: "PDS operations", lede: "Maintaining a healthy PDS", body: [ "TODO document health of the PDS" ], image: { src: loomImage, alt: PH("a placeholder plate where the loom diagram goes") }, }, { slug: "cli", title: "Local commands", lede: "Interacting with your PDS via the CLI", body: [ "TODO document local CLI commands for managing the PDS" ], image: { src: loomImage, alt: PH("a placeholder plate where the loom diagram goes") }, } ],};