From cf0d0ded02da423d3e1cdc080ad6a894bd1d83dd Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 10:14:15 +0300 Subject: [PATCH 01/21] Widen ChargeType to 32 bits The CIP-11 charge and the CIP-1852 role accept any level index, but ChargeType was uint8, so the parsed value was truncated to a byte: m/1852'/1815'/0'/256/0 parsed as role 0, re-serialised as m/1852'/1815'/0'/0/0 and returned role 0 in Levels(). Two URNs named the same key. ChargeType is now uint32 and keeps the full value in Charge(), Levels() and String(). Start CHANGELOG.md with the 1.2.0 entry. --- CHANGELOG.md | 18 ++++++++++++++++++ derivation_path.go | 6 +++++- mhda_test.go | 38 ++++++++++++++++++++++++++++++++++++++ 3 files changed, 61 insertions(+), 1 deletion(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..e2f3753 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,18 @@ +# Changelog + +All notable changes to this project will be documented here. The format +follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the +project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +Releases before 1.2.0 are described by their tags and commit messages. + +## [1.2.0] — 2026-10-05 + +### Fixed + +- **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the + CIP-1852 role accept any level index, but the parsed value was truncated + to a byte: `m/1852'/1815'/0'/256/0` parsed as role 0, so it named the + role-0 key, re-serialised as `m/1852'/1815'/0'/0/0`, and `Levels()` + returned the truncated value. The full value is now kept in `Charge()`, + `Levels()` and `String()`. Code that converts `Charge()` to `uint8` must + widen its own variable. diff --git a/derivation_path.go b/derivation_path.go index 95f8513..eabce00 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -59,7 +59,11 @@ func DerivationTypeFromString(src string) (DerivationType, error) { type AccountIndex uint32 -type ChargeType uint8 +// ChargeType is the level after the account: the change level of BIP-32 and +// the BIP-44 family (0 external, 1 internal), the CIP-11 charge and the +// CIP-1852 role. It is as wide as a level index: the CIP-11 charge and the +// CIP-1852 role take any index. +type ChargeType uint32 type AddressIndex struct { Index uint32 diff --git a/mhda_test.go b/mhda_test.go index 2bac992..737e959 100644 --- a/mhda_test.go +++ b/mhda_test.go @@ -895,6 +895,44 @@ func TestCIP1852Levels(t *testing.T) { } } +// TestWideChargeLevel: the CIP-11 charge and the CIP-1852 role take any +// level index. A value above 255 must keep its full width - truncated to a +// byte, role 256 would name the role-0 key. +func TestWideChargeLevel(t *testing.T) { + cases := []struct { + urn string + want uint32 + }{ + {`urn:mhda:nt:cardano:ci:mainnet:dt:cip1852:dp:m/1852'/1815'/0'/256/0`, 256}, + {`urn:mhda:nt:cardano:ci:mainnet:dt:cip1852:dp:m/1852'/1815'/0'/2147483647/0`, 2147483647}, + {`urn:mhda:nt:cosmos:ci:cosmoshub:dt:cip11:dp:m/44'/118'/0'/257/0`, 257}, + {`urn:mhda:nt:cosmos:ci:cosmoshub:dt:cip11:dp:m/44'/118'/0'/65536/0`, 65536}, + } + for _, c := range cases { + addr, err := ParseURNStrict(c.urn) + if err != nil { + t.Errorf("ParseURNStrict(%q): %v", c.urn, err) + continue + } + if addr.String() != c.urn { + t.Errorf("round-trip:\n got: %s\n want: %s", addr.String(), c.urn) + } + dp := addr.DerivationPath() + if uint32(dp.Charge()) != c.want { + t.Errorf("%q: Charge() = %d, want %d", c.urn, dp.Charge(), c.want) + } + if got := dp.Levels()[3]; got != (AddressIndex{Index: c.want}) { + t.Errorf("%q: level[3] = %+v, want {%d false}", c.urn, got, c.want) + } + } + + role := uint32(300) + dp := NewDerivationPath(CIP1852, ADA, 0, ChargeType(role), AddressIndex{Index: 1}) + if got, want := dp.String(), `m/1852'/1815'/0'/300/1`; got != want { + t.Errorf("NewDerivationPath role 300: String() = %q, want %q", got, want) + } +} + // TestSLIP10 covers the generic SLIP-10 derivation type with paths from // real-world chains: Solana (4 levels), Stellar (SEP-0005, 3 levels), Sui // ed25519 (5 levels all-hardened), Aptos (5 levels all-hardened). From 557f05c857f9cb92d8cd7b7fe2ba4733b3a43320 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 10:19:01 +0300 Subject: [PATCH 02/21] Refuse derivation-path levels with an index of 2^31 or more A BIP-32 child number keeps the hardened flag in its top bit: n' is child number 2^31+n, so a level index must stay below 2^31. ParsePath accepted any 32-bit value, and a consumer computing hardened ? 0x80000000|index : index got an alias: m/44'/60'/2147483648'/0/0 derived the key of m/44'/60'/0'/0/0, and an unhardened .../0/2147483648 asked for a hardened child number through the public-key formula. Every level of every derivation type is now parsed with a 31-bit bound and refused with ErrInvalidDerivationPath otherwise, hardened or not. The ct component is not a path level and keeps its 32-bit range. Leading zeros are unchanged and now documented: a variable level accepts them and String() drops them; a fixed level (purpose, fixed coin, 0|1 charge) is a regex literal and refuses them. testdata/dp_conformance.txt is a table shared verbatim with the C++ port: every row is parsed standalone and inside a URN, so a path one implementation refuses, the other refuses too. The fuzz seed that pinned 4294967295 now sits at the new bound, and FuzzDerivationPath checks that no accepted level exceeds 2^31-1. SPEC.md and CHANGELOG.md describe the rule and the URNs that no longer parse. --- CHANGELOG.md | 26 ++ SPEC.md | 18 +- derivation_path.go | 7 +- fuzz_test.go | 15 +- index_range_test.go | 134 +++++++++++ testdata/dp_conformance.txt | 466 ++++++++++++++++++++++++++++++++++++ 6 files changed, 659 insertions(+), 7 deletions(-) create mode 100644 index_range_test.go create mode 100644 testdata/dp_conformance.txt diff --git a/CHANGELOG.md b/CHANGELOG.md index e2f3753..fea2fba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,32 @@ Releases before 1.2.0 are described by their tags and commit messages. ## [1.2.0] — 2026-10-05 +URNs accepted by 1.1 are refused now: a derivation path with a level index +of 2^31 or more no longer parses. + +### Changed + +- **A derivation-path level index of 2^31 or more is refused** with + `ErrInvalidDerivationPath`, at every level of every derivation type + (`bip32`, `bip44`, `bip49`, `bip54`, `bip74`, `bip84`, `bip86`, `cip11`, + `cip1852`, `zip32`, `slip10`), hardened or not. 1.1 accepted any value up + to 2^32-1. A BIP-32 child number keeps the hardened flag in its top bit + (`n'` is child number 2^31+n), so such an index aliased another key: a + consumer computing `hardened ? 0x80000000 | index : index` derives the key + of `m/44'/60'/0'/0/0` for `m/44'/60'/2147483648'/0/0`, and an unhardened + `m/44'/60'/0'/0/2147483648` asks for a hardened child number through the + public-key formula. No longer parse: any `dp` with a level of + `2147483648` to `4294967295`, with or without a hardened marker, e.g. + `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/2147483648'/0/0` and + `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/4294967295`. The largest + index is `2147483647`. The `ct` component is not a path level and keeps + its 32-bit range. +- Leading zeros in a path level are unchanged and now documented: accepted + in a variable level and dropped in canonical output (`060'` is `60'`), + refused in a fixed level (the purpose, the fixed coin of `cip11`, + `cip1852` and `zip32`, the `0`/`1` charge of `bip32` and the BIP-44 + family). + ### Fixed - **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the diff --git a/SPEC.md b/SPEC.md index 1b9aafc..5185dc6 100644 --- a/SPEC.md +++ b/SPEC.md @@ -231,7 +231,7 @@ protocol messages. | bip74 | `m/74'/coin'/account'/charge/index[']` | 5 | sui-keys/src/key_derive.rs (Sui secp256r1) | | bip84 | `m/84'/coin'/account'/charge/index[']` | 5 | https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki | | bip86 | `m/86'/coin'/account'/charge/index[']` | 5 | https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki | -| slip10 | `m(/uint32['])+` (variable length) | 1+ | https://github.com/satoshilabs/slips/blob/master/slip-0010.md | +| slip10 | `m(/index['])+` (variable length) | 1+ | https://github.com/satoshilabs/slips/blob/master/slip-0010.md | | cip11 | `m/44'/118'/account'/charge_extra/index[']` | 5 | https://github.com/confio/cosmos-hd-key-derivation-spec | | cip1852 | `m/1852'/1815'/account'/role/index[']` | 5 | https://github.com/cardano-foundation/CIPs/blob/master/CIP-1852/ | | zip32 | `m/32'/133'/account'[/index[']]` | 3 or 4 | https://zips.z.cash/zip-0032 | @@ -240,6 +240,17 @@ Hardening markers in input: `'`, `H`, or `h` are all accepted and normalised to `'` in canonical output. The trailing `[']` on `index` denotes that the leaf level itself may be hardened. +Each level's index is 0..2^31-1 (at most `2147483647`); the hardened marker +is a separate flag, so `n'` is BIP-32 child number 2^31+n. An index of 2^31 +or more is refused at every level of every derivation type, hardened or not: +it collides with the hardened bit and would name the key of another path. + +Leading zeros are accepted in a variable level and dropped in canonical +output (`m/44'/060'/0'/0/0` is `m/44'/60'/0'/0/0`); the range applies to the +value. A fixed level (the purpose, the fixed coin of `cip11`, `cip1852` and +`zip32`, the `0`/`1` charge of `bip32` and the BIP-44 family) must be spelled +exactly as in the template. + ### 3.1 Variable-length paths `slip10` accepts any number of levels and is the right type for chains whose @@ -302,7 +313,8 @@ Performs structural validation only: whitespace around the whole URN is trimmed). - Chain ID is non-empty. - Derivation type, if present, is one of the registered constants. -- Derivation path, if present, matches the regex of its derivation type. +- Derivation path, if present, matches the regex of its derivation type, + and every level's index is below 2^31 (§3). - Algorithm, if present, is one of the registered constants. - Format, if present, is one of the registered constants. @@ -348,7 +360,7 @@ text. | `ErrInvalidChainKey` | `ChainFromKey` input is not the canonical identity form | | `ErrInvalidValue` | Free-form setter value with `:`/`?`/`#`/whitespace | | `ErrInvalidDerivationType` | `dt` value not registered | -| `ErrInvalidDerivationPath` | `dp` does not match the regex of `dt` | +| `ErrInvalidDerivationPath` | `dp` does not match `dt`, or a level index is >= 2^31 | | `ErrInvalidAlgorithm` | `aa` value not registered | | `ErrInvalidFormat` | `af` value not registered | | `ErrIncompatible` | Strict validation: triple not allowed for the network | diff --git a/derivation_path.go b/derivation_path.go index eabce00..3ba52e9 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -65,6 +65,8 @@ type AccountIndex uint32 // CIP-1852 role take any index. type ChargeType uint32 +// AddressIndex is one level of a derivation path. Index is below 2^31 in +// every parsed path; IsHardened is the separate hardened flag. type AddressIndex struct { Index uint32 IsHardened bool @@ -291,8 +293,11 @@ func (dp *DerivationPath) ParsePath(path string) error { return fmt.Errorf("%w: %q", ErrInvalidDerivationPath, path) } + // A level's index has 31 bits: a BIP-32 child number keeps the hardened + // flag in its top bit (n' is 2^31+n), so an index of 2^31 or more would + // name another level's key. Refused at every level, hardened or not. parseUint := func(s, label string) (uint32, error) { - v, err := strconv.ParseUint(s, 10, 32) + v, err := strconv.ParseUint(s, 10, 31) if err != nil { return 0, fmt.Errorf("%w: cannot parse %s %q: %s", ErrInvalidDerivationPath, label, s, err) } diff --git a/fuzz_test.go b/fuzz_test.go index ff97d2f..0d495d1 100644 --- a/fuzz_test.go +++ b/fuzz_test.go @@ -69,10 +69,10 @@ func FuzzParseURN(f *testing.F) { func FuzzDerivationPath(f *testing.F) { // Seeds: one valid path per known derivation type plus a few degenerate // inputs that have historically been weak spots (variable-length ZIP-32, - // SLIP-10 with mixed hardening, hardened leaf, max-uint32 indices, etc). + // SLIP-10 with mixed hardening, hardened leaf, the largest index, etc). seeds := []struct{ dt, path string }{ {"bip32", "m/0'/0/0"}, - {"bip32", "m/2147483647'/1/4294967295'"}, + {"bip32", "m/2147483647'/1/2147483647'"}, // largest index, 2^31-1 {"bip44", "m/44'/60'/0'/0/0"}, {"bip44", "m/44'/0'/0'/0/0'"}, // hardened leaf {"bip49", "m/49'/0'/0'/0/0"}, @@ -96,7 +96,9 @@ func FuzzDerivationPath(f *testing.F) { {"bip44", "m/44'/0'/0'/0"}, // missing leaf {"slip10", "m"}, {"slip10", "m/"}, - {"slip10", "m/99999999999999999999"}, // overflow + {"slip10", "m/99999999999999999999"}, // overflow + {"bip32", "m/2147483648'/1/0"}, // index 2^31 + {"bip44", "m/44'/60'/0'/0/4294967295"}, // index 2^32-1 {"unknown", "m/0/0/0"}, } for _, s := range seeds { @@ -124,6 +126,13 @@ func FuzzDerivationPath(f *testing.F) { serialized, dp2.String(), dt, path) } + // No accepted level may carry an index of 2^31 or more. + for i, lvl := range dp.Levels() { + if lvl.Index > 1<<31-1 { + t.Fatalf("level[%d] = %d is above 2^31-1 (input: dt=%q path=%q)", i, lvl.Index, dt, path) + } + } + // Levels() must always be safe to call (may be empty for ROOT). _ = dp.Levels() }) diff --git a/index_range_test.go b/index_range_test.go new file mode 100644 index 0000000..351b880 --- /dev/null +++ b/index_range_test.go @@ -0,0 +1,134 @@ +package go_mhda + +import ( + "bufio" + "errors" + "os" + "strings" + "testing" +) + +// testMaxLevelIndex is the largest index of a derivation-path level: a BIP-32 +// child number keeps the hardened flag in its top bit, so the index has 31 +// bits. +const testMaxLevelIndex = 1<<31 - 1 + +// TestLevelIndexAliasRefused: an index of 2^31 or more collides with the +// hardened bit of a BIP-32 child number. m/44'/60'/2147483648'/0/0 would +// derive the key of m/44'/60'/0'/0/0, and an unhardened 2147483648 would ask +// for a hardened child through the public-key formula. +func TestLevelIndexAliasRefused(t *testing.T) { + for _, urn := range []string{ + `urn:mhda:nt:evm:ci:1:ct:60:dt:bip44:dp:m/44'/60'/2147483648'/0/0`, + `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/2147483648'/0/0`, + `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/2147483648`, + `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/4294967295`, + `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/2147483708'/0'/0/0`, + `urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/2147483648'/0'`, + } { + if _, err := ParseURN(urn); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("ParseURN(%q): got %v, want ErrInvalidDerivationPath", urn, err) + } + if _, err := ParseURNStrict(urn); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("ParseURNStrict(%q): got %v, want ErrInvalidDerivationPath", urn, err) + } + } + + const largest = `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/2147483647'/0/2147483647'` + addr, err := ParseURNStrict(largest) + if err != nil { + t.Fatalf("ParseURNStrict(%q): %v", largest, err) + } + if addr.String() != largest { + t.Errorf("round-trip:\n got: %s\n want: %s", addr.String(), largest) + } + if got := addr.DerivationPath().Account(); got != testMaxLevelIndex { + t.Errorf("Account() = %d, want %d", got, testMaxLevelIndex) + } +} + +// TestCoinTypeIsNotALevel: the ct component is SLIP-44 metadata, not a path +// level, and keeps the full 32-bit range. +func TestCoinTypeIsNotALevel(t *testing.T) { + for urn, want := range map[string]CoinType{ + `urn:mhda:nt:evm:ci:1:ct:2147483648:dt:bip44:dp:m/44'/60'/0'/0/0`: 2147483648, + `urn:mhda:nt:evm:ci:1:ct:4294967295:dt:bip44:dp:m/44'/60'/0'/0/0`: 4294967295, + } { + addr, err := ParseURN(urn) + if err != nil { + t.Errorf("ParseURN(%q): %v", urn, err) + continue + } + if got := addr.Chain().CoinType(); got != want { + t.Errorf("ParseURN(%q): ct = %d, want %d", urn, got, want) + } + if addr.String() != urn { + t.Errorf("round-trip:\n got: %s\n want: %s", addr.String(), urn) + } + } +} + +// TestDerivationPathConformance runs the derivation-path table shared with +// the C++ port (testdata/dp_conformance.txt, a verbatim copy of the port's +// tests/data/dp_conformance.txt). Every row is parsed standalone and inside a +// URN; both must agree with the row. +func TestDerivationPathConformance(t *testing.T) { + f, err := os.Open("testdata/dp_conformance.txt") + if err != nil { + t.Fatal(err) + } + defer f.Close() + + rows := 0 + sc := bufio.NewScanner(f) + for line := 1; sc.Scan(); line++ { + text := strings.TrimSpace(sc.Text()) + if text == "" || strings.HasPrefix(text, "#") { + continue + } + fields := strings.Fields(text) + accept := fields[0] == "accept" + if !(accept && len(fields) == 4) && !(fields[0] == "refuse" && len(fields) == 3) { + t.Fatalf("dp_conformance.txt:%d: malformed row %q", line, text) + } + rows++ + dt, path := DerivationType(fields[1]), fields[2] + + dp, err := ParseDerivationPath(dt, path) + if accept { + if err != nil { + t.Errorf("line %d: ParseDerivationPath(%s, %q): %v", line, dt, path, err) + } else { + if got := dp.String(); got != fields[3] { + t.Errorf("line %d: ParseDerivationPath(%s, %q).String() = %q, want %q", line, dt, path, got, fields[3]) + } + for i, lvl := range dp.Levels() { + if lvl.Index > testMaxLevelIndex { + t.Errorf("line %d: level[%d] = %d is above 2^31-1", line, i, lvl.Index) + } + } + } + } else if !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("line %d: ParseDerivationPath(%s, %q): got %v, want ErrInvalidDerivationPath", line, dt, path, err) + } + + urn := `urn:mhda:nt:evm:ci:1:dt:` + string(dt) + `:dp:` + path + addr, err := ParseURN(urn) + if accept { + want := `urn:mhda:nt:evm:ci:1:dt:` + string(dt) + `:dp:` + fields[3] + if err != nil { + t.Errorf("line %d: ParseURN(%q): %v", line, urn, err) + } else if addr.String() != want { + t.Errorf("line %d: ParseURN(%q).String() = %q, want %q", line, urn, addr.String(), want) + } + } else if !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("line %d: ParseURN(%q): got %v, want ErrInvalidDerivationPath", line, urn, err) + } + } + if err := sc.Err(); err != nil { + t.Fatal(err) + } + if rows < 300 { + t.Fatalf("dp_conformance.txt: %d rows, the table is truncated", rows) + } +} diff --git a/testdata/dp_conformance.txt b/testdata/dp_conformance.txt new file mode 100644 index 0000000..2056e69 --- /dev/null +++ b/testdata/dp_conformance.txt @@ -0,0 +1,466 @@ +# Derivation-path conformance table, shared verbatim by go-mhda +# (testdata/dp_conformance.txt) and the C++ port (tests/data/dp_conformance.txt). +# Both test suites run every row; a path one implementation refuses, the other +# refuses too. Edit both copies together. +# +# Row forms: +# accept
+# refuse
+# A refused row fails with ErrInvalidDerivationPath / error_code::invalid_derivation_path. +# +# Each level's index is 0..2^31-1; the hardened marker is a separate flag. +# 2147483647 is the largest index, 2147483648 (2^31) and 4294967295 (2^32-1) +# are refused at every level of every type, hardened or not. Values at a +# level whose shape they do not fit (an unhardened account, a hardened +# charge, any value in a fixed level) are refused for shape. + +# bip32 m/0'/0/0 +# bip32 account (hardened only) +refuse bip32 m/2147483647/0/0 +accept bip32 m/2147483647'/0/0 m/2147483647'/0/0 +refuse bip32 m/2147483648/0/0 +refuse bip32 m/2147483648'/0/0 +refuse bip32 m/4294967295/0/0 +refuse bip32 m/4294967295'/0/0 +# bip32 charge (fixed 0|1) +refuse bip32 m/0'/2147483647/0 +refuse bip32 m/0'/2147483647'/0 +refuse bip32 m/0'/2147483648/0 +refuse bip32 m/0'/2147483648'/0 +refuse bip32 m/0'/4294967295/0 +refuse bip32 m/0'/4294967295'/0 +# bip32 index (hardening optional) +accept bip32 m/0'/0/2147483647 m/0'/0/2147483647 +accept bip32 m/0'/0/2147483647' m/0'/0/2147483647' +refuse bip32 m/0'/0/2147483648 +refuse bip32 m/0'/0/2147483648' +refuse bip32 m/0'/0/4294967295 +refuse bip32 m/0'/0/4294967295' + +# bip44 m/44'/60'/0'/0/0 +# bip44 purpose (fixed) +refuse bip44 m/2147483647/60'/0'/0/0 +refuse bip44 m/2147483647'/60'/0'/0/0 +refuse bip44 m/2147483648/60'/0'/0/0 +refuse bip44 m/2147483648'/60'/0'/0/0 +refuse bip44 m/4294967295/60'/0'/0/0 +refuse bip44 m/4294967295'/60'/0'/0/0 +# bip44 coin (hardened only) +refuse bip44 m/44'/2147483647/0'/0/0 +accept bip44 m/44'/2147483647'/0'/0/0 m/44'/2147483647'/0'/0/0 +refuse bip44 m/44'/2147483648/0'/0/0 +refuse bip44 m/44'/2147483648'/0'/0/0 +refuse bip44 m/44'/4294967295/0'/0/0 +refuse bip44 m/44'/4294967295'/0'/0/0 +# bip44 account (hardened only) +refuse bip44 m/44'/60'/2147483647/0/0 +accept bip44 m/44'/60'/2147483647'/0/0 m/44'/60'/2147483647'/0/0 +refuse bip44 m/44'/60'/2147483648/0/0 +refuse bip44 m/44'/60'/2147483648'/0/0 +refuse bip44 m/44'/60'/4294967295/0/0 +refuse bip44 m/44'/60'/4294967295'/0/0 +# bip44 charge (fixed 0|1) +refuse bip44 m/44'/60'/0'/2147483647/0 +refuse bip44 m/44'/60'/0'/2147483647'/0 +refuse bip44 m/44'/60'/0'/2147483648/0 +refuse bip44 m/44'/60'/0'/2147483648'/0 +refuse bip44 m/44'/60'/0'/4294967295/0 +refuse bip44 m/44'/60'/0'/4294967295'/0 +# bip44 index (hardening optional) +accept bip44 m/44'/60'/0'/0/2147483647 m/44'/60'/0'/0/2147483647 +accept bip44 m/44'/60'/0'/0/2147483647' m/44'/60'/0'/0/2147483647' +refuse bip44 m/44'/60'/0'/0/2147483648 +refuse bip44 m/44'/60'/0'/0/2147483648' +refuse bip44 m/44'/60'/0'/0/4294967295 +refuse bip44 m/44'/60'/0'/0/4294967295' + +# bip49 m/49'/0'/0'/0/0 +# bip49 purpose (fixed) +refuse bip49 m/2147483647/0'/0'/0/0 +refuse bip49 m/2147483647'/0'/0'/0/0 +refuse bip49 m/2147483648/0'/0'/0/0 +refuse bip49 m/2147483648'/0'/0'/0/0 +refuse bip49 m/4294967295/0'/0'/0/0 +refuse bip49 m/4294967295'/0'/0'/0/0 +# bip49 coin (hardened only) +refuse bip49 m/49'/2147483647/0'/0/0 +accept bip49 m/49'/2147483647'/0'/0/0 m/49'/2147483647'/0'/0/0 +refuse bip49 m/49'/2147483648/0'/0/0 +refuse bip49 m/49'/2147483648'/0'/0/0 +refuse bip49 m/49'/4294967295/0'/0/0 +refuse bip49 m/49'/4294967295'/0'/0/0 +# bip49 account (hardened only) +refuse bip49 m/49'/0'/2147483647/0/0 +accept bip49 m/49'/0'/2147483647'/0/0 m/49'/0'/2147483647'/0/0 +refuse bip49 m/49'/0'/2147483648/0/0 +refuse bip49 m/49'/0'/2147483648'/0/0 +refuse bip49 m/49'/0'/4294967295/0/0 +refuse bip49 m/49'/0'/4294967295'/0/0 +# bip49 charge (fixed 0|1) +refuse bip49 m/49'/0'/0'/2147483647/0 +refuse bip49 m/49'/0'/0'/2147483647'/0 +refuse bip49 m/49'/0'/0'/2147483648/0 +refuse bip49 m/49'/0'/0'/2147483648'/0 +refuse bip49 m/49'/0'/0'/4294967295/0 +refuse bip49 m/49'/0'/0'/4294967295'/0 +# bip49 index (hardening optional) +accept bip49 m/49'/0'/0'/0/2147483647 m/49'/0'/0'/0/2147483647 +accept bip49 m/49'/0'/0'/0/2147483647' m/49'/0'/0'/0/2147483647' +refuse bip49 m/49'/0'/0'/0/2147483648 +refuse bip49 m/49'/0'/0'/0/2147483648' +refuse bip49 m/49'/0'/0'/0/4294967295 +refuse bip49 m/49'/0'/0'/0/4294967295' + +# bip54 m/54'/784'/0'/0/0 +# bip54 purpose (fixed) +refuse bip54 m/2147483647/784'/0'/0/0 +refuse bip54 m/2147483647'/784'/0'/0/0 +refuse bip54 m/2147483648/784'/0'/0/0 +refuse bip54 m/2147483648'/784'/0'/0/0 +refuse bip54 m/4294967295/784'/0'/0/0 +refuse bip54 m/4294967295'/784'/0'/0/0 +# bip54 coin (hardened only) +refuse bip54 m/54'/2147483647/0'/0/0 +accept bip54 m/54'/2147483647'/0'/0/0 m/54'/2147483647'/0'/0/0 +refuse bip54 m/54'/2147483648/0'/0/0 +refuse bip54 m/54'/2147483648'/0'/0/0 +refuse bip54 m/54'/4294967295/0'/0/0 +refuse bip54 m/54'/4294967295'/0'/0/0 +# bip54 account (hardened only) +refuse bip54 m/54'/784'/2147483647/0/0 +accept bip54 m/54'/784'/2147483647'/0/0 m/54'/784'/2147483647'/0/0 +refuse bip54 m/54'/784'/2147483648/0/0 +refuse bip54 m/54'/784'/2147483648'/0/0 +refuse bip54 m/54'/784'/4294967295/0/0 +refuse bip54 m/54'/784'/4294967295'/0/0 +# bip54 charge (fixed 0|1) +refuse bip54 m/54'/784'/0'/2147483647/0 +refuse bip54 m/54'/784'/0'/2147483647'/0 +refuse bip54 m/54'/784'/0'/2147483648/0 +refuse bip54 m/54'/784'/0'/2147483648'/0 +refuse bip54 m/54'/784'/0'/4294967295/0 +refuse bip54 m/54'/784'/0'/4294967295'/0 +# bip54 index (hardening optional) +accept bip54 m/54'/784'/0'/0/2147483647 m/54'/784'/0'/0/2147483647 +accept bip54 m/54'/784'/0'/0/2147483647' m/54'/784'/0'/0/2147483647' +refuse bip54 m/54'/784'/0'/0/2147483648 +refuse bip54 m/54'/784'/0'/0/2147483648' +refuse bip54 m/54'/784'/0'/0/4294967295 +refuse bip54 m/54'/784'/0'/0/4294967295' + +# bip74 m/74'/784'/0'/0/0 +# bip74 purpose (fixed) +refuse bip74 m/2147483647/784'/0'/0/0 +refuse bip74 m/2147483647'/784'/0'/0/0 +refuse bip74 m/2147483648/784'/0'/0/0 +refuse bip74 m/2147483648'/784'/0'/0/0 +refuse bip74 m/4294967295/784'/0'/0/0 +refuse bip74 m/4294967295'/784'/0'/0/0 +# bip74 coin (hardened only) +refuse bip74 m/74'/2147483647/0'/0/0 +accept bip74 m/74'/2147483647'/0'/0/0 m/74'/2147483647'/0'/0/0 +refuse bip74 m/74'/2147483648/0'/0/0 +refuse bip74 m/74'/2147483648'/0'/0/0 +refuse bip74 m/74'/4294967295/0'/0/0 +refuse bip74 m/74'/4294967295'/0'/0/0 +# bip74 account (hardened only) +refuse bip74 m/74'/784'/2147483647/0/0 +accept bip74 m/74'/784'/2147483647'/0/0 m/74'/784'/2147483647'/0/0 +refuse bip74 m/74'/784'/2147483648/0/0 +refuse bip74 m/74'/784'/2147483648'/0/0 +refuse bip74 m/74'/784'/4294967295/0/0 +refuse bip74 m/74'/784'/4294967295'/0/0 +# bip74 charge (fixed 0|1) +refuse bip74 m/74'/784'/0'/2147483647/0 +refuse bip74 m/74'/784'/0'/2147483647'/0 +refuse bip74 m/74'/784'/0'/2147483648/0 +refuse bip74 m/74'/784'/0'/2147483648'/0 +refuse bip74 m/74'/784'/0'/4294967295/0 +refuse bip74 m/74'/784'/0'/4294967295'/0 +# bip74 index (hardening optional) +accept bip74 m/74'/784'/0'/0/2147483647 m/74'/784'/0'/0/2147483647 +accept bip74 m/74'/784'/0'/0/2147483647' m/74'/784'/0'/0/2147483647' +refuse bip74 m/74'/784'/0'/0/2147483648 +refuse bip74 m/74'/784'/0'/0/2147483648' +refuse bip74 m/74'/784'/0'/0/4294967295 +refuse bip74 m/74'/784'/0'/0/4294967295' + +# bip84 m/84'/0'/0'/0/0 +# bip84 purpose (fixed) +refuse bip84 m/2147483647/0'/0'/0/0 +refuse bip84 m/2147483647'/0'/0'/0/0 +refuse bip84 m/2147483648/0'/0'/0/0 +refuse bip84 m/2147483648'/0'/0'/0/0 +refuse bip84 m/4294967295/0'/0'/0/0 +refuse bip84 m/4294967295'/0'/0'/0/0 +# bip84 coin (hardened only) +refuse bip84 m/84'/2147483647/0'/0/0 +accept bip84 m/84'/2147483647'/0'/0/0 m/84'/2147483647'/0'/0/0 +refuse bip84 m/84'/2147483648/0'/0/0 +refuse bip84 m/84'/2147483648'/0'/0/0 +refuse bip84 m/84'/4294967295/0'/0/0 +refuse bip84 m/84'/4294967295'/0'/0/0 +# bip84 account (hardened only) +refuse bip84 m/84'/0'/2147483647/0/0 +accept bip84 m/84'/0'/2147483647'/0/0 m/84'/0'/2147483647'/0/0 +refuse bip84 m/84'/0'/2147483648/0/0 +refuse bip84 m/84'/0'/2147483648'/0/0 +refuse bip84 m/84'/0'/4294967295/0/0 +refuse bip84 m/84'/0'/4294967295'/0/0 +# bip84 charge (fixed 0|1) +refuse bip84 m/84'/0'/0'/2147483647/0 +refuse bip84 m/84'/0'/0'/2147483647'/0 +refuse bip84 m/84'/0'/0'/2147483648/0 +refuse bip84 m/84'/0'/0'/2147483648'/0 +refuse bip84 m/84'/0'/0'/4294967295/0 +refuse bip84 m/84'/0'/0'/4294967295'/0 +# bip84 index (hardening optional) +accept bip84 m/84'/0'/0'/0/2147483647 m/84'/0'/0'/0/2147483647 +accept bip84 m/84'/0'/0'/0/2147483647' m/84'/0'/0'/0/2147483647' +refuse bip84 m/84'/0'/0'/0/2147483648 +refuse bip84 m/84'/0'/0'/0/2147483648' +refuse bip84 m/84'/0'/0'/0/4294967295 +refuse bip84 m/84'/0'/0'/0/4294967295' + +# bip86 m/86'/0'/0'/0/0 +# bip86 purpose (fixed) +refuse bip86 m/2147483647/0'/0'/0/0 +refuse bip86 m/2147483647'/0'/0'/0/0 +refuse bip86 m/2147483648/0'/0'/0/0 +refuse bip86 m/2147483648'/0'/0'/0/0 +refuse bip86 m/4294967295/0'/0'/0/0 +refuse bip86 m/4294967295'/0'/0'/0/0 +# bip86 coin (hardened only) +refuse bip86 m/86'/2147483647/0'/0/0 +accept bip86 m/86'/2147483647'/0'/0/0 m/86'/2147483647'/0'/0/0 +refuse bip86 m/86'/2147483648/0'/0/0 +refuse bip86 m/86'/2147483648'/0'/0/0 +refuse bip86 m/86'/4294967295/0'/0/0 +refuse bip86 m/86'/4294967295'/0'/0/0 +# bip86 account (hardened only) +refuse bip86 m/86'/0'/2147483647/0/0 +accept bip86 m/86'/0'/2147483647'/0/0 m/86'/0'/2147483647'/0/0 +refuse bip86 m/86'/0'/2147483648/0/0 +refuse bip86 m/86'/0'/2147483648'/0/0 +refuse bip86 m/86'/0'/4294967295/0/0 +refuse bip86 m/86'/0'/4294967295'/0/0 +# bip86 charge (fixed 0|1) +refuse bip86 m/86'/0'/0'/2147483647/0 +refuse bip86 m/86'/0'/0'/2147483647'/0 +refuse bip86 m/86'/0'/0'/2147483648/0 +refuse bip86 m/86'/0'/0'/2147483648'/0 +refuse bip86 m/86'/0'/0'/4294967295/0 +refuse bip86 m/86'/0'/0'/4294967295'/0 +# bip86 index (hardening optional) +accept bip86 m/86'/0'/0'/0/2147483647 m/86'/0'/0'/0/2147483647 +accept bip86 m/86'/0'/0'/0/2147483647' m/86'/0'/0'/0/2147483647' +refuse bip86 m/86'/0'/0'/0/2147483648 +refuse bip86 m/86'/0'/0'/0/2147483648' +refuse bip86 m/86'/0'/0'/0/4294967295 +refuse bip86 m/86'/0'/0'/0/4294967295' + +# cip11 m/44'/118'/0'/0/0 +# cip11 purpose (fixed) +refuse cip11 m/2147483647/118'/0'/0/0 +refuse cip11 m/2147483647'/118'/0'/0/0 +refuse cip11 m/2147483648/118'/0'/0/0 +refuse cip11 m/2147483648'/118'/0'/0/0 +refuse cip11 m/4294967295/118'/0'/0/0 +refuse cip11 m/4294967295'/118'/0'/0/0 +# cip11 coin (fixed) +refuse cip11 m/44'/2147483647/0'/0/0 +refuse cip11 m/44'/2147483647'/0'/0/0 +refuse cip11 m/44'/2147483648/0'/0/0 +refuse cip11 m/44'/2147483648'/0'/0/0 +refuse cip11 m/44'/4294967295/0'/0/0 +refuse cip11 m/44'/4294967295'/0'/0/0 +# cip11 account (hardened only) +refuse cip11 m/44'/118'/2147483647/0/0 +accept cip11 m/44'/118'/2147483647'/0/0 m/44'/118'/2147483647'/0/0 +refuse cip11 m/44'/118'/2147483648/0/0 +refuse cip11 m/44'/118'/2147483648'/0/0 +refuse cip11 m/44'/118'/4294967295/0/0 +refuse cip11 m/44'/118'/4294967295'/0/0 +# cip11 charge (soft only) +accept cip11 m/44'/118'/0'/2147483647/0 m/44'/118'/0'/2147483647/0 +refuse cip11 m/44'/118'/0'/2147483647'/0 +refuse cip11 m/44'/118'/0'/2147483648/0 +refuse cip11 m/44'/118'/0'/2147483648'/0 +refuse cip11 m/44'/118'/0'/4294967295/0 +refuse cip11 m/44'/118'/0'/4294967295'/0 +# cip11 index (hardening optional) +accept cip11 m/44'/118'/0'/0/2147483647 m/44'/118'/0'/0/2147483647 +accept cip11 m/44'/118'/0'/0/2147483647' m/44'/118'/0'/0/2147483647' +refuse cip11 m/44'/118'/0'/0/2147483648 +refuse cip11 m/44'/118'/0'/0/2147483648' +refuse cip11 m/44'/118'/0'/0/4294967295 +refuse cip11 m/44'/118'/0'/0/4294967295' + +# cip1852 m/1852'/1815'/0'/0/0 +# cip1852 purpose (fixed) +refuse cip1852 m/2147483647/1815'/0'/0/0 +refuse cip1852 m/2147483647'/1815'/0'/0/0 +refuse cip1852 m/2147483648/1815'/0'/0/0 +refuse cip1852 m/2147483648'/1815'/0'/0/0 +refuse cip1852 m/4294967295/1815'/0'/0/0 +refuse cip1852 m/4294967295'/1815'/0'/0/0 +# cip1852 coin (fixed) +refuse cip1852 m/1852'/2147483647/0'/0/0 +refuse cip1852 m/1852'/2147483647'/0'/0/0 +refuse cip1852 m/1852'/2147483648/0'/0/0 +refuse cip1852 m/1852'/2147483648'/0'/0/0 +refuse cip1852 m/1852'/4294967295/0'/0/0 +refuse cip1852 m/1852'/4294967295'/0'/0/0 +# cip1852 account (hardened only) +refuse cip1852 m/1852'/1815'/2147483647/0/0 +accept cip1852 m/1852'/1815'/2147483647'/0/0 m/1852'/1815'/2147483647'/0/0 +refuse cip1852 m/1852'/1815'/2147483648/0/0 +refuse cip1852 m/1852'/1815'/2147483648'/0/0 +refuse cip1852 m/1852'/1815'/4294967295/0/0 +refuse cip1852 m/1852'/1815'/4294967295'/0/0 +# cip1852 role (soft only) +accept cip1852 m/1852'/1815'/0'/2147483647/0 m/1852'/1815'/0'/2147483647/0 +refuse cip1852 m/1852'/1815'/0'/2147483647'/0 +refuse cip1852 m/1852'/1815'/0'/2147483648/0 +refuse cip1852 m/1852'/1815'/0'/2147483648'/0 +refuse cip1852 m/1852'/1815'/0'/4294967295/0 +refuse cip1852 m/1852'/1815'/0'/4294967295'/0 +# cip1852 index (hardening optional) +accept cip1852 m/1852'/1815'/0'/0/2147483647 m/1852'/1815'/0'/0/2147483647 +accept cip1852 m/1852'/1815'/0'/0/2147483647' m/1852'/1815'/0'/0/2147483647' +refuse cip1852 m/1852'/1815'/0'/0/2147483648 +refuse cip1852 m/1852'/1815'/0'/0/2147483648' +refuse cip1852 m/1852'/1815'/0'/0/4294967295 +refuse cip1852 m/1852'/1815'/0'/0/4294967295' + +# zip32 m/32'/133'/0' +# zip32 purpose (fixed) +refuse zip32 m/2147483647/133'/0' +refuse zip32 m/2147483647'/133'/0' +refuse zip32 m/2147483648/133'/0' +refuse zip32 m/2147483648'/133'/0' +refuse zip32 m/4294967295/133'/0' +refuse zip32 m/4294967295'/133'/0' +# zip32 coin (fixed) +refuse zip32 m/32'/2147483647/0' +refuse zip32 m/32'/2147483647'/0' +refuse zip32 m/32'/2147483648/0' +refuse zip32 m/32'/2147483648'/0' +refuse zip32 m/32'/4294967295/0' +refuse zip32 m/32'/4294967295'/0' +# zip32 account (hardened only) +refuse zip32 m/32'/133'/2147483647 +accept zip32 m/32'/133'/2147483647' m/32'/133'/2147483647' +refuse zip32 m/32'/133'/2147483648 +refuse zip32 m/32'/133'/2147483648' +refuse zip32 m/32'/133'/4294967295 +refuse zip32 m/32'/133'/4294967295' + +# zip32 m/32'/133'/0'/0 +# zip32 purpose (fixed) +refuse zip32 m/2147483647/133'/0'/0 +refuse zip32 m/2147483647'/133'/0'/0 +refuse zip32 m/2147483648/133'/0'/0 +refuse zip32 m/2147483648'/133'/0'/0 +refuse zip32 m/4294967295/133'/0'/0 +refuse zip32 m/4294967295'/133'/0'/0 +# zip32 coin (fixed) +refuse zip32 m/32'/2147483647/0'/0 +refuse zip32 m/32'/2147483647'/0'/0 +refuse zip32 m/32'/2147483648/0'/0 +refuse zip32 m/32'/2147483648'/0'/0 +refuse zip32 m/32'/4294967295/0'/0 +refuse zip32 m/32'/4294967295'/0'/0 +# zip32 account (hardened only) +refuse zip32 m/32'/133'/2147483647/0 +accept zip32 m/32'/133'/2147483647'/0 m/32'/133'/2147483647'/0 +refuse zip32 m/32'/133'/2147483648/0 +refuse zip32 m/32'/133'/2147483648'/0 +refuse zip32 m/32'/133'/4294967295/0 +refuse zip32 m/32'/133'/4294967295'/0 +# zip32 index (hardening optional) +accept zip32 m/32'/133'/0'/2147483647 m/32'/133'/0'/2147483647 +accept zip32 m/32'/133'/0'/2147483647' m/32'/133'/0'/2147483647' +refuse zip32 m/32'/133'/0'/2147483648 +refuse zip32 m/32'/133'/0'/2147483648' +refuse zip32 m/32'/133'/0'/4294967295 +refuse zip32 m/32'/133'/0'/4294967295' + +# slip10 m/44'/501'/0'/0' +# slip10 level 0 (hardening optional) +accept slip10 m/2147483647/501'/0'/0' m/2147483647/501'/0'/0' +accept slip10 m/2147483647'/501'/0'/0' m/2147483647'/501'/0'/0' +refuse slip10 m/2147483648/501'/0'/0' +refuse slip10 m/2147483648'/501'/0'/0' +refuse slip10 m/4294967295/501'/0'/0' +refuse slip10 m/4294967295'/501'/0'/0' +# slip10 level 1 (hardening optional) +accept slip10 m/44'/2147483647/0'/0' m/44'/2147483647/0'/0' +accept slip10 m/44'/2147483647'/0'/0' m/44'/2147483647'/0'/0' +refuse slip10 m/44'/2147483648/0'/0' +refuse slip10 m/44'/2147483648'/0'/0' +refuse slip10 m/44'/4294967295/0'/0' +refuse slip10 m/44'/4294967295'/0'/0' +# slip10 level 2 (hardening optional) +accept slip10 m/44'/501'/2147483647/0' m/44'/501'/2147483647/0' +accept slip10 m/44'/501'/2147483647'/0' m/44'/501'/2147483647'/0' +refuse slip10 m/44'/501'/2147483648/0' +refuse slip10 m/44'/501'/2147483648'/0' +refuse slip10 m/44'/501'/4294967295/0' +refuse slip10 m/44'/501'/4294967295'/0' +# slip10 level 3 (hardening optional) +accept slip10 m/44'/501'/0'/2147483647 m/44'/501'/0'/2147483647 +accept slip10 m/44'/501'/0'/2147483647' m/44'/501'/0'/2147483647' +refuse slip10 m/44'/501'/0'/2147483648 +refuse slip10 m/44'/501'/0'/2147483648' +refuse slip10 m/44'/501'/0'/4294967295 +refuse slip10 m/44'/501'/0'/4294967295' + +# slip10 m/0 +# slip10 level 0 (hardening optional) +accept slip10 m/2147483647 m/2147483647 +accept slip10 m/2147483647' m/2147483647' +refuse slip10 m/2147483648 +refuse slip10 m/2147483648' +refuse slip10 m/4294967295 +refuse slip10 m/4294967295' + +# Hardened markers h and H count like ' and are emitted as '. +accept bip44 m/44h/60H/2147483647h/0/2147483647H m/44'/60'/2147483647'/0/2147483647' +refuse bip44 m/44'/60'/2147483648h/0/0 +refuse bip44 m/44'/60'/0'/0/2147483648H +accept slip10 m/2147483647h/2147483647H/2147483647 m/2147483647'/2147483647'/2147483647 +refuse slip10 m/2147483647h/2147483648H + +# Beyond 32 bits. +refuse bip44 m/44'/60'/0'/0/4294967296 +refuse bip44 m/44'/60'/0'/0/18446744073709551616 +refuse slip10 m/99999999999999999999 +refuse slip10 m/0/99999999999999999999' + +# Leading zeros. A variable level accepts them and the canonical form drops +# them; the range check applies to the value. A fixed level (purpose, the +# fixed coin of cip11/cip1852/zip32, the 0|1 charge of bip32 and the +# BIP-44 family) must be spelled exactly as in its template. +accept bip44 m/44'/060'/0'/0/0 m/44'/60'/0'/0/0 +accept bip44 m/44'/60'/00'/0/00 m/44'/60'/0'/0/0 +accept bip44 m/44'/60'/0'/0/02147483647 m/44'/60'/0'/0/2147483647 +accept bip44 m/44'/60'/0'/0/000000000000000000002147483647' m/44'/60'/0'/0/2147483647' +refuse bip44 m/44'/60'/0'/0/02147483648 +refuse bip44 m/44'/60'/000000000000000000002147483648'/0/0 +refuse bip44 m/044'/60'/0'/0/0 +refuse bip44 m/44'/60'/0'/00/0 +refuse bip44 m/44'/60'/0'/01/0 +refuse bip84 m/084'/0'/0'/0/0 +refuse bip32 m/0'/00/0 +accept bip32 m/00'/1/007' m/0'/1/7' +refuse cip11 m/044'/118'/0'/0/0 +refuse cip11 m/44'/0118'/0'/0/0 +accept cip11 m/44'/118'/0'/09/0 m/44'/118'/0'/9/0 +refuse cip1852 m/01852'/1815'/0'/0/0 +refuse cip1852 m/1852'/01815'/0'/0/0 +accept cip1852 m/1852'/1815'/0'/02/0 m/1852'/1815'/0'/2/0 +refuse zip32 m/032'/133'/0' +refuse zip32 m/32'/0133'/0' +accept zip32 m/32'/133'/00'/00' m/32'/133'/0'/0' +accept slip10 m/044'/0501'/00' m/44'/501'/0' From 2c8988698aae08b691499575c1effae80e6c7b15 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:30:24 +0300 Subject: [PATCH 03/21] Validate network type, chain id and derivation type set in code The network type, the chain id and the derivation type are written verbatim into every URN and chain key, but nothing checked them when they were set programmatically. A chain id such as 1:dt:bip44:dp:m/44'/60'/0'/0/666 on a root address produced a URN that re-parsed as a bip44 path, so the text named a different key than the object. NewChain now requires a registered network type and a non-empty chain id of printable ASCII without ':', '?' or '#' (ASCII-trimmed, the rule of the free-form setters) and panics otherwise, like NewAddress. Chain.SetNetworkType and Chain.SetChainId return the error and keep the old value. NewDerivationPath and NewDerivationPathFromLevels panic with ErrInvalidDerivationType on an unregistered type. An Address whose path has no type serialises like a root address instead of emitting empty dt/dp components. --- CHANGELOG.md | 14 +++++++ SPEC.md | 12 +++++- chain.go | 44 ++++++++++++++++++++-- derivation_path.go | 12 +++++- hardening_test.go | 93 ++++++++++++++++++++++++++++++++++++++++++++++ mhda.go | 4 +- 6 files changed, 171 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fea2fba..b0b33b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,20 @@ of 2^31 or more no longer parses. refused in a fixed level (the purpose, the fixed coin of `cip11`, `cip1852` and `zip32`, the `0`/`1` charge of `bip32` and the BIP-44 family). +- **Programmatic values are validated like parsed input.** The network + type, the chain id and the derivation type are written verbatim into + every URN, and nothing checked them when set in code: a chain id + `1:dt:bip44:dp:m/44'/60'/0'/0/666` on a root address produced a URN that + re-parsed as a bip44 path. `NewChain` now requires a registered network + type and a non-empty chain id of printable ASCII without `:`, `?` or `#` + (ASCII-trimmed) and panics otherwise, like `NewAddress`. + `Chain.SetNetworkType` and `Chain.SetChainId` return an error + (`ErrInvalidNetworkType`, `ErrMissingChainID`, `ErrInvalidValue`) and + leave the chain unchanged; they returned nothing before. + `NewDerivationPath` and `NewDerivationPathFromLevels` panic with + `ErrInvalidDerivationType` on an unregistered type. An `Address` whose + path has no type serialises like a root address instead of emitting + empty `dt`/`dp` components. ### Fixed diff --git a/SPEC.md b/SPEC.md index 5185dc6..7ebc192 100644 --- a/SPEC.md +++ b/SPEC.md @@ -358,7 +358,7 @@ text. | `ErrMissingChainID` | `ci` absent | | `ErrCoinTypeInChainKey` | `ChainFromKey` input carries `ct` (pre-1.1 key format) | | `ErrInvalidChainKey` | `ChainFromKey` input is not the canonical identity form | -| `ErrInvalidValue` | Free-form setter value with `:`/`?`/`#`/whitespace | +| `ErrInvalidValue` | Free-form or chain id value with `:`/`?`/`#`/whitespace | | `ErrInvalidDerivationType` | `dt` value not registered | | `ErrInvalidDerivationPath` | `dp` does not match `dt`, or a level index is >= 2^31 | | `ErrInvalidAlgorithm` | `aa` value not registered | @@ -410,6 +410,16 @@ with its own factory functions: | `ChainFromNSS(s string)` | Extract the chain domain from any NSS (lenient). | | `ChainFromKey(key)` | Parse a `ChainKey` (alias of string) produced by `Key()`.| +Values set programmatically are written verbatim into every URN and chain +key, so they are validated like parsed input. `NewChain`, +`Chain.SetNetworkType` and `Chain.SetChainId` require a registered network +type and a non-empty chain id (ASCII-trimmed) of printable ASCII without +`:`, `?` or `#`; a `:` would otherwise inject components on re-parse. +`NewChain` panics on an invalid value; the setters return +`ErrInvalidNetworkType`, `ErrMissingChainID` or `ErrInvalidValue` and leave +the chain unchanged. `NewDerivationPath` and `NewDerivationPathFromLevels` +panic with `ErrInvalidDerivationType` on an unregistered derivation type. + `Chain.String()` and `Chain.Key()` both return the canonical chain key `nt::ci:`, suitable for use as a map key, cache key or content hash input. The format is a strict prefix of any full URN NSS, so diff --git a/chain.go b/chain.go index ef1dea8..1cdb6e9 100644 --- a/chain.go +++ b/chain.go @@ -25,8 +25,23 @@ type Chain struct { hasCoinType bool } +// NewChain builds a chain from a registered network type and a chain id. +// Both are written verbatim into every URN and chain key, so they are +// validated like parsed input: the network type must be one of the +// registered constants, and the chain id (ASCII-trimmed) must be non-empty +// printable ASCII without ':', '?' or '#' - a ':' would inject components on +// re-parse. An invalid value panics (programmer error at a construction +// site, as with NewAddress). For untrusted input use SetNetworkType / +// SetChainId, which return the error, or ChainFromKey. func NewChain(networkType NetworkType, chainId ChainId) *Chain { - return &Chain{networkType: networkType, chainId: chainId} + c := &Chain{} + if err := c.SetNetworkType(networkType); err != nil { + panic(err) + } + if err := c.SetChainId(chainId); err != nil { + panic(err) + } + return c } // ChainFromKey parses a Chain from a key produced by Chain.Key(). A chain key @@ -131,8 +146,31 @@ func parseCoinType(s string) (CoinType, error) { return CoinType(v), nil } -func (c *Chain) SetNetworkType(networkType NetworkType) { c.networkType = networkType } -func (c *Chain) SetChainId(chainId ChainId) { c.chainId = chainId } +// SetNetworkType sets the network type. It must be one of the registered +// constants (ErrInvalidNetworkType); on error the chain is left unchanged. +func (c *Chain) SetNetworkType(networkType NetworkType) error { + if !networkType.IsValid() { + return fmt.Errorf("%w: %q", ErrInvalidNetworkType, networkType) + } + c.networkType = networkType + return nil +} + +// SetChainId sets the chain id. The value is ASCII-trimmed and must be +// non-empty (ErrMissingChainID) printable ASCII without ':', '?' or '#' +// (ErrInvalidValue, see validateFreeFormValue); on error the chain is left +// unchanged. +func (c *Chain) SetChainId(chainId ChainId) error { + id := asciiTrim(string(chainId)) + if id == "" { + return ErrMissingChainID + } + if err := validateFreeFormValue(compChainId, id); err != nil { + return err + } + c.chainId = ChainId(id) + return nil +} // SetCoinType attaches the optional SLIP-44 coin-type metadata. func (c *Chain) SetCoinType(coinType CoinType) { diff --git a/derivation_path.go b/derivation_path.go index 3ba52e9..7108073 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -91,8 +91,12 @@ type DerivationPath struct { // 74/84/86, CIP-11, CIP-1852, ZIP-32) using the canonical "shortcut" fields. // For SLIP-10 (variable-length) callers must use NewDerivationPathFromLevels // instead - SLIP-10 cannot be reconstructed from these five fields and this -// constructor will panic if asked to. +// constructor will panic if asked to. An unregistered derivation type panics +// with ErrInvalidDerivationType: the type is written verbatim into the URN. func NewDerivationPath(derivationType DerivationType, coin CoinType, account AccountIndex, charge ChargeType, index AddressIndex) *DerivationPath { + if !derivationType.IsValid() { + panic(fmt.Errorf("%w: %q", ErrInvalidDerivationType, derivationType)) + } if derivationType == SLIP10 { panic("mhda: NewDerivationPath cannot construct SLIP10 paths; use NewDerivationPathFromLevels") } @@ -114,8 +118,12 @@ func NewDerivationPath(derivationType DerivationType, coin CoinType, account Acc // // For BIP-family schemes the shortcut fields (coin/account/charge/index) are // populated from the levels so subsequent String() and getter calls behave the -// same as if the path had been parsed. +// same as if the path had been parsed. An unregistered derivation type panics +// with ErrInvalidDerivationType. func NewDerivationPathFromLevels(derivationType DerivationType, levels []AddressIndex) *DerivationPath { + if !derivationType.IsValid() { + panic(fmt.Errorf("%w: %q", ErrInvalidDerivationType, derivationType)) + } cp := make([]AddressIndex, len(levels)) copy(cp, levels) dp := &DerivationPath{ diff --git a/hardening_test.go b/hardening_test.go index c0fe8af..5075821 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -179,3 +179,96 @@ func TestFreeFormValuesPreserveCase(t *testing.T) { t.Error("wallet type lost its case") } } + +// panicErr runs f and returns the error it panicked with, or nil when it did +// not panic. +func panicErr(t *testing.T, f func()) (err error) { + t.Helper() + defer func() { + if r := recover(); r != nil { + e, ok := r.(error) + if !ok { + t.Fatalf("panicked with a non-error value %v", r) + } + err = e + } + }() + f() + return nil +} + +// TestProgrammaticValuesCannotInjectComponents: the network type, the chain +// id and the derivation type are written verbatim into every URN. A value +// carrying ':' would inject components on re-parse (a root address whose URN +// reads back as a bip44 path), '?' / '#' would truncate it. Constructors +// panic on such a value, setters return the error and keep the old value. +func TestProgrammaticValuesCannotInjectComponents(t *testing.T) { + for _, c := range []struct { + nt NetworkType + ci ChainId + want error + }{ + {EthereumVM, "1:dt:bip44:dp:m/44'/60'/0'/0/666", ErrInvalidValue}, + {EthereumVM, "1:wi:attacker", ErrInvalidValue}, + {EthereumVM, "1?=q", ErrInvalidValue}, + {EthereumVM, "1#f", ErrInvalidValue}, + {EthereumVM, "a b", ErrInvalidValue}, + {EthereumVM, " 1", ErrInvalidValue}, + {EthereumVM, "", ErrMissingChainID}, + {EthereumVM, " \t", ErrMissingChainID}, + {NetworkType("evm:ci:1:dt:bip44"), "1", ErrInvalidNetworkType}, + {NetworkType("polkadot"), "1", ErrInvalidNetworkType}, + {NetworkType("EVM"), "1", ErrInvalidNetworkType}, + {NetworkType(""), "1", ErrInvalidNetworkType}, + } { + err := panicErr(t, func() { NewChain(c.nt, c.ci) }) + if !errors.Is(err, c.want) { + t.Errorf("NewChain(%q, %q): panic %v, want %v", c.nt, c.ci, err, c.want) + } + } + + if got := NewChain(EthereumVM, " 0x1 ").ChainId(); got != "0x1" { + t.Errorf("NewChain trims ASCII whitespace: ChainId() = %q, want %q", got, "0x1") + } + + ch := NewChain(EthereumVM, "1") + if err := ch.SetChainId("1:dt:bip44"); !errors.Is(err, ErrInvalidValue) { + t.Errorf("SetChainId: got %v, want ErrInvalidValue", err) + } + if err := ch.SetChainId(""); !errors.Is(err, ErrMissingChainID) { + t.Errorf("SetChainId(\"\"): got %v, want ErrMissingChainID", err) + } + if err := ch.SetNetworkType(NetworkType("evm:x")); !errors.Is(err, ErrInvalidNetworkType) { + t.Errorf("SetNetworkType: got %v, want ErrInvalidNetworkType", err) + } + if got := ch.String(); got != "nt:evm:ci:1" { + t.Errorf("failed setters changed the chain: %q", got) + } + if err := ch.SetChainId("56"); err != nil { + t.Errorf("SetChainId(56): %v", err) + } + if err := ch.SetNetworkType(Bitcoin); err != nil { + t.Errorf("SetNetworkType(Bitcoin): %v", err) + } + if got := ch.String(); got != "nt:bitcoin:ci:56" { + t.Errorf("setters: String() = %q", got) + } + + for _, dt := range []DerivationType{"bip44:wi:x", "bogus", "BIP44", ""} { + err := panicErr(t, func() { NewDerivationPath(dt, 60, 0, 0, AddressIndex{}) }) + if !errors.Is(err, ErrInvalidDerivationType) { + t.Errorf("NewDerivationPath(%q): panic %v, want ErrInvalidDerivationType", dt, err) + } + err = panicErr(t, func() { NewDerivationPathFromLevels(dt, nil) }) + if !errors.Is(err, ErrInvalidDerivationType) { + t.Errorf("NewDerivationPathFromLevels(%q): panic %v, want ErrInvalidDerivationType", dt, err) + } + } + + // A zero DerivationPath has no type; it serialises like a root address + // instead of emitting empty dt/dp components. + addr := NewAddress(NewChain(EthereumVM, "1"), &DerivationPath{}) + if got := addr.String(); got != "urn:mhda:nt:evm:ci:1" { + t.Errorf("zero DerivationPath: String() = %q, want urn:mhda:nt:evm:ci:1", got) + } +} diff --git a/mhda.go b/mhda.go index 5f10281..93f9f11 100644 --- a/mhda.go +++ b/mhda.go @@ -327,8 +327,8 @@ func (a *Address) NSS() string { _, _ = fmt.Fprintf(&b, ":ct:%d", a.chain.coinType) } - // Derivation domain - present when not ROOT. - if a.path != nil && a.path.derivationType != ROOT { + // Derivation domain - present when a type other than ROOT is set. + if a.path != nil && a.path.derivationType != ROOT && a.path.derivationType != "" { b.WriteString(":dt:") b.WriteString(string(a.path.derivationType)) b.WriteString(":dp:") From 627af1d3a2c09dfadecfac952d3af3652e817b5f Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:31:16 +0300 Subject: [PATCH 04/21] Refuse a derivation path without a derivation type or under root SetDerivationPath returned early for a root address, so a dp with no dt (which parses as root) or with dt:root was dropped silently: urn:mhda:nt:evm:ci:1:dp:m/44'/60'/0'/0/0 parsed as urn:mhda:nt:evm:ci:1, naming the root key instead of the path it spells out. ParsePath already refused a non-empty path for ROOT; the address setter now does the same and returns ErrInvalidDerivationPath. An empty dp under root stays a no-op. testdata/urn_conformance.txt is a URN-level table shared verbatim with the C++ port, run through ParseURN / ParseNSS; this change adds its first rows. --- CHANGELOG.md | 7 +++ SPEC.md | 9 ++- mhda.go | 8 +++ testdata/urn_conformance.txt | 28 +++++++++ urn_conformance_test.go | 106 +++++++++++++++++++++++++++++++++++ 5 files changed, 157 insertions(+), 1 deletion(-) create mode 100644 testdata/urn_conformance.txt create mode 100644 urn_conformance_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index b0b33b8..4776058 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,6 +46,13 @@ of 2^31 or more no longer parses. `ErrInvalidDerivationType` on an unregistered type. An `Address` whose path has no type serialises like a root address instead of emitting empty `dt`/`dp` components. +- **A derivation path without a derivation type, or under `dt:root`, is + refused** with `ErrInvalidDerivationPath`. Both used to be dropped + silently: `urn:mhda:nt:evm:ci:1:dp:m/44'/60'/0'/0/0` and + `urn:mhda:nt:evm:ci:1:dt:root:dp:m/0` parsed as the root address + `urn:mhda:nt:evm:ci:1`, naming the root key instead of the path they + spell out. `Address.SetDerivationPath` on a root address accepts only an + empty path. ### Fixed diff --git a/SPEC.md b/SPEC.md index 7ebc192..ddeb5bc 100644 --- a/SPEC.md +++ b/SPEC.md @@ -43,6 +43,11 @@ Optional components are emitted in canonical output ONLY when explicitly set. A short input form round-trips back to the same short form; a long form round-trips back to the same long form. +`dp` is present exactly when `dt` is a type other than `root`. A `dp` +without `dt` (which makes the address root) or with `dt:root` is refused +with `ErrInvalidDerivationPath`: dropping it would make the URN name the root +key instead of the path it spells out. + The chain identity is the `(nt, ci)` pair. The `ct` component is OPTIONAL SLIP-44 coin-type metadata: it never participates in the chain identity or in chain keys (see §1.6 and §10). For HD addresses the coin type is already @@ -315,6 +320,8 @@ Performs structural validation only: - Derivation type, if present, is one of the registered constants. - Derivation path, if present, matches the regex of its derivation type, and every level's index is below 2^31 (§3). +- Derivation path is present if and only if the derivation type is set and + is not `root` (§1.2). - Algorithm, if present, is one of the registered constants. - Format, if present, is one of the registered constants. @@ -360,7 +367,7 @@ text. | `ErrInvalidChainKey` | `ChainFromKey` input is not the canonical identity form | | `ErrInvalidValue` | Free-form or chain id value with `:`/`?`/`#`/whitespace | | `ErrInvalidDerivationType` | `dt` value not registered | -| `ErrInvalidDerivationPath` | `dp` does not match `dt`, or a level index is >= 2^31 | +| `ErrInvalidDerivationPath` | `dp` does not fit `dt` (or no `dt`), or an index >= 2^31 | | `ErrInvalidAlgorithm` | `aa` value not registered | | `ErrInvalidFormat` | `af` value not registered | | `ErrIncompatible` | Strict validation: triple not allowed for the network | diff --git a/mhda.go b/mhda.go index 93f9f11..f95cb64 100644 --- a/mhda.go +++ b/mhda.go @@ -166,8 +166,16 @@ func (a *Address) SetDerivationType(dt string) error { return nil } +// SetDerivationPath parses dp under the address' derivation type. A root +// address has no path: an empty dp is accepted, anything else is refused +// with ErrInvalidDerivationPath. Dropping it instead would let a URN with a +// dp but no dt (which parses as root) name the root key rather than the +// path it spells out. func (a *Address) SetDerivationPath(dp string) error { if a.path.derivationType == ROOT { + if p := strings.TrimSpace(dp); p != `` { + return fmt.Errorf("%w: root derivation must have empty path, got %q", ErrInvalidDerivationPath, p) + } return nil } diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt new file mode 100644 index 0000000..4e15661 --- /dev/null +++ b/testdata/urn_conformance.txt @@ -0,0 +1,28 @@ +# URN conformance table, shared verbatim by go-mhda +# (testdata/urn_conformance.txt) and the C++ port (tests/data/urn_conformance.txt). +# Both test suites run every row through the lenient parser; an input one +# implementation refuses, the other refuses too, with the same error. Edit +# both copies together. +# +# Row forms: +# accept urn +# accept nss +# refuse urn +# refuse nss +# is the C++ error_code name; go-mhda maps it to its sentinel +# (invalid_nss is ErrInvalidNSS, invalid_derivation_path is +# ErrInvalidDerivationPath, ...). + +# A derivation path needs a derivation type other than root. Without dt the +# address is root, and a dp there would be dropped: the URN would name the +# root key instead of the path it spells out. +refuse urn invalid_derivation_path urn:mhda:nt:evm:ci:1:dp:m/44'/60'/0'/0/0 +refuse urn invalid_derivation_path urn:mhda:nt:evm:ci:1:dt:root:dp:m/0 +refuse urn invalid_derivation_path urn:mhda:nt:evm:ci:1:dt:ROOT:dp:m/0 +refuse urn invalid_derivation_path urn:mhda:nt:ton:ci:mainnet:dt:root:dp:m/44'/607'/0' +refuse urn invalid_derivation_path urn:mhda:dp:m/44'/60'/0'/0/0:nt:evm:ci:1 +refuse nss invalid_derivation_path nt:evm:ci:1:dp:m/44'/60'/0'/0/0 +refuse urn invalid_derivation_path urn:mhda:nt:evm:ci:1:dt:bip44 +accept urn urn:mhda:nt:ton:ci:mainnet urn:mhda:nt:ton:ci:mainnet +accept urn urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 +accept nss nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 diff --git a/urn_conformance_test.go b/urn_conformance_test.go new file mode 100644 index 0000000..bec6430 --- /dev/null +++ b/urn_conformance_test.go @@ -0,0 +1,106 @@ +package go_mhda + +import ( + "bufio" + "errors" + "os" + "strings" + "testing" +) + +// conformanceErrors maps the error names of the shared URN table (the C++ +// error_code names) to the sentinels. +var conformanceErrors = map[string]error{ + "invalid_urn": ErrInvalidURN, + "invalid_nss": ErrInvalidNSS, + "missing_network_type": ErrMissingNetworkType, + "invalid_network_type": ErrInvalidNetworkType, + "invalid_coin_type": ErrInvalidCoinType, + "missing_chain_id": ErrMissingChainID, + "invalid_derivation_type": ErrInvalidDerivationType, + "invalid_derivation_path": ErrInvalidDerivationPath, + "invalid_algorithm": ErrInvalidAlgorithm, + "invalid_format": ErrInvalidFormat, + "invalid_value": ErrInvalidValue, +} + +// TestURNConformance runs the URN table shared with the C++ port +// (testdata/urn_conformance.txt, a verbatim copy of the port's +// tests/data/urn_conformance.txt). +func TestURNConformance(t *testing.T) { + f, err := os.Open("testdata/urn_conformance.txt") + if err != nil { + t.Fatal(err) + } + defer f.Close() + + rows := 0 + sc := bufio.NewScanner(f) + sc.Buffer(make([]byte, 64*1024), 1024*1024) + for line := 1; sc.Scan(); line++ { + text := strings.TrimSpace(sc.Text()) + if text == "" || strings.HasPrefix(text, "#") { + continue + } + fields := strings.Fields(text) + if len(fields) != 4 || (fields[1] != "urn" && fields[1] != "nss") { + t.Fatalf("urn_conformance.txt:%d: malformed row %q", line, text) + } + rows++ + accept := fields[0] == "accept" + input, want := fields[2], fields[3] + var wantErr error + switch { + case accept: + case fields[0] == "refuse": + input, want = fields[3], "" + if wantErr = conformanceErrors[fields[2]]; wantErr == nil { + t.Fatalf("urn_conformance.txt:%d: unknown error %q", line, fields[2]) + } + default: + t.Fatalf("urn_conformance.txt:%d: malformed row %q", line, text) + } + + parse := ParseURN + if fields[1] == "nss" { + parse = ParseNSS + } + addr, err := parse(input) + if accept { + if err != nil { + t.Errorf("line %d: parse %s %q: %v", line, fields[1], input, err) + } else if got := addr.String(); got != want { + t.Errorf("line %d: parse %s %q: String() = %q, want %q", line, fields[1], input, got, want) + } + } else if !errors.Is(err, wantErr) { + t.Errorf("line %d: parse %s %q: got %v, want %v", line, fields[1], input, err, wantErr) + } + } + if err := sc.Err(); err != nil { + t.Fatal(err) + } + if rows == 0 { + t.Fatal("urn_conformance.txt: no rows") + } +} + +// TestSetDerivationPathUnderRoot: the setter refuses a path while the type +// is root, and accepts an empty one. +func TestSetDerivationPathUnderRoot(t *testing.T) { + parsed, err := ParseURN(`urn:mhda:nt:evm:ci:1`) + if err != nil { + t.Fatal(err) + } + addr := parsed.(*Address) + if err := addr.SetDerivationPath("m/44'/60'/0'/0/0"); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("SetDerivationPath under root: got %v, want ErrInvalidDerivationPath", err) + } + for _, empty := range []string{"", " "} { + if err := addr.SetDerivationPath(empty); err != nil { + t.Errorf("SetDerivationPath(%q) under root: %v", empty, err) + } + } + if got := addr.String(); got != `urn:mhda:nt:evm:ci:1` { + t.Errorf("String() = %q", got) + } +} From da402de8cd2a1c373aac15da014a07d27acf9427 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:32:27 +0300 Subject: [PATCH 05/21] Parse the NSS strictly as key:value pairs parseNSS skipped an unknown token on its own, so the token after it was read as a key: a value could become a key and a known key could become a value. A key with the wrong case was skipped with it, dropping the component silently. ...:ci:1:DT:bip44:DP:m/44'/60'/0'/0/5 parsed as the root address urn:mhda:nt:evm:ci:1, and ...:ci:1:ext:wi:dt:bip44:... took dt as the wallet id. The NSS is now split into pairs: an odd number of tokens is refused, an unknown component is skipped together with its value, and a key that differs from a known key only by case is refused with ErrInvalidNSS. Keys must be non-empty printable ASCII, like values. An empty NSS still has no components. ChainFromKey keeps reporting a dangling token as ErrInvalidChainKey. --- CHANGELOG.md | 9 +++++++ SPEC.md | 11 +++++++- chain.go | 5 ++++ parser.go | 51 ++++++++++++++++++++++++++---------- testdata/urn_conformance.txt | 21 +++++++++++++++ 5 files changed, 82 insertions(+), 15 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4776058..134dfa7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -53,6 +53,15 @@ of 2^31 or more no longer parses. `urn:mhda:nt:evm:ci:1`, naming the root key instead of the path they spell out. `Address.SetDerivationPath` on a root address accepts only an empty path. +- **The NSS is parsed strictly as `key:value` pairs.** An unknown key was + skipped as a single token, so its value was read as the next key and a + key with the wrong case vanished: `...:ci:1:DT:bip44:DP:m/44'/60'/0'/0/5` + parsed as the root address `urn:mhda:nt:evm:ci:1`, and + `...:ci:1:ext:wi:dt:bip44:...` read `dt` as the wallet id. An unknown + component is now skipped together with its value; a key that differs from + a known key only by case, a dangling token, a trailing `:` and an empty + key are refused with `ErrInvalidNSS`. `ChainFromKey` reports a dangling + token as `ErrInvalidChainKey`, as before. ### Fixed diff --git a/SPEC.md b/SPEC.md index ddeb5bc..47067a8 100644 --- a/SPEC.md +++ b/SPEC.md @@ -19,7 +19,16 @@ urn:mhda:nt::ci::ct::dt::dp::aa: 0x7e { + return fmt.Errorf("%w: non-ASCII or control byte in component key %q", ErrInvalidNSS, key) + } + } + return nil +} + // stripRQF strips the optional rq-components ("?+" / "?=") and f-component // ("#") trailing the assigned-name part, per RFC 8141 §2. The current parser // does not interpret resource/query/fragment metadata; they are silently @@ -157,27 +171,31 @@ func ParseNSS(nss string) (MHDA, error) { // parseNSS is the shared low-level NSS parser. It returns the raw component // map; callers (ParseNSS, ChainFromNSS) interpret the map per their domain. // -// Form: a sequence of `key:value` pairs joined by `:` separators. Unknown -// keys are silently skipped (forward-compat with future URN extensions); -// duplicate keys and empty values are rejected. +// Form: a sequence of `key:value` pairs joined by `:` separators; an empty +// NSS has no components. A pair with an unknown key is skipped together with +// its value (forward-compat with future URN extensions), so a value is never +// read as a key and a following known key is never read as a value. A key +// that differs from a known key only by case is rejected, not skipped: it +// would drop the component silently. A key without a value, an empty key or +// value and a duplicate known key are rejected too. // // Values may not contain ':'; this holds for every component currently // defined in MHDA. Adding a value type that needs ':' would require // percent-encoding support. func parseNSS(nss string) (map[string]string, error) { - parts := strings.Split(nss, ":") components := make(map[string]string, len(componentsNames)) + if nss == "" { + return components, nil + } + parts := strings.Split(nss, ":") + if len(parts)%2 != 0 { + return nil, fmt.Errorf("%w: missing value for %q", ErrInvalidNSS, parts[len(parts)-1]) + } - for i := 0; i < len(parts); { + for i := 0; i < len(parts); i += 2 { key := parts[i] - if _, ok := knownComponents[key]; !ok { - // Unknown token (could be an unrelated word, a future component - // name, or part of a value we mis-identified). Skip and move on. - i++ - continue - } - if i+1 >= len(parts) { - return nil, fmt.Errorf("%w: missing value for %q", ErrInvalidNSS, key) + if err := validateKeyCharset(key); err != nil { + return nil, err } // RFC 8141 NSS does not permit unescaped whitespace; trim ASCII // whitespace so any trailing space (e.g. from "ci:0 #frag" where @@ -193,11 +211,16 @@ func parseNSS(nss string) (map[string]string, error) { if err := validateValueCharset(key, value); err != nil { return nil, err } + if _, ok := knownComponents[key]; !ok { + if _, ok := knownComponents[strings.ToLower(key)]; ok { + return nil, fmt.Errorf("%w: component key %q must be lowercase", ErrInvalidNSS, key) + } + continue // unknown component, skipped with its value + } if _, dup := components[key]; dup { return nil, fmt.Errorf("%w: duplicate component %q", ErrInvalidNSS, key) } components[key] = value - i += 2 } return components, nil } diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt index 4e15661..995e633 100644 --- a/testdata/urn_conformance.txt +++ b/testdata/urn_conformance.txt @@ -26,3 +26,24 @@ refuse urn invalid_derivation_path urn:mhda:nt:evm:ci:1:dt:bip44 accept urn urn:mhda:nt:ton:ci:mainnet urn:mhda:nt:ton:ci:mainnet accept urn urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 accept nss nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 + +# The NSS is a sequence of key:value pairs. An unknown key is skipped +# together with its value (forward compatibility), so a following known key +# is never read as its value. A key that differs from a known key only by +# case is refused rather than skipped, and so is a token without a value. +refuse urn invalid_nss urn:mhda:nt:evm:ci:1:DT:bip44:DP:m/44'/60'/0'/0/5 +refuse urn invalid_nss urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0:WI:wallet-A +refuse urn invalid_nss urn:mhda:NT:evm:ci:1 +refuse urn invalid_nss urn:mhda:nt:evm:Ci:1 +accept urn urn:mhda:nt:evm:ci:1:ext:wi:dt:bip44:dp:m/44'/60'/0'/0/5 urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/5 +accept urn urn:mhda:nt:evm:ci:1:xx:future urn:mhda:nt:evm:ci:1 +accept urn urn:mhda:xx:nt:nt:evm:ci:1 urn:mhda:nt:evm:ci:1 +refuse urn invalid_nss urn:mhda:nt:evm:ci:1:garbage +refuse urn invalid_nss urn:mhda:nt:evm:junk:ci:1 +refuse urn invalid_nss urn:mhda:nt:evm:ci:1: +refuse urn invalid_nss urn:mhda::nt:evm:ci:1 +refuse urn invalid_nss urn:mhda:nt:evm:ci:1::x +refuse urn invalid_nss urn:mhda:nt:evm:ci:1:xx: +refuse urn missing_network_type urn:mhda: +refuse nss invalid_nss nt:evm:ci:1:foo +accept nss nt:evm:ci:1:wt:web3 urn:mhda:nt:evm:ci:1:wt:web3 From c4672192b01989bf42d0abbe36745033e566ae85 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:33:09 +0300 Subject: [PATCH 06/21] Refuse '?' and '#' in an NSS parsed on its own ParseURN strips the RFC 8141 r/q/f components at the first '?' or '#', but ParseNSS, ChainFromNSS and ChainFromKey took the NSS as given and kept the byte in a value. The URN emitted from such an address was truncated on the next parse: ParseNSS("nt:evm:ci:1?=q:dt:bip44:dp:m/44'/60'/0'/0/0") returned a bip44 address whose String() re-parsed as the root address urn:mhda:nt:evm:ci:1, and ChainFromKey("nt:evm:ci:1#a") was accepted. parseNSS now refuses either byte with ErrInvalidNSS. FuzzParseNSS claimed the idempotency contract without checking it; it now re-parses the emitted URN and compares, with the truncating input as a seed. --- CHANGELOG.md | 7 +++++++ SPEC.md | 5 +++++ chain_test.go | 14 ++++++++++++++ fuzz_test.go | 18 +++++++++++++++--- parser.go | 8 ++++++++ testdata/urn_conformance.txt | 10 ++++++++++ 6 files changed, 59 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 134dfa7..1fea0cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -62,6 +62,13 @@ of 2^31 or more no longer parses. a known key only by case, a dangling token, a trailing `:` and an empty key are refused with `ErrInvalidNSS`. `ChainFromKey` reports a dangling token as `ErrInvalidChainKey`, as before. +- **`ParseNSS`, `ChainFromNSS` and `ChainFromKey` refuse `?` and `#`** with + `ErrInvalidNSS`. `ParseURN` strips the RFC 8141 r/q/f components before + parsing, but an NSS given on its own kept the byte in a value: + `ParseNSS("nt:evm:ci:1?=q:dt:bip44:dp:m/44'/60'/0'/0/0")` returned a bip44 + address whose URN re-parsed as the root address `urn:mhda:nt:evm:ci:1`, + and `ChainFromKey("nt:evm:ci:1#a")` was accepted. `FuzzParseNSS` now + checks that the emitted URN re-parses to itself. ### Fixed diff --git a/SPEC.md b/SPEC.md index 47067a8..4df58cb 100644 --- a/SPEC.md +++ b/SPEC.md @@ -89,6 +89,11 @@ interpreted; they are stripped before parsing: Example: `urn:mhda:nt:evm:ci:1?+resolver=example.com#sec` parses identically to the bare URN; `String()` does not preserve these elements. +An NSS given on its own (`ParseNSS`, `ChainFromNSS`, `ChainFromKey`) has no +r/q/f components to strip, so it must not contain `?` or `#` at all; such +input is refused with `ErrInvalidNSS`. Kept in a value, the byte would +truncate the URN emitted from it on the next parse. + ### 1.5 Charset NSS values must consist of ASCII characters allowed by RFC 8141 NSS production diff --git a/chain_test.go b/chain_test.go index 410c9a1..1e3360b 100644 --- a/chain_test.go +++ b/chain_test.go @@ -80,6 +80,20 @@ func TestChainFromKeyRejectsExtraComponents(t *testing.T) { } } +// TestChainParsersRefuseRQFDelimiters: '?' and '#' open the RFC 8141 r/q/f +// components; a chain key or NSS carrying one in a value would be truncated +// once embedded in a URN. +func TestChainParsersRefuseRQFDelimiters(t *testing.T) { + for _, s := range []string{`nt:evm:ci:1#a`, `nt:evm:ci:1?=q`, `nt:evm:ci:a?b`} { + if _, err := ChainFromKey(ChainKey(s)); !errors.Is(err, ErrInvalidNSS) { + t.Errorf("ChainFromKey(%q): got %v, want ErrInvalidNSS", s, err) + } + if _, err := ChainFromNSS(s); !errors.Is(err, ErrInvalidNSS) { + t.Errorf("ChainFromNSS(%q): got %v, want ErrInvalidNSS", s, err) + } + } +} + // TestChainFromNSSAcceptsOptionalCoinType: the lenient NSS extractor accepts // the optional ct metadata (in any position) and keeps it off the key. func TestChainFromNSSAcceptsOptionalCoinType(t *testing.T) { diff --git a/fuzz_test.go b/fuzz_test.go index 0d495d1..a867091 100644 --- a/fuzz_test.go +++ b/fuzz_test.go @@ -139,7 +139,8 @@ func FuzzDerivationPath(f *testing.F) { } // FuzzParseNSS targets the lower-level byte parser. Same contract as -// FuzzParseURN: no panics, idempotent on success. +// FuzzParseURN: no panics, and on success the emitted URN re-parses to +// itself. func FuzzParseNSS(f *testing.F) { for _, s := range uriMHDA { f.Add(s[prefixOffset:]) @@ -147,6 +148,8 @@ func FuzzParseNSS(f *testing.F) { for _, s := range []string{ "", "n", "nt", "nt:", "nt:evm", "nt:evm:ci:1:ct:60", "nt:evm:ci:1", "nt:evm:ci:1:wt:web3:wi:5f2a8c31", + "nt:evm:ci:1?=q:dt:bip44:dp:m/44'/60'/0'/0/0", + "nt:evm:ci:1:wi:a#b", } { f.Add(s) } @@ -159,7 +162,16 @@ func FuzzParseNSS(f *testing.F) { if addr == nil { t.Fatalf("ParseNSS returned (nil, nil) for %q", src) } - _ = addr.String() - _ = addr.NSS() + serialized := addr.String() + if serialized != prefixMHDA+addr.NSS() { + t.Fatalf("String() %q is not the prefix plus NSS() %q", serialized, addr.NSS()) + } + again, err := ParseURN(serialized) + if err != nil { + t.Fatalf("re-parse of %q (from NSS %q) failed: %v", serialized, src, err) + } + if again.String() != serialized { + t.Fatalf("not idempotent:\n once: %s\n twice: %s\n input: %q", serialized, again.String(), src) + } }) } diff --git a/parser.go b/parser.go index 6d14aa9..478f5cf 100644 --- a/parser.go +++ b/parser.go @@ -179,6 +179,11 @@ func ParseNSS(nss string) (MHDA, error) { // would drop the component silently. A key without a value, an empty key or // value and a duplicate known key are rejected too. // +// '?' and '#' open the RFC 8141 r/q/f components. ParseURN strips them before +// the NSS reaches this parser; an NSS that still carries one (ParseNSS, +// ChainFromNSS, ChainFromKey) is rejected, since the URN emitted from it would +// be truncated at that byte on the next parse. +// // Values may not contain ':'; this holds for every component currently // defined in MHDA. Adding a value type that needs ':' would require // percent-encoding support. @@ -187,6 +192,9 @@ func parseNSS(nss string) (map[string]string, error) { if nss == "" { return components, nil } + if i := strings.IndexAny(nss, "?#"); i >= 0 { + return nil, fmt.Errorf("%w: %q inside the NSS", ErrInvalidNSS, nss[i]) + } parts := strings.Split(nss, ":") if len(parts)%2 != 0 { return nil, fmt.Errorf("%w: missing value for %q", ErrInvalidNSS, parts[len(parts)-1]) diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt index 995e633..7c027ce 100644 --- a/testdata/urn_conformance.txt +++ b/testdata/urn_conformance.txt @@ -47,3 +47,13 @@ refuse urn invalid_nss urn:mhda:nt:evm:ci:1:xx: refuse urn missing_network_type urn:mhda: refuse nss invalid_nss nt:evm:ci:1:foo accept nss nt:evm:ci:1:wt:web3 urn:mhda:nt:evm:ci:1:wt:web3 + +# '?' and '#' open the RFC 8141 r/q/f components. ParseURN strips them with +# everything after; an NSS passed on its own must not carry them in a value, +# or the URN emitted from it would be truncated on the next parse. +refuse nss invalid_nss nt:evm:ci:1?=q:dt:bip44:dp:m/44'/60'/0'/0/0 +refuse nss invalid_nss nt:evm:ci:1#f +refuse nss invalid_nss nt:evm:ci:1:wi:a?b +refuse nss invalid_nss nt:evm:ci:1:x#y:z +accept urn urn:mhda:nt:evm:ci:1?=q:dt:bip44 urn:mhda:nt:evm:ci:1 +accept urn urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0#frag urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 From 9f62c3b36687c3f55d0c07d50bbc28d9bc2d503a Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:33:28 +0300 Subject: [PATCH 07/21] Limit SLIP-10 paths to 255 levels BIP-32 serialises a key's depth in one byte, so a path deeper than 255 levels names a key no wallet can represent; ParsePath accepted any depth. A slip10 path with more than 255 levels is now refused with ErrInvalidDerivationPath. The shared derivation-path table gets the 255/256 boundary rows. --- CHANGELOG.md | 3 +++ SPEC.md | 8 +++++--- derivation_path.go | 7 +++++++ testdata/dp_conformance.txt | 6 ++++++ 4 files changed, 21 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fea0cf..cf3ea75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -69,6 +69,9 @@ of 2^31 or more no longer parses. address whose URN re-parsed as the root address `urn:mhda:nt:evm:ci:1`, and `ChainFromKey("nt:evm:ci:1#a")` was accepted. `FuzzParseNSS` now checks that the emitted URN re-parses to itself. +- **A `slip10` path has at most 255 levels**; a deeper one is refused with + `ErrInvalidDerivationPath`. BIP-32 serialises a key's depth in one byte, + so no wallet can represent a deeper key. ### Fixed diff --git a/SPEC.md b/SPEC.md index 4df58cb..7ee85c2 100644 --- a/SPEC.md +++ b/SPEC.md @@ -250,7 +250,7 @@ protocol messages. | bip74 | `m/74'/coin'/account'/charge/index[']` | 5 | sui-keys/src/key_derive.rs (Sui secp256r1) | | bip84 | `m/84'/coin'/account'/charge/index[']` | 5 | https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki | | bip86 | `m/86'/coin'/account'/charge/index[']` | 5 | https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki | -| slip10 | `m(/index['])+` (variable length) | 1+ | https://github.com/satoshilabs/slips/blob/master/slip-0010.md | +| slip10 | `m(/index['])+` (variable length) | 1-255 | https://github.com/satoshilabs/slips/blob/master/slip-0010.md | | cip11 | `m/44'/118'/account'/charge_extra/index[']` | 5 | https://github.com/confio/cosmos-hd-key-derivation-spec | | cip1852 | `m/1852'/1815'/account'/role/index[']` | 5 | https://github.com/cardano-foundation/CIPs/blob/master/CIP-1852/ | | zip32 | `m/32'/133'/account'[/index[']]` | 3 or 4 | https://zips.z.cash/zip-0032 | @@ -272,9 +272,11 @@ exactly as in the template. ### 3.1 Variable-length paths -`slip10` accepts any number of levels and is the right type for chains whose +`slip10` accepts 1 to 255 levels and is the right type for chains whose HD derivation does not fit a fixed shape (Solana, Stellar, Aptos ed25519, -Sui ed25519, NEAR, Ledger TON). +Sui ed25519, NEAR, Ledger TON). The upper bound is BIP-32's: a key's depth +is serialised in one byte, so a deeper path is refused with +`ErrInvalidDerivationPath`. `zip32` accepts both 3-level (`m/32'/133'/account'`) and 4-level (`m/32'/133'/account'/index[']`) forms; both round-trip exactly. diff --git a/derivation_path.go b/derivation_path.go index 7108073..671b298 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -59,6 +59,10 @@ func DerivationTypeFromString(src string) (DerivationType, error) { type AccountIndex uint32 +// maxSlip10Depth is the deepest SLIP-10 path: BIP-32 serialises a key's depth +// in one byte. +const maxSlip10Depth = 255 + // ChargeType is the level after the account: the change level of BIP-32 and // the BIP-44 family (0 external, 1 internal), the CIP-11 charge and the // CIP-1852 role. It is as wide as a level index: the CIP-11 charge and the @@ -402,6 +406,9 @@ func (dp *DerivationPath) ParsePath(path string) error { // Generic SLIP-0010: split the path manually to extract per-level // index and hardening marker. The regex above only validates shape. segments := strings.Split(path[2:], "/") // skip leading "m/" + if len(segments) > maxSlip10Depth { + return fmt.Errorf("%w: %d levels, at most %d", ErrInvalidDerivationPath, len(segments), maxSlip10Depth) + } levels := make([]AddressIndex, 0, len(segments)) for i, seg := range segments { hardened := false diff --git a/testdata/dp_conformance.txt b/testdata/dp_conformance.txt index 2056e69..5adba1d 100644 --- a/testdata/dp_conformance.txt +++ b/testdata/dp_conformance.txt @@ -464,3 +464,9 @@ refuse zip32 m/032'/133'/0' refuse zip32 m/32'/0133'/0' accept zip32 m/32'/133'/00'/00' m/32'/133'/0'/0' accept slip10 m/044'/0501'/00' m/44'/501'/0' + +# SLIP-10 depth. BIP-32 serialises a key's depth in one byte, so a path has +# at most 255 levels. +accept slip10 m/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0' m/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0' +accept slip10 m/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/2147483647' m/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/7/2147483647' +refuse slip10 m/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0'/0' From 110daf920c7b7727e5cd70da10bfa03037fce60d Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:34:01 +0300 Subject: [PATCH 08/21] Document dt:root folding and ZIP-32 without a network SPEC.md promised that a long form round-trips to itself, but an explicit dt:root is folded away: ...:ci:1:dt:root serialises as ...:ci:1. That is the intended behaviour (root is the default and has no path, so a root address keeps one canonical form and one hash, and consumers rely on it); the spec now says so, and the Algorand and TON notes no longer call dt:root the canonical form. zip32 parses, but no network registers it, so ParseURNStrict refuses it everywhere; the spec lists that as a known limitation. Tests pin both: dt:root rows in the shared URN table and a strict-refusal check over every network. --- CHANGELOG.md | 9 +++++++++ SPEC.md | 19 ++++++++++++++----- hardening_test.go | 14 ++++++++++++++ testdata/urn_conformance.txt | 6 ++++++ 4 files changed, 43 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cf3ea75..10b4f33 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -73,6 +73,15 @@ of 2^31 or more no longer parses. `ErrInvalidDerivationPath`. BIP-32 serialises a key's depth in one byte, so no wallet can represent a deeper key. +### Documentation + +- SPEC.md states that an explicit `dt:root` is folded away (root is the + default and has no path, so a root address has one canonical form and + one hash); the Algorand and TON notes no longer call `dt:root` the + canonical form. It also lists ZIP-32 as a known limitation: `zip32` + parses, but no network registers it, so strict parsing refuses it. Both + behaviours are unchanged and now pinned by tests. + ### Fixed - **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the diff --git a/SPEC.md b/SPEC.md index 7ee85c2..d239dda 100644 --- a/SPEC.md +++ b/SPEC.md @@ -50,7 +50,10 @@ lowercase in the canonical form; free-form values (`ci`, `ap`, `as`, `wt`, Optional components are emitted in canonical output ONLY when explicitly set. A short input form round-trips back to the same short form; a long form -round-trips back to the same long form. +round-trips back to the same long form. The one exception is `dt:root`: +root is the default derivation type and carries no path, so an explicit +`dt:root` is folded away and `...:ci:1:dt:root` serialises as `...:ci:1`. +A root address therefore has a single canonical form (and a single hash). `dp` is present exactly when `dt` is a type other than `root`. A `dp` without `dt` (which makes the address root) or with `dt:root` is refused @@ -221,9 +224,9 @@ CIP-19); Byron-era addresses use base58 and remain on-chain. #### Algorand (`algorand`) Native scheme is non-HD: a 25-word BIP-39-style mnemonic encodes the -32-byte ed25519 seed directly. Canonical URNs use `dt:root`. Some third-party -wallets layer SLIP-10 at `m/44'/283'/account'/0'/0'`; this is accepted but is -not Algorand-canonical. +32-byte ed25519 seed directly. Canonical URNs are root (no `dt`/`dp`). Some +third-party wallets layer SLIP-10 at `m/44'/283'/account'/0'/0'`; this is +accepted but is not Algorand-canonical. #### TON (`ton`) Native scheme is non-HD: a 24-word TON-specific mnemonic (different word list @@ -488,13 +491,19 @@ A `database/sql` adapter is not currently provided; callers can wrap model. A future `dt:substrate` could be added if needed. - **Algorand** and **TON** native schemes are not hierarchical. Their - canonical URN form uses `dt:root` (no `dp`). HD forms (`m/44'/283'/...` / + canonical URN form is root (no `dt`, no `dp`). HD forms (`m/44'/283'/...` / `m/44'/607'/...`) are wallet-specific layering on top, not protocol-canonical. - **Sui** uses the `purpose` field of the derivation path to encode the signature scheme (44'/54'/74'). This is supported via three distinct derivation types (`bip44`, `bip54`, `bip74`). +- **ZIP-32** (`dt:zip32`) parses, but no network registers it: Zcash is not + a registered network type, and its shielded keys use curves (Jubjub, + Pallas) outside the algorithm catalogue. `ParseURNStrict` therefore + refuses every `zip32` URN with `ErrIncompatible`; only lenient parsing + accepts one. + - **Hardening markers** are accepted in three input forms (`'`, `H`, `h`) but always serialised canonically as `'`. Round-trip `Parse(s).String() == s` therefore holds only for inputs already in diff --git a/hardening_test.go b/hardening_test.go index 5075821..68f8c5f 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -272,3 +272,17 @@ func TestProgrammaticValuesCannotInjectComponents(t *testing.T) { t.Errorf("zero DerivationPath: String() = %q, want urn:mhda:nt:evm:ci:1", got) } } + +// TestZIP32HasNoNetwork pins SPEC §12: zip32 parses leniently, but no +// network registers it, so strict parsing refuses it on every network. +func TestZIP32HasNoNetwork(t *testing.T) { + for nt := range ntIndex { + urn := `urn:mhda:nt:` + nt + `:ci:x:dt:zip32:dp:m/32'/133'/0'` + if _, err := ParseURN(urn); err != nil { + t.Errorf("ParseURN(%q): %v", urn, err) + } + if _, err := ParseURNStrict(urn); !errors.Is(err, ErrIncompatible) { + t.Errorf("ParseURNStrict(%q): got %v, want ErrIncompatible", urn, err) + } + } +} diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt index 7c027ce..ce5a55f 100644 --- a/testdata/urn_conformance.txt +++ b/testdata/urn_conformance.txt @@ -57,3 +57,9 @@ refuse nss invalid_nss nt:evm:ci:1:wi:a?b refuse nss invalid_nss nt:evm:ci:1:x#y:z accept urn urn:mhda:nt:evm:ci:1?=q:dt:bip44 urn:mhda:nt:evm:ci:1 accept urn urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0#frag urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0 + +# Root is the default derivation type and carries no path: an explicit +# dt:root is folded away, so a root address has one canonical form. +accept urn urn:mhda:nt:ton:ci:mainnet:dt:root urn:mhda:nt:ton:ci:mainnet +accept urn urn:mhda:nt:algorand:ci:mainnet:ct:283:dt:root:af:base32 urn:mhda:nt:algorand:ci:mainnet:ct:283:af:base32 +accept urn urn:mhda:nt:evm:ci:1:dt:ROOT urn:mhda:nt:evm:ci:1 From f7362cce0efbae86c57d388bf2aae9fff44a278f Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:34:36 +0300 Subject: [PATCH 09/21] Pin hash digests at the SHA block boundaries The hash tests only checked determinism and digest length. Add reference digests for str() of 55, 56, 63, 64, 119, 120, 128 and 1000 bytes (the NSS is 9 bytes shorter, so it covers 55 too), computed with Python's hashlib. The C++ port, whose SHA-1 and SHA-256 are hand-written, pins the same values, so both implementations must produce the same identifiers across every padding case. --- mhda_test.go | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/mhda_test.go b/mhda_test.go index 737e959..99162f5 100644 --- a/mhda_test.go +++ b/mhda_test.go @@ -1755,6 +1755,57 @@ func TestHashFunctions(t *testing.T) { } } +// TestHashReferenceVectors pins the four digests at the SHA-1/SHA-256 block +// and padding boundaries: str() of 55, 56, 63, 64, 119, 120, 128 and 1000 +// bytes (the NSS is 9 bytes shorter, so it covers 55 too). The values were +// computed with Python's hashlib and are shared with the C++ port, whose +// hashes are hand-written. +func TestHashReferenceVectors(t *testing.T) { + cases := []struct { + size int + hash, hash256, nssHash, nssHash256 string + }{ + {55, "7230ec9cac1176541d5e454a5977547849806ef3", "4bcf74edcd630246d1cb1f03be5dc2deb7cc850270a2d3f279d68166778e2065", + "3c1704aa5f179b7d21a9f726e20473ac2b5786e1", "c85613e0a6562581d353224545cbebc3710ddb496d4b03baddd435fa311b7bbb"}, + {56, "7c08382a5672e118ef014b54c8d1b42e7b6cb90b", "a176aa8ff4ccdcb7b05e3e39440cc40b8b17219910f3081c062045abbf331255", + "8f17a0079072eb355e316ebdbb73aa4328762ff7", "242f19fedc19e36ab9c4378b45922e731269ea04c325b58c4a90d4389ffce482"}, + {63, "6b6034fd2e44f4ad8ea9da946a6915f017966ead", "0be4d717499d1b2a081c60cf64f0c59b5e09a1a0da1e65c497c83e839caef655", + "4b8360e09c0db0f1c423342d03db990ee4795695", "0bd7a04f6ca2b30eca17273961fa78db6f345e654ed80ac78a85d780d73d0267"}, + {64, "c5b9fb4f88ee7f77e14566483838fe03eb5f722a", "be3e95721333ec68988eedb3b6c37c7c48ee30211c3bef96900609e8f1dd3546", + "fba8bdfdfb761ca75bc1a38886a7219cba376adc", "713ea1b363b46219865aded589c56341e7d0e63c9278e7e11ae154f05883d1c5"}, + {119, "91f3a5706cdf32541f6c2d45ea4280399da43847", "d04d2a8a7f6df456cada8d263a746f0d21e4b600ef7bdcea4f6e645c17d94914", + "94285bd9afc8f49eb2059992f3660aee22e76063", "d3398acc7f987d3d3c90acd2e4ef958bd7053a8a88e4b2d51b5774b0fb03cfdc"}, + {120, "8f7e2ab8a8a0c101e299154982f0e262bf43b7d0", "a4ed7ff3b82d6f7fa7a322ca72971a2b1e6474a5d08475599bc965282acb49c7", + "7eb1dc21b8685d3b9dbc9c2cbb9240acc90a2660", "aba04d6e4a96a9f662bb9ac433ba50f2c34d7991aee8cb2787ab91bc4228e88a"}, + {128, "56e36e13d0581067945cd12955e3ce4b21967a48", "b6fb21cc83b07ab98648ec0b1bb04a3d79cd31d231cc07303d24ce73145a46ed", + "c792663db1797615b2433d56b96bf73d859a3e6f", "2c04bb624a604bd96c5b0e4b9e1006bbe898f134b60a40a1ed81d63e03897ea7"}, + {1000, "f3acba196b25a975d6989beef6693337b5987f26", "7d57f53b9e4785b1735151906fd63ccb70547a8a2292986b613cf23db7b0f3d7", + "d16eb7a3991c6ace27d58b3e80e617567cfd242b", "2e7dd698a37e3fb7660b19bcad20b60677bd1e7f01d79870daa09a8a1f7269d8"}, + } + for _, c := range cases { + urn := `urn:mhda:nt:evm:ci:` + strings.Repeat("x", c.size-19) + addr, err := ParseURN(urn) + if err != nil { + t.Fatalf("ParseURN(%d bytes): %v", c.size, err) + } + if got := len(addr.String()); got != c.size { + t.Fatalf("String() is %d bytes, want %d", got, c.size) + } + if got := addr.Hash(); got != c.hash { + t.Errorf("%d bytes: Hash() = %s, want %s", c.size, got, c.hash) + } + if got := addr.Hash256(); got != c.hash256 { + t.Errorf("%d bytes: Hash256() = %s, want %s", c.size, got, c.hash256) + } + if got := addr.NSSHash(); got != c.nssHash { + t.Errorf("%d bytes: NSSHash() = %s, want %s", c.size, got, c.nssHash) + } + if got := addr.NSSHash256(); got != c.nssHash256 { + t.Errorf("%d bytes: NSSHash256() = %s, want %s", c.size, got, c.nssHash256) + } + } +} + // TestSLIP10ProgrammaticConstruction ensures NewDerivationPathFromLevels for // SLIP-10 produces a path that round-trips through a full URN. func TestSLIP10ProgrammaticConstruction(t *testing.T) { From c8c9a90f136030efcb31eb604c00da2aae374875 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 11:36:03 +0300 Subject: [PATCH 10/21] CI: vet, gofmt, race detector and fuzzing The workflow ran plain `go test` on push only. It now also runs on pull requests with read-only permissions, vets and tests ./... on every Go version of the matrix (plus the current stable release), and a check job on stable verifies gofmt, runs the race detector and fuzzes each target for 30 seconds. checkout and setup-go move to v4 and v5. --- .github/workflows/linux.yml | 39 ++++++++++++++++++++++++++++++++----- 1 file changed, 34 insertions(+), 5 deletions(-) diff --git a/.github/workflows/linux.yml b/.github/workflows/linux.yml index 7bd9c98..f71af74 100644 --- a/.github/workflows/linux.yml +++ b/.github/workflows/linux.yml @@ -1,6 +1,9 @@ name: linux -on: [push] +on: [push, pull_request] + +permissions: + contents: read jobs: build: @@ -8,15 +11,41 @@ jobs: runs-on: ubuntu-latest strategy: matrix: - go-version: [ '1.18', '1.20', '1.21' ] + go-version: [ '1.18', '1.20', '1.21', 'stable' ] steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Go ${{ matrix.go-version }} - uses: actions/setup-go@v4 + uses: actions/setup-go@v5 with: go-version: ${{ matrix.go-version }} + cache: false - name: Display Go version run: go version + - name: Vet + run: go vet ./... - name: Test with the Go CLI - run: go test + run: go test ./... + + check: + + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + - name: Setup Go + uses: actions/setup-go@v5 + with: + go-version: stable + cache: false + - name: Formatting + run: | + unformatted="$(gofmt -l .)" + if [ -n "$unformatted" ]; then echo "$unformatted"; exit 1; fi + - name: Race detector + run: go test -race ./... + - name: Fuzz (30s per target) + run: | + for target in FuzzParseURN FuzzParseNSS FuzzDerivationPath; do + go test -run '^$' -fuzz "^${target}\$" -fuzztime=30s . + done From 003936b6ea4e820de5c0feb3065d9e7953328251 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:42:55 +0300 Subject: [PATCH 11/21] Replace the derivation path as a whole, never field by field ParsePath updated the fields of the path in place. Re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (m/32'/133'/1' read back as m/32'/133'/1'/5), a SLIP-10 path kept the coin, account and charge of a BIP-44 path parsed before it, and an error midway left a half-updated path. SetDerivationType changed the type and kept the old path: a bip44 address switched to zip32 serialised as dt:zip32:dp:m/32'/133'/3'/9, a valid URN naming a key nobody gave. ParsePath now parses into a fresh path and replaces the old one only on success. A new derivation type drops the old path; until a path is set, String() of the path is empty, the URN carries dt without dp (so it does not parse) and Validate / MarshalText return ErrInvalidDerivationPath. Address.SetDerivation(dt, dp) sets both at once and changes nothing on error; parseAddress uses it. --- CHANGELOG.md | 13 +++++ SPEC.md | 8 +++ compatibility.go | 3 + derivation_path.go | 21 ++++++- mhda.go | 59 ++++++++++++++----- state_test.go | 137 +++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 226 insertions(+), 15 deletions(-) create mode 100644 state_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index 10b4f33..b60b014 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -84,6 +84,19 @@ of 2^31 or more no longer parses. ### Fixed +- **No stale or mixed derivation state.** `ParsePath` updated the fields + of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level + one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), + a SLIP-10 path kept the coin, account and charge of a BIP-44 path parsed + before it, and an error midway left a half-updated path. + `SetDerivationType` changed the type and kept the old path, so a bip44 + address switched to zip32 serialised as `dt:zip32:dp:m/32'/133'/3'/9`, a + valid URN naming a key nobody gave. `ParsePath` now replaces the whole + path or nothing. A new derivation type drops the old path; until a path + is set the URN carries `dt` without `dp` (and does not parse), and + `Validate` / `MarshalText` return `ErrInvalidDerivationPath`. The new + `Address.SetDerivation(dt, dp)` sets both at once and changes nothing on + error; the URN parser uses it. - **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the CIP-1852 role accept any level index, but the parsed value was truncated to a byte: `m/1852'/1815'/0'/256/0` parsed as role 0, so it named the diff --git a/SPEC.md b/SPEC.md index d239dda..263a1e1 100644 --- a/SPEC.md +++ b/SPEC.md @@ -356,6 +356,14 @@ as if rewritten in long form. ROOT is always accepted regardless of network. +An address built in code can have a derivation type without a path: +`SetDerivationType` with a new type drops the old path, which belongs to the +old scheme. Such an address serialises with `dt` but no `dp`, so its URN does +not parse, and `Validate` / `MarshalText` refuse it with +`ErrInvalidDerivationPath`. `SetDerivation(dt, dp)` sets both at once and +changes nothing unless both are valid. `ParsePath` replaces the whole path, +or leaves it unchanged on error. + ### 6.3 Round-trip semantics The reference implementation guarantees: diff --git a/compatibility.go b/compatibility.go index 1af5cd8..b2d509a 100644 --- a/compatibility.go +++ b/compatibility.go @@ -203,6 +203,9 @@ func (a *Address) Validate() error { if a == nil || a.chain == nil { return ErrUninitializedAddress } + if err := a.checkPathSet(); err != nil { + return err + } compat, ok := networkCompatibility[a.chain.networkType] if !ok { return fmt.Errorf("%w: unknown network type %q", ErrIncompatible, a.chain.networkType) diff --git a/derivation_path.go b/derivation_path.go index 671b298..1a0b65a 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -287,7 +287,21 @@ var ( } ) +// ParsePath replaces the path with the result of parsing path under its +// derivation type. The whole path is replaced, so nothing of a previous path +// survives (a ZIP-32 index, the BIP-44 shortcuts of a path later parsed as +// SLIP-10); on error the path is left unchanged. func (dp *DerivationPath) ParsePath(path string) error { + fresh := DerivationPath{derivationType: dp.derivationType} + if err := fresh.parse(path); err != nil { + return err + } + *dp = fresh + return nil +} + +// parse fills dp, which carries only its derivation type, from path. +func (dp *DerivationPath) parse(path string) error { rx, ok := derivationIndex[dp.derivationType] if !ok { return fmt.Errorf("%w: %q", ErrInvalidDerivationType, dp.derivationType) @@ -539,8 +553,13 @@ func (dp *DerivationPath) Levels() []AddressIndex { // String returns the canonical textual form of the derivation path. // Hardened markers are emitted as `'` regardless of which marker (`'`, `H`, -// `h`) appeared in the input. +// `h`) appeared in the input. A path whose type is set but which has no +// levels yet (none was parsed or constructed) is empty: rendering the zero +// shortcuts would name a path nobody gave. func (dp *DerivationPath) String() string { + if dp.derivationType != ROOT && len(dp.levels) == 0 { + return `` + } switch dp.derivationType { case ROOT: return `` diff --git a/mhda.go b/mhda.go index f95cb64..e12281e 100644 --- a/mhda.go +++ b/mhda.go @@ -82,10 +82,7 @@ func parseAddress(m map[string]string) (MHDA, error) { mhda := &Address{chain: chain} - if err := mhda.SetDerivationType(m[compDerivationType]); err != nil { - return nil, err - } - if err := mhda.SetDerivationPath(m[compDerivationPath]); err != nil { + if err := mhda.SetDerivation(m[compDerivationType], m[compDerivationPath]); err != nil { return nil, err } if err := mhda.SetAddressAlgorithm(m[compAddressAlgorithm]); err != nil { @@ -145,24 +142,42 @@ func (a *Address) Format() Format { return defaultFormat(a.chain.networkType) } +// SetDerivationType sets the derivation type; an empty string means ROOT. +// A type other than the current one drops the current path, which belongs to +// the old scheme: until SetDerivationPath sets a new one the address has no +// path, its URN carries dt without dp, and Validate / MarshalText refuse it. +// Setting the current type again keeps the path. Use SetDerivation to change +// both at once. func (a *Address) SetDerivationType(dt string) error { dt = strings.TrimSpace(dt) dt = strings.ToLower(dt) - if a.path == nil { - a.path = &DerivationPath{} - } - + next := ROOT if dt != `` { if _, ok := derivationIndex[DerivationType(dt)]; !ok { return fmt.Errorf("%w: %q", ErrInvalidDerivationType, dt) } + next = DerivationType(dt) + } - a.path.derivationType = DerivationType(dt) - } else { - a.path.derivationType = ROOT + if a.path == nil || a.path.derivationType != next { + a.path = &DerivationPath{derivationType: next} } + return nil +} +// SetDerivation sets the derivation type and path together, as a parsed URN +// does: both are validated first, and the address changes only if both are +// valid. An empty dt means ROOT, which takes an empty dp. +func (a *Address) SetDerivation(dt, dp string) error { + var scratch Address + if err := scratch.SetDerivationType(dt); err != nil { + return err + } + if err := scratch.SetDerivationPath(dp); err != nil { + return err + } + a.path = scratch.path return nil } @@ -335,12 +350,16 @@ func (a *Address) NSS() string { _, _ = fmt.Fprintf(&b, ":ct:%d", a.chain.coinType) } - // Derivation domain - present when a type other than ROOT is set. + // Derivation domain - present when a type other than ROOT is set. A type + // set without a path yet is emitted without dp, so the URN fails to parse + // rather than name another key. if a.path != nil && a.path.derivationType != ROOT && a.path.derivationType != "" { b.WriteString(":dt:") b.WriteString(string(a.path.derivationType)) - b.WriteString(":dp:") - b.WriteString(a.path.String()) + if p := a.path.String(); p != "" { + b.WriteString(":dp:") + b.WriteString(p) + } } // Address-format metadata - emitted only when explicitly set. @@ -410,9 +429,21 @@ func (a *Address) MarshalText() ([]byte, error) { if a == nil || a.chain == nil { return nil, ErrUninitializedAddress } + if err := a.checkPathSet(); err != nil { + return nil, err + } return []byte(a.String()), nil } +// checkPathSet reports a derivation type set without a path (see +// SetDerivationType): such an address serialises to a URN that does not parse. +func (a *Address) checkPathSet() error { + if a.path != nil && a.path.derivationType != ROOT && a.path.derivationType != "" && len(a.path.levels) == 0 { + return fmt.Errorf("%w: derivation type %q is set without a path", ErrInvalidDerivationPath, a.path.derivationType) + } + return nil +} + // UnmarshalText implements encoding.TextUnmarshaler. func (a *Address) UnmarshalText(data []byte) error { parsed, err := ParseURN(string(data)) diff --git a/state_test.go b/state_test.go new file mode 100644 index 0000000..bb326e8 --- /dev/null +++ b/state_test.go @@ -0,0 +1,137 @@ +package go_mhda + +import ( + "errors" + "testing" +) + +// TestReparseLeavesNoStaleState: parsing replaces the whole path, and a +// failed parse leaves it as it was. +func TestReparseLeavesNoStaleState(t *testing.T) { + // ZIP-32: a 3-level path after a 4-level one has no index left over. + dp, err := ParseDerivationPath(ZIP32, "m/32'/133'/0'/5") + if err != nil { + t.Fatal(err) + } + if err := dp.ParsePath("m/32'/133'/1'"); err != nil { + t.Fatal(err) + } + if got := dp.String(); got != "m/32'/133'/1'" { + t.Errorf("ZIP-32 re-parse: String() = %q, want m/32'/133'/1'", got) + } + if n := len(dp.Levels()); n != 3 { + t.Errorf("ZIP-32 re-parse: %d levels, want 3", n) + } + if dp.AddressIndex() != (AddressIndex{}) { + t.Errorf("ZIP-32 re-parse kept index %+v", dp.AddressIndex()) + } + + // SLIP-10 after BIP-44: no BIP-44 shortcut survives. + sl, err := ParseDerivationPath(BIP44, "m/44'/60'/5'/1/9") + if err != nil { + t.Fatal(err) + } + sl.derivationType = SLIP10 + if err := sl.ParsePath("m/0'"); err != nil { + t.Fatal(err) + } + if sl.Coin() != 0 || sl.Account() != 0 || sl.Charge() != 0 || sl.AddressIndex() != (AddressIndex{}) { + t.Errorf("SLIP-10 re-parse kept shortcuts: coin=%d account=%d charge=%d index=%+v", + sl.Coin(), sl.Account(), sl.Charge(), sl.AddressIndex()) + } + + // A failed parse changes nothing. + keep, err := ParseDerivationPath(BIP44, "m/44'/60'/3'/1/9") + if err != nil { + t.Fatal(err) + } + if err := keep.ParsePath("m/44'/60'/4'/0/2147483648"); !errors.Is(err, ErrInvalidDerivationPath) { + t.Fatalf("ParsePath: got %v, want ErrInvalidDerivationPath", err) + } + if got := keep.String(); got != "m/44'/60'/3'/1/9" || keep.Account() != 3 { + t.Errorf("failed ParsePath changed the path: %q account=%d", got, keep.Account()) + } +} + +func mustAddress(t *testing.T, urn string) *Address { + t.Helper() + a, err := ParseURN(urn) + if err != nil { + t.Fatalf("ParseURN(%q): %v", urn, err) + } + return a.(*Address) +} + +// TestDerivationTypeChangeDropsPath: a new derivation type invalidates the +// old path. Until a path is set the address names no path at all: its URN +// carries dt without dp (and so does not parse), and Validate / MarshalText +// refuse it, instead of serialising some other path under the new type. +func TestDerivationTypeChangeDropsPath(t *testing.T) { + const bip44 = `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/3'/1/9` + + a := mustAddress(t, bip44) + if err := a.SetDerivationType("zip32"); err != nil { + t.Fatal(err) + } + if got := a.String(); got != `urn:mhda:nt:evm:ci:1:dt:zip32` { + t.Errorf("after a type change: String() = %q, want urn:mhda:nt:evm:ci:1:dt:zip32", got) + } + if len(a.DerivationPath().Levels()) != 0 { + t.Errorf("after a type change: levels %v survive", a.DerivationPath().Levels()) + } + if err := a.Validate(); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("Validate without a path: got %v, want ErrInvalidDerivationPath", err) + } + if _, err := a.MarshalText(); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("MarshalText without a path: got %v, want ErrInvalidDerivationPath", err) + } + if _, err := ParseURN(a.String()); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("re-parse of %q: got %v, want ErrInvalidDerivationPath", a.String(), err) + } + if err := a.SetDerivationPath("m/32'/133'/7'"); err != nil { + t.Fatal(err) + } + if got := a.String(); got != `urn:mhda:nt:evm:ci:1:dt:zip32:dp:m/32'/133'/7'` { + t.Errorf("String() = %q", got) + } + + // The same type, in any spelling, keeps the path. + b := mustAddress(t, bip44) + if err := b.SetDerivationType(" BIP44 "); err != nil { + t.Fatal(err) + } + if got := b.String(); got != bip44 { + t.Errorf("same type: String() = %q, want %q", got, bip44) + } +} + +// TestSetDerivationIsAtomic: SetDerivation validates the type and the path +// before changing anything. +func TestSetDerivationIsAtomic(t *testing.T) { + const bip44 = `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/3'/1/9` + a := mustAddress(t, bip44) + if err := a.SetDerivation("slip10", "garbage"); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("SetDerivation(slip10, garbage): got %v, want ErrInvalidDerivationPath", err) + } + if err := a.SetDerivation("bogus", "m/0'"); !errors.Is(err, ErrInvalidDerivationType) { + t.Errorf("SetDerivation(bogus): got %v, want ErrInvalidDerivationType", err) + } + if got := a.String(); got != bip44 { + t.Errorf("failed SetDerivation changed the address: %q", got) + } + if err := a.SetDerivation("slip10", "m/0'/1'"); err != nil { + t.Fatal(err) + } + if got := a.String(); got != `urn:mhda:nt:evm:ci:1:dt:slip10:dp:m/0'/1'` { + t.Errorf("String() = %q", got) + } + if a.DerivationPath().Account() != 0 { + t.Errorf("SLIP-10 path kept the BIP-44 account %d", a.DerivationPath().Account()) + } + if err := a.SetDerivation("", ""); err != nil { + t.Fatal(err) + } + if got := a.String(); got != `urn:mhda:nt:evm:ci:1` { + t.Errorf("root: String() = %q", got) + } +} From c1a286bab295d165c7e793357da0fa1113098545 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:45:14 +0300 Subject: [PATCH 12/21] Keep Levels() and String() of a path in agreement NewDerivationPathFromLevels kept the levels it was given while String() printed the type's template: a BIP-44 path built from 49'/60'/0/0/0 printed m/44'/60'/0'/0/0 but returned purpose 49' and an unhardened account from Levels(), which is what a wallet derives from. Too few levels or an index of 2^31 gave a URN that does not parse, and NewDerivationPath accepted a charge of 7 or an account of 2^31. Both constructors now return the path the parser gives back for their own String() and panic with ErrInvalidDerivationPath unless it has exactly the requested levels. Levels() returns a copy instead of the internal slice, and NewAddress keeps its own copies of the chain and the path, so addresses built from one path no longer change together. The fuzz targets check that a re-parsed path has the same levels. --- CHANGELOG.md | 11 +++++ SPEC.md | 8 ++++ chain.go | 9 ++++ derivation_path.go | 39 +++++++++++++++-- fuzz_test.go | 10 +++++ mhda.go | 5 ++- state_test.go | 107 +++++++++++++++++++++++++++++++++++++++++++++ 7 files changed, 184 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b60b014..e98cc6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -97,6 +97,17 @@ of 2^31 or more no longer parses. `Validate` / `MarshalText` return `ErrInvalidDerivationPath`. The new `Address.SetDerivation(dt, dp)` sets both at once and changes nothing on error; the URN parser uses it. +- **`Levels()` and `String()` cannot disagree.** `NewDerivationPathFromLevels` + kept any levels it was given while `String()` printed the type's + template: a BIP-44 path built from `49'/60'/0/0/0` printed + `m/44'/60'/0'/0/0` but returned purpose 49' and an unhardened account from + `Levels()`, and too few levels or an index of 2^31 produced a URN that + does not parse. Both constructors now return exactly the path the parser + gives back for `String()`, and panic with `ErrInvalidDerivationPath` + otherwise. `Levels()` returned the internal slice, so a caller that + changed it changed the path; it returns a copy. `NewAddress` stored the + caller's chain and path, so two addresses built from them changed + together; it keeps copies. - **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the CIP-1852 role accept any level index, but the parsed value was truncated to a byte: `m/1852'/1815'/0'/256/0` parsed as role 0, so it named the diff --git a/SPEC.md b/SPEC.md index 263a1e1..9c89240 100644 --- a/SPEC.md +++ b/SPEC.md @@ -290,6 +290,14 @@ Regardless of derivation type, the canonical level-by-level view is exposed via `DerivationPath.Levels()`. For BIP-family schemes the BIP-44 shortcut fields (`Coin`, `Account`, `Charge`, `AddressIndex`) are also populated. +`Levels()` and `String()` always describe the same path. A path built in code +(`NewDerivationPath`, `NewDerivationPathFromLevels`) must be one the parser +would produce from its own `String()`: levels that do not fit the type (a +BIP-44 path with purpose `49'`, an unhardened account, too few levels, a +SLIP-10 path with none) or an index of 2^31 or more panic with +`ErrInvalidDerivationPath`. `Levels()` returns a copy, and `NewAddress` keeps +its own copies of the chain and the path it is given. + ## 4. Algorithms | `aa` | Notes | diff --git a/chain.go b/chain.go index dcbdecd..44894a2 100644 --- a/chain.go +++ b/chain.go @@ -151,6 +151,15 @@ func parseCoinType(s string) (CoinType, error) { return CoinType(v), nil } +// clone returns a copy of c. +func (c *Chain) clone() *Chain { + if c == nil { + return nil + } + cp := *c + return &cp +} + // SetNetworkType sets the network type. It must be one of the registered // constants (ErrInvalidNetworkType); on error the chain is left unchanged. func (c *Chain) SetNetworkType(networkType NetworkType) error { diff --git a/derivation_path.go b/derivation_path.go index 1a0b65a..a266e70 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -113,7 +113,7 @@ func NewDerivationPath(derivationType DerivationType, coin CoinType, account Acc hasIndex: derivationType != ROOT, } dp.rebuildLevels() - return dp + return reparsed(dp, dp.levels) } // NewDerivationPathFromLevels constructs a path from an explicit sequence of @@ -135,7 +135,38 @@ func NewDerivationPathFromLevels(derivationType DerivationType, levels []Address levels: cp, } dp.populateShortcutsFromLevels() - return dp + return reparsed(dp, cp) +} + +// reparsed returns the path parsed back from dp.String() and panics with +// ErrInvalidDerivationPath unless it has exactly the given levels. A +// constructed path is then identical to a parsed one: its URN parses, and +// Levels() never disagrees with String() (a BIP-44 path given purpose 49', an +// unhardened account, too few levels or an index of 2^31 is refused). +func reparsed(dp *DerivationPath, levels []AddressIndex) *DerivationPath { + out := &DerivationPath{derivationType: dp.derivationType} + if err := out.parse(dp.String()); err != nil { + panic(err) + } + if len(out.levels) != len(levels) { + panic(fmt.Errorf("%w: levels %v do not form a %s path", ErrInvalidDerivationPath, levels, dp.derivationType)) + } + for i := range levels { + if out.levels[i] != levels[i] { + panic(fmt.Errorf("%w: levels %v do not form a %s path", ErrInvalidDerivationPath, levels, dp.derivationType)) + } + } + return out +} + +// clone returns a copy that shares no memory with dp. +func (dp *DerivationPath) clone() *DerivationPath { + if dp == nil { + return nil + } + c := *dp + c.levels = append([]AddressIndex(nil), dp.levels...) + return &c } // populateShortcutsFromLevels fills the BIP-44-style shortcut fields from @@ -546,9 +577,9 @@ func (dp *DerivationPath) rebuildLevels() { } // Levels returns the canonical level-by-level view of the derivation path. -// Empty for ROOT. +// Empty for ROOT. The slice is a copy: changing it does not change the path. func (dp *DerivationPath) Levels() []AddressIndex { - return dp.levels + return append([]AddressIndex(nil), dp.levels...) } // String returns the canonical textual form of the derivation path. diff --git a/fuzz_test.go b/fuzz_test.go index a867091..1a880e3 100644 --- a/fuzz_test.go +++ b/fuzz_test.go @@ -58,6 +58,11 @@ func FuzzParseURN(f *testing.F) { if again.String() != serialized { t.Fatalf("not idempotent:\n once: %s\n twice: %s\n input: %q", serialized, again.String(), src) } + // The levels a wallet derives from must survive the round trip. + if !samePath(addr.DerivationPath(), again.DerivationPath()) { + t.Fatalf("path changed on re-parse: %v -> %v (input: %q)", + addr.DerivationPath().Levels(), again.DerivationPath().Levels(), src) + } }) } @@ -126,6 +131,11 @@ func FuzzDerivationPath(f *testing.F) { serialized, dp2.String(), dt, path) } + // String() and Levels() describe the same path. + if !samePath(dp, dp2) { + t.Fatalf("path changed on re-parse: %v -> %v (input: dt=%q path=%q)", dp.Levels(), dp2.Levels(), dt, path) + } + // No accepted level may carry an index of 2^31 or more. for i, lvl := range dp.Levels() { if lvl.Index > 1<<31-1 { diff --git a/mhda.go b/mhda.go index e12281e..1f6a8b6 100644 --- a/mhda.go +++ b/mhda.go @@ -54,8 +54,11 @@ type Address struct { // exactly like parsed input; an invalid value panics (programmer error at a // construction site — mirroring the NewDerivationPath precedent). The parse // entry points never panic. +// +// The address keeps its own copies of chain and path: changing them later, +// or another address built from them, does not change this one. func NewAddress(chain *Chain, path *DerivationPath, params ...string) *Address { - a := &Address{chain: chain, path: path} + a := &Address{chain: chain.clone(), path: path.clone()} get := func(i int) string { if i < len(params) { return params[i] diff --git a/state_test.go b/state_test.go index bb326e8..531e28c 100644 --- a/state_test.go +++ b/state_test.go @@ -135,3 +135,110 @@ func TestSetDerivationIsAtomic(t *testing.T) { t.Errorf("root: String() = %q", got) } } + +// TestConstructorsMakeParseablePaths: a constructed path is exactly what +// parsing its String() gives back, so Levels() and the URN cannot disagree. +// Anything else panics with ErrInvalidDerivationPath. +func TestConstructorsMakeParseablePaths(t *testing.T) { + for name, f := range map[string]func(){ + "bip44 purpose 49": func() { + NewDerivationPathFromLevels(BIP44, []AddressIndex{{49, true}, {60, true}, {0, true}, {0, false}, {0, false}}) + }, + "bip44 soft account": func() { + NewDerivationPathFromLevels(BIP44, []AddressIndex{{44, true}, {60, true}, {0, false}, {0, false}, {0, false}}) + }, + "bip44 two levels": func() { NewDerivationPathFromLevels(BIP44, []AddressIndex{{44, true}, {60, true}}) }, + "slip10 no levels": func() { NewDerivationPathFromLevels(SLIP10, nil) }, + "slip10 index 2^31": func() { NewDerivationPathFromLevels(SLIP10, []AddressIndex{{1 << 31, false}}) }, + "root with a level": func() { NewDerivationPathFromLevels(ROOT, []AddressIndex{{0, true}}) }, + "bip44 account 2^31": func() { NewDerivationPath(BIP44, 60, 1<<31, 0, AddressIndex{}) }, + "bip44 charge 7": func() { NewDerivationPath(BIP44, 60, 0, 7, AddressIndex{}) }, + "bip32 index 4294967295": func() { NewDerivationPath(BIP32, 0, 0, 0, AddressIndex{Index: 4294967295}) }, + } { + if err := panicErr(t, f); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("%s: panic %v, want ErrInvalidDerivationPath", name, err) + } + } + + dp := NewDerivationPathFromLevels(BIP44, []AddressIndex{{44, true}, {60, true}, {0, true}, {0, false}, {5, false}}) + if got := dp.String(); got != "m/44'/60'/0'/0/5" { + t.Errorf("String() = %q", got) + } + parsed, err := ParseDerivationPath(BIP44, "m/44'/60'/0'/0/5") + if err != nil { + t.Fatal(err) + } + if !samePath(dp, parsed) { + t.Errorf("constructed path %+v differs from the parsed one %+v", *dp, *parsed) + } + // BIP-32 has no coin level: the constructor drops the coin like the parser. + if c := NewDerivationPath(BIP32, 60, 0, 0, AddressIndex{}).Coin(); c != 0 { + t.Errorf("BIP-32 path keeps coin %d", c) + } +} + +// TestLevelsReturnsACopy: the caller cannot change a path through Levels(). +func TestLevelsReturnsACopy(t *testing.T) { + for dt, p := range map[DerivationType]string{SLIP10: "m/44'/501'/0'/0'", BIP44: "m/44'/60'/0'/0/0"} { + dp, err := ParseDerivationPath(dt, p) + if err != nil { + t.Fatal(err) + } + lv := dp.Levels() + lv[2].Index = 9 + lv[2].IsHardened = false + if got := dp.String(); got != p { + t.Errorf("%s: String() = %q after changing a copy", dt, got) + } + if got := dp.Levels()[2]; got != (AddressIndex{Index: 0, IsHardened: true}) { + t.Errorf("%s: Levels()[2] = %+v after changing a copy", dt, got) + } + } +} + +// TestNewAddressCopiesChainAndPath: two addresses built from one chain and +// one path are independent of each other and of the originals. +func TestNewAddressCopiesChainAndPath(t *testing.T) { + p, err := ParseDerivationPath(BIP44, "m/44'/60'/0'/0/0") + if err != nil { + t.Fatal(err) + } + c := NewChain(EthereumVM, "1") + x := NewAddress(c, p) + y := NewAddress(c, p) + if err := x.SetDerivationPath("m/44'/60'/0'/0/9"); err != nil { + t.Fatal(err) + } + if err := x.SetCoinType("60"); err != nil { + t.Fatal(err) + } + if err := c.SetChainId("56"); err != nil { + t.Fatal(err) + } + const want = `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0` + if got := y.String(); got != want { + t.Errorf("y changed with x or c: %q, want %q", got, want) + } + if got := p.String(); got != "m/44'/60'/0'/0/0" { + t.Errorf("the original path changed: %q", got) + } + if got := x.String(); got != `urn:mhda:nt:evm:ci:1:ct:60:dt:bip44:dp:m/44'/60'/0'/0/9` { + t.Errorf("x: %q", got) + } +} + +// samePath compares two paths through their public view. +func samePath(a, b *DerivationPath) bool { + la, lb := a.Levels(), b.Levels() + if len(la) != len(lb) { + return false + } + for i := range la { + if la[i] != lb[i] { + return false + } + } + return a.DerivationType() == b.DerivationType() && a.String() == b.String() && + a.Coin() == b.Coin() && a.Account() == b.Account() && a.Charge() == b.Charge() && + a.AddressIndex() == b.AddressIndex() +} From 893d86cd9ad58f945e59111346335886dc7e1cb0 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:47:39 +0300 Subject: [PATCH 13/21] Refuse underivable curve, purpose and format pairs in strict mode Validate checked the algorithm, the format and the derivation type each against the network on its own. It accepted SLIP-10 ed25519 paths with soft levels (ed25519 has no soft derivation), bip44 with ed25519 on XRPL, NEAR and Aptos, Sui bip54 with ed25519 or secp256r1 (the purpose encodes the scheme), a Bitcoin bip84 path with af:p2pkh, and Cosmos bip44 with coin 118', which is the cip11 path under a second name. Validate now also refuses, with ErrIncompatible: an ed25519 path with an unhardened level, except cip1852 (BIP32-Ed25519); a derivation type with another curve than its own where the network binds them (Sui: slip10 ed25519, bip54 secp256k1, bip74 secp256r1; Aptos and NEAR: slip10 ed25519, bip44 secp256k1); an explicit Bitcoin format that does not match the purpose; and Cosmos bip44 with coin 118'. A Bitcoin URN without af stays valid, and SPEC.md no longer says strict mode needs it. The shared URN table gains strict rows for each rule. Tests that pinned now-refused pairs move to matching purposes (p2sh under bip49, p2wsh under bip32), and the XRPL ed25519 example becomes the root form its family-seed keys have. --- CHANGELOG.md | 17 +++++++++ SPEC.md | 36 +++++++++++++++--- compatibility.go | 70 +++++++++++++++++++++++++++++++---- mhda_test.go | 13 ++++--- testdata/urn_conformance.txt | 71 +++++++++++++++++++++++++++++++++--- urn_conformance_test.go | 8 +++- 6 files changed, 189 insertions(+), 26 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e98cc6a..6a46809 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -82,6 +82,23 @@ of 2^31 or more no longer parses. parses, but no network registers it, so strict parsing refuses it. Both behaviours are unchanged and now pinned by tests. +- **Strict validation refuses curve, purpose and format combinations no + wallet can derive.** It checked the algorithm, the format and the + derivation type each on its own, so it accepted SLIP-10 ed25519 paths + with soft levels (`nt:solana:...:dp:m/44'/501'/0/0`; ed25519 has no soft + derivation), `bip44` with ed25519 on XRPL, NEAR and Aptos, Sui `bip54` + with ed25519 or secp256r1, a Bitcoin `bip84` path with `af:p2pkh`, and + Cosmos `bip44` with coin `118'`, which is the `cip11` path again. + `ParseURNStrict` / `Validate` now return `ErrIncompatible` for: an + ed25519 path with an unhardened level (except `cip1852`, which is + BIP32-Ed25519); a derivation type with another curve than its own on Sui + (`slip10` ed25519, `bip54` secp256k1, `bip74` secp256r1), Aptos and NEAR + (`slip10` ed25519, `bip44` secp256k1); an explicit Bitcoin format that + does not match the purpose (`bip44` p2pkh, `bip49` p2sh, `bip84` p2wpkh + or bech32, `bip86` p2tr or bech32m); and Cosmos `bip44` with coin + `118'`. A Bitcoin URN without `af` stays valid; SPEC.md no longer claims + strict mode requires it. Lenient parsing is unchanged. + ### Fixed - **No stale or mixed derivation state.** `ParsePath` updated the fields diff --git a/SPEC.md b/SPEC.md index 9c89240..80717cc 100644 --- a/SPEC.md +++ b/SPEC.md @@ -164,9 +164,11 @@ keeps the family name rather than any flagship chain's name. ### 2.1 Per-network notes #### Bitcoin (`bitcoin`) -Multiple legitimate scripts; format must be specified explicitly under strict -validation. `ap` is conventionally `1` (P2PKH), `3` (P2SH), `bc1q` (bech32), -`bc1p` (bech32m / Taproot). +Multiple legitimate scripts, so there is no default format and `af` may be +omitted. When given, it must match the script the purpose defines, under +strict validation: `bip44` p2pkh, `bip49` p2sh, `bip84` p2wpkh or bech32, +`bip86` p2tr or bech32m; `bip32` takes any. `ap` is conventionally `1` +(P2PKH), `3` (P2SH), `bc1q` (bech32), `bc1p` (bech32m / Taproot). #### Ethereum and EVM clones (`evm`) Single canonical format (hex). Chain ID typically a numeric chain ID such as @@ -179,6 +181,8 @@ C-Chain uses hex (EVM-compatible); X/P-Chain use bech32 with HRPs `X-avax`, #### Cosmos (`cosmos`) Cosmos chains traditionally use BIP-44 with coin type 118; some deployments register their own SLIP-44 entries. CIP-11 is `m/44'/118'/account'/charge_extra/address`. +`bip44` with coin `118'` is the same path as `cip11`, so strict validation +refuses it and keeps the `cip11` spelling; `bip44` with another coin stays. #### Solana (`solana`) SLIP-10 ed25519 only. Common path forms: `m/44'/501'`, `m/44'/501'/account'`, @@ -186,7 +190,9 @@ SLIP-10 ed25519 only. Common path forms: `m/44'/501'`, `m/44'/501'/account'`, #### XRP Ledger (`xrpl`) secp256k1 is the historical default; ed25519 is supported by newer wallets. -Addresses use base58 with XRPL's custom alphabet (start with `r`). +XRPL ed25519 keys come from a family seed, not an HD path, so their URN is +root (`aa:ed25519`, no `dt`); `bip44` with ed25519 fails strict validation +(see §6.2). Addresses use base58 with XRPL's custom alphabet (start with `r`). #### Stellar (`stellar`) SEP-0005 mandates SLIP-10 ed25519 with `m/44'/148'/account'` (3 levels, all @@ -197,11 +203,14 @@ SEP-0023. Common version bytes: `G` (account), `S` (seed), `M` (muxed), #### NEAR (`near`) ed25519-implicit accounts use raw 64-char hex of pubkey. ETH-implicit accounts use `0x` + 40 hex from secp256k1 + keccak256. Named accounts (`alice.near`) -are not HD-derived and not represented by MHDA. +are not HD-derived and not represented by MHDA. ed25519 keys derive through +`slip10`, secp256k1 keys through `bip44`; strict validation holds each +derivation type to its curve. #### Aptos (`aptos`) ed25519 path `m/44'/637'/account'/change'/index'` (all 5 hardened, enforced by aptos-ts-sdk). secp256k1 path `m/44'/637'/account'/change/index` (BIP-44). +Strict validation holds `slip10` to ed25519 and `bip44` to secp256k1. #### Sui (`sui`) The signature scheme is encoded in the `purpose` field of the path: @@ -213,7 +222,9 @@ secp256r1: m/74'/784'/account'/change/index (BIP-32, purpose=74') ``` Address = Blake2b-256(flag || pubkey), 0x + 64 hex chars. Flag bytes: -0x00 ed25519, 0x01 secp256k1, 0x02 secp256r1. +0x00 ed25519, 0x01 secp256k1, 0x02 secp256r1. Strict validation holds each +derivation type to its scheme: `slip10` ed25519, `bip54` secp256k1, `bip74` +secp256r1. #### Cardano (`cardano`) BIP32-Ed25519 (extended keys with soft-derivation, distinct from SLIP-10 @@ -364,6 +375,19 @@ as if rewritten in long form. ROOT is always accepted regardless of network. +Strict validation also refuses combinations no wallet can derive or that +name one key twice: + +- ed25519 with any unhardened level, except under `cip1852`: SLIP-10 + derives ed25519 keys through hardened levels only (CIP-1852 is + BIP32-Ed25519, which has soft derivation). +- A derivation type with a curve other than its own where the network binds + them (Sui, Aptos, NEAR; see §2.1). +- A Bitcoin format that does not match the purpose of the path (§2.1). +- A Cosmos `bip44` path with coin `118'`, which is the `cip11` path. + +These fail with `ErrIncompatible`; lenient parsing still accepts the paths. + An address built in code can have a derivation type without a path: `SetDerivationType` with a new type drops the old path, which belongs to the old scheme. Such an address serialises with `dt` but no `dp`, so its URN does diff --git a/compatibility.go b/compatibility.go index b2d509a..e3f6b25 100644 --- a/compatibility.go +++ b/compatibility.go @@ -15,8 +15,9 @@ var ErrIncompatible = errors.New("mhda: incompatible network/algorithm/format") // defaults to apply when the URN omits the optional aa/af components. // // "format zero-value" (empty Format) is allowed for networks that have many -// reasonable choices (e.g. Bitcoin: legacy, segwit, taproot) - in that case -// the URN must spell the format out explicitly to use Strict mode. +// reasonable choices (e.g. Bitcoin: legacy, segwit, taproot); a URN for one +// of them may omit af, and an af it spells out must match the purpose +// (derivationFormats). // // ROOT is implicitly accepted for every registered network; it represents // the non-HD form (no derivation path) and is always structurally valid. @@ -26,6 +27,12 @@ type networkCompat struct { derivations map[DerivationType]struct{} defaultAlgorithm Algorithm defaultFormat Format + // derivationAlgorithm binds a derivation type to the one algorithm it + // derives on this network; unbound types take any listed algorithm. + derivationAlgorithm map[DerivationType]Algorithm + // derivationFormats binds a derivation type to the formats its purpose + // defines, checked when a format is resolved; unbound types take any. + derivationFormats map[DerivationType]map[Format]struct{} } var networkCompatibility = map[NetworkType]networkCompat{ @@ -34,7 +41,14 @@ var networkCompatibility = map[NetworkType]networkCompat{ formats: set(P2PKH, P2SH, P2WPKH, P2WSH, P2TR, Bech32, Bech32m), derivations: set(BIP32, BIP44, BIP49, BIP84, BIP86), defaultAlgorithm: Secp256k1, - // no default format: BTC has multiple legitimate scripts + // no default format: BTC has multiple legitimate scripts. The + // purpose defines the script, so an explicit format must match it. + derivationFormats: map[DerivationType]map[Format]struct{}{ + BIP44: set(P2PKH), + BIP49: set(P2SH), + BIP84: set(P2WPKH, Bech32), + BIP86: set(P2TR, Bech32m), + }, }, EthereumVM: { algorithms: set(Secp256k1), @@ -101,6 +115,10 @@ var networkCompatibility = map[NetworkType]networkCompat{ derivations: set(SLIP10, BIP44), defaultAlgorithm: Ed25519, defaultFormat: HEX, + derivationAlgorithm: map[DerivationType]Algorithm{ + SLIP10: Ed25519, + BIP44: Secp256k1, + }, }, // Aptos. The Aptos TS SDK enforces two distinct path shapes: // ed25519: m/44'/637'/account'/change'/index' (all 5 hardened) @@ -113,6 +131,10 @@ var networkCompatibility = map[NetworkType]networkCompat{ derivations: set(SLIP10, BIP44), defaultAlgorithm: Ed25519, defaultFormat: HEX, + derivationAlgorithm: map[DerivationType]Algorithm{ + SLIP10: Ed25519, + BIP44: Secp256k1, + }, }, // Sui. Three signature schemes, distinguished by the purpose field of // the derivation path (sui-keys/src/key_derive.rs): @@ -127,6 +149,11 @@ var networkCompatibility = map[NetworkType]networkCompat{ derivations: set(SLIP10, BIP54, BIP74), defaultAlgorithm: Ed25519, defaultFormat: HEX, + derivationAlgorithm: map[DerivationType]Algorithm{ + SLIP10: Ed25519, + BIP54: Secp256k1, + BIP74: Secp256r1, + }, }, // Cardano (ADA). Single-curve protocol using BIP32-Ed25519 (extended // keys, soft derivation supported - distinct from SLIP-10 ed25519). @@ -229,12 +256,41 @@ func (a *Address) Validate() error { // ROOT (no derivation path) is always permitted; it represents the non-HD // form. Any other derivation type must be in the per-network whitelist. - if a.path != nil && a.path.derivationType != ROOT { - if _, ok := compat.derivations[a.path.derivationType]; !ok { - return fmt.Errorf("%w: derivation %q not allowed for network %q", - ErrIncompatible, a.path.derivationType, a.chain.networkType) + if a.path == nil || a.path.derivationType == ROOT || a.path.derivationType == "" { + return nil + } + dt := a.path.derivationType + if _, ok := compat.derivations[dt]; !ok { + return fmt.Errorf("%w: derivation %q not allowed for network %q", + ErrIncompatible, dt, a.chain.networkType) + } + if want, ok := compat.derivationAlgorithm[dt]; ok && algo != want { + return fmt.Errorf("%w: derivation %q derives %q keys on network %q, not %q", + ErrIncompatible, dt, want, a.chain.networkType, algo) + } + if formats, ok := compat.derivationFormats[dt]; ok { + if format := a.Format(); format != "" { + if _, ok := formats[format]; !ok { + return fmt.Errorf("%w: format %q does not match the purpose of derivation %q on network %q", + ErrIncompatible, format, dt, a.chain.networkType) + } } } + // SLIP-10 derives ed25519 keys through hardened levels only; CIP-1852 + // (BIP32-Ed25519) is the one ed25519 scheme with soft derivation. + if algo == Ed25519 && dt != CIP1852 { + for i, lvl := range a.path.levels { + if !lvl.IsHardened { + return fmt.Errorf("%w: ed25519 derives hardened levels only, level %d of %q is not hardened", + ErrIncompatible, i, a.path.String()) + } + } + } + // On Cosmos, bip44 with coin 118' is the cip11 path under another name; + // strict mode keeps the one spelling. + if a.chain.networkType == Cosmos && dt == BIP44 && a.path.coin == ATOM { + return fmt.Errorf("%w: %q with coin 118' is the cip11 path, use dt:cip11", ErrIncompatible, dt) + } return nil } diff --git a/mhda_test.go b/mhda_test.go index 99162f5..f102b48 100644 --- a/mhda_test.go +++ b/mhda_test.go @@ -180,9 +180,10 @@ func TestStrictPreservesLenient(t *testing.T) { func TestBitcoinFormats(t *testing.T) { for _, urn := range []string{ `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip44:dp:m/44'/0'/0'/0/0:af:p2pkh`, - `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip44:dp:m/44'/0'/0'/0/0:af:p2sh`, + `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip49:dp:m/49'/0'/0'/0/0:af:p2sh`, `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip84:dp:m/84'/0'/0'/0/0:af:p2wpkh`, - `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip84:dp:m/84'/0'/0'/0/0:af:p2wsh`, + // P2WSH has no single-key purpose (multisig is BIP-48): plain bip32. + `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip32:dp:m/0'/0/0:af:p2wsh`, `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip84:dp:m/84'/0'/0'/0/0:af:bech32`, `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip86:dp:m/86'/0'/0'/0/0:af:p2tr`, `urn:mhda:nt:bitcoin:ci:bitcoin:ct:0:dt:bip86:dp:m/86'/0'/0'/0/0:af:bech32m`, @@ -265,7 +266,7 @@ func TestREADMEExamples(t *testing.T) { `urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0'/0'`, // XRP Ledger `urn:mhda:nt:xrpl:ci:mainnet:dt:bip44:dp:m/44'/144'/0'/0/0`, - `urn:mhda:nt:xrpl:ci:mainnet:ct:144:dt:bip44:dp:m/44'/144'/0'/0/0:aa:ed25519`, + `urn:mhda:nt:xrpl:ci:mainnet:ct:144:aa:ed25519`, // Stellar `urn:mhda:nt:stellar:ci:mainnet:dt:slip10:dp:m/44'/148'/0'`, // NEAR @@ -771,8 +772,8 @@ func TestXRP(t *testing.T) { `urn:mhda:nt:xrpl:ci:mainnet:ct:144:dt:bip44:dp:m/44'/144'/0'/0/0`, // long form with explicit defaults `urn:mhda:nt:xrpl:ci:mainnet:ct:144:dt:bip44:dp:m/44'/144'/0'/0/0:aa:secp256k1:af:base58`, - // ed25519 variant (XLS-10 / XUMM-style) - `urn:mhda:nt:xrpl:ci:mainnet:ct:144:dt:bip44:dp:m/44'/144'/0'/0/0:aa:ed25519:af:base58`, + // ed25519 keys come from a family seed, not an HD path: root form + `urn:mhda:nt:xrpl:ci:mainnet:ct:144:aa:ed25519:af:base58`, } { addr, err := ParseURNStrict(urn) if err != nil { @@ -803,6 +804,8 @@ func TestXRPRejectsInvalidCombos(t *testing.T) { bad := []string{ `urn:mhda:nt:xrpl:ci:mainnet:ct:144:aa:sr25519`, // unsupported algo `urn:mhda:nt:xrpl:ci:mainnet:ct:144:af:hex`, // unsupported format + // ed25519 has no soft levels, so it cannot derive this BIP-44 path + `urn:mhda:nt:xrpl:ci:mainnet:ct:144:dt:bip44:dp:m/44'/144'/0'/0/0:aa:ed25519`, } for _, urn := range bad { _, err := ParseURNStrict(urn) diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt index ce5a55f..278aff0 100644 --- a/testdata/urn_conformance.txt +++ b/testdata/urn_conformance.txt @@ -1,17 +1,19 @@ # URN conformance table, shared verbatim by go-mhda # (testdata/urn_conformance.txt) and the C++ port (tests/data/urn_conformance.txt). -# Both test suites run every row through the lenient parser; an input one -# implementation refuses, the other refuses too, with the same error. Edit -# both copies together. +# Both test suites run every row; an input one implementation refuses, the +# other refuses too, with the same error. Edit both copies together. # # Row forms: # accept urn # accept nss +# accept strict # refuse urn # refuse nss -# is the C++ error_code name; go-mhda maps it to its sentinel -# (invalid_nss is ErrInvalidNSS, invalid_derivation_path is -# ErrInvalidDerivationPath, ...). +# refuse strict +# urn rows use the lenient parser, strict rows ParseURNStrict / +# parse_urn_strict. is the C++ error_code name; go-mhda maps it to +# its sentinel (invalid_nss is ErrInvalidNSS, incompatible is +# ErrIncompatible, ...). # A derivation path needs a derivation type other than root. Without dt the # address is root, and a dp there would be dropped: the URN would name the @@ -63,3 +65,60 @@ accept urn urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0#frag urn:mhda:nt:ev accept urn urn:mhda:nt:ton:ci:mainnet:dt:root urn:mhda:nt:ton:ci:mainnet accept urn urn:mhda:nt:algorand:ci:mainnet:ct:283:dt:root:af:base32 urn:mhda:nt:algorand:ci:mainnet:ct:283:af:base32 accept urn urn:mhda:nt:evm:ci:1:dt:ROOT urn:mhda:nt:evm:ci:1 + +# Strict mode and the curves. SLIP-10 derives ed25519 keys through hardened +# levels only, so every level of an ed25519 path must be hardened; cip1852 +# (BIP32-Ed25519) is the one ed25519 scheme with soft levels. The lenient +# parser still accepts these paths. +refuse strict incompatible urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0/0 +refuse strict incompatible urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0'/0'/7 +refuse strict incompatible urn:mhda:nt:stellar:ci:pubnet:dt:slip10:dp:m/44'/148'/0 +refuse strict incompatible urn:mhda:nt:ton:ci:mainnet:dt:slip10:dp:m/44'/607'/0'/0'/0 +refuse strict incompatible urn:mhda:nt:cosmos:ci:secret:dt:bip44:dp:m/44'/529'/0'/0/0:aa:ed25519 +refuse strict incompatible urn:mhda:nt:xrpl:ci:mainnet:dt:bip44:dp:m/44'/144'/0'/0/0:aa:ed25519 +accept urn urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0/0 urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0/0 +accept strict urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0'/0' urn:mhda:nt:solana:ci:mainnet:dt:slip10:dp:m/44'/501'/0'/0' +accept strict urn:mhda:nt:stellar:ci:pubnet:dt:slip10:dp:m/44'/148'/0' urn:mhda:nt:stellar:ci:pubnet:dt:slip10:dp:m/44'/148'/0' +accept strict urn:mhda:nt:ton:ci:mainnet:dt:slip10:dp:m/44'/607'/0' urn:mhda:nt:ton:ci:mainnet:dt:slip10:dp:m/44'/607'/0' +accept strict urn:mhda:nt:cardano:ci:mainnet:dt:cip1852:dp:m/1852'/1815'/0'/0/0 urn:mhda:nt:cardano:ci:mainnet:dt:cip1852:dp:m/1852'/1815'/0'/0/0 +accept strict urn:mhda:nt:xrpl:ci:mainnet:dt:bip44:dp:m/44'/144'/0'/0/0 urn:mhda:nt:xrpl:ci:mainnet:dt:bip44:dp:m/44'/144'/0'/0/0 + +# Sui encodes the signature scheme in the purpose (bip54 secp256k1, bip74 +# secp256r1, slip10 ed25519); Aptos and NEAR derive ed25519 through slip10 +# and secp256k1 through bip44. A derivation type takes only its own curve. +refuse strict incompatible urn:mhda:nt:sui:ci:mainnet:dt:bip54:dp:m/54'/784'/0'/0/0 +refuse strict incompatible urn:mhda:nt:sui:ci:mainnet:dt:bip54:dp:m/54'/784'/0'/0/0:aa:secp256r1 +refuse strict incompatible urn:mhda:nt:sui:ci:mainnet:dt:bip74:dp:m/74'/784'/0'/0/0:aa:secp256k1 +refuse strict incompatible urn:mhda:nt:sui:ci:mainnet:dt:slip10:dp:m/44'/784'/0'/0'/0':aa:secp256k1 +refuse strict incompatible urn:mhda:nt:aptos:ci:mainnet:dt:bip44:dp:m/44'/637'/0'/0/0 +refuse strict incompatible urn:mhda:nt:aptos:ci:mainnet:dt:slip10:dp:m/44'/637'/0'/0'/0':aa:secp256k1 +refuse strict incompatible urn:mhda:nt:near:ci:mainnet:dt:bip44:dp:m/44'/397'/0'/0/0 +accept strict urn:mhda:nt:sui:ci:mainnet:dt:bip54:dp:m/54'/784'/0'/0/0:aa:secp256k1 urn:mhda:nt:sui:ci:mainnet:dt:bip54:dp:m/54'/784'/0'/0/0:aa:secp256k1 +accept strict urn:mhda:nt:sui:ci:mainnet:dt:bip74:dp:m/74'/784'/0'/0/0:aa:secp256r1 urn:mhda:nt:sui:ci:mainnet:dt:bip74:dp:m/74'/784'/0'/0/0:aa:secp256r1 +accept strict urn:mhda:nt:sui:ci:mainnet:dt:slip10:dp:m/44'/784'/0'/0'/0' urn:mhda:nt:sui:ci:mainnet:dt:slip10:dp:m/44'/784'/0'/0'/0' +accept strict urn:mhda:nt:aptos:ci:mainnet:dt:bip44:dp:m/44'/637'/0'/0/0:aa:secp256k1 urn:mhda:nt:aptos:ci:mainnet:dt:bip44:dp:m/44'/637'/0'/0/0:aa:secp256k1 +accept strict urn:mhda:nt:aptos:ci:mainnet:dt:slip10:dp:m/44'/637'/0'/0'/0' urn:mhda:nt:aptos:ci:mainnet:dt:slip10:dp:m/44'/637'/0'/0'/0' +accept strict urn:mhda:nt:near:ci:mainnet:dt:bip44:dp:m/44'/397'/0'/0/1:aa:secp256k1 urn:mhda:nt:near:ci:mainnet:dt:bip44:dp:m/44'/397'/0'/0/1:aa:secp256k1 +accept strict urn:mhda:nt:near:ci:mainnet:dt:slip10:dp:m/44'/397'/0' urn:mhda:nt:near:ci:mainnet:dt:slip10:dp:m/44'/397'/0' + +# Bitcoin: the purpose defines the script, so an explicit af must match it +# (bip44 p2pkh, bip49 p2sh, bip84 p2wpkh or bech32, bip86 p2tr or bech32m; +# bip32 takes any). Without af the URN stays valid. +refuse strict incompatible urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0:af:p2pkh +refuse strict incompatible urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip44:dp:m/44'/0'/0'/0/0:af:p2wpkh +refuse strict incompatible urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip49:dp:m/49'/0'/0'/0/0:af:p2wpkh +refuse strict incompatible urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip86:dp:m/86'/0'/0'/0/0:af:bech32 +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0 urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0 +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0:af:p2wpkh urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0:af:p2wpkh +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0:af:bech32 urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip84:dp:m/84'/0'/0'/0/0:af:bech32 +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip86:dp:m/86'/0'/0'/0/0:af:p2tr urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip86:dp:m/86'/0'/0'/0/0:af:p2tr +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip86:dp:m/86'/0'/0'/0/0:af:bech32m urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip86:dp:m/86'/0'/0'/0/0:af:bech32m +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip49:dp:m/49'/0'/0'/0/0:af:p2sh urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip49:dp:m/49'/0'/0'/0/0:af:p2sh +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip44:dp:m/44'/0'/0'/0/0:af:p2pkh urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip44:dp:m/44'/0'/0'/0/0:af:p2pkh +accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip32:dp:m/0'/0/0:af:p2wpkh urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip32:dp:m/0'/0/0:af:p2wpkh + +# Cosmos: bip44 with coin 118' is the cip11 path m/44'/118'/... (one key, +# two spellings); strict mode keeps cip11. bip44 with another coin stays. +refuse strict incompatible urn:mhda:nt:cosmos:ci:cosmoshub:dt:bip44:dp:m/44'/118'/0'/0/0 +accept strict urn:mhda:nt:cosmos:ci:cosmoshub:dt:cip11:dp:m/44'/118'/0'/0/0 urn:mhda:nt:cosmos:ci:cosmoshub:dt:cip11:dp:m/44'/118'/0'/0/0 +accept strict urn:mhda:nt:cosmos:ci:secret:dt:bip44:dp:m/44'/529'/0'/0/0 urn:mhda:nt:cosmos:ci:secret:dt:bip44:dp:m/44'/529'/0'/0/0 diff --git a/urn_conformance_test.go b/urn_conformance_test.go index bec6430..43c77ae 100644 --- a/urn_conformance_test.go +++ b/urn_conformance_test.go @@ -22,6 +22,7 @@ var conformanceErrors = map[string]error{ "invalid_algorithm": ErrInvalidAlgorithm, "invalid_format": ErrInvalidFormat, "invalid_value": ErrInvalidValue, + "incompatible": ErrIncompatible, } // TestURNConformance runs the URN table shared with the C++ port @@ -43,7 +44,7 @@ func TestURNConformance(t *testing.T) { continue } fields := strings.Fields(text) - if len(fields) != 4 || (fields[1] != "urn" && fields[1] != "nss") { + if len(fields) != 4 || (fields[1] != "urn" && fields[1] != "nss" && fields[1] != "strict") { t.Fatalf("urn_conformance.txt:%d: malformed row %q", line, text) } rows++ @@ -62,8 +63,11 @@ func TestURNConformance(t *testing.T) { } parse := ParseURN - if fields[1] == "nss" { + switch fields[1] { + case "nss": parse = ParseNSS + case "strict": + parse = ParseURNStrict } addr, err := parse(input) if accept { From 340fc9c1664241e2f829238fffb2fb851c254452 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:48:56 +0300 Subject: [PATCH 14/21] Handle a zero Address or one without a chain or path String(), NSS(), the hashes, Algorithm() and Format() dereferenced the chain, so the zero Address or NewAddress(nil, ...) panicked, and SetDerivationPath dereferenced the path, so an address built without one panicked too. A missing chain now reads as the zero chain (urn:mhda:nt::ci:, the C++ port's default address) and a missing path as root; SetCoinType without a chain returns ErrUninitializedAddress. --- CHANGELOG.md | 7 +++++++ mhda.go | 33 +++++++++++++++++++++++++-------- state_test.go | 41 +++++++++++++++++++++++++++++++++++++++++ 3 files changed, 73 insertions(+), 8 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6a46809..fff81ed 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -101,6 +101,13 @@ of 2^31 or more no longer parses. ### Fixed +- **No nil dereference on a zero or partial `Address`.** `String()`, + `NSS()`, the hashes, `Algorithm()` and `Format()` panicked on the zero + `Address` or one built with a nil chain, and `SetDerivationPath` panicked + on an address built without a path. They now treat a missing chain as the + zero chain (`urn:mhda:nt::ci:`, as the C++ port's default address) and a + missing path as root; `SetCoinType` without a chain returns + `ErrUninitializedAddress`. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), diff --git a/mhda.go b/mhda.go index 1f6a8b6..f8e0cec 100644 --- a/mhda.go +++ b/mhda.go @@ -132,7 +132,15 @@ func (a *Address) Algorithm() Algorithm { if a.addressAlgorithm != "" { return a.addressAlgorithm } - return defaultAlgorithm(a.chain.networkType) + return defaultAlgorithm(a.networkType()) +} + +// networkType returns the chain's network type, or "" without a chain. +func (a *Address) networkType() NetworkType { + if a.chain == nil { + return "" + } + return a.chain.networkType } // Format returns the explicitly set address format or, if none was set, the @@ -142,7 +150,7 @@ func (a *Address) Format() Format { if a.addressFormat != "" { return a.addressFormat } - return defaultFormat(a.chain.networkType) + return defaultFormat(a.networkType()) } // SetDerivationType sets the derivation type; an empty string means ROOT. @@ -190,7 +198,7 @@ func (a *Address) SetDerivation(dt, dp string) error { // dp but no dt (which parses as root) name the root key rather than the // path it spells out. func (a *Address) SetDerivationPath(dp string) error { - if a.path.derivationType == ROOT { + if a.path == nil || a.path.derivationType == ROOT { if p := strings.TrimSpace(dp); p != `` { return fmt.Errorf("%w: root derivation must have empty path, got %q", ErrInvalidDerivationPath, p) } @@ -216,8 +224,12 @@ func (a *Address) SetDerivationPath(dp string) error { // SetCoinType sets the optional SLIP-44 coin-type metadata on the address' // chain. Passing an empty string clears it. Accepted spellings are plain -// decimal and 0x-prefixed hex (see parseCoinType). +// decimal and 0x-prefixed hex (see parseCoinType). An address without a +// chain returns ErrUninitializedAddress. func (a *Address) SetCoinType(ct string) error { + if a.chain == nil { + return ErrUninitializedAddress + } ct = strings.TrimSpace(ct) if ct == `` { a.chain.ClearCoinType() @@ -345,12 +357,17 @@ func (a *Address) String() string { func (a *Address) NSS() string { var b strings.Builder - // Chain identity - always present. - _, _ = fmt.Fprintf(&b, "nt:%s:ci:%s", a.chain.networkType, a.chain.chainId) + // Chain identity - always present (empty without a chain, like the zero + // Chain). + chain := a.chain + if chain == nil { + chain = &Chain{} + } + _, _ = fmt.Fprintf(&b, "nt:%s:ci:%s", chain.networkType, chain.chainId) // Coin-type metadata - emitted only when explicitly set. - if a.chain.hasCoinType { - _, _ = fmt.Fprintf(&b, ":ct:%d", a.chain.coinType) + if chain.hasCoinType { + _, _ = fmt.Fprintf(&b, ":ct:%d", chain.coinType) } // Derivation domain - present when a type other than ROOT is set. A type diff --git a/state_test.go b/state_test.go index 531e28c..9dae84e 100644 --- a/state_test.go +++ b/state_test.go @@ -242,3 +242,44 @@ func samePath(a, b *DerivationPath) bool { a.Coin() == b.Coin() && a.Account() == b.Account() && a.Charge() == b.Charge() && a.AddressIndex() == b.AddressIndex() } + +// TestZeroAndPartialAddressesAreSafe: the zero Address and an address built +// without a chain or a path behave like the C++ port's default address +// instead of panicking. +func TestZeroAndPartialAddressesAreSafe(t *testing.T) { + for name, a := range map[string]*Address{ + "zero": {}, + "NewAddress(nil)": NewAddress(nil, nil), + } { + if got := a.String(); got != `urn:mhda:nt::ci:` { + t.Errorf("%s: String() = %q", name, got) + } + if len(a.Hash256()) != 64 || len(a.NSSHash()) != 40 { + t.Errorf("%s: hashes have the wrong length", name) + } + if a.Algorithm() != "" || a.Format() != "" || a.DerivationType() != ROOT { + t.Errorf("%s: algorithm %q format %q type %q", name, a.Algorithm(), a.Format(), a.DerivationType()) + } + if err := a.SetCoinType("60"); !errors.Is(err, ErrUninitializedAddress) { + t.Errorf("%s: SetCoinType: got %v, want ErrUninitializedAddress", name, err) + } + if err := a.Validate(); !errors.Is(err, ErrUninitializedAddress) { + t.Errorf("%s: Validate: got %v, want ErrUninitializedAddress", name, err) + } + } + + // No path means root: an empty path is accepted, any other is refused. + a := NewAddress(NewChain(EthereumVM, "1"), nil) + if err := a.SetDerivationPath(""); err != nil { + t.Errorf("SetDerivationPath(\"\") without a path: %v", err) + } + if err := a.SetDerivationPath("m/44'/60'/0'/0/0"); !errors.Is(err, ErrInvalidDerivationPath) { + t.Errorf("SetDerivationPath without a type: got %v, want ErrInvalidDerivationPath", err) + } + if err := a.SetDerivation("bip44", "m/44'/60'/0'/0/0"); err != nil { + t.Fatal(err) + } + if got := a.String(); got != `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0` { + t.Errorf("String() = %q", got) + } +} From 43b940d0a0e7d8ca93de905de3d9c0f8878d35eb Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:49:36 +0300 Subject: [PATCH 15/21] Encode an Address held by value as its URN MarshalText had a pointer receiver, so an Address held by value (a struct field, a map value) was encoded by encoding/json and encoding/xml as a plain struct: {"A":{}}, which then failed to decode. SPEC.md promises the URN form for these codecs. MarshalText now has a value receiver. The codecs still encode a nil *Address themselves (JSON null); a direct MarshalText call on a nil pointer now panics like any value method, so TestMarshalTextNilAddress keeps only its zero-value case. --- CHANGELOG.md | 7 ++++++ SPEC.md | 4 +++- codec_test.go | 65 +++++++++++++++++++++++++++++++++++++++++++++++++++ mhda.go | 8 ++++--- mhda_test.go | 9 +++---- 5 files changed, 83 insertions(+), 10 deletions(-) create mode 100644 codec_test.go diff --git a/CHANGELOG.md b/CHANGELOG.md index fff81ed..c43923e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -108,6 +108,13 @@ of 2^31 or more no longer parses. zero chain (`urn:mhda:nt::ci:`, as the C++ port's default address) and a missing path as root; `SetCoinType` without a chain returns `ErrUninitializedAddress`. +- **An `Address` held by value encodes as its URN.** `MarshalText` had a + pointer receiver, so an `Address` struct field or map value was encoded + by `encoding/json` and `encoding/xml` as an empty object (`{"A":{}}`), + which then failed to decode. `MarshalText` now has a value receiver. A + nil `*Address` is still encoded by the codec (as `null`); calling + `MarshalText` directly on a nil pointer now panics like any value method + instead of returning `ErrUninitializedAddress`. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), diff --git a/SPEC.md b/SPEC.md index 80717cc..1d00eb9 100644 --- a/SPEC.md +++ b/SPEC.md @@ -518,7 +518,9 @@ This automatically provides: - Any framework that consults `TextMarshaler` for value serialisation. `MarshalText` returns the canonical URN form. `UnmarshalText` accepts any -valid input (lenient mode). +valid input (lenient mode). `MarshalText` has a value receiver, so an +`Address` held by value (a struct field, a map value) encodes as its URN as +well; a nil `*Address` is encoded by the codec itself (JSON `null`). A `database/sql` adapter is not currently provided; callers can wrap `MarshalText`/`UnmarshalText` in their own `driver.Valuer` / `sql.Scanner`. diff --git a/codec_test.go b/codec_test.go new file mode 100644 index 0000000..661f394 --- /dev/null +++ b/codec_test.go @@ -0,0 +1,65 @@ +package go_mhda + +import ( + "encoding/json" + "encoding/xml" + "testing" +) + +// TestTextCodecsWithAddressValues: an Address held by value (a struct field, +// a map value) encodes as its URN, not as an empty object, and decodes back. +func TestTextCodecsWithAddressValues(t *testing.T) { + const urn = `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0` + parsed, err := ParseURN(urn) + if err != nil { + t.Fatal(err) + } + addr := *parsed.(*Address) + + type record struct { + A Address + } + raw, err := json.Marshal(record{A: addr}) + if err != nil { + t.Fatal(err) + } + if want := `{"A":"` + urn + `"}`; string(raw) != want { + t.Errorf("json value field: %s, want %s", raw, want) + } + var back record + if err := json.Unmarshal(raw, &back); err != nil { + t.Fatal(err) + } + if back.A.String() != urn { + t.Errorf("json round-trip: %q", back.A.String()) + } + + raw, err = json.Marshal(map[string]Address{"k": addr}) + if err != nil { + t.Fatal(err) + } + if want := `{"k":"` + urn + `"}`; string(raw) != want { + t.Errorf("json map value: %s, want %s", raw, want) + } + + raw, err = xml.Marshal(record{A: addr}) + if err != nil { + t.Fatal(err) + } + var backXML record + if err := xml.Unmarshal(raw, &backXML); err != nil { + t.Fatalf("xml %s: %v", raw, err) + } + if backXML.A.String() != urn { + t.Errorf("xml value field: %s decodes to %q", raw, backXML.A.String()) + } + + // A nil pointer is encoded by the codec itself, as null. + raw, err = json.Marshal(struct{ P *Address }{}) + if err != nil { + t.Fatal(err) + } + if string(raw) != `{"P":null}` { + t.Errorf("json nil pointer: %s", raw) + } +} diff --git a/mhda.go b/mhda.go index f8e0cec..17a0f72 100644 --- a/mhda.go +++ b/mhda.go @@ -444,9 +444,11 @@ func (a *Address) NSSHash256() string { // MarshalText implements encoding.TextMarshaler. This is the integration point // for encoding/json, encoding/xml, gopkg.in/yaml.v3 and similar codecs - they -// will produce the URN form automatically. -func (a *Address) MarshalText() ([]byte, error) { - if a == nil || a.chain == nil { +// will produce the URN form automatically. The value receiver lets an Address +// held by value (a struct field, a map value) encode too; codecs encode a nil +// *Address themselves (as null) without calling it. +func (a Address) MarshalText() ([]byte, error) { + if a.chain == nil { return nil, ErrUninitializedAddress } if err := a.checkPathSet(); err != nil { diff --git a/mhda_test.go b/mhda_test.go index f102b48..3b76a2f 100644 --- a/mhda_test.go +++ b/mhda_test.go @@ -1348,13 +1348,10 @@ func TestDerivationTypeAccessor(t *testing.T) { // TestMarshalTextNilAddress ensures MarshalText returns a sentinel error // rather than panicking on an uninitialised receiver. func TestMarshalTextNilAddress(t *testing.T) { - var a *Address // nil - _, err := a.MarshalText() - if !errors.Is(err, ErrUninitializedAddress) { - t.Errorf("nil receiver: got %v, want ErrUninitializedAddress", err) - } + // A nil *Address is encoded by the codec (as null, see + // TestTextCodecsWithAddressValues); MarshalText has a value receiver. a2 := &Address{} // zero-value, no chain - _, err = a2.MarshalText() + _, err := a2.MarshalText() if !errors.Is(err, ErrUninitializedAddress) { t.Errorf("zero-value: got %v, want ErrUninitializedAddress", err) } From 0eda7e983acf8f297ef21660d2457eacbe1cb107 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:49:54 +0300 Subject: [PATCH 16/21] Wrap the sentinels in the FromString lookup helpers AlgorithmFromString, FormatFromString and NetworkTypeFromString returned plain errors.New values, so errors.Is could not discriminate them, although doc.go promises sentinel errors throughout and DerivationTypeFromString already wrapped ErrInvalidDerivationType. They now wrap ErrInvalidAlgorithm, ErrInvalidFormat and ErrInvalidNetworkType. --- CHANGELOG.md | 5 +++++ address.go | 6 +++--- hardening_test.go | 17 +++++++++++++++++ network_type.go | 4 ++-- 4 files changed, 27 insertions(+), 5 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c43923e..8b0bee1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -115,6 +115,11 @@ of 2^31 or more no longer parses. nil `*Address` is still encoded by the codec (as `null`); calling `MarshalText` directly on a nil pointer now panics like any value method instead of returning `ErrUninitializedAddress`. +- **The lookup helpers wrap their sentinels.** `AlgorithmFromString`, + `FormatFromString` and `NetworkTypeFromString` returned plain + `errors.New` values, so `errors.Is` could not tell them apart, unlike + `DerivationTypeFromString` and the parsers. They now wrap + `ErrInvalidAlgorithm`, `ErrInvalidFormat` and `ErrInvalidNetworkType`. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), diff --git a/address.go b/address.go index 5629437..5e44af3 100644 --- a/address.go +++ b/address.go @@ -1,7 +1,7 @@ package go_mhda import ( - "errors" + "fmt" "strings" ) @@ -84,7 +84,7 @@ func (a Algorithm) String() string { return string(a) } func AlgorithmFromString(src string) (Algorithm, error) { a := Algorithm(normalize(src)) if !a.IsValid() { - return "", errors.New("undefined algorithm") + return "", fmt.Errorf("%w: %q", ErrInvalidAlgorithm, src) } return a, nil } @@ -100,7 +100,7 @@ func (f Format) String() string { return string(f) } func FormatFromString(src string) (Format, error) { f := Format(normalize(src)) if !f.IsValid() { - return "", errors.New("undefined format") + return "", fmt.Errorf("%w: %q", ErrInvalidFormat, src) } return f, nil } diff --git a/hardening_test.go b/hardening_test.go index 68f8c5f..024c970 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -286,3 +286,20 @@ func TestZIP32HasNoNetwork(t *testing.T) { } } } + +// TestFromStringHelpersWrapSentinels: every lookup helper reports an unknown +// value with the sentinel of its component, as doc.go promises. +func TestFromStringHelpersWrapSentinels(t *testing.T) { + if _, err := AlgorithmFromString("rsa"); !errors.Is(err, ErrInvalidAlgorithm) { + t.Errorf("AlgorithmFromString: got %v, want ErrInvalidAlgorithm", err) + } + if _, err := FormatFromString("zzz"); !errors.Is(err, ErrInvalidFormat) { + t.Errorf("FormatFromString: got %v, want ErrInvalidFormat", err) + } + if _, err := NetworkTypeFromString("doge"); !errors.Is(err, ErrInvalidNetworkType) { + t.Errorf("NetworkTypeFromString: got %v, want ErrInvalidNetworkType", err) + } + if _, err := DerivationTypeFromString("bip99"); !errors.Is(err, ErrInvalidDerivationType) { + t.Errorf("DerivationTypeFromString: got %v, want ErrInvalidDerivationType", err) + } +} diff --git a/network_type.go b/network_type.go index 20dd745..3944ab8 100644 --- a/network_type.go +++ b/network_type.go @@ -1,6 +1,6 @@ package go_mhda -import "errors" +import "fmt" type NetworkType string @@ -47,7 +47,7 @@ func NetworkTypeFromString(src string) (NetworkType, error) { if result, ok := ntIndex[normalize(src)]; ok { return result, nil } - return "", errors.New("undefined network type") + return "", fmt.Errorf("%w: %q", ErrInvalidNetworkType, src) } func (nt NetworkType) IsValid() bool { From 0fa3869506e52bc88308606a02e7ebd32c3174a2 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:50:51 +0300 Subject: [PATCH 17/21] Normalise setter and lookup input as ASCII only normalize and the Address setters used strings.TrimSpace and strings.ToLower, which are Unicode-aware: SetAddressAlgorithm accepted "secp256\u212a1" (Kelvin sign) as secp256k1, and NBSP or ideographic spaces around a derivation type, path, format or coin type were trimmed away. The URN parser and the C++ port refuse those bytes, so the two entry points and the two implementations disagreed. normalize now trims ASCII whitespace and folds ASCII case only, and the setters, parseChain and the case-insensitive URN prefix check use it. --- CHANGELOG.md | 7 +++++++ SPEC.md | 4 +++- address.go | 34 +++++++++++++++++++++++++--------- chain.go | 4 ++-- hardening_test.go | 38 ++++++++++++++++++++++++++++++++++++++ mhda.go | 16 ++++++---------- parser.go | 4 ++-- 7 files changed, 83 insertions(+), 24 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8b0bee1..855d94d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -120,6 +120,13 @@ of 2^31 or more no longer parses. `errors.New` values, so `errors.Is` could not tell them apart, unlike `DerivationTypeFromString` and the parsers. They now wrap `ErrInvalidAlgorithm`, `ErrInvalidFormat` and `ErrInvalidNetworkType`. +- **Setters and lookup helpers normalise ASCII only.** They trimmed with + `strings.TrimSpace` and lowercased with `strings.ToLower`, which are + Unicode-aware: `SetAddressAlgorithm("secp256\u212a1")` (Kelvin sign) + was accepted as `secp256k1`, and NBSP or ideographic spaces around a + derivation type, path, format or coin type were trimmed, while the URN + parser and the C++ port refuse the same bytes. They now trim ASCII + whitespace and fold ASCII case only. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), diff --git a/SPEC.md b/SPEC.md index 1d00eb9..559ee5e 100644 --- a/SPEC.md +++ b/SPEC.md @@ -104,7 +104,9 @@ NSS values must consist of ASCII characters allowed by RFC 8141 NSS production ASCII (0x21–0x7E) for every value: control bytes, whitespace of any kind and non-ASCII bytes are rejected. Only ASCII whitespace is trimmed around the URN and around values — a Unicode space is malformed input, never decoration to -strip. Percent-encoding is not implemented; if a value needs to contain `:` +strip. The setters and the `...FromString` helpers follow the same rule: +they trim ASCII whitespace and fold ASCII case only, so a Unicode letter that +lowercases to an ASCII one (the Kelvin sign `K`) is not another spelling. Percent-encoding is not implemented; if a value needs to contain `:` (currently no in-tree value does), percent-encoding support must be added. ### 1.6 Wallet domain diff --git a/address.go b/address.go index 5e44af3..80ee843 100644 --- a/address.go +++ b/address.go @@ -1,15 +1,31 @@ package go_mhda -import ( - "fmt" - "strings" -) - -// normalize trims surrounding whitespace and lowercases the input. Used -// throughout the package to canonicalise component values (network type, -// algorithm, format, derivation type) before lookup. +import "fmt" + +// normalize trims surrounding ASCII whitespace and lowercases ASCII letters. +// Used throughout the package to canonicalise component values (network +// type, algorithm, format, derivation type) before lookup. ASCII only, like +// the URN parser and the C++ port: an NSS is ASCII (RFC 8141), so a Unicode +// space or a letter that lowercases to ASCII (the Kelvin sign) is malformed +// input, not another spelling. func normalize(s string) string { - return strings.ToLower(strings.TrimSpace(s)) + return asciiLower(asciiTrim(s)) +} + +// asciiLower lowercases the ASCII letters of s and leaves every other byte. +func asciiLower(s string) string { + for i := 0; i < len(s); i++ { + if 'A' <= s[i] && s[i] <= 'Z' { + b := []byte(s) + for j := i; j < len(b); j++ { + if 'A' <= b[j] && b[j] <= 'Z' { + b[j] += 'a' - 'A' + } + } + return string(b) + } + } + return s } const ( diff --git a/chain.go b/chain.go index 44894a2..488bf05 100644 --- a/chain.go +++ b/chain.go @@ -111,7 +111,7 @@ func parseChain(m map[string]string) (*Chain, error) { } chainID, ok := m[compChainId] - if !ok || strings.TrimSpace(chainID) == "" { + if !ok || asciiTrim(chainID) == "" { return nil, ErrMissingChainID } @@ -121,7 +121,7 @@ func parseChain(m map[string]string) (*Chain, error) { } if ct, ok := m[compCoinType]; ok { - coinType, err := parseCoinType(strings.TrimSpace(ct)) + coinType, err := parseCoinType(asciiTrim(ct)) if err != nil { return nil, err } diff --git a/hardening_test.go b/hardening_test.go index 024c970..0029d65 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -303,3 +303,41 @@ func TestFromStringHelpersWrapSentinels(t *testing.T) { t.Errorf("DerivationTypeFromString: got %v, want ErrInvalidDerivationType", err) } } + +// TestNormalisationIsASCIIOnly: setters and lookup helpers trim ASCII +// whitespace and lowercase ASCII letters only, like the URN parser and the +// C++ port. A Unicode space is not trimmed and a letter that lowercases to +// ASCII (the Kelvin sign) is not folded: both are malformed input. +func TestNormalisationIsASCIIOnly(t *testing.T) { + const kelvin, nbsp, ideo = "K", " ", " " + addr := mustAddress(t, `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0`) + for name, err := range map[string]error{ + "AlgorithmFromString": func() error { _, e := AlgorithmFromString("secp256" + kelvin + "1"); return e }(), + "FormatFromString": func() error { _, e := FormatFromString(nbsp + "hex"); return e }(), + "NetworkTypeFromString": func() error { _, e := NetworkTypeFromString(nbsp + "evm"); return e }(), + "DerivationTypeFromStr": func() error { _, e := DerivationTypeFromString(nbsp + "BIP44"); return e }(), + "SetAddressAlgorithm": addr.SetAddressAlgorithm("secp256" + kelvin + "1"), + "SetAddressFormat": addr.SetAddressFormat(nbsp + "hex" + nbsp), + "SetDerivationType": addr.SetDerivationType("bip44" + ideo), + "SetDerivationPath": addr.SetDerivationPath(nbsp + "m/44'/60'/0'/0/1"), + "SetCoinType": addr.SetCoinType(nbsp + "60"), + } { + if err == nil { + t.Errorf("%s accepted a non-ASCII spelling", name) + } + } + if got := addr.String(); got != `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0` { + t.Errorf("refused values changed the address: %q", got) + } + + // ASCII whitespace and case are still normalised. + if a, err := AlgorithmFromString(" SECP256K1\t"); err != nil || a != Secp256k1 { + t.Errorf("AlgorithmFromString: %q, %v", a, err) + } + if nt, err := NetworkTypeFromString("\tEVM "); err != nil || nt != EthereumVM { + t.Errorf("NetworkTypeFromString: %q, %v", nt, err) + } + if err := addr.SetDerivation(" BIP44 ", " M/44H/60H/0H/0/1 "); err != nil { + t.Errorf("SetDerivation with ASCII case and spaces: %v", err) + } +} diff --git a/mhda.go b/mhda.go index 17a0f72..cfe5798 100644 --- a/mhda.go +++ b/mhda.go @@ -160,8 +160,7 @@ func (a *Address) Format() Format { // Setting the current type again keeps the path. Use SetDerivation to change // both at once. func (a *Address) SetDerivationType(dt string) error { - dt = strings.TrimSpace(dt) - dt = strings.ToLower(dt) + dt = normalize(dt) next := ROOT if dt != `` { @@ -199,7 +198,7 @@ func (a *Address) SetDerivation(dt, dp string) error { // path it spells out. func (a *Address) SetDerivationPath(dp string) error { if a.path == nil || a.path.derivationType == ROOT { - if p := strings.TrimSpace(dp); p != `` { + if p := asciiTrim(dp); p != `` { return fmt.Errorf("%w: root derivation must have empty path, got %q", ErrInvalidDerivationPath, p) } return nil @@ -210,8 +209,7 @@ func (a *Address) SetDerivationPath(dp string) error { return fmt.Errorf("%w: unknown derivation type %q", ErrInvalidDerivationPath, a.path.derivationType) } - dp = strings.TrimSpace(dp) - dp = strings.ToLower(dp) + dp = normalize(dp) if !rx.MatchString(dp) { return fmt.Errorf("%w: %q", ErrInvalidDerivationPath, dp) @@ -230,7 +228,7 @@ func (a *Address) SetCoinType(ct string) error { if a.chain == nil { return ErrUninitializedAddress } - ct = strings.TrimSpace(ct) + ct = asciiTrim(ct) if ct == `` { a.chain.ClearCoinType() return nil @@ -261,8 +259,7 @@ func validateFreeFormValue(component, v string) error { } func (a *Address) SetAddressAlgorithm(aa string) error { - aa = strings.TrimSpace(aa) - aa = strings.ToLower(aa) + aa = normalize(aa) if aa == `` { a.addressAlgorithm = "" return nil @@ -275,8 +272,7 @@ func (a *Address) SetAddressAlgorithm(aa string) error { } func (a *Address) SetAddressFormat(af string) error { - af = strings.TrimSpace(af) - af = strings.ToLower(af) + af = normalize(af) if af == `` { a.addressFormat = "" return nil diff --git a/parser.go b/parser.go index 478f5cf..975b420 100644 --- a/parser.go +++ b/parser.go @@ -77,7 +77,7 @@ var knownComponents = func() map[string]struct{} { // RFC 8141 §5.1: the leading "urn:" sequence and the NID are case-insensitive // (e.g. "URN:MHDA:..." must parse identically to "urn:mhda:..."). func hasPrefixFold(s, prefix string) bool { - return len(s) >= len(prefix) && strings.EqualFold(s[:len(prefix)], prefix) + return len(s) >= len(prefix) && asciiLower(s[:len(prefix)]) == asciiLower(prefix) } // asciiTrim trims ASCII whitespace only. Unicode spaces (NBSP, ideographic @@ -220,7 +220,7 @@ func parseNSS(nss string) (map[string]string, error) { return nil, err } if _, ok := knownComponents[key]; !ok { - if _, ok := knownComponents[strings.ToLower(key)]; ok { + if _, ok := knownComponents[asciiLower(key)]; ok { return nil, fmt.Errorf("%w: component key %q must be lowercase", ErrInvalidNSS, key) } continue // unknown component, skipped with its value From 3d0cc16b4b2f3f7d5ea27a8f3fdb8ddf33c4c3b9 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:52:19 +0300 Subject: [PATCH 18/21] Refuse whitespace around keys and values inside the NSS parseNSS trimmed every value, so urn:mhda:nt:evm:ci: 1 :dt: bip44 :... parsed like the same URN without the spaces, although SPEC section 6.1 says values contain no whitespace and only the whole URN is trimmed. parseNSS no longer trims; whitespace in a key or value fails the charset check with ErrInvalidNSS. ParseURN trims the URN and the whitespace left before a stripped r/q/f component (ci:0 #frag still parses); ParseNSS, ChainFromNSS and ChainFromKey trim the NSS they are given as a whole. --- CHANGELOG.md | 6 ++++++ SPEC.md | 18 +++++++++++------- chain.go | 5 +++-- hardening_test.go | 40 ++++++++++++++++++++++++++++++++++++++++ parser.go | 34 ++++++++++++++++++++++------------ 5 files changed, 82 insertions(+), 21 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 855d94d..58f46e3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -127,6 +127,12 @@ of 2^31 or more no longer parses. derivation type, path, format or coin type were trimmed, while the URN parser and the C++ port refuse the same bytes. They now trim ASCII whitespace and fold ASCII case only. +- **No whitespace inside the NSS.** Each value was trimmed, so + `urn:mhda:nt:evm:ci: 1 :dt: bip44 :...` parsed like the URN without the + spaces, against SPEC §6.1. ASCII whitespace is now trimmed only around the + whole URN, around an NSS or chain key parsed on its own, and before a + stripped r/q/f component (`ci:0 #frag` still parses); around a key or + value it is refused with `ErrInvalidNSS`. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), diff --git a/SPEC.md b/SPEC.md index 559ee5e..2696ff6 100644 --- a/SPEC.md +++ b/SPEC.md @@ -101,12 +101,14 @@ truncate the URN emitted from it on the next parse. NSS values must consist of ASCII characters allowed by RFC 8141 NSS production (`pchar / "/"` per RFC 3986). The reference implementation enforces printable -ASCII (0x21–0x7E) for every value: control bytes, whitespace of any kind and -non-ASCII bytes are rejected. Only ASCII whitespace is trimmed around the URN -and around values — a Unicode space is malformed input, never decoration to -strip. The setters and the `...FromString` helpers follow the same rule: +ASCII (0x21–0x7E) for every key and value: control bytes, whitespace of any +kind and non-ASCII bytes are rejected. ASCII whitespace is trimmed only around +the whole URN (or around an NSS or chain key parsed on its own), never around +a key or value inside it; a Unicode space is malformed input, never decoration +to strip. The setters and the `...FromString` helpers follow the same rule: they trim ASCII whitespace and fold ASCII case only, so a Unicode letter that -lowercases to an ASCII one (the Kelvin sign `K`) is not another spelling. Percent-encoding is not implemented; if a value needs to contain `:` +lowercases to an ASCII one (the Kelvin sign `K`) is not another spelling. +Percent-encoding is not implemented; if a value needs to contain `:` (currently no in-tree value does), percent-encoding support must be added. ### 1.6 Wallet domain @@ -354,8 +356,10 @@ Performs structural validation only: - Network type is one of the registered values. - Coin type, if present, is a valid 32-bit unsigned integer, spelled as plain decimal or `0x`-prefixed hex only (no other integer-literal forms). -- Values contain no whitespace (interior whitespace is rejected; surrounding - whitespace around the whole URN is trimmed). +- Values contain no whitespace. ASCII whitespace around the whole URN (or + around an NSS or chain key parsed on its own, or before a stripped r/q/f + component) is trimmed; around a key or value inside the NSS it is + rejected. - Chain ID is non-empty. - Derivation type, if present, is one of the registered constants. - Derivation path, if present, matches the regex of its derivation type, diff --git a/chain.go b/chain.go index 488bf05..41b70c7 100644 --- a/chain.go +++ b/chain.go @@ -86,9 +86,10 @@ func ChainFromKey(chainKey ChainKey) (*Chain, error) { // ChainFromNSS parses the chain-domain components ("nt", "ci" and the // optional "ct" metadata) from the given NSS string. Other components are -// tolerated and ignored, so a full address NSS is valid input. +// tolerated and ignored, so a full address NSS is valid input. Surrounding +// ASCII whitespace is trimmed; whitespace inside the NSS is refused. func ChainFromNSS(src string) (*Chain, error) { - components, err := parseNSS(src) + components, err := parseNSS(asciiTrim(src)) if err != nil { return nil, err } diff --git a/hardening_test.go b/hardening_test.go index 0029d65..67bc056 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -341,3 +341,43 @@ func TestNormalisationIsASCIIOnly(t *testing.T) { t.Errorf("SetDerivation with ASCII case and spaces: %v", err) } } + +// TestNoWhitespaceInsideNSS: ASCII whitespace is trimmed around the whole +// URN (and around an NSS or chain key given on its own, and before an r/q/f +// component), never around a key or value inside it; there it is malformed +// input, as SPEC §6.1 says. +func TestNoWhitespaceInsideNSS(t *testing.T) { + for _, urn := range []string{ + "urn:mhda:nt:evm:ci: 1", + "urn:mhda:nt:evm:ci:1 :dt:bip44:dp:m/44'/60'/0'/0/0", + "urn:mhda:nt: evm:ci:1", + "urn:mhda:nt:evm:ci:1:dt: bip44 :dp:m/44'/60'/0'/0/0", + "urn:mhda: nt:evm:ci:1", + "urn:mhda:nt:evm:ci:1\t:wt:x", + } { + if _, err := ParseURN(urn); !errors.Is(err, ErrInvalidNSS) { + t.Errorf("ParseURN(%q): got %v, want ErrInvalidNSS", urn, err) + } + } + for in, want := range map[string]string{ + " urn:mhda:nt:evm:ci:1\t": "urn:mhda:nt:evm:ci:1", + "urn:mhda:nt:evm:ci:0 #frag": "urn:mhda:nt:evm:ci:0", + "urn:mhda:nt:evm:ci:1 ?=q": "urn:mhda:nt:evm:ci:1", + } { + addr, err := ParseURN(in) + if err != nil { + t.Errorf("ParseURN(%q): %v", in, err) + } else if addr.String() != want { + t.Errorf("ParseURN(%q) = %q, want %q", in, addr.String(), want) + } + } + if _, err := ParseNSS(" nt:evm:ci:1 "); err != nil { + t.Errorf("ParseNSS with surrounding whitespace: %v", err) + } + if _, err := ChainFromNSS("\tnt:evm:ci:1 "); err != nil { + t.Errorf("ChainFromNSS with surrounding whitespace: %v", err) + } + if _, err := ChainFromNSS("nt:evm:ci: 1"); !errors.Is(err, ErrInvalidNSS) { + t.Errorf("ChainFromNSS with a space inside: got %v, want ErrInvalidNSS", err) + } +} diff --git a/parser.go b/parser.go index 975b420..8a999bb 100644 --- a/parser.go +++ b/parser.go @@ -86,9 +86,12 @@ func hasPrefixFold(s, prefix string) bool { // check rejects it loudly. Trimming it instead (as a Unicode-aware trim // would) silently accepts a malformed URN and diverges from the C++ port. func asciiTrim(s string) string { - return strings.Trim(s, " \t\n\v\f\r") + return strings.Trim(s, asciiSpace) } +// asciiSpace is the ASCII whitespace asciiTrim removes. +const asciiSpace = " \t\n\v\f\r" + // validateValueCharset enforces SPEC §1.5: NSS values consist of printable // ASCII only. Control characters, whitespace of any kind and non-ASCII bytes // are rejected — they cannot appear in a conforming URN and would serialise @@ -136,7 +139,10 @@ func ParseURN(src string) (MHDA, error) { if !hasPrefixFold(src, prefixMHDA) { return nil, ErrInvalidURN } - return ParseNSS(stripRQF(src[prefixOffset:])) + // Whitespace left before a stripped r/q/f component ("ci:0 #frag") ends + // the URN like the whitespace trimmed above; any other whitespace in the + // NSS is malformed and parseNSS refuses it. + return parseAddressNSS(strings.TrimRight(stripRQF(src[prefixOffset:]), asciiSpace)) } // ParseURNStrict is ParseURN + Validate(). It rejects URNs whose @@ -156,8 +162,15 @@ func ParseURNStrict(src string) (MHDA, error) { } // ParseNSS parses an MHDA namespace-specific string into an MHDA address. -// Requires the network type ("nt") component to be present. +// Requires the network type ("nt") component to be present. Surrounding ASCII +// whitespace is trimmed; whitespace inside the NSS is refused. func ParseNSS(nss string) (MHDA, error) { + return parseAddressNSS(asciiTrim(nss)) +} + +// parseAddressNSS parses an NSS without surrounding whitespace into an +// address. +func parseAddressNSS(nss string) (MHDA, error) { components, err := parseNSS(nss) if err != nil { return nil, err @@ -177,7 +190,9 @@ func ParseNSS(nss string) (MHDA, error) { // read as a key and a following known key is never read as a value. A key // that differs from a known key only by case is rejected, not skipped: it // would drop the component silently. A key without a value, an empty key or -// value and a duplicate known key are rejected too. +// value and a duplicate known key are rejected too. Nothing is trimmed: the +// caller removes whitespace around the whole NSS, and whitespace around a key +// or value is malformed input. // // '?' and '#' open the RFC 8141 r/q/f components. ParseURN strips them before // the NSS reaches this parser; an NSS that still carries one (ParseNSS, @@ -205,17 +220,12 @@ func parseNSS(nss string) (map[string]string, error) { if err := validateKeyCharset(key); err != nil { return nil, err } - // RFC 8141 NSS does not permit unescaped whitespace; trim ASCII - // whitespace so any trailing space (e.g. from "ci:0 #frag" where - // stripRQF leaves the space) does not leak into the canonical form - // and break round-trip. - value := asciiTrim(parts[i+1]) + value := parts[i+1] if value == "" { return nil, fmt.Errorf("%w: empty value for %q", ErrInvalidNSS, key) } - // Everything that survives the trim must be printable ASCII — - // interior whitespace, control bytes and Unicode spaces are all - // malformed input, never silently normalised. + // A value is printable ASCII: whitespace, control bytes and Unicode + // spaces are malformed input, never silently normalised. if err := validateValueCharset(key, value); err != nil { return nil, err } From 180d9567e5b2a4f0b17a58b7d2ae121f5d5d9bd9 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:53:45 +0300 Subject: [PATCH 19/21] Restrict NSS keys and values to the RFC 3986 byte set Keys and values accepted any printable ASCII, so '"', '<', '>', '\', '^', '`', '{', '|', '}', '[', ']' and a raw '%' passed and were emitted in URNs that RFC 8141 does not allow, although SPEC section 1.5 requires the NSS production (RFC 3986 pchar and "/"). One predicate, nssByte, now admits letters, digits and -._~!$&'()*+,;=@/ - pchar and "/" without ':' (the separator) and '%' (percent-encoding is not supported, and %41 would be a second spelling of "A"). The parser uses it for keys and values (ErrInvalidNSS), and validateFreeFormValue for ap/as/wt/wi and the chain id (ErrInvalidValue). The shared URN table gets a row per refused byte. --- CHANGELOG.md | 8 ++++++++ SPEC.md | 35 ++++++++++++++++++++--------------- hardening_test.go | 17 +++++++++++++++++ mhda.go | 14 +++++++------- parser.go | 34 +++++++++++++++++++++++----------- testdata/urn_conformance.txt | 21 +++++++++++++++++++++ 6 files changed, 96 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 58f46e3..a99ec27 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -133,6 +133,14 @@ of 2^31 or more no longer parses. whole URN, around an NSS or chain key parsed on its own, and before a stripped r/q/f component (`ci:0 #frag` still parses); around a key or value it is refused with `ErrInvalidNSS`. +- **NSS bytes follow RFC 3986.** Keys and values accepted any printable + ASCII, so `"`, `<`, `>`, `\`, `^`, `` ` ``, `{`, `|`, `}`, `[`, `]` and a + raw `%` passed and were emitted in URNs that RFC 8141 does not allow. A + key or value is now made of letters, digits and `-._~!$&'()*+,;=@/` + only (RFC 3986 pchar and `/`, without `:` and `%`); anything else is + `ErrInvalidNSS` when parsed and `ErrInvalidValue` from the setters and + `NewChain`. `%` is refused because percent-encoding is not supported and + `%41` would be a second spelling of `A`. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), diff --git a/SPEC.md b/SPEC.md index 2696ff6..c9c0596 100644 --- a/SPEC.md +++ b/SPEC.md @@ -99,17 +99,21 @@ truncate the URN emitted from it on the next parse. ### 1.5 Charset -NSS values must consist of ASCII characters allowed by RFC 8141 NSS production -(`pchar / "/"` per RFC 3986). The reference implementation enforces printable -ASCII (0x21–0x7E) for every key and value: control bytes, whitespace of any -kind and non-ASCII bytes are rejected. ASCII whitespace is trimmed only around -the whole URN (or around an NSS or chain key parsed on its own), never around -a key or value inside it; a Unicode space is malformed input, never decoration -to strip. The setters and the `...FromString` helpers follow the same rule: -they trim ASCII whitespace and fold ASCII case only, so a Unicode letter that -lowercases to an ASCII one (the Kelvin sign `K`) is not another spelling. -Percent-encoding is not implemented; if a value needs to contain `:` -(currently no in-tree value does), percent-encoding support must be added. +NSS keys and values must consist of ASCII characters allowed by RFC 8141 NSS +production (`pchar / "/"` per RFC 3986): letters, digits and +`-._~!$&'()*+,;=@/`. `:` separates components and is never part of a value. +`%` is rejected too: percent-encoding is not implemented, and a raw `%41` +would be a second spelling of `A` (if a value ever needs `:`, percent-encoding +support must be added first). Everything else — whitespace, control bytes, +non-ASCII bytes and the printable ASCII outside that set +(``"<>\^`{|}[]?#``) — is rejected with `ErrInvalidNSS`. + +ASCII whitespace is trimmed only around the whole URN (or around an NSS or +chain key parsed on its own), never around a key or value inside it; a +Unicode space is malformed input, never decoration to strip. The setters and +the `...FromString` helpers follow the same rule: they trim ASCII whitespace +and fold ASCII case only, so a Unicode letter that lowercases to an ASCII one +(the Kelvin sign `K`) is not another spelling. ### 1.6 Wallet domain @@ -127,9 +131,10 @@ When set, the wallet domain participates in the serialised NSS (and therefore in the NSS hashes, §9); it is never part of the chain key. Because these values are typically client-supplied, the setters validate them -against NSS-corrupting characters: a value may not contain `:` (component -injection on re-parse), `?` or `#` (RFC 8141 r/q/f truncation), or -whitespace. The same rule applies to the free-form `ap` / `as` values. +against the §1.5 byte set and return `ErrInvalidValue` otherwise: in +particular a value may not contain `:` (component injection on re-parse), +`?` or `#` (RFC 8141 r/q/f truncation), or whitespace. The same rule applies +to the free-form `ap` / `as` values and to the chain id. ## 2. Network Catalogue @@ -430,7 +435,7 @@ text. | `ErrMissingChainID` | `ci` absent | | `ErrCoinTypeInChainKey` | `ChainFromKey` input carries `ct` (pre-1.1 key format) | | `ErrInvalidChainKey` | `ChainFromKey` input is not the canonical identity form | -| `ErrInvalidValue` | Free-form or chain id value with `:`/`?`/`#`/whitespace | +| `ErrInvalidValue` | Free-form or chain id value outside the §1.5 byte set | | `ErrInvalidDerivationType` | `dt` value not registered | | `ErrInvalidDerivationPath` | `dp` does not fit `dt` (or no `dt`), or an index >= 2^31 | | `ErrInvalidAlgorithm` | `aa` value not registered | diff --git a/hardening_test.go b/hardening_test.go index 67bc056..0c068ec 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -381,3 +381,20 @@ func TestNoWhitespaceInsideNSS(t *testing.T) { t.Errorf("ChainFromNSS with a space inside: got %v, want ErrInvalidNSS", err) } } + +// TestFreeFormValuesUseTheNSSCharset: values set in code obey the same RFC +// 3986 byte set as parsed ones. +func TestFreeFormValuesUseTheNSSCharset(t *testing.T) { + addr := mustAddress(t, `urn:mhda:nt:evm:ci:1`) + for _, v := range []string{"x|y", "a%41", "", `a"b`, "a{b}", "a\\b"} { + if err := addr.SetWalletId(v); !errors.Is(err, ErrInvalidValue) { + t.Errorf("SetWalletId(%q): got %v, want ErrInvalidValue", v, err) + } + if err := panicErr(t, func() { NewChain(EthereumVM, ChainId(v)) }); !errors.Is(err, ErrInvalidValue) { + t.Errorf("NewChain(%q): panic %v, want ErrInvalidValue", v, err) + } + } + if err := addr.SetWalletId("c0a8f2d4-3b6e_x.y~z@w"); err != nil { + t.Errorf("SetWalletId with pchar punctuation: %v", err) + } +} diff --git a/mhda.go b/mhda.go index cfe5798..780bebf 100644 --- a/mhda.go +++ b/mhda.go @@ -243,15 +243,15 @@ func (a *Address) SetCoinType(ct string) error { return nil } -// validateFreeFormValue guards the case-preserving free-form components -// (ap/as/wt/wi) against characters that would corrupt the serialised NSS: -// the ':' component separator would inject foreign components on re-parse, -// '?' / '#' would truncate the URN at the RFC 8141 r/q/f delimiters, and -// anything outside printable ASCII (whitespace of any kind, control bytes, -// Unicode) cannot appear in a conforming NSS at all. +// validateFreeFormValue guards a value written verbatim into the NSS +// (ap/as/wt/wi and the chain id) with the NSS byte set (see nssByte): the ':' +// component separator would inject foreign components on re-parse, '?' / '#' +// would truncate the URN at the RFC 8141 r/q/f delimiters, and whitespace, +// control bytes, Unicode and the rest of the printable ASCII outside RFC 3986 +// pchar cannot appear in a conforming NSS at all. func validateFreeFormValue(component, v string) error { for i := 0; i < len(v); i++ { - if v[i] < 0x21 || v[i] > 0x7e || v[i] == ':' || v[i] == '?' || v[i] == '#' { + if !nssByte(v[i]) { return fmt.Errorf("%w: %q for %q", ErrInvalidValue, v, component) } } diff --git a/parser.go b/parser.go index 8a999bb..8013f9e 100644 --- a/parser.go +++ b/parser.go @@ -92,29 +92,41 @@ func asciiTrim(s string) string { // asciiSpace is the ASCII whitespace asciiTrim removes. const asciiSpace = " \t\n\v\f\r" -// validateValueCharset enforces SPEC §1.5: NSS values consist of printable -// ASCII only. Control characters, whitespace of any kind and non-ASCII bytes -// are rejected — they cannot appear in a conforming URN and would serialise -// into a non-parseable or ambiguous canonical form. +// nssByte reports whether c may appear in an NSS key or value (SPEC §1.5): +// an RFC 3986 pchar or "/" - letters, digits and -._~!$&'()*+,;=@/ - except +// ':' (the component separator) and '%' (percent-encoding is not supported, +// and a raw "%41" would be a second spelling of "A"). Whitespace, control +// bytes, non-ASCII bytes and the printable ASCII outside pchar ('"', '<', +// '>', '\', '^', '`', '{', '|', '}', '[', ']', '?', '#') cannot appear in a +// conforming URN. +func nssByte(c byte) bool { + switch { + case 'a' <= c && c <= 'z', 'A' <= c && c <= 'Z', '0' <= c && c <= '9': + return true + } + return strings.IndexByte("-._~!$&'()*+,;=@/", c) >= 0 +} + +// validateValueCharset enforces SPEC §1.5 on an NSS value (see nssByte). func validateValueCharset(key, value string) error { for i := 0; i < len(value); i++ { - if value[i] < 0x21 || value[i] > 0x7e { - return fmt.Errorf("%w: non-ASCII or control byte in value for %q", - ErrInvalidNSS, key) + if !nssByte(value[i]) { + return fmt.Errorf("%w: byte %q not allowed in value for %q", + ErrInvalidNSS, value[i], key) } } return nil } -// validateKeyCharset requires a component key to be non-empty printable -// ASCII, the same byte range as values. +// validateKeyCharset requires a component key to be non-empty and made of +// the same bytes as values (see nssByte). func validateKeyCharset(key string) error { if key == "" { return fmt.Errorf("%w: empty component key", ErrInvalidNSS) } for i := 0; i < len(key); i++ { - if key[i] < 0x21 || key[i] > 0x7e { - return fmt.Errorf("%w: non-ASCII or control byte in component key %q", ErrInvalidNSS, key) + if !nssByte(key[i]) { + return fmt.Errorf("%w: byte %q not allowed in component key %q", ErrInvalidNSS, key[i], key) } } return nil diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt index 278aff0..3212e3d 100644 --- a/testdata/urn_conformance.txt +++ b/testdata/urn_conformance.txt @@ -122,3 +122,24 @@ accept strict urn:mhda:nt:bitcoin:ci:bitcoin:dt:bip32:dp:m/0'/0/0:af:p2wpkh urn: refuse strict incompatible urn:mhda:nt:cosmos:ci:cosmoshub:dt:bip44:dp:m/44'/118'/0'/0/0 accept strict urn:mhda:nt:cosmos:ci:cosmoshub:dt:cip11:dp:m/44'/118'/0'/0/0 urn:mhda:nt:cosmos:ci:cosmoshub:dt:cip11:dp:m/44'/118'/0'/0/0 accept strict urn:mhda:nt:cosmos:ci:secret:dt:bip44:dp:m/44'/529'/0'/0/0 urn:mhda:nt:cosmos:ci:secret:dt:bip44:dp:m/44'/529'/0'/0/0 + +# NSS bytes are RFC 3986 pchar or "/": letters, digits and -._~!$&'()*+,;=@/, +# except ':' (the component separator) and '%' (percent-encoding is not +# supported, and a raw %41 would be a second spelling of "A"). The other +# printable ASCII bytes cannot appear in a URN at all. +refuse urn invalid_nss urn:mhda:nt:evm:ci:a"b +refuse urn invalid_nss urn:mhda:nt:evm:ci:ab +refuse urn invalid_nss urn:mhda:nt:evm:ci:a\b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a^b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a`b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a{b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a|b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a}b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a[b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a]b +refuse urn invalid_nss urn:mhda:nt:evm:ci:a%41 +refuse urn invalid_nss urn:mhda:nt:evm:ci:1:wi:x|y +refuse urn invalid_nss urn:mhda:nt:evm:ci:1:x|y:z +accept urn urn:mhda:nt:evm:ci:a-b.c_d~e!f$g&h'i(j)k*l+m,n;o=p@q/r urn:mhda:nt:evm:ci:a-b.c_d~e!f$g&h'i(j)k*l+m,n;o=p@q/r +accept urn urn:mhda:nt:cosmos:ci:cosmoshub-4:ap:X-avax:wi:c0a8f2d4-3b6e urn:mhda:nt:cosmos:ci:cosmoshub-4:ap:X-avax:wi:c0a8f2d4-3b6e From 77f0fd67ee42ce2a9e94dc260859157b1f4dad4c Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 12:54:35 +0300 Subject: [PATCH 20/21] Document EVM chain id spellings; regroup the 1.2.0 changelog ci:1, ci:0x1 and ci:01 are three chain keys and hashes for one chain. MHDA keeps the chain id opaque; SPEC.md now says so and asks a producer to keep to one spelling (the EIP-155 decimal form is the usual one). The 1.2.0 changelog had grown entry by entry; it is regrouped into Changed (inputs refused now), Fixed and Documentation, with the intro pointing at the changes. --- CHANGELOG.md | 99 +++++++++++++++++++++++++++------------------------- SPEC.md | 5 ++- 2 files changed, 55 insertions(+), 49 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a99ec27..234e008 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,8 +7,9 @@ Releases before 1.2.0 are described by their tags and commit messages. ## [1.2.0] — 2026-10-05 -URNs accepted by 1.1 are refused now: a derivation path with a level index -of 2^31 or more no longer parses. +URNs and values accepted by 1.1 are refused now: see Changed. Code that +builds addresses gets stricter constructors and setters, and +`Chain.SetNetworkType` / `Chain.SetChainId` return an error. ### Changed @@ -72,16 +73,6 @@ of 2^31 or more no longer parses. - **A `slip10` path has at most 255 levels**; a deeper one is refused with `ErrInvalidDerivationPath`. BIP-32 serialises a key's depth in one byte, so no wallet can represent a deeper key. - -### Documentation - -- SPEC.md states that an explicit `dt:root` is folded away (root is the - default and has no path, so a root address has one canonical form and - one hash); the Algorand and TON notes no longer call `dt:root` the - canonical form. It also lists ZIP-32 as a known limitation: `zip32` - parses, but no network registers it, so strict parsing refuses it. Both - behaviours are unchanged and now pinned by tests. - - **Strict validation refuses curve, purpose and format combinations no wallet can derive.** It checked the algorithm, the format and the derivation type each on its own, so it accepted SLIP-10 ed25519 paths @@ -98,35 +89,6 @@ of 2^31 or more no longer parses. or bech32, `bip86` p2tr or bech32m); and Cosmos `bip44` with coin `118'`. A Bitcoin URN without `af` stays valid; SPEC.md no longer claims strict mode requires it. Lenient parsing is unchanged. - -### Fixed - -- **No nil dereference on a zero or partial `Address`.** `String()`, - `NSS()`, the hashes, `Algorithm()` and `Format()` panicked on the zero - `Address` or one built with a nil chain, and `SetDerivationPath` panicked - on an address built without a path. They now treat a missing chain as the - zero chain (`urn:mhda:nt::ci:`, as the C++ port's default address) and a - missing path as root; `SetCoinType` without a chain returns - `ErrUninitializedAddress`. -- **An `Address` held by value encodes as its URN.** `MarshalText` had a - pointer receiver, so an `Address` struct field or map value was encoded - by `encoding/json` and `encoding/xml` as an empty object (`{"A":{}}`), - which then failed to decode. `MarshalText` now has a value receiver. A - nil `*Address` is still encoded by the codec (as `null`); calling - `MarshalText` directly on a nil pointer now panics like any value method - instead of returning `ErrUninitializedAddress`. -- **The lookup helpers wrap their sentinels.** `AlgorithmFromString`, - `FormatFromString` and `NetworkTypeFromString` returned plain - `errors.New` values, so `errors.Is` could not tell them apart, unlike - `DerivationTypeFromString` and the parsers. They now wrap - `ErrInvalidAlgorithm`, `ErrInvalidFormat` and `ErrInvalidNetworkType`. -- **Setters and lookup helpers normalise ASCII only.** They trimmed with - `strings.TrimSpace` and lowercased with `strings.ToLower`, which are - Unicode-aware: `SetAddressAlgorithm("secp256\u212a1")` (Kelvin sign) - was accepted as `secp256k1`, and NBSP or ideographic spaces around a - derivation type, path, format or coin type were trimmed, while the URN - parser and the C++ port refuse the same bytes. They now trim ASCII - whitespace and fold ASCII case only. - **No whitespace inside the NSS.** Each value was trimmed, so `urn:mhda:nt:evm:ci: 1 :dt: bip44 :...` parsed like the URN without the spaces, against SPEC §6.1. ASCII whitespace is now trimmed only around the @@ -141,6 +103,16 @@ of 2^31 or more no longer parses. `ErrInvalidNSS` when parsed and `ErrInvalidValue` from the setters and `NewChain`. `%` is refused because percent-encoding is not supported and `%41` would be a second spelling of `A`. + +### Fixed + +- **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the + CIP-1852 role accept any level index, but the parsed value was truncated + to a byte: `m/1852'/1815'/0'/256/0` parsed as role 0, so it named the + role-0 key, re-serialised as `m/1852'/1815'/0'/0/0`, and `Levels()` + returned the truncated value. The full value is now kept in `Charge()`, + `Levels()` and `String()`. Code that converts `Charge()` to `uint8` must + widen its own variable. - **No stale or mixed derivation state.** `ParsePath` updated the fields of the path it was given: re-parsing a 4-level ZIP-32 path with a 3-level one kept the old index (`m/32'/133'/1'` read back as `m/32'/133'/1'/5`), @@ -165,10 +137,41 @@ of 2^31 or more no longer parses. changed it changed the path; it returns a copy. `NewAddress` stored the caller's chain and path, so two addresses built from them changed together; it keeps copies. -- **`ChargeType` is 32 bits wide (was `uint8`).** The CIP-11 charge and the - CIP-1852 role accept any level index, but the parsed value was truncated - to a byte: `m/1852'/1815'/0'/256/0` parsed as role 0, so it named the - role-0 key, re-serialised as `m/1852'/1815'/0'/0/0`, and `Levels()` - returned the truncated value. The full value is now kept in `Charge()`, - `Levels()` and `String()`. Code that converts `Charge()` to `uint8` must - widen its own variable. +- **No nil dereference on a zero or partial `Address`.** `String()`, + `NSS()`, the hashes, `Algorithm()` and `Format()` panicked on the zero + `Address` or one built with a nil chain, and `SetDerivationPath` panicked + on an address built without a path. They now treat a missing chain as the + zero chain (`urn:mhda:nt::ci:`, as the C++ port's default address) and a + missing path as root; `SetCoinType` without a chain returns + `ErrUninitializedAddress`. +- **An `Address` held by value encodes as its URN.** `MarshalText` had a + pointer receiver, so an `Address` struct field or map value was encoded + by `encoding/json` and `encoding/xml` as an empty object (`{"A":{}}`), + which then failed to decode. `MarshalText` now has a value receiver. A + nil `*Address` is still encoded by the codec (as `null`); calling + `MarshalText` directly on a nil pointer now panics like any value method + instead of returning `ErrUninitializedAddress`. +- **The lookup helpers wrap their sentinels.** `AlgorithmFromString`, + `FormatFromString` and `NetworkTypeFromString` returned plain + `errors.New` values, so `errors.Is` could not tell them apart, unlike + `DerivationTypeFromString` and the parsers. They now wrap + `ErrInvalidAlgorithm`, `ErrInvalidFormat` and `ErrInvalidNetworkType`. +- **Setters and lookup helpers normalise ASCII only.** They trimmed with + `strings.TrimSpace` and lowercased with `strings.ToLower`, which are + Unicode-aware: `SetAddressAlgorithm("secp256\u212a1")` (Kelvin sign) + was accepted as `secp256k1`, and NBSP or ideographic spaces around a + derivation type, path, format or coin type were trimmed, while the URN + parser and the C++ port refuse the same bytes. They now trim ASCII + whitespace and fold ASCII case only. + +### Documentation + +- SPEC.md states that an explicit `dt:root` is folded away (root is the + default and has no path, so a root address has one canonical form and + one hash); the Algorand and TON notes no longer call `dt:root` the + canonical form. It also lists ZIP-32 as a known limitation: `zip32` + parses, but no network registers it, so strict parsing refuses it. Both + behaviours are unchanged and now pinned by tests. +- SPEC.md notes that an EVM chain id is opaque: `ci:1`, `ci:0x1` and + `ci:01` are three chain keys for one chain, and a producer must keep to + one spelling. diff --git a/SPEC.md b/SPEC.md index c9c0596..fb73174 100644 --- a/SPEC.md +++ b/SPEC.md @@ -181,7 +181,10 @@ strict validation: `bip44` p2pkh, `bip49` p2sh, `bip84` p2wpkh or bech32, #### Ethereum and EVM clones (`evm`) Single canonical format (hex). Chain ID typically a numeric chain ID such as -`1`, `0xa86a`, `0x10`. +`1`, `0xa86a`, `0x10`. The chain id is opaque: MHDA does not canonicalise +it, so `ci:1`, `ci:0x1` and `ci:01` are three different chain keys (and +hashes) for one chain. Chain keys compare as strings; a producer must keep to +one spelling for a chain (the EIP-155 decimal form is the usual choice). #### Avalanche (`avalanche`) C-Chain uses hex (EVM-compatible); X/P-Chain use bech32 with HRPs `X-avax`, From 4119e14cd3f9bbcecbd2ddea3d6975c5ff1321f6 Mon Sep 17 00:00:00 2001 From: x88 Date: Mon, 5 Oct 2026 13:10:38 +0300 Subject: [PATCH 21/21] Spell the Unicode test inputs as escapes Two test inputs held the Kelvin sign, a no-break space and an ideographic space as literal characters, which look like a K and plain spaces in the source. They are now written as \u escapes; the bytes the tests use are unchanged. --- hardening_test.go | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/hardening_test.go b/hardening_test.go index 0c068ec..70a606e 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -213,7 +213,7 @@ func TestProgrammaticValuesCannotInjectComponents(t *testing.T) { {EthereumVM, "1?=q", ErrInvalidValue}, {EthereumVM, "1#f", ErrInvalidValue}, {EthereumVM, "a b", ErrInvalidValue}, - {EthereumVM, " 1", ErrInvalidValue}, + {EthereumVM, "\u00a01", ErrInvalidValue}, {EthereumVM, "", ErrMissingChainID}, {EthereumVM, " \t", ErrMissingChainID}, {NetworkType("evm:ci:1:dt:bip44"), "1", ErrInvalidNetworkType}, @@ -309,7 +309,7 @@ func TestFromStringHelpersWrapSentinels(t *testing.T) { // C++ port. A Unicode space is not trimmed and a letter that lowercases to // ASCII (the Kelvin sign) is not folded: both are malformed input. func TestNormalisationIsASCIIOnly(t *testing.T) { - const kelvin, nbsp, ideo = "K", " ", " " + const kelvin, nbsp, ideo = "\u212a", "\u00a0", "\u3000" addr := mustAddress(t, `urn:mhda:nt:evm:ci:1:dt:bip44:dp:m/44'/60'/0'/0/0`) for name, err := range map[string]error{ "AlgorithmFromString": func() error { _, e := AlgorithmFromString("secp256" + kelvin + "1"); return e }(),