Something went wrong. Try again.
A URI parser and formatter for Zig, modelled on Python's hyperlink package, with LDAP URLs, file: URIs and sdns:// DNS stamps beside it.
Something went wrong. Try again.
123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie <jeff@ocjtech.us>// SPDX-License-Identifier: MIT
//! IDNA as specified by [UTS #46], the profile browsers implement.//!//! `toAscii` turns a Unicode domain name into its all-ASCII `xn--` form for//! the wire; `toUnicode` reverses it for display. Both run the UTS #46 §4//! processing pipeline: map each code point through the IDNA mapping table,//! normalize to NFC, split on `.`, then convert and validate each label.//!//! The mapping table is generated into `idna_table.zig`; every other Unicode//! property comes from uucode. Non-transitional processing is the default,//! matching current browsers: `faß.de` keeps its `ß` rather than becoming//! `fass.de`.//!//! [UTS #46]: https://www.unicode.org/reports/tr46/
const std = @import("std");const uucode = @import("uucode");
const normalization = @import("normalization.zig");const punycode = @import("punycode.zig");const table = @import("idna_table.zig");
const acePrefix = "xn--";
pub const Error = error{ /// A code point that UTS #46 marks disallowed, or one rejected by the /// STD3 rules when those are enabled. DisallowedCodePoint, /// A label is not in Normalization Form C, begins or ends with a hyphen, /// has hyphens in the third and fourth positions, or begins with a /// combining mark. InvalidLabel, /// A ZWJ or ZWNJ appeared somewhere the CONTEXTJ rules forbid. InvalidJoiner, /// The label violates the Bidi rule of RFC 5893. InvalidBidi, /// An `xn--` label whose Punycode body does not decode. InvalidPunycode, /// A label is empty or longer than 63 bytes, or the name exceeds 253. InvalidLength, /// An empty label somewhere other than the end, as in `a..c`. A single /// trailing empty label is the DNS root and is allowed. EmptyLabel, /// The input is not well-formed UTF-8. InvalidUtf8,} || std.mem.Allocator.Error;
pub const Options = struct { /// Apply the deviation mappings, folding `ß` to `ss` and `ς` to `σ`. /// Off by default: browsers moved to non-transitional processing, and /// leaving it off keeps `faß.de` distinct from `fass.de`. transitional: bool = false, /// Restrict labels to letters, digits and hyphen (STD3 rules). use_std3_ascii_rules: bool = false, /// Reject leading, trailing and double hyphens in the third and fourth /// positions. check_hyphens: bool = true, /// Apply the CONTEXTJ rules for ZWJ and ZWNJ. check_joiners: bool = true, /// Apply the Bidi rule of RFC 5893. check_bidi: bool = true, /// Enforce the DNS length limits: 1..63 bytes per label, 1..253 overall. verify_dns_length: bool = true,};
/// The UTS #46 status of a code point.fn lookup(cp: u21) table.Entry { var lo: usize = 0; var hi: usize = table.entries.len; while (lo < hi) { const mid = lo + (hi - lo) / 2; const e = table.entries[mid]; if (cp < e.lo) hi = mid else if (cp > e.hi) lo = mid + 1 else return e; } // The generated table covers the whole code point space, so this is // unreachable for any valid u21. unreachable;}
fn isMark(cp: u21) bool { return switch (uucode.get(.general_category, cp)) { .mark_nonspacing, .mark_spacing_combining, .mark_enclosing => true, else => false, };}
/// STD3: ASCII letters, digits and hyphen only.fn isStd3Ascii(cp: u21) bool { return (cp >= 'a' and cp <= 'z') or (cp >= 'A' and cp <= 'Z') or (cp >= '0' and cp <= '9') or cp == '-';}
/// UTS #46 §4 step 1: map every code point through the IDNA table.fn mapCodePoints(alloc: std.mem.Allocator, input: []const u21, opts: Options) Error![]u21 { var out: std.ArrayList(u21) = .empty; errdefer out.deinit(alloc); try out.ensureTotalCapacity(alloc, input.len);
for (input) |cp| { // The STD3 restriction is deliberately *not* applied here. It belongs // to label validation, after normalization: `=` followed by U+0338 // composes to U+2260, and rejecting the `=` up front would lose a // name that is perfectly valid once composed. const e = lookup(cp); switch (e.status) { .valid => try out.append(alloc, cp), .ignored => {}, .mapped => try out.appendSlice(alloc, table.mappings[e.map_off..][0..e.map_len]), .deviation => if (opts.transitional) try out.appendSlice(alloc, table.mappings[e.map_off..][0..e.map_len]) else try out.append(alloc, cp), .disallowed => return error.DisallowedCodePoint, } } return out.toOwnedSlice(alloc);}
/// RFC 5892 Appendix A.1 and A.2, the CONTEXTJ rules.fn checkJoiners(label: []const u21) Error!void { for (label, 0..) |cp, i| { if (cp != 0x200C and cp != 0x200D) continue; if (i == 0) return error.InvalidJoiner; // Both joiners are allowed directly after a Virama. if (uucode.get(.canonical_combining_class, label[i - 1]) == 9) continue; // ZWJ has no other legal context. if (cp == 0x200D) return error.InvalidJoiner;
// ZWNJ additionally allows a joining sequence: // (L|D) T* ZWNJ T* (R|D) var j = i; var ok_before = false; while (j > 0) { j -= 1; switch (uucode.get(.joining_type, label[j])) { .transparent => continue, .left_joining, .dual_joining => ok_before = true, else => {}, } break; } if (!ok_before) return error.InvalidJoiner;
var k = i + 1; var ok_after = false; while (k < label.len) : (k += 1) { switch (uucode.get(.joining_type, label[k])) { .transparent => continue, .right_joining, .dual_joining => ok_after = true, else => {}, } break; } if (!ok_after) return error.InvalidJoiner; }}
const Bidi = enum { ltr, rtl };
/// Whether any label makes this a "Bidi domain name" (RFC 5893 §1.4).fn isBidiDomain(labels: []const []const u21) bool { for (labels) |label| { for (label) |cp| { switch (uucode.get(.bidi_class, cp)) { .right_to_left, .right_to_left_arabic, .arabic_number => return true, else => {}, } } } return false;}
/// The Bidi rule, RFC 5893 §2.fn checkBidi(label: []const u21) Error!void { if (label.len == 0) return;
const direction: Bidi = switch (uucode.get(.bidi_class, label[0])) { .left_to_right => .ltr, .right_to_left, .right_to_left_arabic => .rtl, else => return error.InvalidBidi, // rule 1 };
var has_en = false; var has_an = false; for (label) |cp| { const bc = uucode.get(.bidi_class, cp); switch (direction) { .rtl => switch (bc) { // rule 2 .right_to_left, .right_to_left_arabic, .arabic_number, .european_number, .european_number_separator, .common_number_separator, .european_number_terminator, .other_neutrals, .boundary_neutral, .nonspacing_mark, => {}, else => return error.InvalidBidi, }, .ltr => switch (bc) { // rule 5 .left_to_right, .european_number, .european_number_separator, .common_number_separator, .european_number_terminator, .other_neutrals, .boundary_neutral, .nonspacing_mark, => {}, else => return error.InvalidBidi, }, } if (bc == .european_number) has_en = true; if (bc == .arabic_number) has_an = true; }
// Rules 3 and 6: the last non-NSM character. var last = label.len; while (last > 0) : (last -= 1) { if (uucode.get(.bidi_class, label[last - 1]) != .nonspacing_mark) break; } if (last == 0) return error.InvalidBidi; const bc = uucode.get(.bidi_class, label[last - 1]); switch (direction) { .rtl => switch (bc) { .right_to_left, .right_to_left_arabic, .european_number, .arabic_number => {}, else => return error.InvalidBidi, }, .ltr => switch (bc) { .left_to_right, .european_number => {}, else => return error.InvalidBidi, }, }
// Rule 4: an RTL label may not mix European and Arabic numbers. if (direction == .rtl and has_en and has_an) return error.InvalidBidi;}
/// UTS #46 §4.1 label validity, minus the checks the caller has already done.fn validateLabel(alloc: std.mem.Allocator, label: []const u21, opts: Options) Error!void { if (label.len == 0) return;
// Must already be in NFC. const n = try normalization.nfc(alloc, label); defer alloc.free(n); if (!std.mem.eql(u21, label, n)) return error.InvalidLabel;
if (opts.check_hyphens) { if (label[0] == '-' or label[label.len - 1] == '-') return error.InvalidLabel; if (label.len >= 4 and label[2] == '-' and label[3] == '-') return error.InvalidLabel; } // A dot can only appear here if it survived label splitting, which it // cannot; kept because UTS #46 lists it and costs nothing. for (label) |cp| if (cp == '.') return error.InvalidLabel;
if (isMark(label[0])) return error.InvalidLabel;
for (label) |cp| { if (opts.use_std3_ascii_rules and cp < 0x80 and !isStd3Ascii(cp)) { return error.DisallowedCodePoint; } switch (lookup(cp).status) { .valid => {}, // In non-transitional processing a deviation character is valid; // in transitional processing mapping already removed it. .deviation => if (opts.transitional) return error.DisallowedCodePoint, else => return error.DisallowedCodePoint, } }
if (opts.check_joiners) try checkJoiners(label);}
fn utf8ToCodePoints(alloc: std.mem.Allocator, s: []const u8) Error![]u21 { var out: std.ArrayList(u21) = .empty; errdefer out.deinit(alloc); var view = std.unicode.Utf8View.init(s) catch return error.InvalidUtf8; var it = view.iterator(); while (it.nextCodepoint()) |cp| try out.append(alloc, cp); return out.toOwnedSlice(alloc);}
fn codePointsToUtf8(alloc: std.mem.Allocator, cps: []const u21) Error![]u8 { var out: std.ArrayList(u8) = .empty; errdefer out.deinit(alloc); var buf: [4]u8 = undefined; for (cps) |cp| { const n = std.unicode.utf8Encode(cp, &buf) catch return error.InvalidUtf8; try out.appendSlice(alloc, buf[0..n]); } return out.toOwnedSlice(alloc);}
/// Split on U+002E and decode any `xn--` labels, leaving Unicode labels.fn processToLabels( alloc: std.mem.Allocator, arena: std.mem.Allocator, name: []const u8, opts: Options,) Error![][]const u21 { const cps = try utf8ToCodePoints(alloc, name); defer alloc.free(cps);
const mapped = try mapCodePoints(alloc, cps, opts); defer alloc.free(mapped);
const normalized = try normalization.nfc(alloc, mapped); defer alloc.free(normalized);
var labels: std.ArrayList([]const u21) = .empty; errdefer labels.deinit(arena);
var start: usize = 0; while (true) { const end = std.mem.indexOfScalarPos(u21, normalized, start, '.') orelse normalized.len; const raw = normalized[start..end];
var label: []const u21 = try arena.dupe(u21, raw); var was_ace = false; if (raw.len > acePrefix.len) { var is_ace = true; for (acePrefix, 0..) |c, i| { // The prefix compares case-insensitively, though mapping has // already lowercased anything that could differ. Guard the // narrowing: a label may well start with a non-ASCII code // point, which is simply not a prefix match. if (raw[i] > 0x7F or std.ascii.toLower(@intCast(raw[i])) != c) { is_ace = false; break; } } if (is_ace) { var ascii: std.ArrayList(u8) = .empty; defer ascii.deinit(alloc); for (raw[acePrefix.len..]) |cp| { if (cp >= 0x80) return error.InvalidPunycode; try ascii.append(alloc, @intCast(cp)); } const decoded = punycode.decode(alloc, ascii.items) catch return error.InvalidPunycode; defer alloc.free(decoded); if (decoded.len == 0) return error.InvalidPunycode; // An ACE label must decode to something that actually needed // encoding; `xn--ASCII-` decodes to plain `ascii`, which // would never re-encode to that label. var has_non_ascii = false; for (decoded) |cp| { if (cp >= 0x80) { has_non_ascii = true; break; } } if (!has_non_ascii) return error.InvalidPunycode; label = try arena.dupe(u21, decoded); was_ace = true; } }
// A decoded label is validated non-transitionally, whatever the // caller asked for: it was already encoded, so deviation characters // in it were deliberate. var label_opts = opts; if (was_ace) label_opts.transitional = false; try validateLabel(alloc, label, label_opts);
try labels.append(arena, label); if (end == normalized.len) break; start = end + 1; }
// An empty label is only meaningful as the trailing root label; `a..c` // and the empty name itself are errors (UTS #46 §4, step 3). for (labels.items, 0..) |label, i| { const is_last = i + 1 == labels.items.len; if (label.len == 0 and (!is_last or labels.items.len == 1)) return error.EmptyLabel; }
if (opts.check_bidi and isBidiDomain(labels.items)) { for (labels.items) |label| try checkBidi(label); }
return labels.toOwnedSlice(arena);}
/// Convert a domain name to its ASCII (`xn--`) form. Caller owns the result.pub fn toAscii(alloc: std.mem.Allocator, name: []const u8, opts: Options) Error![]u8 { var arena_state = std.heap.ArenaAllocator.init(alloc); defer arena_state.deinit(); const arena = arena_state.allocator();
const labels = try processToLabels(alloc, arena, name, opts);
var out: std.ArrayList(u8) = .empty; errdefer out.deinit(alloc);
for (labels, 0..) |label, i| { if (i > 0) try out.append(alloc, '.'); const before = out.items.len;
var all_ascii = true; for (label) |cp| { if (cp >= 0x80) { all_ascii = false; break; } } if (all_ascii) { for (label) |cp| try out.append(alloc, @intCast(cp)); } else { const encoded = punycode.encode(alloc, label) catch return error.InvalidPunycode; defer alloc.free(encoded); try out.appendSlice(alloc, acePrefix); try out.appendSlice(alloc, encoded); }
if (opts.verify_dns_length) { // Every label, including a trailing empty root label, must be // 1..63. That makes `a.b.c.` a VerifyDnsLength error, which is // what UTS #46 specifies and what IdnaTestV2 asserts. const len = out.items.len - before; if (len < 1 or len > 63) return error.InvalidLength; } }
if (opts.verify_dns_length) { // A single trailing dot is allowed and excluded from the total. var total = out.items.len; if (total > 0 and out.items[total - 1] == '.') total -= 1; if (total < 1 or total > 253) return error.InvalidLength; }
return out.toOwnedSlice(alloc);}
/// Convert a domain name to its Unicode form for display. Caller owns the/// result. Per UTS #46 §4.3 this is always non-transitional.pub fn toUnicode(alloc: std.mem.Allocator, name: []const u8, opts: Options) Error![]u8 { var arena_state = std.heap.ArenaAllocator.init(alloc); defer arena_state.deinit(); const arena = arena_state.allocator();
var o = opts; o.transitional = false; o.verify_dns_length = false; const labels = try processToLabels(alloc, arena, name, o);
var joined: std.ArrayList(u21) = .empty; defer joined.deinit(alloc); for (labels, 0..) |label, i| { if (i > 0) try joined.append(alloc, '.'); try joined.appendSlice(alloc, label); } return codePointsToUtf8(alloc, joined.items);}