initial commit: zig atproto primitives

internal APIs for TID, AtUri, and Did parsing.
- Tid: parse/generate timestamp identifiers (base32-sortable)
- AtUri: parse at://did/collection/rkey URIs
- Did: parse did:plc and did:web identifiers

all APIs start in internal module, promoted to root when stable.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

.gitignore

···
+.zig-cache/
+zig-out/

build.zig

···
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+    const optimize = b.standardOptimizeOption(.{});
+
+    const mod = b.addModule("zat", .{
+        .root_source_file = b.path("src/root.zig"),
+        .target = target,
+        .optimize = optimize,
+    });
+
+    const tests = b.addTest(.{ .root_module = mod });
+    const run_tests = b.addRunArtifact(tests);
+
+    const test_step = b.step("test", "run unit tests");
+    test_step.dependOn(&run_tests.step);
+}

build.zig.zon

···
+.{
+    .name = .zat,
+    .version = "0.0.1-alpha",
+    .fingerprint = 0x8da9db57ee82fbe4,
+    .minimum_zig_version = "0.15.0",
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+    },
+}

docs/plan.md

···
+# zat - zig atproto primitives
+
+low-level building blocks for atproto applications in zig. not a full sdk - just the pieces that everyone reimplements.
+
+## philosophy
+
+from studying the wishlists: the pain is real, but the suggested solutions often over-engineer. we want:
+
+1. **primitives, not frameworks** - types and parsers, not http clients or feed scaffolds
+2. **layered design** - each piece usable independently
+3. **zig idioms** - explicit buffers, comptime validation, no hidden allocations
+4. **minimal scope** - solve the repeated pain, not every possible need
+
+## scope
+
+### in scope (v0.1)
+
+**tid** - timestamp identifiers
+- parse tid string to timestamp (microseconds)
+- generate tid from timestamp
+- extract clock id
+- comptime validation of format
+
+**at-uri** - `at://did:plc:xyz/collection/rkey`
+- parse to components (did, collection, rkey)
+- construct from components
+- validation
+
+**did** - decentralized identifiers
+- parse did:plc and did:web
+- validate format
+- type-safe wrapper (not just `[]const u8`)
+
+### maybe v0.2
+
+**facets** - extract links/mentions/tags from post records
+- given a json value with `text` and `facets`, extract urls
+- byte-offset handling for utf-8
+
+**cid** - content identifiers
+- parse cid strings
+- validate format
+
+### out of scope (for now)
+
+- lexicon codegen (too big, could be its own project)
+- xrpc client (std.http.Client is fine)
+- session management (app-specific)
+- jetstream client (websocket.zig exists, just wire it)
+- feed generator framework (each feed is unique)
+- did resolution (requires http, out of primitive scope)
+
+## design
+
+### tid.zig
+
+```zig
+pub const Tid = struct {
+    raw: [13]u8,
+
+    /// parse a tid string. returns null if invalid.
+    pub fn parse(s: []const u8) ?Tid
+
+    /// timestamp in microseconds since unix epoch
+    pub fn timestamp(self: Tid) u64
+
+    /// clock identifier (lower 10 bits)
+    pub fn clockId(self: Tid) u10
+
+    /// generate tid for current time
+    pub fn now() Tid
+
+    /// generate tid for specific timestamp
+    pub fn fromTimestamp(ts: u64, clock_id: u10) Tid
+
+    /// format to string
+    pub fn format(self: Tid, buf: *[13]u8) void
+};
+```
+
+encoding: base32-sortable (chars `234567abcdefghijklmnopqrstuvwxyz`), 13 chars, first 11 encode 53-bit timestamp, last 2 encode 10-bit clock id.
+
+### at_uri.zig
+
+```zig
+pub const AtUri = struct {
+    /// the full uri string (borrowed, not owned)
+    raw: []const u8,
+
+    /// offsets into raw for each component
+    did_end: usize,
+    collection_end: usize,
+
+    pub fn parse(s: []const u8) ?AtUri
+
+    pub fn did(self: AtUri) []const u8
+    pub fn collection(self: AtUri) []const u8
+    pub fn rkey(self: AtUri) []const u8
+
+    /// construct a new uri. caller owns the buffer.
+    pub fn format(
+        buf: []u8,
+        did: []const u8,
+        collection: []const u8,
+        rkey: []const u8,
+    ) ?[]const u8
+};
+```
+
+### did.zig
+
+```zig
+pub const Did = union(enum) {
+    plc: [24]u8,  // the identifier after "did:plc:"
+    web: []const u8,  // the domain after "did:web:"
+
+    pub fn parse(s: []const u8) ?Did
+
+    /// format to string
+    pub fn format(self: Did, buf: []u8) ?[]const u8
+
+    /// check if this is a plc did
+    pub fn isPlc(self: Did) bool
+};
+```
+
+## structure
+
+```
+zat/
+├── build.zig
+├── build.zig.zon
+├── src/
+│   ├── root.zig           # public API (stable exports)
+│   ├── internal.zig       # internal API (experimental)
+│   └── internal/
+│       ├── tid.zig
+│       ├── at_uri.zig
+│       └── did.zig
+└── docs/
+    └── plan.md
+```
+
+## internal → public promotion
+
+new features start in `internal` where we can iterate freely. when an API stabilizes:
+
+```zig
+// in root.zig, uncomment to promote:
+pub const Tid = internal.Tid;
+```
+
+users who need bleeding-edge access can always use:
+
+```zig
+const zat = @import("zat");
+const tid = zat.internal.Tid.parse("...");
+```
+
+this pattern exists indefinitely - even after 1.0, new experimental features start in internal.
+
+## decisions
+
+### why not typed lexicons?
+
+codegen from lexicon json is a big project on its own. the core pain (json navigation) can be partially addressed by documenting patterns, and the sdk should work regardless of how people parse json.
+
+### why not an http client wrapper?
+
+zig 0.15's `std.http.Client` with `Io.Writer.Allocating` works well. wrapping it doesn't add much value. the real pain is around auth token refresh and rate limiting - those are better solved at the application level where retry logic is domain-specific.
+
+### why not websocket/jetstream?
+
+websocket.zig already exists and works well. the jetstream protocol is simple json messages. a thin wrapper doesn't justify a dependency.
+
+### borrowing vs owning
+
+for parse operations, we borrow slices into the input rather than allocating. callers who need owned data can dupe. this matches zig's explicit memory style.
+
+## next steps
+
+1. ~~implement tid.zig with tests~~ done
+2. ~~implement at_uri.zig with tests~~ done
+3. ~~implement did.zig with tests~~ done
+4. ~~wire up build.zig as a module~~ done
+5. try using it in find-bufo or music-atmosphere-feed to validate the api
+6. iterate on internal APIs based on real usage
+7. promote stable APIs to root.zig

src/internal.zig

···
+//! zat internal module
+//!
+//! experimental APIs that haven't stabilized yet.
+//! everything here is subject to change without notice.
+//!
+//! when an API stabilizes, it gets promoted to root.zig.
+
+pub const Tid = @import("internal/tid.zig").Tid;
+pub const AtUri = @import("internal/at_uri.zig").AtUri;
+pub const Did = @import("internal/did.zig").Did;
+
+test {
+    _ = @import("internal/tid.zig");
+    _ = @import("internal/at_uri.zig");
+    _ = @import("internal/did.zig");
+}

src/internal/at_uri.zig

···
+//! AT-URI Parser
+//!
+//! at-uris identify records in the atproto network.
+//! format: at://<did>/<collection>/<rkey>
+//!
+//! examples:
+//! - at://did:plc:xyz/app.bsky.feed.post/abc123
+//! - at://did:web:example.com/app.bsky.actor.profile/self
+
+const std = @import("std");
+
+pub const AtUri = struct {
+    /// the full uri string (borrowed, not owned)
+    raw: []const u8,
+
+    /// offset where did ends (after "at://")
+    did_end: usize,
+
+    /// offset where collection ends
+    collection_end: usize,
+
+    const prefix = "at://";
+
+    /// parse an at-uri. returns null if invalid.
+    pub fn parse(s: []const u8) ?AtUri {
+        if (!std.mem.startsWith(u8, s, prefix)) return null;
+
+        const after_prefix = s[prefix.len..];
+
+        // find first slash (end of did)
+        const did_end_rel = std.mem.indexOfScalar(u8, after_prefix, '/') orelse return null;
+        if (did_end_rel == 0) return null; // empty did
+
+        const after_did = after_prefix[did_end_rel + 1 ..];
+
+        // find second slash (end of collection)
+        const collection_end_rel = std.mem.indexOfScalar(u8, after_did, '/') orelse return null;
+        if (collection_end_rel == 0) return null; // empty collection
+
+        // check rkey isn't empty
+        const rkey_start = prefix.len + did_end_rel + 1 + collection_end_rel + 1;
+        if (rkey_start >= s.len) return null;
+
+        return .{
+            .raw = s,
+            .did_end = prefix.len + did_end_rel,
+            .collection_end = prefix.len + did_end_rel + 1 + collection_end_rel,
+        };
+    }
+
+    /// the did portion (e.g., "did:plc:xyz")
+    pub fn did(self: AtUri) []const u8 {
+        return self.raw[prefix.len..self.did_end];
+    }
+
+    /// the collection portion (e.g., "app.bsky.feed.post")
+    pub fn collection(self: AtUri) []const u8 {
+        return self.raw[self.did_end + 1 .. self.collection_end];
+    }
+
+    /// the rkey portion (e.g., "abc123")
+    pub fn rkey(self: AtUri) []const u8 {
+        return self.raw[self.collection_end + 1 ..];
+    }
+
+    /// format a new at-uri into the provided buffer.
+    /// returns the slice of the buffer used, or null if buffer too small.
+    pub fn format(
+        buf: []u8,
+        did_str: []const u8,
+        collection_str: []const u8,
+        rkey_str: []const u8,
+    ) ?[]const u8 {
+        const total_len = prefix.len + did_str.len + 1 + collection_str.len + 1 + rkey_str.len;
+        if (buf.len < total_len) return null;
+
+        var pos: usize = 0;
+
+        @memcpy(buf[pos..][0..prefix.len], prefix);
+        pos += prefix.len;
+
+        @memcpy(buf[pos..][0..did_str.len], did_str);
+        pos += did_str.len;
+
+        buf[pos] = '/';
+        pos += 1;
+
+        @memcpy(buf[pos..][0..collection_str.len], collection_str);
+        pos += collection_str.len;
+
+        buf[pos] = '/';
+        pos += 1;
+
+        @memcpy(buf[pos..][0..rkey_str.len], rkey_str);
+        pos += rkey_str.len;
+
+        return buf[0..pos];
+    }
+};
+
+test "parse valid at-uri" {
+    const uri = AtUri.parse("at://did:plc:xyz/app.bsky.feed.post/abc123") orelse return error.InvalidUri;
+    try std.testing.expectEqualStrings("did:plc:xyz", uri.did());
+    try std.testing.expectEqualStrings("app.bsky.feed.post", uri.collection());
+    try std.testing.expectEqualStrings("abc123", uri.rkey());
+}
+
+test "parse did:web uri" {
+    const uri = AtUri.parse("at://did:web:example.com/app.bsky.actor.profile/self") orelse return error.InvalidUri;
+    try std.testing.expectEqualStrings("did:web:example.com", uri.did());
+    try std.testing.expectEqualStrings("app.bsky.actor.profile", uri.collection());
+    try std.testing.expectEqualStrings("self", uri.rkey());
+}
+
+test "reject invalid uris" {
+    // missing prefix
+    try std.testing.expect(AtUri.parse("did:plc:xyz/app.bsky.feed.post/abc") == null);
+
+    // wrong prefix
+    try std.testing.expect(AtUri.parse("http://did:plc:xyz/app.bsky.feed.post/abc") == null);
+
+    // missing collection
+    try std.testing.expect(AtUri.parse("at://did:plc:xyz") == null);
+
+    // missing rkey
+    try std.testing.expect(AtUri.parse("at://did:plc:xyz/app.bsky.feed.post") == null);
+
+    // empty did
+    try std.testing.expect(AtUri.parse("at:///app.bsky.feed.post/abc") == null);
+}
+
+test "format at-uri" {
+    var buf: [256]u8 = undefined;
+    const result = AtUri.format(&buf, "did:plc:xyz", "app.bsky.feed.post", "abc123") orelse return error.BufferTooSmall;
+    try std.testing.expectEqualStrings("at://did:plc:xyz/app.bsky.feed.post/abc123", result);
+}

src/internal/did.zig

···
+//! DID - Decentralized Identifier
+//!
+//! dids are globally unique identifiers in the atproto network.
+//! supports did:plc and did:web methods.
+//!
+//! examples:
+//! - did:plc:z72i7hdynmk6r22z27h6tvur
+//! - did:web:example.com
+
+const std = @import("std");
+
+pub const Did = struct {
+    /// the full did string (borrowed, not owned)
+    raw: []const u8,
+
+    /// the method (plc or web)
+    method: Method,
+
+    /// offset where method-specific identifier starts
+    id_start: usize,
+
+    pub const Method = enum {
+        plc,
+        web,
+    };
+
+    /// parse a did string. returns null if invalid.
+    pub fn parse(s: []const u8) ?Did {
+        if (!std.mem.startsWith(u8, s, "did:")) return null;
+
+        const after_did = s[4..];
+
+        if (std.mem.startsWith(u8, after_did, "plc:")) {
+            const id = after_did[4..];
+            if (id.len == 0) return null;
+            // plc identifiers should be 24 base32 chars
+            if (!isValidPlcId(id)) return null;
+            return .{
+                .raw = s,
+                .method = .plc,
+                .id_start = 8,
+            };
+        }
+
+        if (std.mem.startsWith(u8, after_did, "web:")) {
+            const domain = after_did[4..];
+            if (domain.len == 0) return null;
+            return .{
+                .raw = s,
+                .method = .web,
+                .id_start = 8,
+            };
+        }
+
+        return null;
+    }
+
+    /// the method-specific identifier
+    /// for plc: the 24-char base32 id
+    /// for web: the domain
+    pub fn identifier(self: Did) []const u8 {
+        return self.raw[self.id_start..];
+    }
+
+    /// check if this is a plc did
+    pub fn isPlc(self: Did) bool {
+        return self.method == .plc;
+    }
+
+    /// check if this is a web did
+    pub fn isWeb(self: Did) bool {
+        return self.method == .web;
+    }
+
+    /// get the full did string
+    pub fn str(self: Did) []const u8 {
+        return self.raw;
+    }
+
+    fn isValidPlcId(id: []const u8) bool {
+        // plc ids are base32 encoded (a-z, 2-7)
+        for (id) |c| {
+            const valid = (c >= 'a' and c <= 'z') or (c >= '2' and c <= '7');
+            if (!valid) return false;
+        }
+        return true;
+    }
+};
+
+test "parse did:plc" {
+    const did = Did.parse("did:plc:z72i7hdynmk6r22z27h6tvur") orelse return error.InvalidDid;
+    try std.testing.expect(did.isPlc());
+    try std.testing.expect(!did.isWeb());
+    try std.testing.expectEqualStrings("z72i7hdynmk6r22z27h6tvur", did.identifier());
+}
+
+test "parse did:web" {
+    const did = Did.parse("did:web:example.com") orelse return error.InvalidDid;
+    try std.testing.expect(did.isWeb());
+    try std.testing.expect(!did.isPlc());
+    try std.testing.expectEqualStrings("example.com", did.identifier());
+}
+
+test "reject invalid dids" {
+    // missing prefix
+    try std.testing.expect(Did.parse("plc:xyz") == null);
+
+    // unknown method
+    try std.testing.expect(Did.parse("did:unknown:xyz") == null);
+
+    // empty identifier
+    try std.testing.expect(Did.parse("did:plc:") == null);
+    try std.testing.expect(Did.parse("did:web:") == null);
+
+    // invalid plc chars
+    try std.testing.expect(Did.parse("did:plc:INVALID") == null);
+}

src/internal/tid.zig

···
+//! TID - Timestamp Identifier
+//!
+//! tids encode a timestamp and clock id in a base32-sortable format.
+//! format: 13 characters using alphabet "234567abcdefghijklmnopqrstuvwxyz"
+//! - first 11 chars: 53-bit timestamp (microseconds since epoch)
+//! - last 2 chars: 10-bit clock identifier
+//!
+//! the encoding is designed to be lexicographically sortable by time.
+
+const std = @import("std");
+
+pub const Tid = struct {
+    raw: [13]u8,
+
+    const alphabet = "234567abcdefghijklmnopqrstuvwxyz";
+
+    /// parse a tid string. returns null if invalid.
+    pub fn parse(s: []const u8) ?Tid {
+        if (s.len != 13) return null;
+
+        var result: Tid = undefined;
+        for (s, 0..) |c, i| {
+            if (charToValue(c) == null) return null;
+            result.raw[i] = c;
+        }
+        return result;
+    }
+
+    /// timestamp in microseconds since unix epoch
+    pub fn timestamp(self: Tid) u64 {
+        var ts: u64 = 0;
+        for (self.raw[0..11]) |c| {
+            const val = charToValue(c) orelse unreachable;
+            ts = (ts << 5) | val;
+        }
+        return ts;
+    }
+
+    /// clock identifier (lower 10 bits)
+    pub fn clockId(self: Tid) u10 {
+        var id: u10 = 0;
+        for (self.raw[11..13]) |c| {
+            const val: u10 = @intCast(charToValue(c) orelse unreachable);
+            id = (id << 5) | val;
+        }
+        return id;
+    }
+
+    /// generate tid from timestamp and clock id
+    pub fn fromTimestamp(ts: u64, clock_id: u10) Tid {
+        var result: Tid = undefined;
+
+        // encode timestamp (53 bits -> 11 chars)
+        var t = ts;
+        var i: usize = 11;
+        while (i > 0) {
+            i -= 1;
+            result.raw[i] = alphabet[@intCast(t & 0x1f)];
+            t >>= 5;
+        }
+
+        // encode clock id (10 bits -> 2 chars)
+        var c: u10 = clock_id;
+        i = 13;
+        while (i > 11) {
+            i -= 1;
+            result.raw[i] = alphabet[@intCast(c & 0x1f)];
+            c >>= 5;
+        }
+
+        return result;
+    }
+
+    /// get the raw string representation
+    pub fn str(self: *const Tid) []const u8 {
+        return &self.raw;
+    }
+
+    fn charToValue(c: u8) ?u5 {
+        return switch (c) {
+            '2'...'7' => @intCast(c - '2'),
+            'a'...'z' => @intCast(c - 'a' + 6),
+            else => null,
+        };
+    }
+};
+
+test "parse valid tid" {
+    // generate a valid tid and parse it back
+    const generated = Tid.fromTimestamp(1704067200000000, 42);
+    const tid = Tid.parse(generated.str()) orelse return error.InvalidTid;
+    try std.testing.expectEqual(@as(u64, 1704067200000000), tid.timestamp());
+    try std.testing.expectEqual(@as(u10, 42), tid.clockId());
+}
+
+test "reject invalid tid" {
+    // wrong length
+    try std.testing.expect(Tid.parse("abc") == null);
+    try std.testing.expect(Tid.parse("") == null);
+
+    // invalid chars
+    try std.testing.expect(Tid.parse("0000000000000") == null);
+    try std.testing.expect(Tid.parse("1111111111111") == null);
+}
+
+test "roundtrip" {
+    const ts: u64 = 1704067200000000; // 2024-01-01 00:00:00 UTC in microseconds
+    const clock: u10 = 42;
+
+    const tid = Tid.fromTimestamp(ts, clock);
+    try std.testing.expectEqual(ts, tid.timestamp());
+    try std.testing.expectEqual(clock, tid.clockId());
+}

src/root.zig

···
+//! zat - zig atproto primitives (alpha)
+//!
+//! low-level building blocks for atproto applications.
+//! not a full sdk - just the pieces everyone reimplements.
+//!
+//! ## stability
+//!
+//! this is alpha software (0.0.1-alpha). the public API is minimal by design.
+//! new features start in `internal` and get promoted here when stable.
+//!
+//! ## public api
+//!
+//! currently empty - everything is still in internal while we iterate.
+//!
+//! ## internal api
+//!
+//! for bleeding-edge features, use the internal module directly:
+//!
+//! ```zig
+//! const zat = @import("zat");
+//!
+//! // internal APIs - subject to change
+//! const tid = zat.internal.Tid.parse("...") orelse return error.InvalidTid;
+//! const uri = zat.internal.AtUri.parse("at://did:plc:xyz/collection/rkey") orelse return error.InvalidUri;
+//! const did = zat.internal.Did.parse("did:plc:xyz") orelse return error.InvalidDid;
+//! ```
+//!
+//! when these stabilize, they'll be promoted to `zat.Tid`, `zat.AtUri`, etc.
+
+/// experimental and in-progress APIs.
+/// everything here is subject to change without notice.
+pub const internal = @import("internal.zig");
+
+// --- stable public API ---
+// (promoted from internal when ready)
+//
+// example of promotion:
+// pub const Tid = internal.Tid;
+
+test {
+    _ = internal;
+}