docs/The front door
The front door
Every human page has a machine counterpart, and the split is carried by the URL shape alone — no API keys, no content negotiation, plain HTTP built for curl.
The URL grammar
| Shape | Meaning |
|---|---|
/{publisher} | A publisher: a domain handle (graham.systems) or a DID (did:plc:…) |
/{publisher}/{project} | A project landing; nested paths welcome (/dist-town/cli) |
…/{project}@{selector} | A release: @1.2.0 names a version, @latest resolves a pointer |
…/{project}/~releases, …/~changelog | Human surfaces (tabs); ~-segments are routes, never names |
…@{selector}/{artifact} | Machine: 302 to the artifact bytes on the publisher’s storage |
…@{selector}/SHA256SUMS | Machine: checksums for every artifact, sha256sum -c format |
…@{selector}/{artifact}.sha256 | Machine: one artifact’s checksum |
A slash after the @ segment means machine surface. Everything else is a page.
Downloads are 302s
dist.town serves zero artifact bytes. An artifact URL answers with a redirect to the publisher’s storage, plus an RFC 9530 Repr-Digest header carrying the expected sha256 — follow with curl -L and verify what arrived.
Checksums come from the signed record
SHA256SUMS and .sha256 responses are generated from the digests in the publisher’s signed release record — never read from the storage that serves the bytes. A compromised bucket can change what it serves, but it cannot change what the sums say the bytes should be.
curl -LO https://dist.town/{publisher}/{project}@{version}/SHA256SUMS
sha256sum -c SHA256SUMS --ignore-missingLifecycle on every response
Every front-door response carries X-Dist-Status (active, yanked, deprecated, archived). The yank rules:
- An explicit version (
@1.2.0) always serves — with its status attached, so your tooling can decide. - A pointer (
@latest) never resolves to a yanked release; the request fails with409and an explanation. Channels don’t hand out known-bad versions; pins keep working.
The read plane
Everything the pages show comes from public XRPC under /xrpc/town.dist.* — the same read plane the site itself consumes, with no private API behind it. If you’re building richer tooling than downloads, that’s your surface.
Moderation is legible too
dist.town’s moderation actions are published as signed labels under its service identity (did:web:dist.town): query them at com.atproto.label.queryLabels or follow the stream at com.atproto.label.subscribeLabels. A suppression emits a suppressed label on the subject; reversal emits a negation. Content reports go to com.atproto.moderation.createReport on this origin.