- Zig 97%
- JavaScript 1%
- CSS <1%
- HTML <1%
- Shell <1%
zat #
AT Protocol building blocks for zig.
this readme is an ATProto record
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;
hasDisallowedTldfor 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) andtoStringMillis(thetoISOStringform), 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 thehmac-sha256signatures a syncer requests withAccept-Signature(tagsatproto-space-commitandatproto-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 changes0.x.y- bug fixes-alpha.N- prereleases of the next version
the changelog marks breaking changes breaking.