// SPDX-FileCopyrightText: © 2026 Jeffrey C. Ollie // 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("uri").punycode; 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); }