Szzt Gateway Conformance Specification + Implementation Guide

A gateway is the read-side host that answers https://<name>.szzt.app/… (and bound custom domains): it resolves a request to a mini-site's signed atproto state, hash-verifies every byte it serves, and terminates the request. Each requirement below appears twice:

1. As a normative spec clause (RFC-2119 MUST/SHOULD/MAY) an independent implementer could build a conforming gateway against, derived from mini-site-spec.md §9–§17 and the §18 conformance summary.
2. As an as-built account of how this repository satisfies it.

Where the standing audit (conformance-audit.md) and the current code disagree, the divergence is flagged inline under AUDIT DELTA — the audit is a dated snapshot (last full sweep 2026-07-16 at 17c2b01) and several of its OPEN gaps have since been wired.

Conformance language

The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, MAY are to be interpreted as in RFC 2119. A conforming gateway satisfies every MUST in §§1–8 below. The as-built notes describe one conforming implementation; they are not themselves normative on other implementations.

Two scope limits inherited from the spec and audit, stated once so nothing below overreads:

• Verifying signatures on the read path evicts a malicious gateway or mirror from the trust base. It does not evict a malicious PDS: repo commits are signed by the PDS-held signing key, so the origin PDS remains in the trusted computing base (conformance-audit.md "The honest scope limit").
• §9.3's PSL-listed apex is a SHOULD that §18 explicitly relaxes to "recommended, not required", so a gateway on a non-PSL apex (like szzt.app) is conforming.

1. Request demultiplexing — the host names the site

Normative

• A gateway MUST derive the identity of the mini-site being served from the Host alone. It MUST NOT expose a path-based identity route (a /at/<handle>/… style path on a shared origin), because author JavaScript served there would run on the gateway's own origin beside publisher credentials (§11.3).
• A gateway MUST classify each request into exactly one serving intent and MUST turn a malformed host or path into a defined HTTP error response, never an exception or a crash.
• A gateway MUST reserve gateway-owned verbs under a namespace that cannot collide with a legal author resource path (the spec uses /.well-known/minisite/). A bare author path (e.g. /tile/logo.png, /export.zip) MUST be served as ordinary content, not shadowed by a gateway verb.
• A gateway MAY offer per-request tile-mode selection; if it does, the selector MUST live in the reserved namespace and apply identically on every front-end.

As-built

packages/server/src/request.ts parseRequest() is the pure demux: it reduces a RawRequest (host + path + navigation flag) to a GatewayRequest union and touches no signed state.

• Host → site is parseHost() (packages/server/src/apex.ts), producing one of slug, siteOrigin (a reversible <siteRkey>--<did-suffix> label decoded by parseSiteOriginLabel), domain, version (a root-CID host, which sets pinned = true), or apex. The bare apex names no site — its only content route is the §13 mirror — enforcing the §11.3 ban on a path-based identity route.
• Reserved verbs are constants: BUNDLE_PATH (/.well-known/minisite/bundle), EXPORT_PATH (/.well-known/minisite/export.zip), and TILE_PREFIX (/.well-known/minisite/tile/). The header comment on TILE_PREFIX records the H16 decision that a bare /tile/… or <site>/export.zip would shadow a real author file, so the reserved namespace is load-bearing, not cosmetic.
• Malformed inputs become { kind: "invalid", status, message } (e.g. a bad ACME token → 400, an unparseable host → 404), never a throw.
• Per-request tile selection strips TILE_PREFIX before host demux and forces mode = "tile", so one site-mode origin also answers tile requests, host-agnostically.

2. Serving intents — the dispatch switch

Normative

A gateway MUST resolve each classified request against signed state and MUST NOT throw: every failure — naming miss, malformed signed state, integrity failure, upstream unavailability — MUST become a defined HTTP response. Fail-closed status discipline:

• A definitive naming/absence miss MUST be a 404 (the record was reached and authoritatively reported absent), distinct from a 502 upstream/integrity failure.
• An integrity or root-CID mismatch MUST fail closed (5xx, cache-control: no-store), never serve the mismatched bytes.

As-built

packages/server/src/dispatch.ts dispatch() is the async core; its header states "It never throws … All verification lives in the gateway engine; the server adds none." It switches over GatewayRequest.kind:

Fail-closed mapping is centralized in errorResponse(): RecordNotFoundError → 404; GatewayError (root-CID mismatch / unresolvable signed state) → 502 with x-minisite-verify: failed; any other reader/PDS failure → 502 with x-minisite-verify: unavailable. A per-CID hash failure is verifyFailed() → distinct 502, no-store, carrying path/expected/computed CID. The rasl path additionally re-checks isSafeHeaderValue() on the signed content-type before writing headers (a hostile value fails closed to 502 rather than crashing writeHead).

3. Hash-verify every served byte (fail-closed) — SECURITY INVARIANT

Normative

• A gateway MUST derive every served byte's identity from the mini-site's signed repo state and MUST re-hash every block against the CID it was requested under before serving or caching it. A block whose bytes do not hash to its CID MUST fail closed.
• A gateway MUST verify the repo's commit signature chain — not merely that CIDs are internally self-consistent — so that a malicious gateway or mirror cannot substitute a self-consistent but unsigned record. (This is stronger than §9.2's literal text, which only requires CID derivation; see the SPEC-vs-code note at the end.)
• There MUST be no "skip verification" / "unknown key" / "trust this reader" bypass on the read path.

As-built

packages/verify/src/car.ts verifyCarRecord() is the read-path verifier. Given the bytes of a com.atproto.sync.getRecord proof CAR plus the repo's expected signing key, it walks the whole chain and returns a record only if all five steps pass (else throws CarVerifyError):

1. every block's bytes hash to the CID it is filed under (readCarWithRoot, with the skipCidVerification escape hatch deliberately not passed);
2. the CAR root parses as a v3 commit for the requested DID;
3. the commit signature verifies under the expected signing key (verifyCommitSig) — "THE check the read path was missing (§10.2)", the reason the file exists;
4. the MST path from the signed commit.data root resolves to the leaf;
5. the leaf names a record block the CAR actually carries and it decodes as a CBOR map.

Fail-closed is structural, not conventional. The VerifiedRecord brand (verifiedRecordBrand, a unique symbol) is deliberately unexported: outside car.ts there is no way to name the type, so no caller can construct, cast, or mock a VerifiedRecord — the only producer is verifyCarRecord(), and there is no boolean-returning variant or ok flag to forget to check. A function that accepts a VerifiedRecord cannot be handed an unverified one. signingKey is a REQUIRED input with no "skip" branch. Availability failures are not special-cased into a pass: "the server didn't give me the proof" and "the proof is bad" are the same rejection.

This reader is packages/verify/src/reader.ts atpReader(), wired unconditionally in apps/gateway/src/main.ts createServerFromEnv() via createMultiPdsReader — above and outside the if (env.SERVICE_DID) auth block — so the read path verifies whether or not publisher-auth is configured. On the serving side, @minisite/gateway's VerifyingCache re-hashes every blob before store.set(); packages/server/src/http.ts makeHandler() builds new VerifyingCache(opts.fetcher, opts.blobStore), and the encoder-boundary note in car.ts's header explains why a served CID is a property of the bytes on the wire, never of a re-encode.

4. SSRF-guarded egress — two fetch implementations on purpose — SECURITY INVARIANT

Normative

• Every outbound request a gateway makes to an attacker-named host — a target's PDS endpoint (from its DID document), a did:web host, or a mirror hint from a site record — makes the gateway a potential confused deputy. The transport MUST refuse private/loopback/link-local/CGNAT targets.
• The guard MUST cover the URL shape, every redirect hop (the platform's automatic redirect following would otherwise carry a vetted public URL to http://169.254.169.254/), and the address the hostname actually resolves to — and MUST pin the connection to the vetted address so the address checked is the address dialed (no DNS-rebinding gap between check and connect).

As-built

Two implementations of one SafeFetch seam (packages/gateway/src/safe-fetch.ts), by design — its header enumerates them:

• createSafeFetch() (packages/gateway/src/safe-fetch.ts) — browser-pure: URL shape + manual redirect re-validation via fetchFollowingRedirects() against isPublicHttpsUrl with a hop cap. All a browser/service-worker package can offer, since it cannot resolve hostnames.
• createGuardedFetch() (packages/server/src/guarded-fetch.ts) — the Node transport: shape + redirects plus post-resolution address checking and IP pinning (roadmap H15). firstPrivateAddress is the total-function security kernel; the DNS hop and undici dispatcher are injected so the guard is unit-tested against fakes and opens no socket.

The single injection site is apps/gateway/src/main.ts createServerFromEnv(), which builds createGuardedFetch() once and threads it into all four attacker-influenced transports: the DID-document fetcher (createDidDocumentFetcher), the multi-PDS reader (createMultiPdsReader → atpReader({ fetch: guardedFetch })), the mirror race (createUrlFetcher(guardedFetch)), and the publisher-auth signing-key resolver. The header comment is explicit that it is built once (one undici connection pool, one policy site) and never as a module-level or lazy singleton.

5. Read-path rate limiting

Normative

• A gateway SHOULD shed a caller flooding distinct unknown CIDs before paying the expensive site resolve, and MUST negative-cache unknown-CID misses so repeats are O(1). The two halves — negative cache and rate limit — are both required by §12.
• A per-caller limiter MUST be keyed on a trustworthy client identifier. Behind a single trusted reverse proxy this is the right-most X-Forwarded-For hop (every earlier entry is client-forgeable).

As-built

packages/server/src/dispatch.ts readShed() consumes one token from deps.readLimiter keyed by clientIp, charged on handleRasl, handleMirrorRasl, handleBundle, handleExport, and handleServe before the resolve. The key is packages/server/src/request.ts rightmostForwardedFor() (documented rationale: the edge appends the real peer last). The production TokenBucketLimiter (capacity: 120, refillPerSecond: 60) is built in apps/gateway/src/main.ts createServerFromEnv() (readLimiter), swept by an unref'd prune() interval. The negative cache is @minisite/gateway's NegativeCache (a ~10k-entry LRU with its own global token bucket); handleRasl short-circuits a per-(site, cid) known-unknown in O(1) via resolved.cache.isNegativeCached(site, req.cid) — scoped to the resolved site (roadmap H7) so a redeploy's new rootCid can't be masked by a stale global "absent" fact.

AUDIT DELTA (G3): the audit records G3 as FIXED (2026-07-11); current code matches. No delta.

6. Naming — slugs, custom domains, version-pinned, credible exit

Normative

• Slugs (§11.1): an authoritative slug allocator MUST refuse CID-shaped labels so the slug and version-pinned (<rootCID>.<apex>) label spaces never collide, and MUST retain a released slug's confusable skeleton so it stays refused.
• Custom domains (§11.2): a gateway that binds custom domains MUST (a) verify a _drop.<domain> TXT proof before binding, (b) periodically re-check that proof on a short interval and promptly invalidate a binding whose proof has definitively disappeared (the dangling-CNAME / domain-hijack control), and (c) if it terminates its own TLS, revoke/drop the certificate when the binding is invalidated.
• Credible exit (§11.3): every mini-site MUST be reachable by an index-free at:// route and an independent verifier, so a publisher is never locked to this gateway.
• Version-pinned (§11.5): a <rootCID> host MUST address immutable content whose resolved index never expires.

As-built

• Slugs: packages/moderation/src/slugs.ts validateSlug() refuses cid-shape (order charset → length → cid-shape → reserved) and SlugRegistry retains skeletons across release(). Wired via SqliteNameStore.allocateSlug(), endpoint gated on SERVICE_DID + NAME_DB_PATH in createServerFromEnv() (slug = { auth: authSlug, limiter, allocator: store }).
• Custom domains: the HTTP bind route is packages/server/src/http.ts at DOMAIN_BIND_PATH (handleDomainBind), wired as opts.domain from createServerFromEnv() (authDomain + DnsTxtResolver), which DNS-fetches and verifies the _drop.<domain> proof before writing (a). The re-check loop is startDomainRecheck() / runDomainRecheckLoop() (domain-recheck.ts), started at the entry point over the shared name-store handle, interval from resolveDomainRecheckIntervalMs() (default 5 min); a definitive proof-gone drops the binding, a transient DNS failure leaves it untouched (b). TLS revoke-on-drop threads the same certStore into the re-check loop's onOutcomes (c).
• Credible exit: packages/server/src/resolve.ts resolveSiteTarget() builds the at:// URI with no index; @minisite/verify ships the independent minisite-verify CLI, which resolves DID→PDS and DID→signing-key from the target's own DID document and verifies every record (H3's verify tail).
• Version-pinned: request.ts parseRequest() sets pinned = true on a version host; dispatch.ts indexFor() treats by === "rootCid" as immutable so its resolved index never expires, and handleServe() keeps the immutable cache-control (never downgraded to the pointer TTL).

AUDIT DELTA (G9, Clause 8 §11.2): the audit marks §11.2 an outright FAIL — "TXT-recheck + cert revocation both unwired", the only caller of verifyDomainProof()/invalidateDomain() being the operator CLI. This is now stale. Current main.ts + http.ts wire the HTTP domain-bind endpoint, the startDomainRecheck loop, and the full ACME lifecycle (§8 below). The audit's own cross-reference notes item 10/14 were PARKED at audit time; they have since landed. A conforming reader should treat §11.2 as satisfied by the current code, not by the audit verdict.

7. Federation & moderation

7a. Content-only RASL mirror (§13)

Normative: a mirror MUST serve only CIDs it has pinned (a cold miss is 404, not a fetch), and the serve MUST carry zero trust — the consuming verifier re-hashes every byte, so a corrupt or hostile mirror can only fail verification. A gateway consuming a resolved site's hints MUST re-hash every mirror byte against the CID and fall back to the PDS on any failure.

As-built: dispatch.ts handleMirrorRasl() serves opaque, immutable, nosniff bytes from deps.mirror (a RaslMirror), returning 404 on an unpinned CID. Hint federation is indexFor() wrapping the cache in a per-site MirrorFetcher when deps.urlFetcher is set and the index has hints; main.ts wires urlFetcher: createUrlFetcher(guardedFetch) unconditionally, so mirror URLs are SSRF-guarded and a site with no hints short-circuits to the PDS.

7b. Moderation (§17)

Normative: a gateway subscribed to a labeler MUST (§17.5) enforce takedown labels on serving, RASL, and cache paths — refusing a labeled DID / AT-URI / root CID / content CID — and MAY gate serving on the label stream being synced. Enforcement MUST be attributable (who labeled, what value). §17.4 is delist, not erase: the content MUST remain reachable via the PDS and credible-exit routes; erasure is a PDS-side action (§17.6), never a gateway one. §17.3: a gateway that accepts abuse reports MUST route them into a review path.

As-built:

• Subscription + runtime: apps/gateway/src/main.ts startLabelerModeration() builds a LabelStore over the trusted-DID allowlist, an Enforcer, and a LabelerSync driven by runLabelerSync over the real connectLabelStream WebSocket. Enabled by default toward the Bluesky mod service (BSKY_LABELER_DID / BSKY_LABELER_ENDPOINT); an operator opts out with empty LABELER_ENDPOINT / LABELER_TRUSTED_DIDS (resolveLabelerConfig(), fail-closed trusted set).
• Enforcement seam: dispatch.ts syncGate() (503 until Moderation.ready()), guardServe() (451 on DID/URI/root/any-resource-CID takedown — delist the surface if ANY block is labeled), guardCid() (451 on a labeled content CID for RASL/mirror). takenDown() returns 451 with the attributing labeler DID + label value in the body (CR/LF-safe: only the fixed reason enum goes in a header). The body explicitly states the content remains reachable via the PDS and credible-exit routes — delist, not erase.
• Delist of further publishing (§17.4): main.ts threads Enforcer.didBlockedBy() as runtime.isDidBlocked into SqliteNameStore, so a labeled DID's slug/domain writes are refused.
• Reports (§17.3): the anonymous /.well-known/minisite/report endpoint is wired when REVIEW_DB_PATH is set (report = { review: { queue: SqliteReviewQueue }, limiter }), per-IP rate-limited; child-safety/ncii reports are refused (422) at the boundary in the no-mandatory-reporter posture.
• Strict vs. enforce-as-you-go: LABELER_HEAD_CURSOR arms strict sync-before-serve (gate holds through backfill); unset is the documented default (serve immediately, enforce each label as it arrives), not a degraded fallback.

AUDIT DELTA (G4, Clause 14 §17): the audit's headline verdict is FAIL — "kernel complete, entirely unwired; no labeler subscription, no report path, no enforcement", and §17.4's isDidBlocked is called "a permanent no-op in production." All of this is now stale. The subscription (startLabelerModeration), the enforcement gates (syncGate/guardServe/guardCid), the report endpoint, and the isDidBlocked threading are present in current code. This is the single largest audit-vs-code divergence; treat Clause 14 as substantially wired, not FAIL. (The §17.2 publish-time detection SHOULD remains a separate, publisher-side concern not covered by this gateway document.)

8. App-owned TLS / ACME lifecycle (§11.2c) — DORMANT by default

Normative

A gateway that terminates its own TLS for bound custom domains MUST obtain a certificate per bound domain, persist it across restarts (Let's Encrypt rate limits make persistence mandatory), renew before expiry, and drop a certificate when its binding is invalidated. A gateway that terminates TLS at an upstream edge MAY omit all of this.

As-built

Entirely gated on CERT_DB_PATH (+ a name store) and default OFF: unset ⇒ the gateway binds a plain http.createServer() behind the Railway edge, byte-for-byte the production posture. When set, apps/gateway/src/main.ts (entry point, below createServerFromEnv) builds the ACME driver (obtainCertificate over fetchAcmeHttp + a WebCryptoAcmeSigner), persists issued certs in SqliteCertStore, runs startCertRenewal() (default 12 h cadence, 30-day renew-before), and drops a cert on binding invalidation via the shared re-check loop. CUSTOM_DOMAIN_TLS additionally arms an https.createServer with a per-SNI SNICallback reading runtime.certStore — this switch is dormant pending the Railway raw-TLS topology (the HTTP-01 :80 bootstrap listener is intentionally not yet wired; customDomainTlsEnabled() is default-off and rejects garbage values).

AUDIT DELTA (Clause 8 §11.2c): the audit states "no cert subsystem runs at all … the RFC 8555 stack … has zero callers in apps/gateway/src." Now stale — the stack is wired at the entry point as above, though the TLS listener remains deliberately dormant. Certificate obtain/renew/ revoke run when CERT_DB_PATH is set; only self-termination waits on topology.

9. Composition invariant — socket-free factory, sockets at the entry point

This is an architectural conformance property of this implementation (not a spec MUST), but it is what makes the security invariants above testable.

apps/gateway/src/main.ts createServerFromEnv() is socket-free: it constructs the whole request pipeline but opens no socket and starts no background loop. Everything that dials the network — the §17.5 labeler subscription, the §11.2(b) DNS re-check loop, the §11.2(c) ACME driver and renewal loop, the durable SQLite name store — is built outside the factory at the real entry point (if (import.meta.url === …)) and injected via the ServerRuntime struct (moderation, isDidBlocked, store, certStore, challenges, certProvisioner). Consequences:

• Tests call createServerFromEnv() and drive the entire pipeline against fakes with no real DNS, no socket, no timer — the same discipline the pure SSRF/verify kernels follow.
• The guarded fetch, the DID-document cache, and the signing-key resolver are each built once in the factory and shared, so there is one connection pool and one policy site.
• A last-resort process guard (unhandledRejection/uncaughtException → log and keep serving) lives only at the entry point, backstopping the multi-tenant invariant that one tenant's bad request must never crash the process (roadmap H2).

10. Credentials stay client-held — SECURITY INVARIANT

Normative

A gateway MUST NOT hold a publisher's PDS write credentials and MUST NOT write to any PDS. Publish, rollback, and prune are the publisher's own authenticated actions against their own repo; the gateway is a pure read/serve surface plus (optionally) credential-free naming and mirror-pin endpoints authenticated by short-lived, audience-bound service-auth JWTs — never by held write creds.

As-built

• The gateway never imports a PDS write client. Its only publisher-authenticated endpoints (notify, slug, domain, pin/unpin) verify a short-lived service-auth JWT via ServiceAuthVerifier (createServerFromEnv() authFor()), each audience-bound to SERVICE_DID and lxm-scoped with maxLifetimeSeconds: 300. None of them writes to a PDS: notify only force-refreshes the pointer cache from re-read, re-verified signed state; slug/domain write the gateway's own SQLite naming index; pin/unpin write the gateway's own blob store.
• Publish and rollback happen browser-side in the publisher app. Rollback is packages/publish/src/rollback.ts rollback() — a guarded putRecord of the pub.mini.site record against the publisher's own PdsClient, with swapRecord + swapCommit CAS guards. The publisher UI calls it via apps/publisher/src/main.ts revertTo(), which passes atpClient(agent) — the browser's own OAuth agent (agent.did), never a gateway-held credential. The gateway is never in the write path.

Requirements the code satisfies but the SPEC under-specifies (flagged, not invented)

• §9.2 has no serve-path signature MUST. §9.2 requires only CID derivation from a signed record; it does not demand that the record was signed at all. This gateway verifies the commit signature chain anyway (§3 above), so it passes §9.2 on the merits — but a different conforming implementation could verify nothing and still pass §9.2 as written. conformance-audit.md "Spec defects" recommends §9.2 gain an explicit serve-path signature MUST to codify what this code does. §3 above states the stronger requirement as the intended bar; §9.2 read literally alone is weaker.

Summary of audit-vs-code divergences

The standing audit was last fully swept 2026-07-16 (17c2b01); its OPEN gaps have since largely been closed. Where a reader might otherwise trust a stale FAIL/OPEN verdict:

G3 (read-path rate limit), G5 (notify signature chain), G1/G2 (SSRF redirects, slug CID-shape) are recorded FIXED by the audit and match current code. §10.3 push coalesce (G7) is now confirmed PASS: packages/server/src/pointer-cache.ts PointerCache.refresh() routes through the private #coalesce(), sharing the same #inflight single-flight map as resolve(). (The 2026-07-19 audit refresh flipped G7 PARTIAL → PASS on this evidence.)