libp2r2p 0.2.0 → 0.3.0

package/README.md

@@ -174,3 +174,16 @@ clearing is asynchronous too: `await messenger.clearChannel(channelPubkey)`.
 Use explicit subpath imports for bundle size. The package root re-exports the
 main messenger API for convenience, but applications that only need one piece
 should import that subpath directly.
+
+## Binary encodings
+
+Base16, Base36, Base62, Base64/Base64URL, and Base93 helpers are available
+through their matching `libp2r2p/<encoding>` subpaths. Base36 exposes both a
+binary-safe variable-width codec and the canonical 32-byte/50-character
+NsiteBase36 representation from NIP-5A. Base62 uses the same case-sensitive
+alphabet as app NIP-19 entities; its default byte mode preserves leading zero
+bytes, while integer mode supports fixed-width identifiers.
+
+In NIP-5A, "no padding" means that no separate padding character such as `=`
+is used. Leading `0` digits are nevertheless required to make every Nsite
+Base36 value exactly 50 characters long.

package/base16/index.js

@@ -5,8 +5,13 @@ export function bytesToBase16 (bytes) {
 }
 
 export function base16ToBytes (base16) {
+  if (typeof base16 !== 'string') throw new TypeError('Base16 value should be a string')
+  if (base16.length % 2 !== 0) throw new Error('Invalid Base16 length')
+  if (!/^[0-9a-f]*$/i.test(base16)) throw new Error('Invalid Base16 character')
   const out = new Uint8Array(base16.length / 2)
-  for (let i = 0; i < out.length; i++) out[i] = parseInt(base16.slice(i * 2, i * 2 + 2), 16)
+  for (let i = 0; i < out.length; i++) {
+    out[i] = Number.parseInt(base16.slice(i * 2, i * 2 + 2), 16)
+  }
   return out
 }
 

package/base36/index.js

@@ -0,0 +1,114 @@
+import { base16ToBytes, bytesToBase16 } from '../base16/index.js'
+
+export const BASE36_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+
+const BASE = BigInt(BASE36_ALPHABET.length)
+const LEADER = BASE36_ALPHABET[0]
+const CHAR_MAP = new Map(
+  [...BASE36_ALPHABET].map((character, index) => [character, BigInt(index)])
+)
+const NSITE_BYTE_LENGTH = 32
+const NSITE_TEXT_LENGTH = 50
+const MAX_NSITE_VALUE = (1n << 256n) - 1n
+
+function bytesToInteger (bytes) {
+  let number = 0n
+  for (const byte of bytes) number = (number << 8n) + BigInt(byte)
+  return number
+}
+
+function integerToBase36 (number) {
+  let result = ''
+  while (number > 0n) {
+    result = BASE36_ALPHABET[Number(number % BASE)] + result
+    number /= BASE
+  }
+  return result || LEADER
+}
+
+function parseBase36Integer (value) {
+  let number = 0n
+  for (const character of value) {
+    const digit = CHAR_MAP.get(character)
+    if (digit === undefined) throw new Error('Invalid Base36 character: ' + character)
+    number = number * BASE + digit
+  }
+  return number
+}
+
+function integerToMinimalBytes (number) {
+  if (number === 0n) return new Uint8Array([0])
+  const bytes = []
+  while (number > 0n) {
+    bytes.unshift(Number(number & 0xffn))
+    number >>= 8n
+  }
+  return Uint8Array.from(bytes)
+}
+
+// A binary-safe Base36 codec. Every leading zero byte is represented by a
+// leading zero character, making arbitrary byte arrays round-trip exactly.
+export function bytesToBase36 (bytes) {
+  if (bytes.length === 0) return ''
+
+  const number = bytesToInteger(bytes)
+  let result = number === 0n ? '' : integerToBase36(number)
+  let leadingZeros = 0
+  while (leadingZeros < bytes.length && bytes[leadingZeros] === 0) leadingZeros++
+  result = LEADER.repeat(leadingZeros) + result
+  return result
+}
+
+export function base36ToBytes (value) {
+  if (typeof value !== 'string') throw new TypeError('Base36 value should be a string')
+  if (value.length === 0) return new Uint8Array()
+
+  let leadingZeros = 0
+  while (value[leadingZeros] === LEADER) leadingZeros++
+  const number = parseBase36Integer(value)
+  const suffix = number === 0n ? new Uint8Array() : integerToMinimalBytes(number)
+  const result = new Uint8Array(leadingZeros + suffix.length)
+  result.set(suffix, leadingZeros)
+  return result
+}
+
+export function base16ToBase36 (value) {
+  return bytesToBase36(base16ToBytes(value))
+}
+
+export function base36ToBase16 (value) {
+  return bytesToBase16(base36ToBytes(value))
+}
+
+// NIP-5A treats a raw 32-byte value as one unsigned integer and represents it
+// as exactly 50 lowercase Base36 digits. Its leading zeros are numeric width,
+// not zero-byte markers as they are in the binary-safe codec above.
+export function bytesToNsiteBase36 (bytes) {
+  if (bytes.length !== NSITE_BYTE_LENGTH) {
+    throw new Error('Nsite Base36 input should be ' + NSITE_BYTE_LENGTH + ' bytes')
+  }
+  return integerToBase36(bytesToInteger(bytes)).padStart(NSITE_TEXT_LENGTH, LEADER)
+}
+
+export function nsiteBase36ToBytes (value) {
+  if (typeof value !== 'string') throw new TypeError('Nsite Base36 value should be a string')
+  if (value.length !== NSITE_TEXT_LENGTH) {
+    throw new Error('Nsite Base36 value should be ' + NSITE_TEXT_LENGTH + ' characters')
+  }
+  if (!/^[0-9a-z]+$/.test(value)) throw new Error('Invalid Nsite Base36 character')
+
+  const number = parseBase36Integer(value)
+  if (number > MAX_NSITE_VALUE) throw new Error('Nsite Base36 value exceeds 32 bytes')
+  const bytes = integerToMinimalBytes(number)
+  const result = new Uint8Array(NSITE_BYTE_LENGTH)
+  if (number !== 0n) result.set(bytes, NSITE_BYTE_LENGTH - bytes.length)
+  return result
+}
+
+export function base16ToNsiteBase36 (value) {
+  return bytesToNsiteBase36(base16ToBytes(value))
+}
+
+export function nsiteBase36ToBase16 (value) {
+  return bytesToBase16(nsiteBase36ToBytes(value))
+}

package/base62/index.js

@@ -0,0 +1,127 @@
+import { base16ToBytes, bytesToBase16 } from '../base16/index.js'
+
+export const BASE62_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
+
+const BASE = BigInt(BASE62_ALPHABET.length)
+const LEADER = BASE62_ALPHABET[0]
+const CHAR_MAP = new Map(
+  [...BASE62_ALPHABET].map((character, index) => [character, BigInt(index)])
+)
+
+function readOptions (options, allowedKeys) {
+  if (options === undefined) return {}
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new TypeError('Base62 options should be an object')
+  }
+  for (const key of Object.keys(options)) {
+    if (!allowedKeys.includes(key)) throw new Error('Unknown Base62 option: ' + key)
+  }
+  return options
+}
+
+function readMode (mode = 'bytes') {
+  if (mode !== 'bytes' && mode !== 'integer') throw new Error('Invalid Base62 mode: ' + mode)
+  return mode
+}
+
+function readLength (value, name, defaultValue, minimum = 0) {
+  if (value === undefined) return defaultValue
+  if (!Number.isSafeInteger(value) || value < minimum) {
+    const qualifier = minimum === 0 ? 'non-negative' : 'positive'
+    throw new RangeError('Base62 ' + name + ' should be a ' + qualifier + ' safe integer')
+  }
+  return value
+}
+
+function bytesToInteger (bytes) {
+  let number = 0n
+  for (const byte of bytes) number = (number << 8n) + BigInt(byte)
+  return number
+}
+
+function integerToBase62 (number) {
+  let result = ''
+  while (number > 0n) {
+    result = BASE62_ALPHABET[Number(number % BASE)] + result
+    number /= BASE
+  }
+  return result || LEADER
+}
+
+function parseBase62Integer (value) {
+  let number = 0n
+  for (const character of value) {
+    const digit = CHAR_MAP.get(character)
+    if (digit === undefined) throw new Error('Invalid Base62 character: ' + character)
+    number = number * BASE + digit
+  }
+  return number
+}
+
+function integerToMinimalBytes (number) {
+  if (number === 0n) return new Uint8Array([0])
+  const bytes = []
+  while (number > 0n) {
+    bytes.unshift(Number(number & 0xffn))
+    number >>= 8n
+  }
+  return Uint8Array.from(bytes)
+}
+
+// Byte mode preserves every leading zero byte. Integer mode treats the input
+// as an unsigned big-endian value and supports fixed-width textual output.
+export function bytesToBase62 (bytes, options) {
+  const { mode: rawMode, minLength: rawMinLength } = readOptions(options, ['mode', 'minLength'])
+  const mode = readMode(rawMode)
+  if (mode === 'bytes' && rawMinLength !== undefined) {
+    throw new Error('Base62 minLength requires integer mode')
+  }
+  if (mode === 'integer') {
+    if (bytes.length === 0) throw new Error('Base62 integer input should not be empty')
+    const minLength = readLength(rawMinLength, 'minLength', 0)
+    return integerToBase62(bytesToInteger(bytes)).padStart(minLength, LEADER)
+  }
+  if (bytes.length === 0) return ''
+
+  const number = bytesToInteger(bytes)
+  let result = number === 0n ? '' : integerToBase62(number)
+  let leadingZeros = 0
+  while (leadingZeros < bytes.length && bytes[leadingZeros] === 0) leadingZeros++
+  result = LEADER.repeat(leadingZeros) + result
+  return result
+}
+
+export function base62ToBytes (value, options) {
+  if (typeof value !== 'string') throw new TypeError('Base62 value should be a string')
+  const { mode: rawMode, byteLength: rawByteLength } = readOptions(options, ['mode', 'byteLength'])
+  const mode = readMode(rawMode)
+  if (mode === 'bytes' && rawByteLength !== undefined) {
+    throw new Error('Base62 byteLength requires integer mode')
+  }
+  if (mode === 'integer') {
+    if (value.length === 0) throw new Error('Base62 integer value should not be empty')
+    const byteLength = readLength(rawByteLength, 'byteLength', undefined, 1)
+    const bytes = integerToMinimalBytes(parseBase62Integer(value))
+    if (byteLength === undefined) return bytes
+    if (bytes.length > byteLength) throw new Error('Base62 integer exceeds ' + byteLength + ' bytes')
+    const result = new Uint8Array(byteLength)
+    result.set(bytes, byteLength - bytes.length)
+    return result
+  }
+
+  let leadingZeros = 0
+  while (value[leadingZeros] === LEADER) leadingZeros++
+  const number = parseBase62Integer(value)
+  const suffix = number === 0n ? new Uint8Array() : integerToMinimalBytes(number)
+  const result = new Uint8Array(leadingZeros + suffix.length)
+  result.set(suffix, leadingZeros)
+  return result
+}
+
+export function base16ToBase62 (value, options) {
+  return bytesToBase62(base16ToBytes(value), options)
+}
+
+export function base62ToBase16 (value, options) {
+  return bytesToBase16(base62ToBytes(value, options))
+}

package/base64/index.js

@@ -3,6 +3,9 @@
 // base64 is useful for WebAuthn credential IDs and URL/query-string material.
 
 export function bytesToBase64 (bytes) {
+  if (typeof Buffer === 'function' && typeof Buffer.from === 'function') {
+    return Buffer.from(bytes).toString('base64')
+  }
   let s = ''
   for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i])
   return btoa(s)

package/index.js

@@ -1,6 +1,8 @@
 export * from './private-messenger/index.js'
 
 export * as base16 from './base16/index.js'
+export * as base36 from './base36/index.js'
+export * as base62 from './base62/index.js'
 export * as base64 from './base64/index.js'
 export * as contentKey from './content-key/index.js'
 export * as contentKeyEvent from './content-key/event/index.js'

package/nip19/index.js

@@ -1,15 +1,9 @@
 import { bech32 } from '@scure/base'
+import { BASE62_ALPHABET, base62ToBytes, bytesToBase62 } from '../base62/index.js'
 
 const MAX_ENTITY_SIZE = 5000
 const MAX_TLV_VALUE_SIZE = 255
 const NOSTR_APP_D_TAG_MAX_LENGTH = 260
-const BASE62_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
-const BASE62_BASE = BigInt(BASE62_ALPHABET.length)
-const BASE62_LEADER = BASE62_ALPHABET[0]
-const BASE62_CHAR_MAP = new Map(
-  [...BASE62_ALPHABET].map((character, index) => [character, BigInt(index)])
-)
-
 export const NAPP_ENTITY_REGEX = new RegExp(
   `^\\+{1,3}[${BASE62_ALPHABET}]{48,${MAX_ENTITY_SIZE}}$`
 )
@@ -178,45 +172,6 @@ export function nfileDecode (entity) {
   return result
 }
 
-function bytesToBase62 (bytes) {
-  if (bytes.length === 0) return ''
-  let number = 0n
-  for (const byte of bytes) number = (number << 8n) + BigInt(byte)
-
-  let result = ''
-  if (number === 0n) return BASE62_LEADER
-  while (number > 0n) {
-    result = BASE62_ALPHABET[Number(number % BASE62_BASE)] + result
-    number /= BASE62_BASE
-  }
-  for (const byte of bytes) {
-    if (byte !== 0) break
-    result = BASE62_LEADER + result
-  }
-  return result
-}
-
-function base62ToBytes (value) {
-  if (typeof value !== 'string') throw new TypeError('Base62 value should be a string')
-  let leadingZeros = 0
-  while (value[leadingZeros] === BASE62_LEADER) leadingZeros++
-
-  let number = 0n
-  for (const character of value) {
-    const digit = BASE62_CHAR_MAP.get(character)
-    if (digit === undefined) throw new Error(`Invalid Base62 character: ${character}`)
-    number = number * BASE62_BASE + digit
-  }
-  const suffix = []
-  while (number > 0n) {
-    suffix.unshift(Number(number & 0xffn))
-    number >>= 8n
-  }
-  const result = new Uint8Array(leadingZeros + suffix.length)
-  result.set(suffix, leadingZeros)
-  return result
-}
-
 function isNostrAppDTagSafe (value) {
   return typeof value === 'string' && value.length <= NOSTR_APP_D_TAG_MAX_LENGTH
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "libp2r2p",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Peer-to-relay-to-peer",
   "keywords": [
     "p2r2p",
@@ -13,6 +13,8 @@
   "sideEffects": false,
   "files": [
     "base16",
+    "base36",
+    "base62",
     "base64",
     "base93",
     "content-key",
@@ -40,6 +42,8 @@
   "exports": {
     ".": "./index.js",
     "./base16": "./base16/index.js",
+    "./base36": "./base36/index.js",
+    "./base62": "./base62/index.js",
     "./base64": "./base64/index.js",
     "./base93": "./base93/index.js",
     "./content-key": "./content-key/index.js",