atproto utils for zig zat.dev
README.md

zat #

AT Protocol building blocks for zig.

this readme is an ATProto record

view in zat.dev's repository

zat publishes this readme, the changelog and the devlog as site.standard.document records in the zat.dev repository, written with zat itself. AT Protocol readers and search engines find the docs through them; the records link to the website.

install #

requires zig 0.17+. zat links no libc: its Linux binaries are static, and it builds for Windows and wasi without a C runtime.

zig fetch --save https://tangled.org/zat.dev/zat/archive/main

then in build.zig:

const zat = b.dependency("zat", .{}).module("zat");
exe.root_module.addImport("zat", zat);

what's here #

string primitives - parsing and validation for atproto identifiers
  • Tid - timestamp identifiers (base32-sortable)
  • Did - decentralized identifiers
  • Handle - domain-based handles; hasDisallowedTld for the spec's reserved TLDs (.local, .onion, ...), which parse but must not be registered or resolved
  • Nsid - namespaced identifiers (lexicon types)
  • Rkey - record keys
  • AtUri - at:// URIs
  • Datetime - RFC 3339 datetimes; toString (microseconds) and toStringMillis (the toISOString form), from unix seconds or millis
const zat = @import("zat");

if (zat.AtUri.parse(uri_string)) |uri| {
    const authority = uri.authority();
    const collection = uri.collection();
    const rkey = uri.rkey();
}
identity resolution - resolve handles and DIDs to documents
// handle → DID
var handle_resolver = zat.HandleResolver.init(io, allocator);
defer handle_resolver.deinit();
const did = try handle_resolver.resolve(zat.Handle.parse("bsky.app").?);
defer allocator.free(did);

// DID → document
var did_resolver = zat.DidResolver.init(io, allocator);
defer did_resolver.deinit();
var doc = try did_resolver.resolve(zat.Did.parse("did:plc:z72i7hdynmk6r22z27h6tvur").?);
defer doc.deinit();

const pds = doc.pdsEndpoint();       // "https://..."
const key = doc.signingKey();         // verification method

supports did:plc (via plc.directory) and did:web. handle resolution via HTTP well-known and DNS TXT. HandleResolver.resolveLexiconAuthority(nsid) resolves the DID that publishes an NSID's lexicons from its _lexicon TXT record.

zat.plc builds, signs and hashes did:plc operations: the DAG-CBOR the rotation key signs, the operation CID that the next operation's prev names, and the DID a genesis operation derives.

const op: zat.plc.Operation = .{
    .rotation_keys = &.{rotation_did_key},
    .verification_methods = &.{.{ .id = "atproto", .key = signing_did_key }},
    .also_known_as = &.{"at://alice.example.com"},
    .services = &.{.{ .id = "atproto_pds", .type = "AtprotoPersonalDataServer", .endpoint = "https://pds.example.com" }},
};
const signed = try op.sign(allocator, &rotation_key);
defer signed.deinit(allocator);
const did = signed.did(); // "did:plc:..."; POST signed.json to the directory
CBOR codec - DAG-CBOR encoding and decoding
// decode; the value borrows from `bytes` and allocates its maps and arrays
// without a deinit, so pass an arena
const record = try zat.cbor.decodeAll(arena, bytes);

// navigate values
const text = record.getString("text");
const cid = record.getCid("data");

// encode (deterministic key ordering)
const encoded = try zat.cbor.encodeAlloc(allocator, value);
defer allocator.free(encoded);

full DAG-CBOR support: maps, arrays, byte strings, text strings, integers, floats, booleans, null, CID tags (tag 42). deterministic encoding with sorted keys for signature verification.

cbor.fromJson and cbor.toJson convert between Value and atproto JSON ($bytes, $link). fromJson accepts $bytes with or without padding; toJson writes it unpadded, as the reference PDS does.

cbor.collectBlobRefs lists the ref CID of every {$type: "blob"} in a record, at any depth.

CAR codec - Content Addressable aRchive parsing with CID verification
// parse with SHA-256 CID verification (default); pass an arena
const parsed = try zat.car.read(arena, car_bytes);

const root_cid = parsed.roots[0];
for (parsed.blocks) |block| {
    // block.cid_raw, block.data
}

// skip verification for trusted local data
const fast = try zat.car.readWithOptions(arena, car_bytes, .{
    .verify_block_hashes = false,
});

enforces size limits (configurable max_size, max_blocks) matching indigo's production defaults.

STAR - streaming archives and public repository verification
var reader = try zat.star.PublicRepoReader.init(allocator, input, .{});
defer reader.deinit();
try reader.verifyCommit(public_key, expected_did);
while (try reader.next()) |record| {
    // accumulate provisional results; slices borrow the reader
}
// EOF confirms the reconstructed MST root; publish results now

implements STAR as published 2026-11-03 and the public-repo profiles. STAR-lite archives, which have no control bytes, do not parse. star.Reader validates canonical metadata and reads arbitrary byte pairs; next() supplies a key and value length, and readValue(buffer) consumes the value in caller-sized chunks. Limits can be lowered for an application. PublicRepoReader adds path, order, commit, and root validation, buffering at most one 1 MiB record. Its unsigned-subtree profile verifies integrity without claiming account authenticity. Neither profile establishes freshness. zig build example-verify-star -- repository.star checks repository integrity.

var writer = try zat.star.Writer.init(allocator, output, metadata, .{ .ordered_keys = true });
defer writer.deinit();
try writer.writePair("app.bsky.feed.post/3k2yihcrp6f2c", record_bytes);
try writer.finish();

star.Writer frames pairs after a canonical metadata header and rejects any metadata a Reader would reject. finish() writes the end byte, so an archive is incomplete until it is called. beginPair(key, value_len) followed by writeValue chunks streams a value; ordered_keys enforces the strict key order the atproto repository profiles require. Readers and writers agree with the interop fixtures from cobalt/star.

permissioned spaces - credentials, HTTP signatures, MACs and archives for com.atproto.space.*

zat.space implements the wire primitives of the 2026-11-12 spaces alpha, as the permissioned-data branch of bluesky-social/atproto and its @atproto/space package define them. The protocol is alpha, so this module changes when that branch does, without aliases for superseded names.

const zat = @import("zat");

// a holder signs each request it authorizes with a space credential
const signed = try zat.space.signCredentialUse(allocator, &holder_key, authorization, audience_did);
// ...and the receiver finds that signature by its tag
try zat.space.verifyCredentialUse(allocator, authorization, audience_did, signature_input, signature, cnf_kid);

// a repo host answers a syncer's Accept-Signature with a MAC over the commit
if (try zat.space.mac.parseMacRequest(arena, accept_signature, .commit)) |request| {
    const secret = try zat.space.decapsulate(author_kem_secret, request.key_share);
    const headers = try zat.space.mac.createCommitMacHeaders(allocator, commit, request, &secret);
}
  • SpaceUri - space refs and the URIs of records within a space
  • token - delegation tokens, space credentials and client attestations
  • http_signature - RFC 9421 signatures found by tag (atproto-space-credential), on an RFC 8941 parser
  • kem / mac - the HPKE secret export (info atproto-mac) and the hmac-sha256 signatures a syncer requests with Accept-Signature (tags atproto-space-commit and atproto-space-record)
  • LtHash and archive - the repo set hash, repo STAR and space meta STAR
MST - Merkle Search Tree
// the tree has no deinit: give it an arena
var tree = zat.mst.Mst.init(arena);

try tree.put("app.bsky.feed.post/abc123", value_cid);
const found = tree.get("app.bsky.feed.post/abc123");
try tree.delete("app.bsky.feed.post/abc123");

// compute root CID (serialize → hash → CID)
const root = try tree.rootCid();

the core data structure of an atproto repo. key layer derived from leading zero bits of SHA-256(key), nodes serialized with prefix compression.

crypto - signing, verification, key encoding
// JWT verification
var token = try zat.Jwt.parse(allocator, token_string);
defer token.deinit();
try token.verify(public_key_multibase);

// ECDSA signature verification (P-256 and secp256k1)
try zat.jwt.verifySecp256k1(hash, signature, public_key);
try zat.jwt.verifyP256(hash, signature, public_key);

// multibase/multicodec key parsing
const key_bytes = try zat.multibase.decode(allocator, "zQ3sh...");
defer allocator.free(key_bytes);
const parsed = try zat.multicodec.parsePublicKey(key_bytes);
// parsed.key_type: .secp256k1 or .p256
// parsed.raw: 33-byte compressed public key

// private multikeys ("z..." secp256k1-priv / p256-priv), e.g. a PDS rotation key
const rotation_key = try zat.Keypair.fromPrivateMultikey(allocator, "z3vLWgA9...");

ES256 (P-256) and ES256K (secp256k1) with low-S normalization. RFC 6979 deterministic signing. did:key construction and multibase encoding.

zat.jwt.decodeLeaky(arena, token) splits any compact JWS into its header and payload as JSON objects, the signing input and the signature, for verifiers that check their own claims; it decodes as leniently as the reference SDKs do. zat.jwt.decode returns the same in an arena it owns.

zat.jwk.parsePublicKey(value) turns a public EC JWK into a key jwt.verifyJose accepts, rejecting points off the curve; zat.jwk.selectFromJwks picks a key from a JWKS by kid and alg, and thumbprint gives its RFC 7638 thumbprint.

zat.service_auth.create(allocator, io, &keypair, .{ .iss = did, .aud = service_did, .lxm = nsid }) mints an inter-service auth JWT. zat.service_auth.verify(arena, token, .{ .now = now, .audiences = &.{service_did}, .lxm = nsid }, &resolver) verifies one, asking your resolver for the issuer's #atproto key and once more, refreshed, if the signature fails.

OAuth client helpers - ATProto OAuth ceremony without app storage policy
var transport = zat.HttpTransport.initWithUserAgent(io, allocator, "myapp/1.0 (+https://example.com)");
defer transport.deinit();

const authserver = try zat.oauth.discoverAuthorizationServer(allocator, &transport, pds_url);
defer allocator.free(authserver);

var metadata = try zat.oauth.fetchAuthorizationServerMetadata(allocator, &transport, authserver);
defer metadata.deinit(allocator);

var secrets = try zat.oauth.prepareAuthRequestSecrets(allocator, io);
defer secrets.deinit(allocator);

var par = try zat.oauth.sendParRequest(allocator, io, &transport, .{
    .par_url = metadata.pushed_authorization_request_endpoint,
    .authserver_issuer = metadata.issuer,
    .client_id = client_id,
    .redirect_uri = redirect_uri,
    .scope = "atproto repo:example.app.record",
    .state = secrets.state,
    .pkce_challenge = secrets.pkce_challenge,
    .login_hint = handle,
    .client_keypair = &client_keypair,
    .dpop_keypair = &secrets.dpop_keypair,
});
defer par.deinit(allocator);

also includes client metadata JSON generation, RFC 3986 percent-encoding (percentEncode, percentEncodeAlloc), authorization URL formatting, code/refresh token exchange, DPoP nonce retry, and DPoP-authenticated resource requests. cookies, sessions, redirects, and persistence stay with your application or web framework.

zat.percent provides strict URI-component decoding: decodeAlloc returns an owned slice and decodedEql compares without allocating. malformed escapes are rejected, decoding happens once, and + stays literal. scope authorization and form-urlencoded parsing remain caller policy.

for the server side, zat.oauth.verifyDpopProof(arena, dpop_header, .{ .htm = method, .htu = url, .now = now }) checks a DPoP proof against the request and returns its key thumbprint and jti; your server keeps the replay store and issues the nonces it passes in. zat.oauth.verifyClientAssertion(arena, assertion, client_jwks, .{ .client_id = client_id, .audience = issuer, .now = now }) does the same for private_key_jwt client assertions; its typ, require_kid and max_lifetime options cover client attestations.

commit verification - check a repo CAR against the account's signing key
// given CAR bytes and the account's public key (see identity resolution)
const result = try zat.verifyCommitCar(allocator, car_bytes, public_key, .{
    .expected_did = did,
    .require_complete_repo = true, // reject CARs with missing MST/record blocks
});
// result.commit_did, result.commit_rev, result.commit_cid, result.record_count

atproto repos are self-authenticating, so anything that accepts one from the network verifies it before trusting it: checks the commit signature, confirms the MST root matches the commit's data CID, and validates every block hash. verifyCommitDiff does the same for the partial CARs on firehose #commit events. this is how zds guards com.atproto.repo.importRepo — an uploaded CAR is verified against the account's DID document before the PDS accepts it.

signCommit is the produce side: it builds and signs the canonical commit block, and round-trips through verifyCommitCar in the test suite.

firehose client - raw CBOR event stream from relay
var client = zat.FirehoseClient.init(io, allocator, .{});
defer client.deinit();

const Handler = struct {
    pub fn onEvent(_: *@This(), event: zat.FirehoseEvent) void {
        switch (event) {
            .commit => |commit| {
                // commit.repo, commit.ops, commit.blocks, ...
                _ = commit;
            },
            else => {},
        }
    }
};
var handler: Handler = .{};
try client.subscribe(&handler);

connects to com.atproto.sync.subscribeRepos via WebSocket. decodes binary CBOR frames into typed events. round-robin host rotation with backoff.

the server side encodes the same frames: firehose.encodeCommitEvent, encodeSyncEvent, encodeIdentityEvent, encodeAccountEvent and encodeInfoEvent validate what the lexicon requires and return a frame ready to send. encodeSyncEvent takes the signed commit block and reads did and rev from it. encodeErrorFrame writes the {op: -1} frame a server sends before closing the stream, such as FutureCursor.

jetstream client - typed JSON event stream
var client = zat.JetstreamClient.init(io, allocator, .{
    .wanted_collections = &.{"app.bsky.feed.post"},
});
defer client.deinit();

const Handler = struct {
    pub fn onEvent(_: *@This(), event: zat.JetstreamEvent) void {
        switch (event) {
            .commit => |commit| {
                const record = commit.record orelse return;
                // process...
                _ = record;
            },
            else => {},
        }
    }
};
var handler: Handler = .{};
try client.subscribe(&handler);

connects to jetstream (bluesky's JSON event stream). typed events, automatic reconnection with cursor tracking, round-robin across community relays.

xrpc client - call AT Protocol endpoints
var client = zat.XrpcClient.init(io, allocator, "https://bsky.social");
defer client.deinit();

const nsid = zat.Nsid.parse("app.bsky.actor.getProfile").?;
var response = try client.query(nsid, params);
defer response.deinit();

if (response.ok()) {
    var json = try response.json();
    defer json.deinit();
    // use json.value
}
json helpers - navigate nested json without verbose if-chains

Use the getters when you need a few fields or want to decide what to do with each missing value. They do not allocate: strings, arrays, and objects borrow the parsed JSON's storage, so keep it alive while using the results.

const uri = zat.json.getString(value, "embed.external.uri");
const count = zat.json.getInt(value, "meta.count");
const first_alt = zat.json.getString(value, "embed.images.0.alt");

Paths can be string literals or runtime strings. Dots separate object keys, and numeric segments index arrays. A missing path or wrong type returns null; use orelse to skip, supply a default, or return an application error. When a present value of the wrong type must be rejected separately, use getPath and inspect its tag. For a literal key containing dots, use the object's get method instead.

For a coherent group of fields, extractAt decodes into a local struct. Its tuple path selects an object subtree; .{} selects the root. JSON is still validated at runtime, and unknown fields are ignored.

const FeedPost = struct {
    uri: []const u8,
    cid: []const u8,
    record: struct {
        text: []const u8 = "",
    },
};
var arena = std.heap.ArenaAllocator.init(allocator);
defer arena.deinit();
const post = try zat.json.extractAt(FeedPost, arena.allocator(), value, .{"post"});
// use post before arena.deinit()

Unlike the getters, this uses std.json.parseFromValueLeaky: decoding ordinary string and slice fields allocates, and allocations belong to the supplied allocator, including allocations made before a parse failure. An arena makes cleanup straightforward. Struct defaults apply to absent fields, not wrong-type values; a missing optional field still needs a default such as = null. extractAtOptional catches every decoding error and returns null, including allocation failures, so use extractAt when you need to distinguish errors.

If you already know the shape before parsing the response body, decode directly with std.json.parseFromSlice(T, allocator, body, .{ .ignore_unknown_fields = true }) and defer parsed.deinit() rather than building an intermediate std.json.Value.

used by #

downstream projects — what's building on zat

protocol infrastructure #

project what it does
zds AT Protocol PDS — repos, blobs, OAuth, passkeys, firehose, permissioned spaces (live)
zlay AT Protocol relay — crawls every PDS directly, verifies commit signatures, serves the merged event stream (live)
stream Jetstream V2 service with the whole network archived behind it — 16.3M repos, sealed segments back to seq 1 (live)
jetstream the zig SDK for Jetstream v2 services — subscribe, archive backfill, failover

applications #

project what it does
pub-search keyword and semantic search across AT Protocol publishing platforms, with an Atlas for exploring related writing
typeahead community actor search — indexes profiles and activity from the firehose, with verified identity resolution
pollz real-time polls — polls and votes live in users' repos, written through OAuth and indexed from Jetstream
coral named-entity recognition over the firehose (live)
pensieve public memory search over a repo — semantic artifacts extracted from arbitrary record shapes

develop #

just check                     # formatting and import paths
zig build test --summary all   # unit and interop tests
HEGEL_SEED=101 HEGEL_TEST_CASES=1000 zig build fuzz-percent -Dhegel # optional decoder properties

benchmarks #

zat is benchmarked against the Go (indigo, atmos), Rust (rsky, shrike, jacquard), Python, and Elixir ecosystems in atproto-bench:

  • firehose decode (CID-verified): 226k frames/sec (zat) vs 62k (atmos) vs 53k (rsky) vs 20k (indigo)
  • MST insert + root: 5.7M records/sec, producing the same root bytes as atmos and shrike
  • signature verify: 21.6k verifies/sec — ahead of Go (12k–19k), behind Rust (~27k); ECDSA dominates every SDK's pipeline
  • end-to-end repo verification (handle → signature-checked repo): ~300ms compute (zat) vs ~410ms (indigo) vs ~422ms (rsky crates)

specs #

validation follows atproto.com/specs. passes the atproto interop test suite (syntax, crypto, MST vectors).

scope #

zat grows when something downstream needs it, not ahead of demand. it is a set of building blocks, not a "one true SDK", an opinionated app framework, or a replacement for understanding the protocol.

these stay out unless real demand shows up:

  • lexicon codegen — probably a separate project
  • higher-level clients and frameworks — too opinionated
  • token refresh and session management — app-specific
  • feed generator scaffolding — each feed is unique

versioning #

pre-1.0 semver:

  • 0.x.0 - new features and breaking changes
  • 0.x.y - bug fixes
  • -alpha.N - prereleases of the next version

the changelog marks breaking changes breaking.

license #

MIT


devlog · changelog