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 diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..234e008 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,177 @@ +# 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 + +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 + +- **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). +- **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. +- **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. +- **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. +- **`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. +- **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. +- **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. +- **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`. +- **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`. + +### 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`), + 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. +- **`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. +- **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 1b9aafc..fb73174 100644 --- a/SPEC.md +++ b/SPEC.md @@ -19,7 +19,16 @@ urn:mhda:nt::ci::ct::dt::dp::aa:\^`{|}[]?#``) — 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 @@ -101,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 @@ -142,13 +173,18 @@ 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 -`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`, @@ -157,6 +193,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'`, @@ -164,7 +202,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 @@ -175,11 +215,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: @@ -191,7 +234,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 @@ -202,9 +247,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 @@ -231,7 +276,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-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 | @@ -240,11 +285,24 @@ 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 +`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. @@ -255,6 +313,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 | @@ -298,11 +364,16 @@ 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. +- 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. @@ -318,6 +389,27 @@ 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 +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: @@ -346,9 +438,9 @@ 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 outside the §1.5 byte set | | `ErrInvalidDerivationType` | `dt` value not registered | -| `ErrInvalidDerivationPath` | `dp` does not match the regex of `dt` | +| `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 | @@ -398,6 +490,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 @@ -430,7 +532,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`. @@ -443,13 +547,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/address.go b/address.go index 5629437..80ee843 100644 --- a/address.go +++ b/address.go @@ -1,15 +1,31 @@ package go_mhda -import ( - "errors" - "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 ( @@ -84,7 +100,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 +116,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/chain.go b/chain.go index ef1dea8..41b70c7 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 @@ -39,6 +54,11 @@ func NewChain(networkType NetworkType, chainId ChainId) *Chain { // input must BE the canonical string. func ChainFromKey(chainKey ChainKey) (*Chain, error) { trimmed := asciiTrim(string(chainKey)) + // A dangling token is residue like any other: the input is not the + // canonical key, whatever else it carries. + if trimmed != "" && strings.Count(trimmed, ":")%2 == 0 { + return nil, fmt.Errorf("%w: not a sequence of key:value pairs: %q", ErrInvalidChainKey, trimmed) + } components, err := parseNSS(trimmed) if err != nil { return nil, err @@ -66,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 } @@ -91,7 +112,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 } @@ -101,7 +122,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 } @@ -131,8 +152,40 @@ 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 } +// 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 { + 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/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/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/compatibility.go b/compatibility.go index 1af5cd8..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). @@ -203,6 +230,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) @@ -226,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/derivation_path.go b/derivation_path.go index 95f8513..a266e70 100644 --- a/derivation_path.go +++ b/derivation_path.go @@ -59,8 +59,18 @@ func DerivationTypeFromString(src string) (DerivationType, error) { type AccountIndex uint32 -type ChargeType uint8 - +// 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 +// 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 @@ -85,8 +95,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") } @@ -99,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 @@ -108,8 +122,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{ @@ -117,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 @@ -269,7 +318,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) @@ -287,8 +350,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) } @@ -385,6 +451,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 @@ -508,15 +577,20 @@ 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. // 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/fuzz_test.go b/fuzz_test.go index ff97d2f..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) + } }) } @@ -69,10 +74,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 +101,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,13 +131,26 @@ 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 { + 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() }) } // 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:]) @@ -138,6 +158,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) } @@ -150,7 +172,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/hardening_test.go b/hardening_test.go index c0fe8af..70a606e 100644 --- a/hardening_test.go +++ b/hardening_test.go @@ -179,3 +179,222 @@ 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, "\u00a01", 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) + } +} + +// 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) + } + } +} + +// 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) + } +} + +// 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 = "\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 }(), + "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) + } +} + +// 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) + } +} + +// 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/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/mhda.go b/mhda.go index 5f10281..780bebf 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] @@ -82,10 +85,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 { @@ -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,32 +150,57 @@ 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. +// 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{} - } + dt = normalize(dt) + 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 } +// 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 a.path == nil || a.path.derivationType == ROOT { + if p := asciiTrim(dp); p != `` { + return fmt.Errorf("%w: root derivation must have empty path, got %q", ErrInvalidDerivationPath, p) + } return nil } @@ -176,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) @@ -190,9 +222,13 @@ 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 { - ct = strings.TrimSpace(ct) + if a.chain == nil { + return ErrUninitializedAddress + } + ct = asciiTrim(ct) if ct == `` { a.chain.ClearCoinType() return nil @@ -207,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) } } @@ -223,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 @@ -237,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 @@ -319,20 +353,29 @@ 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 not ROOT. - if a.path != nil && a.path.derivationType != ROOT { + // 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. @@ -397,14 +440,28 @@ 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 { + 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/mhda_test.go b/mhda_test.go index 2bac992..3b76a2f 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) @@ -895,6 +898,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). @@ -1307,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) } @@ -1717,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) { 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 { diff --git a/parser.go b/parser.go index 37bcbd9..8013f9e 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 @@ -86,18 +86,47 @@ 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) } -// 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. +// asciiSpace is the ASCII whitespace asciiTrim removes. +const asciiSpace = " \t\n\v\f\r" + +// 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 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 !nssByte(key[i]) { + return fmt.Errorf("%w: byte %q not allowed in component key %q", ErrInvalidNSS, key[i], key) } } return nil @@ -122,7 +151,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 @@ -142,8 +174,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 @@ -157,47 +196,61 @@ 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. 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, +// 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. func parseNSS(nss string) (map[string]string, error) { - parts := strings.Split(nss, ":") components := make(map[string]string, len(componentsNames)) + 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]) + } - 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 - // 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 } + if _, ok := knownComponents[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 + } 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/state_test.go b/state_test.go new file mode 100644 index 0000000..9dae84e --- /dev/null +++ b/state_test.go @@ -0,0 +1,285 @@ +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) + } +} + +// 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() +} + +// 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) + } +} diff --git a/testdata/dp_conformance.txt b/testdata/dp_conformance.txt new file mode 100644 index 0000000..5adba1d --- /dev/null +++ b/testdata/dp_conformance.txt @@ -0,0 +1,472 @@ +# 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' + +# 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' diff --git a/testdata/urn_conformance.txt b/testdata/urn_conformance.txt new file mode 100644 index 0000000..3212e3d --- /dev/null +++ b/testdata/urn_conformance.txt @@ -0,0 +1,145 @@ +# 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; 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 +# 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 +# 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 + +# 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 + +# '?' 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 + +# 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 + +# 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 + +# 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 diff --git a/urn_conformance_test.go b/urn_conformance_test.go new file mode 100644 index 0000000..43c77ae --- /dev/null +++ b/urn_conformance_test.go @@ -0,0 +1,110 @@ +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, + "incompatible": ErrIncompatible, +} + +// 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" && fields[1] != "strict") { + 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 + switch fields[1] { + case "nss": + parse = ParseNSS + case "strict": + parse = ParseURNStrict + } + 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) + } +}