nip44: fix pseudocode bugs, comment arithmetic, add implementation guidance and test vectors

1 files changed, 40 insertions, 5 deletions

diff --git a/44.md b/44.md
index 4fe3cc1..fcf6009 100644
--- a/44.md
+++ b/44.md
@@ -132,6 +132,17 @@ validation rules, refer to BIP-340.
    - Verify that the length of sliced plaintext matches the decoded length
    - Verify that calculated padding from step 3 of the [encryption](#Encryption) process matches the actual padding
 
+### Implementation considerations
+
+The theoretical maximum plaintext size is 2^32 - 1 bytes (~4 GB). Implementations SHOULD enforce
+their own maximum payload size based on platform and resource constraints, rejecting oversized payloads
+early in `decode_payload` (before base64 decoding) to prevent denial-of-service. Decryption may require
+several times the payload size in working memory due to base64 decoding, byte array slicing, and
+padding operations. For reference, JVM-based systems are limited to ~2 GB contiguous arrays, and mobile
+devices may have significantly less available memory. Note that `calc_padded_len` can return values up
+to 2^32, which exceeds the range of unsigned 32-bit integers; implementations must use 64-bit (or
+larger) arithmetic for padding calculations.
+
 ### Details
 
 - Cryptographic methods
@@ -184,7 +195,7 @@ def calc_padded_len(unpadded_len):
   if unpadded_len <= 32:
     return 32
   else:
-    return chunk * (floor((len - 1) / chunk) + 1)
+    return chunk * (floor((unpadded_len - 1) / chunk) + 1)
 
 # Converts unpadded plaintext to padded bytearray
 def pad(plaintext):
@@ -216,11 +227,11 @@ def unpad(padded):
 
 # metadata: always 65b (version: 1b, nonce: 32b, mac: 32b)
 # plaintext: 1b to 0xffffffff
-# padded plaintext (small, <65536): 32b to 0xffff, with 2b prefix -> 34b to 0xffff+2
-# padded plaintext (large, >=65536): 0x10000 to 0xffffffff, with 6b prefix -> 0x10006 to 0xffffffff+6
+# padded plaintext (small, <65536): 32b to 0x10000, with 2b prefix -> 34b to 0x10000+2
+# padded plaintext (large, >=65536): 0x10000 to 0x100000000, with 6b prefix -> 0x10006 to 0x100000000+6
 # ciphertext: same as padded plaintext (chacha20 doesn't change length)
-# raw payload (small): 99 (65+34) to 65603 (65+0xffff+2)
-# raw payload (large): 65607 (65+0x10006) to 4294967362 (65+0xffffffff+6)
+# raw payload (small): 99 (65+34) to 65603 (65+0x10000+2)
+# raw payload (large): 65607 (65+0x10006) to 4294967367 (65+0x100000000+6)
 def decode_payload(payload):
   plen = len(payload)
   if plen == 0 or payload[0] == '#': raise Exception('unknown version')
@@ -313,3 +324,27 @@ The file also contains intermediate values. A quick guidance with regards to its
 - `invalid.encrypt_msg_lengths`
 - `invalid.get_conversation_key`: calculating conversation_key must throw an error
 - `invalid.decrypt`: decrypting message content must throw an error
+
+#### Extended length prefix test vectors
+
+The following test vectors exercise the boundary between the 2-byte u16 prefix and the 6-byte
+extended prefix. Since the payloads are too large to include inline, SHA-256 checksums of the
+plaintext and base64-encoded payload are provided (following the `encrypt_decrypt_long_msg` pattern).
+
+All vectors use the same `conversation_key` and `nonce` as above. Plaintext is the byte `0x61`
+(`'a'`) repeated to the specified length.
+
+```
+conversation_key: c41c775356fd92eadc63ff5a0dc1da211b268cbea22316767095b2871ea1412d
+nonce:            0000000000000000000000000000000000000000000000000000000000000001
+```
+
+| plaintext_len | prefix | padded_len | plaintext_sha256 | payload_sha256 |
+|---|---|---|---|---|
+| 65535 | u16 (2 bytes) | 65536 | `6e1bebca6a8229364a162a72ef064826c4cd7457bf54f190ef782bd9deff3e42` | `6d8c2810d1e870fbaa1f0a0937126cca837a15f9260e27060c331d70a3c0bc84` |
+| 65536 | extended (6 bytes) | 65536 | `bf718b6f653bebc184e1479f1935b8da974d701b893afcf49e701f3e2f9f9c5a` | `b7b4edb36ba92e267d322d56d9aebc22e7fa96ff52e3c12adc07f07a43cbc616` |
+| 65537 | extended (6 bytes) | 81920 | `008ffc88d3c96a9f307524eb361e47c5222a887fc45fa0c1fb8d429c5c23b430` | `eeb7c7c5373894ea2c1547cfd3ccb15d5a0b2d619da852e5c79df792dcc9e435` |
+
+Note that 65535 and 65536 both have a `padded_len` of 65536, but the total padded-with-prefix
+sizes differ: 65538 (2 + 65536) vs 65542 (6 + 65536). The jump to 65537 triggers the next
+padding bucket at 81920.