libp2r2p 0.11.36 → 0.12.0

package/README.md

@@ -765,6 +765,54 @@ import {
 } from 'libp2r2p/url'
 ```
 
+Event hashing, signing, verification and public-key derivation use a bundled
+libsecp256k1 WebAssembly backend after it becomes ready. Initialization is lazy:
+the first operation uses JavaScript and starts the WASM compiler in the
+background, so existing synchronous calls do not change. To use WASM for the
+first operation, await the optional initializer:
+
+```js
+import {
+  finalizeEvent,
+  initializeEventCrypto
+} from 'libp2r2p/event'
+
+const backend = await initializeEventCrypto() // 'wasm' or 'javascript'
+const event = finalizeEvent(template, secretKey)
+```
+
+Inaccessible WebAssembly, CSP restrictions and backend failures fall back to
+JavaScript. Disable the backend for the current JavaScript realm with
+`configureEventCrypto({ wasm: false })`. This runtime option does not reduce the
+bundle. Applications that want to exclude the WASM artifact entirely should use
+the JS-only event and key entrypoints:
+
+```js
+import { finalizeEvent, isValidEvent } from 'libp2r2p/event/js'
+import { getPublicKey } from 'libp2r2p/key/js'
+```
+
+`generateSecretKey()` always uses JavaScript and does not initialize WASM.
+Maintainers can rebuild the checked-in WASM module with `npm run build:wasm`;
+see the
+[WASM build guide](https://github.com/arthurfranca/libp2r2p/blob/main/wasm/README.md).
+Run the non-gating comparison against the JavaScript backend with
+`npm run benchmark:event`.
+
+Median speedup after explicit WASM initialization, measured with Node.js 24 on
+an AMD Ryzen 5 5600G:
+
+| Operation | 8 KiB | 256 KiB | 1 MiB |
+| --- | ---: | ---: | ---: |
+| `isValidEvent` | 5.83× | 2.58× | 1.94× |
+| `finalizeEvent` | 13.64× | 3.11× | 2.06× |
+| `getEventHash` | 1.27× | 1.60× | 1.59× |
+| `getPublicKey` | 3.61× | — | — |
+
+These numbers compare complete public operations against the same methods from
+`event/js` and `key/js`. They are an indicative local measurement, not a CI
+performance gate.
+
 Blossom server normalization accepts root `http:` origins for local
 development. Public Blossom validation additionally requires `https:` and a
 public host, and rejects credentials, paths, query strings and fragments.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,46 @@
+# Third-party notices
+
+The generated WebAssembly module includes libsecp256k1:
+
+Copyright (c) 2013 Pieter Wuille
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+The build and JavaScript wrapper are derived from nostr-wasm by fiatjaf:
+https://github.com/fiatjaf/nostr-wasm
+
+Copyright (c) 2023 fiatjaf
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/event/helpers/core.js

@@ -0,0 +1,120 @@
+import { schnorr, secp256k1 } from '@noble/curves/secp256k1.js'
+import { sha256 } from '@noble/hashes/sha2.js'
+
+import { bytesToBase16, base16ToBytes } from '../../base16/index.js'
+import { ValidationError } from '../../error/index.js'
+import {
+  isAddressableKind,
+  isEphemeralKind,
+  isRegularKind,
+  isReplaceableKind
+} from '../../kind/index.js'
+import {
+  assertSerializableEvent,
+  isSerializableEvent,
+  serializeEvent,
+  serializableEventError
+} from './serialize.js'
+
+const HEX_32 = /^[0-9a-f]{64}$/
+const HEX_64 = /^[0-9a-f]{128}$/
+const textEncoder = new TextEncoder()
+
+export function copyTags (tags) {
+  return Array.isArray(tags) ? tags.map(tag => Array.isArray(tag) ? tag.slice() : tag) : tags
+}
+
+export function validateSecretKey (secretKey) {
+  if (!(secretKey instanceof Uint8Array) || secretKey.length !== 32 || !secp256k1.utils.isValidSecretKey(secretKey)) {
+    throw new ValidationError('INVALID_SECRET_KEY')
+  }
+}
+
+export function getEventHash (event) {
+  return bytesToBase16(sha256(textEncoder.encode(serializeEvent(event))))
+}
+
+export function finalizeEvent (template, secretKey) {
+  validateSecretKey(secretKey)
+  const pubkey = bytesToBase16(schnorr.getPublicKey(secretKey))
+  const event = { ...template, tags: copyTags(template?.tags), pubkey }
+  const id = getEventHash(event)
+  return { ...event, id, sig: bytesToBase16(schnorr.sign(base16ToBytes(id), secretKey)) }
+}
+
+export function eventValidationError (event) {
+  const structureError = serializableEventError(event)
+  if (structureError) return structureError
+  if (typeof event.id !== 'string' || !HEX_32.test(event.id)) return 'INVALID_EVENT_ID'
+  if (typeof event.sig !== 'string' || !HEX_64.test(event.sig)) return 'INVALID_EVENT_SIGNATURE'
+  try {
+    const id = getEventHash(event)
+    if (id !== event.id) return 'EVENT_ID_MISMATCH'
+    if (!schnorr.verify(base16ToBytes(event.sig), base16ToBytes(id), base16ToBytes(event.pubkey))) {
+      return 'INVALID_EVENT_SIGNATURE'
+    }
+  } catch {
+    return 'INVALID_EVENT_SIGNATURE'
+  }
+  return null
+}
+
+export function isValidEvent (event) {
+  return eventValidationError(event) === null
+}
+
+export function assertValidEvent (event) {
+  const code = eventValidationError(event)
+  if (code) throw new ValidationError(code)
+  return event
+}
+
+function hasTagDefinedClassification (event, classification) {
+  if (!event || typeof event !== 'object' || !Array.isArray(event.tags)) return false
+
+  if (classification === 'ephemeral') {
+    if (!Number.isSafeInteger(event.created_at) || event.created_at < 0) return false
+    const timestamp = String(event.created_at)
+    return event.tags.some(tag => Array.isArray(tag) && tag[0] === 'expiration' && tag[1] === timestamp)
+  }
+
+  const dTag = event.tags.find(tag => Array.isArray(tag) && tag[0] === 'd')
+  if (typeof dTag?.[1] !== 'string') return false
+  if (classification === 'replaceable') return dTag[1] === ''
+  if (classification === 'addressable') return dTag[1] !== ''
+  return false
+}
+
+export function classifyEvent (event, { includeLegacyKindRanges = true } = {}) {
+  if (!event || typeof event !== 'object') return []
+  const options = { includeLegacyKindRanges }
+  return [
+    ['regular', isRegularEvent],
+    ['replaceable', isReplaceableEvent],
+    ['ephemeral', isEphemeralEvent],
+    ['addressable', isAddressableEvent]
+  ].filter(([, predicate]) => predicate(event, options)).map(([classification]) => classification)
+}
+
+export function isRegularEvent (event, options) {
+  if (!event || typeof event !== 'object') return false
+  return (options?.includeLegacyKindRanges !== false && isRegularKind(event.kind)) ||
+    (!isReplaceableEvent(event, options) && !isAddressableEvent(event, options))
+}
+
+export function isReplaceableEvent (event, options) {
+  return (options?.includeLegacyKindRanges !== false && isReplaceableKind(event?.kind)) ||
+    hasTagDefinedClassification(event, 'replaceable')
+}
+
+export function isEphemeralEvent (event, options) {
+  return (options?.includeLegacyKindRanges !== false && isEphemeralKind(event?.kind)) ||
+    hasTagDefinedClassification(event, 'ephemeral')
+}
+
+export function isAddressableEvent (event, options) {
+  return (options?.includeLegacyKindRanges !== false && isAddressableKind(event?.kind)) ||
+    hasTagDefinedClassification(event, 'addressable')
+}
+
+export { assertSerializableEvent, isSerializableEvent }

package/event/helpers/serialize.js

@@ -29,3 +29,59 @@ export function serializeEvent (event) {
   assertSerializableEvent(event)
   return JSON.stringify([0, event.pubkey, event.created_at, event.kind, event.tags, event.content])
 }
+
+function isHighSurrogate (value) {
+  return value >= 0xd800 && value <= 0xdbff
+}
+
+function isLowSurrogate (value) {
+  return value >= 0xdc00 && value <= 0xdfff
+}
+
+function chunkEnd (value, start, chunkSize) {
+  let end = Math.min(start + Math.max(2, chunkSize), value.length)
+  if (
+    end < value.length &&
+    end > start + 1 &&
+    isHighSurrogate(value.charCodeAt(end - 1)) &&
+    isLowSurrogate(value.charCodeAt(end))
+  ) {
+    end--
+  }
+  return end
+}
+
+function * serializeJsonString (value, chunkSize) {
+  yield '"'
+  for (let start = 0; start < value.length;) {
+    const end = chunkEnd(value, start, chunkSize)
+    const serialized = JSON.stringify(value.slice(start, end))
+    yield serialized.slice(1, -1)
+    start = end
+  }
+  yield '"'
+}
+
+/**
+ * Produces the exact same text as serializeEvent() without constructing the
+ * complete serialized event in one JavaScript string.
+ */
+export function * serializeEventChunks (event, { chunkSize = 4 * 1024, validate = true } = {}) {
+  if (validate) assertSerializableEvent(event)
+  yield `[0,"${event.pubkey}",${event.created_at},${event.kind},[`
+
+  for (let tagIndex = 0; tagIndex < event.tags.length; tagIndex++) {
+    if (tagIndex) yield ','
+    yield '['
+    const tag = event.tags[tagIndex]
+    for (let valueIndex = 0; valueIndex < tag.length; valueIndex++) {
+      if (valueIndex) yield ','
+      yield * serializeJsonString(tag[valueIndex], chunkSize)
+    }
+    yield ']'
+  }
+
+  yield '],'
+  yield * serializeJsonString(event.content, chunkSize)
+  yield ']'
+}

package/event/index.js

@@ -1,43 +1,89 @@
-import { schnorr, secp256k1 } from '@noble/curves/secp256k1.js'
-import { sha256 } from '@noble/hashes/sha2.js'
-
-import { bytesToBase16, base16ToBytes } from '../base16/index.js'
+import { base16ToBytes, bytesToBase16 } from '../base16/index.js'
 import { ValidationError } from '../error/index.js'
 import {
-  isAddressableKind,
-  isEphemeralKind,
-  isRegularKind,
-  isReplaceableKind
-} from '../kind/index.js'
+  configureEventCrypto,
+  getReadyEventCryptoBackend,
+  initializeEventCrypto,
+  markEventCryptoUnavailable,
+  scheduleEventCryptoInitialization
+} from '../helpers/secp256k1-wasm/backend.js'
+import {
+  copyTags,
+  eventValidationError as eventValidationErrorWithJavaScript,
+  finalizeEvent as finalizeEventWithJavaScript,
+  getEventHash as getEventHashWithJavaScript,
+  validateSecretKey
+} from './helpers/core.js'
 import {
   assertSerializableEvent,
   isSerializableEvent,
-  serializeEvent,
   serializableEventError
 } from './helpers/serialize.js'
 
+export {
+  classifyEvent,
+  isAddressableEvent,
+  isEphemeralEvent,
+  isRegularEvent,
+  isReplaceableEvent
+} from './helpers/core.js'
+export { assertSerializableEvent, isSerializableEvent }
+export { configureEventCrypto, initializeEventCrypto }
+
 const HEX_32 = /^[0-9a-f]{64}$/
 const HEX_64 = /^[0-9a-f]{128}$/
-const textEncoder = new TextEncoder()
 
-function copyTags (tags) {
-  return Array.isArray(tags) ? tags.map(tag => Array.isArray(tag) ? tag.slice() : tag) : tags
+function useWasmOrFallback (operation, fallback) {
+  scheduleEventCryptoInitialization()
+  const backend = getReadyEventCryptoBackend()
+  if (!backend) return fallback()
+  try {
+    return operation(backend)
+  } catch {
+    markEventCryptoUnavailable()
+    return fallback()
+  }
 }
 
-export { assertSerializableEvent, isSerializableEvent }
-
 export function getEventHash (event) {
-  return bytesToBase16(sha256(textEncoder.encode(serializeEvent(event))))
+  assertSerializableEvent(event)
+  return useWasmOrFallback(
+    backend => bytesToBase16(backend.hashEvent(event)),
+    () => getEventHashWithJavaScript(event)
+  )
 }
 
 export function finalizeEvent (template, secretKey) {
-  if (!(secretKey instanceof Uint8Array) || secretKey.length !== 32 || !secp256k1.utils.isValidSecretKey(secretKey)) {
-    throw new ValidationError('INVALID_SECRET_KEY')
+  validateSecretKey(secretKey)
+  const event = {
+    ...template,
+    tags: copyTags(template?.tags),
+    pubkey: '0'.repeat(64)
   }
-  const pubkey = bytesToBase16(schnorr.getPublicKey(secretKey))
-  const event = { ...template, tags: copyTags(template?.tags), pubkey }
-  const id = getEventHash(event)
-  return { ...event, id, sig: bytesToBase16(schnorr.sign(base16ToBytes(id), secretKey)) }
+  assertSerializableEvent(event)
+  return useWasmOrFallback(
+    backend => {
+      const entropy = crypto.getRandomValues(new Uint8Array(32))
+      let id
+      const { publicKey, signature } = backend.signEventHash(
+        secretKey,
+        publicKeyBytes => {
+          event.pubkey = bytesToBase16(publicKeyBytes)
+          const hash = backend.hashEvent(event)
+          id = bytesToBase16(hash)
+          return hash
+        },
+        entropy
+      )
+      return {
+        ...event,
+        pubkey: bytesToBase16(publicKey),
+        id,
+        sig: bytesToBase16(signature)
+      }
+    },
+    () => finalizeEventWithJavaScript(template, secretKey)
+  )
 }
 
 function eventValidationError (event) {
@@ -45,16 +91,25 @@ function eventValidationError (event) {
   if (structureError) return structureError
   if (typeof event.id !== 'string' || !HEX_32.test(event.id)) return 'INVALID_EVENT_ID'
   if (typeof event.sig !== 'string' || !HEX_64.test(event.sig)) return 'INVALID_EVENT_SIGNATURE'
+
+  scheduleEventCryptoInitialization()
+  const backend = getReadyEventCryptoBackend()
+  if (!backend) return eventValidationErrorWithJavaScript(event)
   try {
-    const id = getEventHash(event)
+    const id = bytesToBase16(backend.hashEvent(event))
     if (id !== event.id) return 'EVENT_ID_MISMATCH'
-    if (!schnorr.verify(base16ToBytes(event.sig), base16ToBytes(id), base16ToBytes(event.pubkey))) {
+    if (!backend.verifyHash(
+      base16ToBytes(event.sig),
+      base16ToBytes(id),
+      base16ToBytes(event.pubkey)
+    )) {
       return 'INVALID_EVENT_SIGNATURE'
     }
+    return null
   } catch {
-    return 'INVALID_EVENT_SIGNATURE'
+    markEventCryptoUnavailable()
+    return eventValidationErrorWithJavaScript(event)
   }
-  return null
 }
 
 export function isValidEvent (event) {
@@ -66,51 +121,3 @@ export function assertValidEvent (event) {
   if (code) throw new ValidationError(code)
   return event
 }
-
-function hasTagDefinedClassification (event, classification) {
-  if (!event || typeof event !== 'object' || !Array.isArray(event.tags)) return false
-
-  if (classification === 'ephemeral') {
-    if (!Number.isSafeInteger(event.created_at) || event.created_at < 0) return false
-    const timestamp = String(event.created_at)
-    return event.tags.some(tag => Array.isArray(tag) && tag[0] === 'expiration' && tag[1] === timestamp)
-  }
-
-  const dTag = event.tags.find(tag => Array.isArray(tag) && tag[0] === 'd')
-  if (typeof dTag?.[1] !== 'string') return false
-  if (classification === 'replaceable') return dTag[1] === ''
-  if (classification === 'addressable') return dTag[1] !== ''
-  return false
-}
-
-export function classifyEvent (event, { includeLegacyKindRanges = true } = {}) {
-  if (!event || typeof event !== 'object') return []
-  const options = { includeLegacyKindRanges }
-  return [
-    ['regular', isRegularEvent],
-    ['replaceable', isReplaceableEvent],
-    ['ephemeral', isEphemeralEvent],
-    ['addressable', isAddressableEvent]
-  ].filter(([, predicate]) => predicate(event, options)).map(([classification]) => classification)
-}
-
-export function isRegularEvent (event, options) {
-  if (!event || typeof event !== 'object') return false
-  return (options?.includeLegacyKindRanges !== false && isRegularKind(event.kind)) ||
-    (!isReplaceableEvent(event, options) && !isAddressableEvent(event, options))
-}
-
-export function isReplaceableEvent (event, options) {
-  return (options?.includeLegacyKindRanges !== false && isReplaceableKind(event?.kind)) ||
-    hasTagDefinedClassification(event, 'replaceable')
-}
-
-export function isEphemeralEvent (event, options) {
-  return (options?.includeLegacyKindRanges !== false && isEphemeralKind(event?.kind)) ||
-    hasTagDefinedClassification(event, 'ephemeral')
-}
-
-export function isAddressableEvent (event, options) {
-  return (options?.includeLegacyKindRanges !== false && isAddressableKind(event?.kind)) ||
-    hasTagDefinedClassification(event, 'addressable')
-}

package/event/js/index.js

@@ -0,0 +1,13 @@
+export {
+  assertSerializableEvent,
+  assertValidEvent,
+  classifyEvent,
+  finalizeEvent,
+  getEventHash,
+  isAddressableEvent,
+  isEphemeralEvent,
+  isRegularEvent,
+  isReplaceableEvent,
+  isSerializableEvent,
+  isValidEvent
+} from '../helpers/core.js'

package/helpers/secp256k1-wasm/backend.js

@@ -0,0 +1,99 @@
+import { ValidationError } from '../../error/index.js'
+import { createSecp256k1WasmBackend } from './binding.js'
+
+const SELF_TEST_SECRET = new Uint8Array(32).fill(7)
+const SELF_TEST_PUBLIC_KEY =
+  '989c0b76cb563971fdc9bef31ec06c3560f3249d6ee9e5d83c57625596e05f6f'
+const SELF_TEST_HASH = new Uint8Array(32).fill(9)
+const SELF_TEST_ENTROPY = new Uint8Array(32).fill(11)
+
+let enabled = true
+let state = 'idle'
+let backend = null
+let pending = null
+let generation = 0
+
+const toHex = bytes => Array.from(bytes, byte => byte.toString(16).padStart(2, '0')).join('')
+
+async function initialize (forceRetry) {
+  if (!enabled) return 'javascript'
+  if (backend) return 'wasm'
+  if (pending) return pending
+  if (state === 'unavailable' && !forceRetry) return 'javascript'
+
+  const currentGeneration = generation
+  state = 'initializing'
+  pending = (async () => {
+    let candidate
+    try {
+      candidate = await createSecp256k1WasmBackend()
+      const publicKey = toHex(candidate.getPublicKey(SELF_TEST_SECRET))
+      const signature = candidate.signHash(
+        SELF_TEST_HASH,
+        SELF_TEST_SECRET,
+        SELF_TEST_ENTROPY
+      )
+      if (
+        publicKey !== SELF_TEST_PUBLIC_KEY ||
+        !candidate.verifyHash(signature, SELF_TEST_HASH, candidate.getPublicKey(SELF_TEST_SECRET))
+      ) {
+        throw Error('secp256k1 WASM self-test failed')
+      }
+      if (!enabled || currentGeneration !== generation) {
+        candidate.dispose()
+        return 'javascript'
+      }
+      backend = candidate
+      state = 'ready'
+      return 'wasm'
+    } catch {
+      candidate?.dispose()
+      if (enabled && currentGeneration === generation) state = 'unavailable'
+      return 'javascript'
+    } finally {
+      pending = null
+    }
+  })()
+  return pending
+}
+
+export function configureEventCrypto (options = {}) {
+  if (!options || typeof options !== 'object' || Array.isArray(options)) {
+    throw new ValidationError('INVALID_EVENT_CRYPTO_OPTIONS')
+  }
+  if (options.wasm !== undefined && typeof options.wasm !== 'boolean') {
+    throw new ValidationError('INVALID_EVENT_CRYPTO_OPTIONS')
+  }
+  const nextEnabled = options.wasm !== false
+  if (nextEnabled === enabled) return
+
+  enabled = nextEnabled
+  generation++
+  if (!enabled) {
+    backend?.dispose()
+    backend = null
+    state = 'disabled'
+  } else {
+    state = 'idle'
+  }
+}
+
+export function initializeEventCrypto () {
+  return initialize(true)
+}
+
+export function scheduleEventCryptoInitialization () {
+  if (!enabled || backend || pending || state === 'unavailable') return
+  initialize(false).catch(() => {})
+}
+
+export function getReadyEventCryptoBackend () {
+  return backend
+}
+
+export function markEventCryptoUnavailable () {
+  if (!backend) return
+  backend.dispose()
+  backend = null
+  state = 'unavailable'
+}