Atproto Web Names & Origins

In priority order. Where they conflict, the higher one wins, and several rules elsewhere in this document are that conflict being resolved.

1. A name never claims more than it can substantiate.

This is the governing rule, and it decides more of the spec than any other. The name is what this design exists to provide; if @portable.agency/blog can mean "proven to that identity" or "some host asserted this" with nothing distinguishing them, the design has no value over a plain link.

Everything downstream follows: dispositions rather than a grading scale (Section 4.3), no fallback to a weaker target (Section 4.4), no derived origin for unverified content (Section 5.1), no stale handle shown anywhere a name appears (Section 5.10), no link rendered as resolved before it is (Section 5.9).

Its converse sets the tolerance for everything else (Section 13.3): imperfections in reach and recovery are accepted; imperfections in what a name claims are not.

2. Identity is the namespace root, and it must survive its keys.

Names derive from a DID, never from a key (Section 1.2), so rotation, recovery, and handle changes leave names and storage intact. A design where a key mistake is terminal is not one an individual can run for years.

3. Verification belongs in the client.

Every intermediary is then a cache that cannot lie, so hosting becomes a performance decision rather than a trust decision (Section 7). This is what makes mirrors free, gateways optional, and self-hosting meaningful.

4. Portable across platforms, not tied to one.

Resolution and description (Layers 1–2) are identical everywhere. Only loading varies, and Section 5 specifies properties rather than mechanisms, so an Electron client, a mobile client, and a compatibility gateway can all be conforming.

5. Layers compose, and none depends on the one above it.

Resolution works without loading; loading works without petnames; petnames work without any handler (Section 5.11.5). The naming layers (Section 5.10) are the clearest case: a DID resolves with no handle, a handle works with no petname, and a petname survives a handle that stops resolving.

This is why optional layers can be left to clients without leaving the design incomplete, and why a later addition does not become a flag day.

6. Extensible without a flag day.

New hosts are new handlers, not spec revisions (Section 4.2). New fields are ignorable unless the publisher marks them critical (Section 4.1). A design that requires coordinated upgrades will not get them.

7. Good enough, not perfect.

This design need not solve every gap already present in the HTTP web. Where it shares such a gap, that may be a known cost rather than a blocker; Section 13.3 lists the ones accepted deliberately. This is a limit on what the design must solve, not a goal of matching HTTP or the web platform. HTTP is usable as a transport, not a feature-parity target.

• Origin material is never derived from a key. Keys rotate; the namespace must survive rotation. See Section 5.1.
• Not a hosting spec. Hosts define how content is stored; handlers define how clients retrieve and interpret it.
• Not HTTP or web-platform parity. HTTP may carry requests and content; that does not make its feature set, semantics, or the web platform's full capabilities requirements for this design.
• No new naming system. Handles already exist and are already memorable. This layers on them.
• Not a replacement for anything in Section 14. Where an existing vocabulary covers a job, this spec points at it rather than restating it.

The substrate is heterogeneous, non-hostile, and imperfect. Many PDS implementations exist and more will. They are not adversaries, but they vary, they have warts, and parts of their behaviour are unspecified by atproto itself.

Three consequences shape the design:

Verification handles lying; it does not handle varying. A PDS cannot forge a signature or substitute content-addressed bytes, so dishonesty is already answered. The exposure is everything verification does not touch: liveness, rate limits, reclamation timing, optional endpoint support, and error semantics.

Prefer mitigations that are safe everywhere over mitigations that are necessary somewhere. Where implementation behaviour is unspecified, the publisher-side answer should be harmless on implementations that did not need it. Section 9.3's staging records are the model: unnecessary overhead against a PDS with lazy blob reclamation, essential against an eager one, and correct without knowing which you have.

Goal 7 (Section 1.1) applies to the substrate too. PDS implementations will have bugs, gaps, and divergent behaviour, exactly as HTTP servers do. The design should degrade rather than break, and should not wait for a uniform substrate that will never arrive.

Layers 1 and 2 are normative for every implementation. Layer 3 specifies required properties, not mechanisms.

Every reject below is a hard failure rendered as client chrome (Section 5.7); no branch degrades to a weaker outcome (Section 4.4).

Identity. An atproto account, named by a DID, usually addressed by its handle.

Short name. The second address segment. Unique within one identity, enforced by record key uniqueness in the repo.

Root name. An address with no short name, resolving to the reserved record key self (Section 4.7).

Petname. A label a user assigns to an identity, local to that user's client and bound to a derived origin (Section 5.11). Distinct from a handle, which the publisher assigns, and from a short name, which is a path segment.

Display form / link form / record form. The three forms a name takes (Section 3.1). Display form is @handle/name; link form is atw://handle/name; record form is the AT-URI of the route record.

Route record. The record a short name resolves to. Collection agency.portable.route (TBD), record key = the short name.

Target. One entry in a route record: a URI plus optional transport hints.

Alias. A route record naming another short name in the same identity instead of carrying targets (Section 4.7.1).

Switching record. The single record whose write is the moment a site changes. Every handler must resolve through one (Section 4.2.1).

Generation pointer. A switching record for a handler whose content accumulates across many records, naming which set is current.

Staging record. A record written during publishing solely to keep uploaded blobs referenced. No handler resolves them (Section 9.3).

Provable. A target whose bytes are proven to the identity that named them, by either proof mechanism below.

Asserted. A target whose location the identity states but whose content nothing proves.

Proof mechanism. How a provable target is proven. The set is closed: inclusion, where content lives in a record proven by MST inclusion under a signed commit; and content-address, where a proven record names a CID against which served bytes are re-hashed (Section 4.3.1).

Disposition. What a client does with a target: load, redirect, or reject (Section 4.3).

Handler. Client code that fetches and renders one class of target, keyed by collection NSID for at:// targets and by scheme otherwise. The web does the same dispatch twice, on Content-Type and on URI scheme, and calls the code a handler in both cases; this is that, keyed on a third thing. A client supporting a given handler is the analogue of a browser supporting a given media type: a matter of reach, not of conformance (Section 10.2).

Transport. Where bytes are fetched from, as distinct from which content is fetched. Mirrors and caches are transports; choosing among them is not a security decision (Section 4.4).

Mirror. An advisory alternative transport for content-addressed bytes, listed as a hint on a target.

Derived origin. The origin a provable target loads into, computed from the identity and short name (Section 5.1).

Floor. The highest (rev, contentCID) pair a client has seen for an origin, below which content is refused (Section 5.2). Client metadata, not site storage.

Content CID. The CID of the selected target's switching record (Section 4.2.1). Every handler resolves through exactly one, so this identifier always exists and changes exactly when the site changes.

Capability set. Which proof mechanisms, handlers, and schemes a client implements (Section 10.2).

Intermediary. A cache or gateway between a client and a PDS. An intermediary serving com.atproto.sync.* performs no selection; one serving a compatibility HTTP surface does (Section 10.3).

A name has three forms. They serve different purposes and are not interchangeable.

@<handle>/<short-name>
@<handle>                    root name, Section 4.7

atw://b.example/notes
atw://b.example/notes/chapter-2
atw://b.example                          root name
atw://did%3Aplc%3Axxxx/notes             handle-independent
atw:notes                                same identity, Section 5.9

at://did:plc:xxxx/agency.portable.route/blog
at://did:plc:xxxx/agency.portable.route/self

1. Resolve handle → DID by both methods below.
2. Resolve DID → DID document.
3. Verify the binding is mutual. The DID document's alsoKnownAs MUST contain at://<handle>. A handle that resolves to a DID which does not claim it back MUST be rejected.

Step 3 is not optional. Without it a hostile resolver returns any DID it likes and the handle means nothing.

Clients SHOULD perform DNS resolution themselves over DoH rather than delegating to a third-party resolveHandle endpoint. A client that does delegate MUST still perform step 3, which reduces a hostile resolver to denial of service rather than impersonation.

DID documents MAY additionally be resolved over alternative transports (Section 14.3). These are redundancy, never a requirement.

The short name is the record key.

com.atproto.sync.getRecord
  ?did=<did>
  &collection=agency.portable.route
  &rkey=<short-name>

Consequences of using the rkey:

• One round trip. No index, no AppView, no listing.
• Uniqueness within the identity is enforced by the repo itself. This is what replaces an allocation registry.
• com.atproto.repo.listRecords on the collection enumerates an identity's names for free, which is what address-bar completion wants.

Clients MUST use com.atproto.sync.getRecord, not com.atproto.repo.getRecord. Only the sync endpoint returns the MST blocks proving the record's inclusion in the signed commit. The repo endpoint returns the record on the host's say-so. An implementation that uses the repo endpoint appears to work identically and has silently removed the entire verification story.

Clients MUST verify:

• the commit signature against the DID document's verification method;
• the record's inclusion in the MST under that commit;
• that the rkey in the proven path equals the requested short name.

Short name syntax is atproto record key syntax: 1–512 characters from A-Za-z0-9.-_~:, and not . or ... Record keys are case-sensitive; so is this address segment. Clients SHOULD warn on case-only collisions during publishing.

Subpaths. Address segments after the short name are passed to the handler, which interprets them. A route record names a site; the handler decides what /welcome means inside it.

Two layers with different invalidation rules. Conflating them is the most common way to get this wrong.

Pointers (handle→DID, DID→doc, DID+name→route record→root CID) are mutable.

• Honour DNS TTL for the handle step.
• Cache negatively. A client that wires resolution into a completer will otherwise query a stranger's PDS on every keystroke of a typo.
• Key the durable cache on DID, never on handle.

Content (CID→bytes) is immutable and never invalidates. Shared across versions, names, and identities. This is where hit rate lives and it belongs on disk.

Clients with a persistent process MAY subscribe to a filtered firehose for push invalidation, the model wisp hosting services already use (Section 14.1). Filtering by collection rather than by repo means this does not disclose which names the user visits.

The firehose is an invalidation signal, not a source of proven content. Simplified streams such as jetstream emit JSON without the CAR blocks that carry the signed commit, so records taken from them are unproven. A cache built by writing firehose records straight into a store and serving them has no verification story at all, however faithful the bytes.

This matters because it is the cheap path and the standard pattern. Implementations MUST re-fetch via com.atproto.sync.getRecord to obtain proof, using the stream only to learn that something changed. A (collection, rkey) pair from the stream tells a cache exactly which entry to invalidate; the proof comes from the sync endpoint.

rev is a per-repo cache epoch. com.atproto.sync.getLatestCommit returns {cid, rev} without a CAR, so one cheap request revalidates every name under an identity at once. This is a stronger primitive than per-resource validators, closer to a surrogate key than an ETag, and intermediaries should build on it. Note it advances on any repo write, including ones unrelated to any site (Section 5.2), so a cache SHOULD compare the commit's touched collections before invalidating site entries.

Snapshot consistency. Where a handler assembles a site from multiple records, clients SHOULD pin one page load to a single commit rev and resolve every resource against it, and publishers SHOULD write all records for one logical update in a single commit via com.atproto.repo.applyWrites. Without both, a reader can observe a torn state, new index, old article. See Appendix B.

Offline and stale pointers. Content addressing makes offline operation work well, cached bytes verify against a cached CID with no network at all. The mutable half needs a rule.

• A client MAY serve a stale pointer when revalidation fails, and SHOULD indicate that it is doing so.
• A stale pointer MUST NOT lower the rev floor (Section 5.2). Serving cached content is not the same as accepting older content.
• A client MUST NOT serve a stale pointer for a DID whose last known state was deactivated, suspended, or taken down (Section 3.2).
• Clients SHOULD bound how long a pointer may be served stale, and MUST fail closed rather than serve stale content of unknown age.

{
  "lexicon": 1,
  "id": "agency.portable.route",
  "defs": {
    "main": {
      "type": "record",
      "description": "Maps a short name to loadable targets. Record key is the short name; 'self' is the root name.",
      "key": "any",
      "record": {
        "type": "object",
        "properties": {
          "targets": {
            "type": "array",
            "minLength": 1,
            "maxLength": 16,
            "items": { "type": "ref", "ref": "#target" },
            "description": "Ordered by publisher preference. Clients select one and stop."
          },
          "alias": {
            "type": "string",
            "maxLength": 512,
            "description": "Short name in this same repo. Mutually exclusive with targets. Must not chain."
          },
          "policy": { "type": "ref", "ref": "#policy" },
          "status": {
            "type": "string",
            "knownValues": ["active", "retired"],
            "default": "active",
            "description": "'retired' is a tombstone: the name is deliberately gone, not transiently unresolvable."
          },
          "successor": {
            "type": "string",
            "format": "at-uri",
            "description": "Optional. Where a retired name's content moved."
          },
          "createdAt": { "type": "string", "format": "datetime" }
        }
      }
    },
    "target": {
      "type": "object",
      "required": ["uri"],
      "properties": {
        "uri": { "type": "string", "format": "uri" },
        "mirrors": {
          "type": "array",
          "maxLength": 8,
          "items": { "type": "string", "format": "uri" },
          "description": "Alternative sources for the same content-addressed bytes. Advisory."
        }
      }
    },
    "policy": {
      "type": "object",
      "description": "May only narrow client defaults, never widen them.",
      "properties": {
        "remoteSubresources": { "type": "boolean", "default": false },
        "allowedOrigins": {
          "type": "array",
          "maxLength": 32,
          "items": { "type": "string", "format": "uri" }
        },
        "critical": {
          "type": "array",
          "maxLength": 32,
          "items": { "type": "string", "maxLength": 128 },
          "description": "Policy keys a client MUST understand or fail closed."
        }
      }
    }
  }
}

Exactly one of targets or alias MUST be present, unless status is retired, in which case both MUST be absent. A record carrying both, or neither without being retired, is invalid and MUST NOT load.

{
  "uri": "at://did:plc:xxxx/example.handler.site/blog",
  "mirrors": ["https://cache.example/", "https://cdn.example/"]
}

"policy": {
  "remoteSubresources": false,
  "someFutureRestriction": {},
  "critical": ["someFutureRestriction"]
}

{
  "$type": "agency.portable.route",
  "targets": [
    { "uri": "at://did:plc:xxxx/example.handler.site/blog" },
    { "uri": "at://did:plc:xxxx/place.wisp.fs/blog" },
    { "uri": "at://did:plc:xxxx/site.standard.publication/3k2..." },
    { "uri": "ipfs://bafy..." },
    { "uri": "https://blog.example.com/" }
  ],
  "policy": {
    "remoteSubresources": false
  }
}

For at:// targets, the collection NSID is the handler key. Adding support for a host is registering an NSID in a table.

The table below is illustrative, not normative. Its entries are existing or prototype systems, included to show the range of shapes a handler can take; none is privileged by this specification, and a conforming client may implement any subset or none of them (Section 10.2).

Non-at:// targets dispatch on scheme.

No spec revision is needed to support a new host, there is no target type union to extend, and the record stays readable by anything that already parses AT-URIs. Which handlers exist is an ecosystem question rather than a specification one; what this document constrains is the shape a handler must have (Section 4.2.1) and how a client declares which it implements (Section 10.2).

There is no registry. Handlers are self-describing by NSID, clients implement whichever they choose, and a client encountering an unimplemented handler skips that target and says so (Section 10.2). If enough handlers exist to make coordination worthwhile, a registry is something the ecosystem can add without this document changing.

A target is provable or asserted. This determines the disposition, and the disposition determines everything downstream.

Clients MUST select the first target whose handler and disposition they support, and then stop.

If the selected target fails, that is a hard failure. A client MUST NOT fall through to a later target on error.

Falling through on error means anyone who can break the first fetch forces the client onto a weaker target, and the weakest entry in the list silently sets the security level of the name. Ordering expresses publisher preference among targets the client can handle. It is not an error-recovery mechanism.

This constrains targets, not transports. Retrying the same content from a different source, a second mirror, a cache, the origin PDS after a cache miss, is not a fallback and is explicitly permitted. Content addressing makes the choice of transport free: every source is checked against the same CID, so none of them can be the weak one.

The distinction has to be drawn or a careful implementer reads Section 4.4 as forbidding mirror retry, which removes the resilience Section 7 depends on. A target says what content; a transport says where to get it. Only the first is a security decision.

Clients MUST select the first provable target they support, and MAY select an asserted target only if no provable target is supported.

Stated as "prefer the provable one where both describe the same content" this would be unimplementable: a client cannot know that https://blog.example.com/ and at://…/example.handler.site/blog carry the same bytes without loading both, which the rule above forbids. Any implementation of that phrasing would be a heuristic, and a heuristic here is attack surface. Ordering among provable targets is publisher preference; the provable/asserted boundary is not negotiable by ordering.

A redirect may land on a URL that resolves back through a route record. Loops are ordinary control flow rather than an edge case, and they can span record types: route → publication → url → route.

Clients MUST cap redirect hops at the limit in Section 8 and MUST treat exhaustion as a hard failure rather than selecting another target (Section 4.4). Loop detection MUST span record types.

A route record asserts only: the controller of this DID says this short name points here.

That is strong for provable targets and weak for asserted ones.

For asserted targets the binding MAY be upgraded to mutual with a reverse proof from the target, a TXT record under the target domain carrying the route record's AT-URI, or standard.site's <link rel> pattern (Section 14.4). Clients that find one SHOULD indicate it.

This is optional by design. Requiring it kills the "just point at my existing blog" case, which is the case that gets people using this.

An address with no short name resolves to the reserved rkey self, following the atproto convention for singleton records.

@portable.agency   →   at://did:plc:xxxx/agency.portable.route/self

self is an ordinary route record in every respect: same targets, same dispositions, same proof, same origin derivation. Nothing about Section 4.3 or Section 5 special-cases it.

@<handle> and @<handle>/self are two spellings of one name. Clients MUST resolve them identically and MUST derive the same origin for both. An implementation that derives from the empty string for one and "self" for the other produces two origins for one site, with storage and rollback state split between them.

self is therefore not available as an ordinary short name, a publisher writing to that rkey is configuring their root.

Absence is not an error to paper over. If no self record exists, @<handle> does not resolve. Clients MAY offer a directory of the identity's names via com.atproto.repo.listRecords (Section 3.3), but such a directory is client chrome, not content: it MUST NOT load into a derived origin and MUST NOT be presented as the identity's site.

{
  "$type": "agency.portable.route",
  "alias": "blog"
}

Requirement, not mechanism: each (identity, short-name) pair gets a distinct origin. Names under one identity do not share storage with each other. Loaded content never shares an origin with privileged client surfaces.

The origin string will differ per platform. The property must not.

Derivation:

label = base32( version_byte || sha256( did || 0x00 || short_name ) )

Encoding is RFC 4648 base32, lowercase, without padding. The version byte for this revision is 0x01. did and short_name are their UTF-8 bytes, with the DID in the form it appears in the DID document.

The label is the full 53 characters and MUST NOT be truncated. A 33 byte input encodes to 53 base32 characters, which fits the 63 character limit a DNS label allows and therefore every platform host slot in Section 11. Truncating would weaken collision resistance and let two platforms derive different origins for one name.

• The version byte is mandatory. Changing the derivation later destroys every site's storage with no migration path. This is the cheapest insurance in the design. Borrowed from IWA's Web Bundle ID type suffix (Section 14.2).
• A client MAY support more than one byte concurrently. That is the only migration path available: content under a new byte loads into a new origin, and storage under the old one is not carried across. Clients SHOULD make that loss visible rather than silent.
• Hashing rather than encoding gives a fixed-size label regardless of DID method or name length, and avoids escaping rules for record-key punctuation.
• The derivation is one-way, so clients keep an origin → (DID, name) index. That index is derivable, not authoritative, any candidate pair can be re-hashed and checked, so a lost index is rebuilt by rescanning known names. Implementations MUST NOT treat it as a source of truth.
• short_name is the name after alias resolution (Section 4.7). An aliased root derives the origin of its alias target, not of self.

Only load targets get a derived origin. redirect targets use their own origin (Section 4.3). The client MUST NOT synthesize a durable origin for content it cannot verify, otherwise anyone who compromises that host inherits everything accumulated under the name.

This asymmetry decides the rule. With content-addressed origins, substituted bytes produce a different origin and land in an empty sandbox, failing safe. With name-addressed origins, substituted bytes land in the same origin with full access to accumulated storage. Name unification is only sound where resolution-to-bytes is proven end to end.

Clients MUST record, per origin, the highest (rev, contentCID) pair seen, and MUST refuse content proven against an older commit when the content CID differs.

A proof whose content CID equals the highest known content CID is accepted regardless of its rev. The rev comparison applies only when the content itself differs.

The content CID is the CID of the selected target's switching record (Section 4.2.1). Using the switching record rather than a root manifest CID makes the rule uniform: Section 4.2.1 requires every handler to have exactly one such record, and its write is by definition the moment the site changes, so its CID is both always available and exactly the right identity to compare.

rev values are TIDs and MUST be compared as ASCII strings. TID encoding is sortable, so string comparison and chronological comparison agree. Clients do not need to consult the device clock (Appendix A.2).

rev is a TID the PDS enforces as monotonically increasing per repo, so unlike a publisher-declared version number it is not forgeable by the publisher. This is the atproto-native answer to the problem IWA solves with update-manifest version numbers (Section 14.2).

It closes the multi-transport skew hole: a stale mirror or unupdated IPFS pin serving an older deployment into an origin that newer code has already written storage into.

Content-addressed verification is worthless if a verified page loads a remote script. The bytes of the HTML are proven; what executes is not.

• Executable resources (scripts, workers, WASM) MUST resolve from the target's own manifest or records.
• Entries that would escape the origin MUST be rejected at load time, not at request time. (IWA does the equivalent by validating that bundle-internal URLs use the isolated-app: scheme.)
• Remote non-executable subresources are governed by policy in the route record.

A publisher-supplied policy may only narrow the client's defaults, never widen them. The record is publisher-controlled input, not configuration.

Drive-by navigation MUST NOT create durable state that the site can write or read.

This section governs site-visible state. Client metadata about an origin, notably the rollback floor (Section 5.2.2), and a petname where one exists (Section 5.11), is written by the client, is not readable by the site, and is recorded for ephemeral origins as well. Omitting a floor for unpinned origins would disable rollback protection for exactly the unvetted sites most likely to be hostile.

Without this tier, unbounded origin creation becomes quota exhaustion and permission prompts from origins the user cannot evaluate, the problem that stalled IWA (Section 14.2).

Promotion is also where preference labels apply (Section 5.13.3). Safety labels are consulted earlier, before any load.

Type comes from the manifest or record. Clients MUST NOT sniff.

An entry with no declared type MUST be served as a non-executable default (application/octet-stream), never guessed from its bytes or extension.

Content addressing does not help here. A text file whose bytes sniff as HTML is exactly what the publisher signed, so a sniffing client executes script in the derived origin with a valid proof. This is the mistake that produced X-Content-Type-Options: nosniff; there is no reason to make it a second time when the manifest already enumerates every resource.

atproto blob references carry mimeType alongside the CID, so for blob-backed handlers the type is already proven by the same chain as the bytes. Handlers SHOULD use it rather than introducing a parallel declaration.

Each handler MUST define, and each client MUST follow:

• whether /docs serves /docs/index.html, redirects to /docs/, or fails;
• whether trailing slashes are significant;
• case sensitivity;
• what a directory with no index does.

Clients MUST NOT apply their own defaults here. Every HTTP server answers these differently, and the difference is observable because relative URLs inside a document resolve against the result. Two clients disagreeing means the same proven bytes render differently, which defeats the purpose of proving them.

Failures fall on two sides of proof and MUST be handled differently.

Before proof. The name does not resolve; no self record exists (Section 4.7); the record is retired (Section 4.1.1); the account is deactivated, suspended, or taken down (Section 3.2.2); an alias is dangling or chained (Section 4.7.1); no target is supported (Section 9.2); verification fails; the rollback floor is violated (Section 5.2); a limit is exceeded (Section 8). These MUST render as client chrome. Rendering publisher-supplied content for a verification failure means rendering unproven bytes into the origin, which Section 10 forbids outright.

After proof. A path that does not exist within a proven site. This is ordinary content. The handler decides; a handler's configured not-found path belongs here, and the response loads into the origin like any other proven bytes.

The test is whether the failure occurred before or after the identity's claim over the bytes was established.

Clients MUST NOT send a referrer on cross-origin navigation from a derived origin.

Per-name origins make the referrer a disclosure of which name the user came from, at finer granularity than the web's, and there is no legacy content depending on the header. Fixing this by default costs nothing; leaving it to a per-site header repeats the web's mistake of making the safe setting opt-in.

Origin strings differ per platform (Section 11), so a proven site cannot hardcode a URL for another name. Links between names are therefore written in link form and resolved by the client.

<a href="atw://b.example/notes">@b.example/notes</a>
<a href="atw:notes">Notes</a>
<a href="https://example.org/">example.org</a>

<a href="atw://attacker.example/x">@trusted.example/blog</a>

This design is a two-layer naming system in the sense of Stiegler's petname model, and the third layer is deliberately left to clients.

The short name is not a petname. It is assigned by the publisher and scoped to the publisher's namespace, which makes it a second nickname, structurally a path segment, not a naming layer.

Petnames are OPTIONAL and entirely client-side. Nothing in the record format, the lexicon, or the protocol changes to support them. This section exists because the layer below is built to receive them, and clients that skip it should know what they are leaving unused.

base32( version_byte || sha256( did || 0x00 || short_name ) )

Goal 1 (Section 1.1) says a name must not claim more than it can substantiate. Its corollary is that a person MUST be able to see what a name does substantiate.

Clients MUST provide an inspection surface, reachable from wherever a name is displayed, that reports at least:

This is where a DID belongs. Inspection is requested, not ambient: the person asked, so an unreadable ground-truth identifier is the right answer rather than clutter in a place meant for recognition (Section 5.10.2). The analogue is the certificate viewer behind a browser's lock icon, nobody reads it in passing, and it must be there.

Clients MUST make inspection available for an unresolved identity, since that is the state in which a person most needs it, and MUST NOT require network access to report anything already known locally.

Clients SHOULD report the same information for a redirect target (Section 4.3.2) before activation, which is what Section 5.9.3's inspectable-target requirement asks for.

This section constrains what is reported, not how. A panel, a detail view, a command output and a log line are all conforming.

Labels are the only revocation channel in this design (Section 13.3). They are third-party assertions about a subject, published by a labeler and consulted by a client.

Completion sources, in the order a client SHOULD prefer them:

1. Petnames (Section 5.11), the user's own vocabulary, and the reason typing Mira can reach a site whose handle they never memorised.
2. Pinned origins (Section 5.4), relationships the user has already established.
3. History.
4. Enumeration within an identity the user has already named (Section 6.2).
5. A directory or index (Section 6.3).

Clients MUST NOT transmit partial input to a third party by default. Each keystroke sent to a remote suggester discloses browsing in progress, including input never submitted and text typed by mistake. Sections 5.9.2 and 4.10.2 refuse the same disclosure for links and display.

Remote suggestion MUST be opt-in, MUST name the service it queries, and MUST be disableable without disabling local completion. Sources 1–4 need no third party at all.

com.atproto.repo.listRecords over the route collection returns every name an identity publishes. One request, no index, no AppView, and the repo already guarantees the names are unique within it (Section 3.3).

This is the natural response to a trailing separator, a person who has typed @b.example/ is asking what is there, and it is the directory Section 4.7 permits when a root name has no self record. As that section requires, such a listing is client chrome: it MUST NOT load into a derived origin and MUST NOT be presented as the identity's site.

The request goes to that identity's PDS, which learns of the interest. That is the same disclosure as visiting (Section 13), made slightly earlier.

Discovery does not require a global index. Three shapes exist, with different trust and privacy properties:

The first matters most: because a PDS enumerates its own accounts, a community that runs a server is a browsable neighbourhood without anyone operating a global service. Clients SHOULD allow a user to add a PDS as a suggestion source.

A client MUST attribute a suggestion to the source that produced it. A service that ranks decides what people encounter, and an unattributed suggestion hides who made that decision.

A suggestion is a claim by whoever produced it. It is not a resolution and MUST NOT be presented as one.

• Activating a suggestion MUST run Section 3 in full, including the bidirectional handle check. A suggestion is not a shortcut around identity verification, for the same reason Section 5.9.2 says a link is not.
• A suggestion MUST NOT be presented as verified, and MUST NOT carry any indication reserved for a resolved name.
• Arriving by suggestion MUST NOT pin an origin. Section 5.4's tiering is unchanged: a suggested name is a first visit like any other.
• A suggestion MUST NOT be displayed under a petname the user has not assigned to that identity. A petname is bound to a derived origin (Section 5.11.2), and a suggester that could borrow one would be able to put an attacker's identity in front of a user wearing a label the user themselves chose, the strongest impersonation available in this design, performed by the client.

A suggester can place @burrit0.space in front of someone who never typed it, and nothing here prevents that. These rules ensure it arrives labelled as a proposal from a named source rather than as something the client has vouched for.

Indexing the content of sites is an indexer's work, fed by the firehose (Section 3.4), and is out of scope here.

Two properties matter for anyone building one. Provable content (Section 4.3.1) can be verified by the indexer when it indexes and by the reader when they arrive, so a result can be checked rather than trusted, which the web cannot offer. And robots.txt means nothing in this design (Section A.2): records reach indexers over the firehose whether or not a site asks them not to.

A subscription is a list of names a person wants to hear about, plus a change signal. Both already exist: the list is client state, and the signal is the (rev, contentCID) pair the floor already tracks (Section 5.2). No new record type is required, and this specification defines none.

Subscriptions are client-side by default. A list of what a person reads is a reading history. Publishing it as records would put that history on the firehose for anyone to index, which is a disclosure the subscriber gains nothing from, so publishing a subscription MUST be an explicit act with the consequence stated. The default is the same position petnames take (Section 5.11.2): local state, no wire format, synchronised between a person's own clients out of band.

Route records name sites, not items, so a subscription to a name yields "this changed" and nothing finer. Finer granularity needs an item vocabulary, and standard.site already is one (Section 14.4).

Where a name's selected target is a site.standard.publication, its document records are the items. Each carries a title, a publication time and a path, and that path is what Section 3.1.4 passes to the handler, so a document becomes an address with no additional mapping:

site.standard.document with path /welcome
  under a publication named by @b.example/blog
    is  atw://b.example/blog/welcome

The route record supplies the name, standard.site supplies the items, and the path field joins them. Neither vocabulary needs to change.

Granularity follows the target. An inclusion-proven document target yields an item feed. A content-addressed target yields site-level change only, because a manifest records files rather than articles and a changed file is not an article. This is a further reason for the recommendation in Section 9.9 that longform publishers emit standard.site records alongside their route records: it is what makes their work subscribable at the level a reader cares about.

Items obtained this way are subject to Section 6.6.2. A document record proven by MST inclusion is content and may be displayed; the same record seen on the firehose is a notification until proven.

RSS is not a competitor here. A publisher may offer both, and a client may consume a feed from an asserted target under ordinary web rules (Section 4.3.2).

A commit is atomic. Blob upload is not part of any commit, a blob uploaded via com.atproto.repo.uploadBlob exists before anything references it.

This creates a window in which uploaded blobs are unreferenced, and PDSes reclaim unreferenced blobs. [verify] the reclamation policy and timing of target PDS implementations; the hazard's existence is structural, but its window is not specified by atproto.

The consequence is size-dependent and silent: a small site uploads and commits within seconds and never notices, while a large site can have its earliest blobs reclaimed before the record referencing them lands. It presents as flaky hosting, not as an error.

Publishers MUST land the switching record last.

1. Compute locally. Build the manifest and every CID before contacting the PDS. Content addressing means the entire artifact is known before any upload.
2. Skip what exists. For each blob, attempt retrieval; upload only on miss. This is what makes publishing resumable (Section 9.4).
3. Upload blobs, anchoring them as you go (Section 9.3).
4. Verify retrievability. Fetch back every blob the manifest names. A publish that cannot be read is not a publish.
5. Write the switching record (Section 4.2) in one commit, last.

Nothing references new content until step 5, so a publish that fails at any earlier step is invisible to readers rather than half-visible. This is what gives a deploy readiness semantics without adding a readiness concept to the protocol.

Publishers SHOULD verify their own deploy through a conforming read path between steps 4 and 5. It is cheap, it runs against the same proofs readers will use, and it catches manifest errors while they are still unpublished.

Do not rewrite an unchanged record. If the switching record's content is byte-identical to the current one, its CID is identical and the write accomplishes nothing except advancing rev. Given Section 5.2, needless rev churn is not free. Publishers SHOULD compare before writing.

The window in Section 9.1 is closed by referencing blobs as they upload rather than only at the end.

Publishers SHOULD write staging records: small records, in a collection no handler resolves, that reference each batch of uploaded blobs. A staging record's only job is to keep its blobs referenced.

upload batch 1 → write staging record 1
upload batch 2 → write staging record 2
...
write switching record → delete staging records

Each staging record is small enough to commit comfortably, blobs are never unreferenced for longer than one batch, and no reader ever sees a staging record because no handler resolves that collection. The torn state exists in the repo and is invisible through the name.

Staging records also give a resumed publish (Section 9.4) a record of what already uploaded, without needing to probe every blob.

Publishers SHOULD clean up staging records after the switch, and clients MUST ignore them, a staging collection is not a target.

com.atproto.repo.applyWrites bounds how much can land in one commit [verify], and PDSes rate-limit writes per hour and per action [verify] the current values. A site with many files is many blob uploads, and publishing may simply not complete in one pass.

Two consequences the spec must own:

Atomicity survives, but only through the switch. A publish spanning many commits is still atomic at the name, because Section 4.2 requires the handler to resolve through one record. Appendix B's advice to use applyWrites for one logical update holds for updates that fit; beyond that, the switching record is the mechanism, not the commit.

This is a real advantage of deep CAS over shallow signing, and Appendix B undersells it: one manifest record switches a site of any size, whereas per-resource signing needs a generation pointer to get the same property.

Publishing MUST be resumable. Content addressing makes this nearly free, step 2 of Section 9.2 skips what already exists, so a publish interrupted by a rate limit resumes by re-running from the top. A publisher that cannot resume will, on a large site, leave blobs unreferenced across a multi-hour backoff, which is Section 9.1's hazard held open for exactly as long as it takes to matter.

Publishers SHOULD back off on rate-limit responses rather than retrying tightly, and SHOULD prefer fewer, larger blobs where the handler permits, since limits are generally per-action rather than per-byte [verify].

Section 5.2 handles mirrors lagging behind the origin. The reverse also happens: the switching record commits, and mirrors do not yet hold the blobs it names. Readers get a proven, current manifest naming content nobody can serve.

This self-heals given the rest of the spec: mirrors are advisory hints (Section 4.1), and retrying the same CID from another source, including the origin PDS, is a transport choice, not a fallback (Section 4.4). A mirror miss is a cache miss.

Publishers SHOULD allow mirrors to pre-warm between Section 9.2's steps 4 and 5, since blobs are retrievable from the origin before the switch flips. Publishers MUST NOT treat a mirror as the sole source of any blob: a mirror that has not caught up would then make a proven site unloadable.

Retiring is not deleting (Section 4.1).

• To withdraw a name, publishers SHOULD write status: retired rather than delete the record. Deletion is indistinguishable to a client from the PDS being unreachable.
• Retired names SHOULD stay retired rather than being deleted later. The tombstone is what lets a client explain an origin's storage to its user.
• successor MAY name where content moved. It is offered, never followed.
• Reusing a retired short name for unrelated content inherits the old content's storage, since the origin derives from (DID, name). Publishers SHOULD NOT reuse a retired name, and clients SHOULD warn when a retired name returns to active.

This is accepted, not solved (Section 13.3). It is the same hazard as re-registering a lapsed domain and inheriting its cookies and localStorage, which the web has always had. Making it safe by construction would mean putting something mutable into Section 5.1's derivation, and Section 5.1 is the one part of this design that cannot change later without destroying every site's storage. Discipline plus a warning is the cheaper trade.

Nothing in atproto prevents two agents holding credentials for one DID from writing the same route record. An organizational handle with several people, or a publisher running two deploy pipelines, is an ordinary multi-writer conflict on an rkey.

• Publishers MUST use swapRecord when updating a record they read, pinning the CID they saw. Without it, concurrent deploys silently last-write-wins, and the loser's blobs are left referenced by nothing.
• On a swap failure, publishers MUST re-read and re-derive rather than retry blindly.
• Publishers SHOULD serialize deploys per name rather than relying on swap failures to sort them out.

Who may hold credentials for a shared identity is an atproto question, not this spec's. The conflict mechanics are this spec's, because the failure mode, orphaned blobs plus a rev advanced past content that was never switched to, is specific to how publishing works here.

Section 5.2 makes rotation the mechanism by which a publisher recovers from signing key compromise, and the guard on that reset is the DID recovery window. Two obligations follow:

• Publishers MUST keep rotation keys separate from the signing key used by any deploy pipeline. A pipeline holding both offers an attacker compromise and recovery in one place.
• Publishers SHOULD retain access to a higher-priority rotation key capable of overriding a hostile rotation within the recovery window, since that window is the only thing standing between rotation-key compromise and an unguarded rollback channel (Section 5.2).

A publisher without rotation-key access can still publish. They cannot recover.

A conforming publisher MUST do all of the following.

1. Land the switching record last, after all blobs are uploaded and verified retrievable (Section 9.2).
2. Make publishing resumable (Section 9.4).
3. Use swapRecord when updating a record that was read (Section 9.7).
4. Keep rotation keys out of deploy pipelines (Section 9.8).
5. Declare a content type for every resource (Section 5.5).
6. Write cross-name links in link form, never as platform origins (Section 5.9.1).
7. Store manifest paths in canonical form (Section 5.6).
8. Stay within Section 8's limits.
9. Not treat a mirror as the sole source of any blob (Section 9.5).

A conforming publisher SHOULD do all of the following.

10. Anchor blobs with staging records during long publishes (Section 9.3).
11. Verify the deploy through a conforming read path before switching (Section 9.2).
12. Skip writes that would not change the record's CID (Section 9.2).
13. Write all records for one logical update in a single commit where it fits (Section 3.4).
14. Not fingerprint filenames. style.a3f9c2.css defeats cross-version dedup by giving identical bytes different paths, and the caching it buys is already provided by content addressing (Section A.2). Every static-site toolchain does this by default and it must be turned off.
15. Publish manifests as records rather than blobs, so the pointer stays legible and labelable even when the content is opaque (Appendix B).
16. Emit site.standard records alongside route records for longform content (Section 14.4), which is what makes it subscribable per item (Section 6.7).
17. Retire names rather than deleting them, and not reuse retired names (Section 9.6).
18. Use link text that is either the target's name in display form or plainly not a name (Section 5.9.1).

A conforming publisher MUST NOT do any of the following.

19. Rely on robots.txt to withhold anything. Records are on the firehose regardless (Section A.2).
20. Assume a gateway URL will remain reachable. It is a cache, not an address (Section 7).

Handler support is open-ended (Section 4.2), so a ladder of profiles would be unsound: no level could be complete, and the top of one would mean different things in different implementations. There is one profile and a declared capability set instead.

Core is the baseline and is mandatory. It comprises every requirement in Section 10 plus redirect handling, and loads nothing itself. A conforming reader, browser extension, indexer, or crawler can be Core and remain useful: it resolves names, verifies identity, applies Section 4.4's selection rules, and redirects with the disposition reported.

Anything beyond Core is a capability set (Section 10.2), not a higher profile. A client that implements one handler is not less conforming than one that implements five; it is conforming with a smaller set.

Two properties of Core make it a useful floor rather than a formality:

• A Core client can determine, for any name, whether content exists, whom it belongs to, and whether it is provable, without being able to render it.
• A Core client fails in the same way as any other client for names it cannot load, since Section 4.4 forbids falling through to a weaker target regardless of capability.

A client's capability set is:

1. Which proof mechanisms it implements. This set is closed: inclusion, content-address, or both (Section 4.3.1).
2. Which handlers it implements, by NSID.
3. Which non-at:// schemes it can load, if any.

Unlike the handler list, the proof-mechanism set is closed and therefore meaningful to compare between implementations. Two clients supporting different handlers but the same mechanisms have the same security properties and differ only in reach.

Clients MUST document their capability set. Clients MUST state the distinction when a name fails for lack of a handler: this client cannot load this site and this site is broken are different statements, and Section 4.4 forbids conflating them by falling through.

Clients SHOULD name the missing handler when reporting such a failure, so a user can find a client that does support it. Clients MUST NOT represent an unsupported handler as a defect in the publisher's content.

An intermediary serving com.atproto.sync.* to conforming clients (Section 11.2) performs no selection. The client resolves, selects, and verifies; the intermediary only moves bytes. No capability declaration is involved.

An intermediary serving a compatibility HTTP surface to non-conforming browsers (Section 7) is a different matter: it selects a target on the browser's behalf, because the browser cannot.

Such an intermediary:

• MUST apply Section 4.4 as a client, using its own capability set.
• MUST NOT present content it selected under one disposition as though it had another. A gateway serving an asserted target MUST NOT present it as proven.
• SHOULD declare its capability set, since which targets it can serve determines which names work through it.

A browser reaching content this way has none of Section 5's guarantees: the origin is the gateway's, verification happened elsewhere, and the browser trusts the gateway as it would any web server. The guarantees stop at the gateway.

com.atproto.sync.getBlob returns whole blobs. There is no range support, no conditional request, no compression negotiation, and rate limits set for a PDS's normal workload rather than for serving a popular site.

Consequences for implementers:

• Satisfy Range by slicing bytes already fetched and verified. The PDS will not help, and the whole blob had to be hashed anyway.
• Cache proofs separately from content, keyed by commit CID. A commit's signature and MST verify once and serve many; a proof cached this way is valid for every record under that commit. This is what makes per-request verification affordable at an intermediary, and clients should key their own proof caches the same way.
• Cache derived artifacts, parsed manifests, path→offset maps, by root CID. Both are immutable, so neither ever needs invalidation.

An intermediary sitting in front of one or more PDSes SHOULD expose com.atproto.sync.* rather than inventing a protocol. A conforming client then points at a different base URL with no new code path, and verification is what makes that safe, the intermediary is an atproto read-path cache, not a trusted party. A compatibility HTTP surface for non-conforming browsers (Section 7) is a second face on the same store.

Intermediaries MUST coalesce concurrent upstream requests. Section 8 caps a client at 8 concurrent blob fetches, which does nothing for an intermediary: a cold cache with ten thousand concurrent readers becomes ten thousand upstream requests against one publisher's VPS. That is exactly the failure Section 7 exists to prevent, caused by the thing meant to prevent it. Single-flight per CID, per record, and per identity resolution.

An intermediary's job is to be one well-behaved client to the origin PDS on behalf of many readers.

• DID document omitting the handle from alsoKnownAs, reject
• Load from a repo the PDS reports as taken down, refuse to load, storage survives
• Load from a deactivated or suspended account, refuse to load

• Record served by a PDS with no valid MST proof, reject
• Proven path whose record key differs from the requested short name, reject
• Short name that is a bare . or .., reject
• Same short name differing only in case, two distinct names
• Record obtained from a simplified firehose stream, not accepted as proof

• Record carrying both alias and targets, invalid
• Record carrying neither, without status: retired, invalid
• Record carrying both status: retired and targets, invalid
• Unknown property on a target, ignored
• Unknown property inside policy listed in critical, fail closed
• The same unknown property unlisted, ignored
• Unknown property inside policy, client not implementing critical, fail closed
• Publisher policy attempting to widen client defaults, narrowed to the client's own

• status: retired, fail as permanent, storage retained
• Retired record carrying a successor, successor not followed
• Record absent entirely, fail as possibly transient, not as retired
• Retired name later returning to active, warn

• Target list where every entry is unsupported, fail, do not degrade
• Asserted target listed before a provable one, provable selected
• Provable target fails to load, hard failure, no later target tried
• Mirror retry after a failed fetch of the same CID, permitted, not treated as fallback
• Mirror offering a CID absent from any proven record, reject
• Redirect loop spanning route → publication url → route, bounded, then hard failure

• @handle and @handle/self, identical resolution, identical origin
• @handle where no self record exists, fail, no directory substituted
• Alias pointing at another alias, hard failure
• Alias naming a nonexistent record, hard failure
• Alias pointing at a name in a different identity, hard failure
• Aliased root, derives the alias target's origin, not self's

• Valid proof against a commit older than one already seen, content differing, refuse
• Identical content proven at a lower rev after an unrelated repo write, accept
• Superseded content at a lower rev, refuse
• Content proven against a commit predating a key rotation, accept only once the rotation has settled
• Floor reset attempted inside the DID recovery window, refuse
• Floor recorded for an ephemeral origin, required

• Manifest entry declaring text/plain whose bytes sniff as HTML, served as declared
• Manifest entry with no declared type, served non-executable
• Manifest entry with a path escaping the origin, reject at load time
• Path a/%252e%252e/b, single decode pass, then reject
• Manifest entry a//b and a request for a/b, one canonical form
• .. ascending past root, hard failure, not clamped to root
• javascript: URL reached via a cross-name link, reject
• data: URL as a script source, reject

• Blob compressing to within limits but expanding past the ratio cap, abort mid-stream
• Manifest within every per-item limit but exceeding a total-bytes budget, fail closed

• Verification mismatch, response is client chrome, not content
• Cross-name link present at render, no resolution occurs
• Cross-name link to a name the client has no handler for, inert, with explanation
• Pinned origin whose handle has since transferred, not displayed under the old handle
• Pinned origin with a petname whose handle no longer resolves, petname displayed
• Unresolvable handle with no petname, stated unresolved, DID not shown as the name
• Inspection requested with no network available, reports what is known locally

• atw://handle/name and @handle/name, identical resolution
• atw://did%3Aplc%3Axxx/name, resolves without handle resolution
• atw://did:plc:xxx/name, colons unescaped, rejected
• atw:name inside proven content, resolves against the containing identity only
• atw:name where the containing content is unproven, not resolved
• atw://name where name was meant as shorthand, treated as an identity, not shorthand
• A link containing a derived origin, rejected
• Link text in display form naming something other than the target, not presented as agreeing
• Link to a retired name, inert, stated permanent
• Link to a name whose selected target is asserted, indicated as leaving
• at:// URI naming a non-route collection, not loaded
• atw://b.example/, resolves to the root name
• atw://b.example/blog?q=1, query reaches the handler, absent from the record key and the derived origin
• atw://b.example/blog#top, fragment never transmitted
• Handle resolving by both DNS and well-known to different DIDs, DNS wins
• Handle served with a zero TTL, cached for the 60 second minimum
• Two rev values compared as ASCII strings

• Safety label on a name, drive-by navigation, no promotion: load refused
• Label consulted with the labeler unreachable: last known set applied, staleness reported
• Label whose signature does not verify against its source DID: ignored
• Negation from the same source, subject and value: earlier label retracted
• Expired label: block may persist; unexpired label MUST NOT be treated as expired
• Label naming a CID: applies to the same bytes under a different name
• Self-label absent where a subscribed labeler asserts one: labeler wins
• Label applied: responsible labeler named

• Partial input with remote suggestion disabled, nothing transmitted
• Suggestion activated, full Section 3 resolution runs, including the bidirectional check
• Suggestion for identity B while a petname is bound to identity A, petname not shown
• Suggestion activated, origin remains ephemeral
• Remote suggestion displayed, source attributed

• Stream event for a followed name: treated as notification, re-fetched with proof before display
• Title taken from a stream event: not displayed as the publisher's words
• Background check without full verification: floor unchanged
• Followed name covered by a safety label: no notification
• Repo revision advanced by an unrelated write: no change reported
• Switching record CID changed: change reported
• Followed name retired: notified once, then silent

• Switching record naming a blob that is not retrievable, publish invalid
• Concurrent writes to one route record without swapRecord, detected rather than silently merged
• Publish resumed after interruption, no duplicate uploads

Trusted: the client and its update channel, the DID method's own guarantees (log integrity and the recovery window), the cryptographic primitives, and the user's device.

Not trusted: every network participant, including the publisher's own PDS, every mirror and intermediary, DNS, suggestion services, indexers, and labelers.

Protected: integrity of provable content against everyone except the holder of the identity's signing key; namespace exclusivity within an identity; origin isolation between names; freshness against rollback; and honest naming, meaning the client never presents a claim it cannot substantiate.

Not protected: reader anonymity (Section 13.2), unpublishability, availability, confidentiality (Section 16), and recognition of a confusable name on first contact (Section 6.4).

Out of scope: compromise of the user's device, traffic analysis beyond the readership disclosure named below, and any guarantee that content remains reachable.

Two properties fall out of the table. Every adversary that can withhold is unable to substitute, which is what makes hosting a performance decision rather than a trust decision (Section 7). And the publisher is an adversary: most of Section 5's rules defend the person reading a site against the person who published it.

Identity takeover inherits everything. Compromise of a DID's rotation keys yields every origin and all accumulated storage under that identity. Roughly par with domain transfer, so not disqualifying, but it is the real argument for publisher key hygiene guidance.

Unbounded origin creation. Any identity can mint arbitrarily many origins at no cost. Section 5.4 is the mitigation; a client that skips it will have a quota problem.

Homograph and near-handle attacks. Handles are domains and inherit every confusable-name problem DNS has. Wherever a client displays a name, a location field, a link, a share sheet, a history entry, is the mitigation point, and a client with no location field has more of them to get right, not fewer.

Petnames (Section 5.11) close this for return visits, since a chosen label cannot be collided with. They do not close first contact, which is where confusables do their work, and Section 6.4 is the path that delivers most of it. Section 5.4's ephemeral tier is the partial answer there: an unpinned origin communicates that no relationship exists yet.

Note an asymmetry in normalization: short names are ASCII by record-key syntax, but handles are IDN and are not. Clients MUST apply IDNA processing to handles before display and before comparison, and SHOULD mark mixed-script handles distinctly. A client that normalizes for resolution but not for display shows one name while loading another.

Direct reads disclose readership. Section 7 removes gateways from the trust path, but gateway-mediated reading also hid readers from publishers. A client fetching blobs directly tells the publisher's PDS operator exactly who read what, and the publisher may operate that PDS themselves.

This is a real cost of the design, not an oversight, and it runs opposite to the usual decentralization intuition: the more direct the fetch, the worse the reader's privacy. Clients that care SHOULD fetch through a cache because a cache learns the reader's identity in the publisher's place, verification is unaffected either way, which is what makes the choice available at all.

Connection-origin decoupling. This intentionally breaks the implicit guarantee that bytes in an origin arrived over a connection authenticated to that origin, the objection Mozilla raised against Signed HTTP Exchanges (Section 14.6). That guarantee is replaced by proof to a signed commit, strictly stronger for provable targets and explicitly absent for asserted ones, which is why Section 4.3 separates them by disposition rather than grading them on one scale.

Revocation is advisory. Labels (Section 5.13) are a retraction channel, but clients choose their labelers and cached content survives. No content addressed this way can be assumed unrecallable.

Goal 7 (Section 1.1) permits deliberately accepting gaps already present in the HTTP web where addressing them would cost more than it buys. The comparisons below explain those trade-offs; they do not set a feature-parity goal or promise equivalent behaviour. The list also identifies limitations specific to this design, so each is argued once here rather than rediscovered as an oversight.

Three problems are not accepted: substituted content, which is always a hard failure; silent downgrade, which Section 4.4 forbids even though the web permits it in several places; and client-performed impersonation, a stale handle, a link presented as resolved, an asserted target shown as proven, which is forbidden in every case.

That division is goal 1 stated as a tolerance, and it is the test for anything added later: does this let a name overstate itself? If yes it is a defect whatever it buys. If no it is a cost to weigh.

wisp is the nearest existing system to this design, so the comparison is the most useful one in this section.

Where they agree, they agree completely. PDS as source of truth, hosts as reconstructable caches, rkey-scoped names with no allocation registry, custom domains as optional decoration. Those were wisp's positions first and this spec adopts them without modification.

The two substantive differences:

Who verifies. In wisp the hosting service verifies and the reader trusts the host over TLS, a sound model, and the reason wisp works in any browser today. This spec moves verification into the client, which demotes the host to a cache that cannot lie (Section 7) but requires a conforming client to get any benefit. wisp's model reaches everyone; this one reaches fewer people with a stronger guarantee. Both are legitimate, and the gateway is where they meet.

Origins. wisp serves every publisher from one origin, so all sites share storage, cookies, and scripting access. Section 5.1 requires per-name origins. This is why a conforming client cannot simply proxy wisp's HTTP surface, it would inherit the shared origin, and why place.wisp.fs is registered as a handler that reads the records directly instead.

The alignment test: a wisp site should be nameable by a route record with no change to wisp. If that ever stops being true, this spec has a bug.

IWA packages apps into signed Web Bundles served from an isolated-app: scheme whose hostname is a Web Bundle ID: base32 of an Ed25519 public key plus a short type suffix. Transport is irrelevant to origin identity.

Borrowed:

• Type-tagged origin derivation. The version byte in Section 5.1.
• Response-reader cache. Path→offset map per bundle, cached, so repeat requests never re-parse (Section 11).
• Load-time scope validation. IWA validates that bundle-internal URLs use the isolated-app: scheme; Section 5.3 rejects entries escaping the origin at load time.
• The whole feasibility proof. IWA is shipped Chromium code demonstrating that a key-derived, DNS-free host works as a first-class origin with full storage.

Aligned: the premise that origin identity can be anchored in a signature rather than a connection.

Diverges, structurally:

• IWA's origin is its key. Keys cannot rotate without renaming the app and destroying its storage. atproto separates identifier from key, rotation keys live in the DID document and the DID survives rotation, so Section 1 makes it a non-goal to derive origin material from a key. A publisher who rotates or loses a signing key keeps their names, their origins, and their users' local state.
• IWA never shipped an open trust model. Its key-trust check remains gated behind enterprise policy and developer mode, because unbounded anonymous origin creation has no answer inside a browser. This spec inherits exactly that problem and answers it with three things IWA lacks: origins displayable as human names (Section 5.1), a labeler-based revocation channel (Section 5.4), and the ephemeral/pinned tier that makes drive-by navigation cost nothing durable (Section 5.4).
• IWA is install-first. This spec is navigation-first with promotion, which is the same ceremony arriving later in the flow.

pkarr publishes signed DNS packets to the Mainline DHT under Ed25519 public keys, giving keys that resolve as sovereign TLDs, with HTTP relays for clients that cannot open UDP sockets.

Adopted: as an optional transport for DID documents (Section 3.2), reducing dependence on a single DID directory. Listed as redundancy, never required. A client with native networking can speak the DHT directly rather than through relays, which is where most of the decentralization claim otherwise leaks.

Not adopted, as the naming layer, for three reasons:

• Records are ephemeral. The DHT drops them after hours and they must be republished. For a publishing tool this is the wrong failure mode: stop running the republisher and the name dies. A PDS is always-on by construction. This trades a hosting dependency for a liveness dependency, and liveness is harder for an individual to maintain.
• 1000-byte limit. Suitable for discovery, not for a target list.
• It declines the naming problem by design. pkarr states that public keys are unmemorable on purpose and that petname systems belong on top. This spec's entire premise is that @portable.agency/blog is typeable, so pkarr sits below the layer that matters here.

standard.site (site.standard.publication, site.standard.document) gives publishers a shared vocabulary for longform content, with documents carrying path, metadata, and text content, verified by a <link rel> on the served page pointing back at the AT-URI.

The verification direction is inverted between the two specs, which is what makes them compose rather than compete:

Aligned / adopted:

• site.standard.publication is a first-class handler (Section 4.2), proven by inclusion (Section 4.3). Documents' path fields supply the subpath tree, so @portable.agency/blog/welcome resolves without this spec inventing a path mechanism.
• A publication's url field is an ordinary asserted target, a redirect, not a second way to load the same entry (Section 4.3).
• The <link rel> reverse-proof pattern is the model for Section 4.6.
• Sites SHOULD emit both record types. One publish, two audiences.

Unresolved friction: site.standard.document expects an HTTPS URL. Content at a derived origin has none. Discovery still works, because indexers consume records from the firehose rather than crawling. But the <link rel> verification handshake needs a reachable document, so a route-only site is indexed but unverified, no publication badge. This is cosmetic rather than structural, and it is the one remaining reason a publisher might want a gateway URL they would not otherwise need (Section 7).

AT Tags is Chris Shank's draft proposal for metadata connecting web pages to atproto records and identities. This comparison describes the draft at commit a783376.

It defines four standard <meta name="at:..." content="..."> properties: at:canonical for the records a page represents, at:alternate for auxiliary records, at:author for the page's authors, and at:me for identities associated with the site or section. Properties may repeat; they describe multiple relationships, not a ranked list of destinations. Namespaced custom properties can describe additional relationships.

The directions are complementary.

AT Tags explicitly leaves translating an arbitrary AT-URI back into an app's web URL to other work. Atproto web names does not provide a general record-to-app URL registry either: its route collection names sites, and handlers interpret the targets selected from those routes. The two proposals address different parts of the navigation problem.

Metadata is not a content proof. A page can claim any author or canonical record in its tags. Discovering that claim does not prove that the named identity published the page's bytes. Tags on an asserted HTTPS target can supply the page-side claim for a reverse-binding check (Section 4.6), but do not change its redirect disposition or entitle it to a derived origin. Tags inside a proven page are authenticated as part of that page; claims they make about other identities still need their own verification. They do not replace the handle binding, signed commit, MST inclusion, or blob hashes required by this specification.

A route record is not necessarily the canonical page object. AT Tags uses deletion as a rule of thumb: removing a canonical record would also remove the page, while removing an alternate would not. Removing a route record removes the name; content hosted elsewhere may remain available. A page may therefore advertise its route as at:alternate while keeping its actual document record as at:canonical, where those relationships apply. Reaching a page through a route is not by itself a reason to label that route canonical.

The HTML choice is separate from the naming scheme. AT Tags uses <meta> partly to avoid the URL-syntax problems of putting existing AT-URIs in <link href> attributes, generalizing the sort of reverse metadata used by standard.site (Section 14.4). Storing an AT-URI as metadata text does not change its syntax or turn it into a navigation URL. This specification separately defines link form (Section 3.1.2); AT Tags neither settles the provisional atw: scheme name nor replaces that link form.

Publishers can support both proposals without changing the route format. AT Tags are optional discovery metadata, not a prerequisite for resolving a name or loading proven content. A client using them for cross-name navigation remains subject to Section 5.9's lazy-resolution rule.

Signed HTTP Exchanges. The same origin/connection decoupling, and the source of the objection recorded in Section 13. This spec accepts it rather than answering it.

WebFinger links. Ordered typed pointers with the same downgrade and over-claiming failure modes. Relevant before Section 4 is frozen.

IPFS. CID-subdomain origins unify on content and lose storage on every publish; IPNS-key origins unify on name. Section 5.1 is the second shape with a DID where IPNS has a raw key, which is what makes rotation possible.

Tangled Pages. Origin-per-identity, path-per-site, backed by git repos and sh.tangled.repo records. The closest existing implementation of the addressing shape, differing in that it uses real DNS subdomains.