// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // SPDX-License-Identifier: MIT //! Tests for `stamp`, the `sdns://` parser. //! //! Two kinds of stamp appear here. The DNSCrypt and DoH ones are taken //! verbatim from the published `public-resolvers.md`, so what they check is //! agreement with the encoders that wrote them. The rest are protocols that //! list does not carry, so they were built with a short Python script — //! `base64.urlsafe_b64encode` over the length-prefixed structure — which is //! still an encoder other than this one, and the comment on each says what is //! in it. //! //! Every case asserts the fields *and* that re-encoding gives back the text it //! came from. The round trip is what catches an offset read wrongly: a decoder //! that swaps two length-prefixed strings of its own accord still round-trips, //! but one that mistakes where a field begins does not. const std = @import("std"); const uri = @import("root.zig"); const Protocol = uri.stamp.Protocol; const Stamp = uri.stamp.Stamp; const expect = std.testing.expect; const expectEqual = std.testing.expectEqual; const expectEqualSlices = std.testing.expectEqualSlices; const expectEqualStrings = std.testing.expectEqualStrings; const expectError = std.testing.expectError; const alloc = std.testing.allocator; /// AdGuard's DNSCrypt resolver, from the published `public-resolvers.md`. const adguard = "sdns://AQMAAAAAAAAAETk0LjE0MC4xNC4xNDo1NDQzINErR_JS3PLCu_iZEIbq95zkSV2LFsigxDIuUso_OQhzIjIuZG5zY3J5cHQuZGVmYXVsdC5uczEuYWRndWFyZC5jb20"; test "a DNSCrypt stamp, as a provider publishes it" { const s = try Stamp.parse(alloc, adguard); defer s.deinit(); try expectEqual(Protocol.dnscrypt, s.protocol()); const d = s.body.dnscrypt; try expectEqualStrings("94.140.14.14:5443", d.address); try expectEqualStrings("2.dnscrypt.default.ns1.adguard.com", d.provider_name); // The provider key, which is the whole of what a DNSCrypt client trusts. var key: [32]u8 = undefined; _ = try std.fmt.hexToBytes(&key, "d12b47f252dcf2c2bbf8991086eaf79ce4495d8b16c8a0c4322e52ca3f390873"); try expectEqualSlices(u8, &key, &d.public_key); // Props 0x03: DNSSEC and no logging, but this one filters. try expect(d.properties.dnssec); try expect(d.properties.no_log); try expect(!d.properties.no_filter); try expectEqual(@as(u61, 0), d.properties.unknown); const text = try s.toText(alloc); defer alloc.free(text); try expectEqualStrings(adguard, text); } // The same property was checked against the whole of the published lists // rather than the ten stamps below, once, by hand: every `sdns://` string in // `public-resolvers.md` and `relays.md` from // `download.dnscrypt.info/resolvers-list/v3/` -- 1205 of them after // de-duplication, on 2026-09-22 -- parsed and came back byte for byte // identical, with none rejected. The lists are not carried here because they // are somebody else's data with its own licence and they change weekly; the // stamps that stay are the ones each shape is worth having a name for. Re-run // it with a throwaway `@embedFile` over a downloaded copy if the reader or the // writer is touched. test "one stamp of every protocol, decoded and written back" { const stamps = [_][]const u8{ // Published, verbatim: AdGuard's DNSCrypt resolver and its family one, // and Cloudflare's DoH. adguard, "sdns://AQMAAAAAAAAAETk0LjE0MC4xNC4xNTo1NDQzILgxXdexS27jIKRw3C7Wsao5jMnlhvhdRUXWuMm1AFq6ITIuZG5zY3J5cHQuZmFtaWx5Lm5zMS5hZGd1YXJkLmNvbQ", "sdns://AgcAAAAAAAAABzEuMC4wLjEAEmRucy5jbG91ZGZsYXJlLmNvbQovZG5zLXF1ZXJ5", // Built for this test, because `public-resolvers.md` carries no stamp // of these kinds: plain DNS at 192.0.2.1; DoT with one pinned hash and // no address; DoQ with an address and no hash; DoH with a hash, a path // and two bootstrap resolvers; an oblivious target and an oblivious // relay; and the DNSCrypt relay, which is the one stamp with no // properties word. "sdns://AAcAAAAAAAAACTE5Mi4wLjIuMQ", "sdns://AwcAAAAAAAAAACAAAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHxNkb3QuZXhhbXBsZS5jb206ODUz", "sdns://BAcAAAAAAAAADTE5Mi4wLjIuMjo4NTMAD2RvcS5leGFtcGxlLmNvbQ", "sdns://AgcAAAAAAAAACTE5Mi4wLjIuMyAAAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHw9kb2guZXhhbXBsZS5jb20KL2Rucy1xdWVyeYc5LjkuOS45BzEuMS4xLjE", "sdns://BQcAAAAAAAAAEG9kb2guZXhhbXBsZS5jb20KL2Rucy1xdWVyeQ", "sdns://hQcAAAAAAAAACTE5Mi4wLjIuNAARcmVsYXkuZXhhbXBsZS5jb20GL3Byb3h5", "sdns://gRI5NS4yMTYuMTQ5LjE1NDo0NDM", }; for (stamps) |text| { const s = Stamp.parse(alloc, text) catch |err| { std.debug.print("failed to parse {s}: {t}\n", .{ text, err }); return err; }; defer s.deinit(); const written = try s.toText(alloc); defer alloc.free(written); try expectEqualStrings(text, written); } } test "a DoH stamp is an address, a hostname and a path" { // Cloudflare's, verbatim from the published list. const s = try Stamp.parse( alloc, "sdns://AgcAAAAAAAAABzEuMC4wLjEAEmRucy5jbG91ZGZsYXJlLmNvbQovZG5zLXF1ZXJ5", ); defer s.deinit(); const d = s.body.doh; try expectEqualStrings("1.0.0.1", d.address); try expectEqualStrings("dns.cloudflare.com", d.hostname); try expectEqualStrings("/dns-query", d.path); // It pins nothing: the chain is checked against the system trust store // like any other. try expectEqual(@as(usize, 0), d.hashes.len); try expectEqual(@as(usize, 0), d.bootstrap.len); } test "a DoT stamp has no path, and its hash is pinned" { const s = try Stamp.parse( alloc, "sdns://AwcAAAAAAAAAACAAAQIDBAUGBwgJCgsMDQ4PEBESExQVFhcYGRobHB0eHxNkb3QuZXhhbXBsZS5jb206ODUz", ); defer s.deinit(); const d = s.body.dot; // No address: the hostname is resolved first, and the port is in it. try expectEqualStrings("", d.address); try expectEqualStrings("dot.example.com:853", d.hostname); try expectEqualStrings("", d.path); try expectEqual(@as(usize, 1), d.hashes.len); try expectEqual(@as(usize, 32), d.hashes[0].len); try expectEqual(@as(u8, 0), d.hashes[0][0]); try expectEqual(@as(u8, 31), d.hashes[0][31]); } test "a DNSCrypt relay has an address and nothing else" { // The trap in the format: no properties word. A reader that takes eight // bytes off the front of every body reads this address length as a // property bit. const s = try Stamp.parse(alloc, "sdns://gRI5NS4yMTYuMTQ5LjE1NDo0NDM"); defer s.deinit(); try expectEqual(Protocol.dnscrypt_relay, s.protocol()); try expectEqualStrings("95.216.149.154:443", s.body.dnscrypt_relay.address); try expectEqual(@as(?uri.stamp.Properties, null), s.properties()); try expectEqualStrings("95.216.149.154:443", s.address()); } test "text that is not a stamp" { try expectError(error.NotAStamp, Stamp.parse(alloc, "")); try expectError(error.NotAStamp, Stamp.parse(alloc, "sdns:/")); try expectError(error.NotAStamp, Stamp.parse(alloc, "https://example.com/dns-query")); // The scheme is case-insensitive, as RFC 3986 §3.1 makes every scheme. const s = try Stamp.parse(alloc, "SDNS://gRI5NS4yMTYuMTQ5LjE1NDo0NDM"); defer s.deinit(); try expectEqual(Protocol.dnscrypt_relay, s.protocol()); } test "a body that is not base64url" { try expectError(error.InvalidBase64, Stamp.parse(alloc, "sdns://not base64")); // Standard base64's two characters are not this alphabet's. try expectError(error.InvalidBase64, Stamp.parse(alloc, "sdns://AQMAAAAAAAAA+/8")); // Padding is accepted, because somebody's encoder adds it and the bytes // underneath are the same. const s = try Stamp.parse(alloc, "sdns://gRI5NS4yMTYuMTQ5LjE1NDo0NDM="); defer s.deinit(); try expectEqualStrings("95.216.149.154:443", s.body.dnscrypt_relay.address); } test "a protocol byte this module does not know" { // 0x06 is not assigned, and a caller handed a stamp it cannot interpret // would have to guess what to do with it. try expectError(error.UnknownProtocol, Stamp.parse(alloc, "sdns://BgcAAAAAAAAAAAA")); try expectError(error.UnknownProtocol, Stamp.parse(alloc, "sdns://_w")); } test "a length that runs off the end" { // Every field is bounded by a length that came out of the same bytes, so // every read can be made to run past them. try expectError(error.Truncated, Stamp.parse(alloc, "sdns://AQ")); // A DNSCrypt stamp whose address length is larger than what follows. try expectError(error.Truncated, Stamp.parse(alloc, "sdns://AQMAAAAAAAAA_zE")); // A relay whose one length byte promises more than it has. try expectError(error.Truncated, Stamp.parse(alloc, "sdns://gf8x")); } test "bytes after the last field" { // A plain stamp with something extra on the end: this module has either // read it wrongly or it was written wrongly, and either way the fields // before it cannot be trusted. (0x00, props, LP("1.1.1.1"), then a byte.) const trailing = "sdns://AAcAAAAAAAAABzEuMS4xLjHB"; try expectError(error.TrailingBytes, Stamp.parse(alloc, trailing)); } test "a DNSCrypt provider key that is not a key" { // 0x01, props, LP("1.1.1.1"), LP(two bytes), LP("x") -- well formed as a // stamp and unusable as DNSCrypt, so it is refused here rather than // downstream where the length would be checked again. try expectError( error.InvalidPublicKey, Stamp.parse(alloc, "sdns://AQcAAAAAAAAABzEuMS4xLjECAAABeA"), ); } test "an empty hash list and a written-out empty one are the same thing" { // Encoders write "no certificate hashes" as a single element of length // zero, so that is what an empty list reads back as -- and what this // writes for one, which is what makes the round trip byte-identical. const cloudflare = "sdns://AgcAAAAAAAAABzEuMC4wLjEAEmRucy5jbG91ZGZsYXJlLmNvbQovZG5zLXF1ZXJ5"; const s = try Stamp.parse(alloc, cloudflare); defer s.deinit(); try expectEqual(@as(usize, 0), s.body.doh.hashes.len); const text = try s.toText(alloc); defer alloc.free(text); try expectEqualStrings(cloudflare, text); } test "properties this specification has not defined survive a round trip" { // A stamp written by something newer than this module keeps its bits: they // are carried in `Properties.unknown` rather than dropped, so re-encoding // does not quietly weaken what a resolver claimed. var built: Stamp = .{ .arena = undefined, .body = .{ .plain = .{ .properties = .{ .dnssec = true, .unknown = 0x10 }, .address = "192.0.2.1", } }, }; // No arena: nothing here was parsed, so nothing is owned. `write` never // touches it. var buffer: [128]u8 = undefined; var w: std.Io.Writer = .fixed(&buffer); try built.write(&w); const s = try Stamp.parse(alloc, w.buffered()); defer s.deinit(); try expect(s.body.plain.properties.dnssec); try expectEqual(@as(u61, 0x10), s.body.plain.properties.unknown); try expectEqualStrings("192.0.2.1", s.body.plain.address); built.arena = undefined; } test "the accessors every protocol answers" { // `protocol`, `properties` and `address` exist so that a caller choosing // between resolvers does not have to switch on the union to read the three // things every stamp but one has. const s = try Stamp.parse(alloc, adguard); defer s.deinit(); try expectEqual(Protocol.dnscrypt, s.protocol()); try expect(s.properties().?.no_log); try expectEqualStrings("94.140.14.14:5443", s.address()); // An oblivious target is reached through a relay, so it has no address to // report. const target = try Stamp.parse(alloc, "sdns://BQcAAAAAAAAAEG9kb2guZXhhbXBsZS5jb20KL2Rucy1xdWVyeQ"); defer target.deinit(); try expectEqualStrings("", target.address()); try expectEqualStrings("odoh.example.com", target.body.odoh_target.hostname); }