Enforce 5-byte NanoNym checksums to prevent mixed decode behavior

Hard-cut over NanoNym v2 address validation to a full 5-byte checksum so encoding, decoding, tests, and spec stay consistent and deterministic. Keep the scalar clamping rationale in crypto derivation to document why modulo reduction preserves the same group results.

Author: cbrunnkvist

docs/rfcs/0001-nanonym-v2-address-format.md

@@ -56,7 +56,7 @@ It does not contain funds, balances, transaction history, relay client configura
 | 33..64  | B_view             | 32 bytes | view pubkey      | Ed25519          |
 | 65..66  | notificationUriLen | 2 bytes  | URI length       | uint16 BE        |
 | 67..N   | notificationUri    | variable | Tier 1 route     | UTF-8            |
-| N+1..N+2| checksum           | 2 bytes  | integrity check  | BLAKE2b-derived  |
+| N+1..N+5| checksum           | 5 bytes  | integrity check  | BLAKE2b-derived  |
 +---------+--------------------+----------+------------------+------------------+
 ```
 

packages/crypto/src/index.ts

@@ -126,9 +126,18 @@ function deriveTweakScalar(sharedSecret: Uint8Array): Uint8Array {
 function blake2bToScalar(input: Uint8Array): Uint8Array {
   const hash64 = blake2b(input, undefined, 64);
   const clamped = new Uint8Array(hash64.slice(0, 32));
+  
+  // Note on Scalar Clamping:
+  // Setting the 254th bit (|= 64) produces an integer larger than the Ed25519 group order `L`. 
+  // The subsequent `% ED25519_L` operation strips this bit, which might appear to defeat the 
+  // purpose of standard Ed25519 clamping. However, because Ed25519 scalar multiplication is 
+  // inherently modular—`(s) * G == (s mod L) * G`—the resulting points and shared secrets 
+  // remain mathematically identical and fully secure. This ensures consistent derivation 
+  // across libraries, even if the scalar clamping is technically redundant before the modulo operation.
   clamped[0] &= 248;
   clamped[31] &= 127;
   clamped[31] |= 64;
+  
   return bigIntToBytesLE(bytesToBigIntLE(clamped) % ED25519_L, 32);
 }
 

packages/protocol/src/internal.ts

@@ -63,7 +63,7 @@ export function decodeNanoBase32(encoded: string): Uint8Array {
 }
 
 export function computeChecksum(payload: Uint8Array): Uint8Array {
-  return new Uint8Array(blake2b(payload, undefined, 5).slice(0, 2));
+  return new Uint8Array(blake2b(payload, undefined, 5));
 }
 
 export function encodeNanoNymAddress(input: NanoNymAddress): string {
@@ -131,7 +131,7 @@ function encodePayload(input: NanoNymAddress): Uint8Array {
   }
 
   const checksumOffset = 67 + uriBytes.length;
-  const payload = new Uint8Array(checksumOffset + 2);
+  const payload = new Uint8Array(checksumOffset + 5);
 
   payload[0] = NANO_NYM_VERSION;
   payload.set(input.spendPublicKey, 1);
@@ -148,9 +148,9 @@ function decodePayload(payload: Uint8Array): NanoNymAddress {
   const uriLength = (payload[65] << 8) | payload[66];
   const checksumOffset = 67 + uriLength;
 
-  if (payload.length !== checksumOffset + 2) {
+  if (payload.length !== checksumOffset + 5) {
     throw new Error(
-      `Invalid NanoNym payload length: expected ${checksumOffset + 2}, got ${payload.length}`,
+      `Invalid NanoNym payload length: expected ${checksumOffset + 5}, got ${payload.length}`,
     );
   }
 
@@ -168,7 +168,7 @@ function decodePayload(payload: Uint8Array): NanoNymAddress {
 
 function verifyChecksum(payload: Uint8Array, checksumOffset: number): void {
   const expected = computeChecksum(payload.slice(0, checksumOffset));
-  const actual = payload.slice(checksumOffset, checksumOffset + 2);
+  const actual = payload.slice(checksumOffset, checksumOffset + 5);
 
   if (!equalBytes(expected, actual)) {
     throw new Error("Invalid NanoNym address checksum");

packages/protocol/test/protocol.test.mjs

@@ -5,6 +5,7 @@ import {
   NANO_NYM_PAYMENT_EVENT_VERSION,
   NANO_NYM_VERSION,
   computeChecksum,
+  encodeNanoBase32,
   decodeNanoNymAddress,
   encodeNanoNymAddress,
   isNanoNymAddress,
@@ -66,7 +67,30 @@ test("computes deterministic checksums", () => {
   const payload = new Uint8Array([1, 2, 3, 4, 5]);
 
   assert.deepEqual(computeChecksum(payload), computeChecksum(payload));
-  assert.equal(computeChecksum(payload).length, 2);
+  assert.equal(computeChecksum(payload).length, 5);
+});
+
+test("rejects legacy 2-byte checksum NanoNym payloads", () => {
+  const input = {
+    version: NANO_NYM_VERSION,
+    spendPublicKey: bytes(7),
+    viewPublicKey: bytes(8),
+    notificationUri: "nostr:npub1legacychecksum",
+  };
+  const uriBytes = new TextEncoder().encode(input.notificationUri);
+  const checksumOffset = 67 + uriBytes.length;
+  const legacyPayload = new Uint8Array(checksumOffset + 2);
+
+  legacyPayload[0] = input.version;
+  legacyPayload.set(input.spendPublicKey, 1);
+  legacyPayload.set(input.viewPublicKey, 33);
+  legacyPayload[65] = (uriBytes.length >>> 8) & 0xff;
+  legacyPayload[66] = uriBytes.length & 0xff;
+  legacyPayload.set(uriBytes, 67);
+  legacyPayload.set(computeChecksum(legacyPayload.slice(0, checksumOffset)).slice(0, 2), checksumOffset);
+
+  const legacyAddress = `nnym_${encodeNanoBase32(legacyPayload)}`;
+  assert.throws(() => decodeNanoNymAddress(legacyAddress), /payload length/);
 });
 
 test("validates NanoNym payment events", () => {