libp2r2p 0.7.0 → 0.9.0

package/README.md

@@ -21,6 +21,8 @@ const messenger = await createPrivateMessenger({
   userSigner,
   contentKeySigner,
   offlineRecoverySeconds: 7 * 24 * 60 * 60,
+  staleChannelSeconds: 45 * 24 * 60 * 60,
+  identityStorageRetentionSeconds: 60 * 24 * 60 * 60,
   channels: [{
     signer: privateChannelSigner,
     relays: ['wss://relay.example'],
@@ -89,7 +91,7 @@ await messenger.tell({
 ```
 
 ```js
-import { finalizeEvent } from 'nostr-tools'
+import { finalizeEvent } from 'libp2r2p/event'
 import { keypairFromSeckey } from 'libp2r2p/key'
 import { relayPool } from 'libp2r2p/relay'
 
@@ -147,26 +149,47 @@ PrivateMessenger.maintainStorage().catch(console.warn)
 
 Maintenance removes interrupted-send staging, expired receive chunks, and
 storage belonging to inactive principal identities. It also
-resumes any interrupted database-set deletion. An application does not need to
+resumes any interrupted storage-set deletion. An application does not need to
 know database names or enumerate IndexedDB. Pass `temporaryStorageArea` only
 when the messenger was configured to use a Storage area other than the default
 `sessionStorage`.
 
-Each principal signer owns internal message, recovery-seed, and channel-state
-databases. The messenger updates their activity lease while it is open and
-closes all handles in `await messenger.close()`. The complete set is removed
-after 60 days without use, including messages that were never consumed.
+Each principal signer owns an internal storage set containing message,
+recovery-seed, and channel-state databases. The messenger updates its activity
+lease while it is open and closes all handles in `await messenger.close()`.
+The complete set is removed after `identityStorageRetentionSeconds` without
+use (60 days by default), including messages that were never consumed.
 Maintenance runs on every initialization and every six hours while a messenger
 is active; failed deletions remain journaled and retry automatically.
 
-Channel recovery state inside an otherwise active identity retains its separate
-45-day stale-channel cleanup policy. Offline recovery defaults to seven days.
+Channel recovery state inside an otherwise active identity uses the separate
+`staleChannelSeconds` cleanup policy (45 days by default). Active instances
+record the channels they administer, so a channel remains protected while any
+instance or tab still uses it. Offline recovery defaults to seven days.
 Set `offlineRecoverySeconds` on an individual channel to override the
 messenger default for its recovery seeds, offline ranges, new outer-event
 expiration, and new incomplete receive groups. Updating a channel applies a
 shorter window immediately to its stored seeds and ranges; increasing it does
 not recreate data already removed.
 
+The effective recovery duration is capped by both `staleChannelSeconds` and
+`identityStorageRetentionSeconds`. The requested per-channel value remains
+stored separately, so raising a cap affects new retention decisions without
+recreating data already removed. Both retention policies can be changed by an
+instance at runtime; omitted fields retain their current persisted values:
+
+```js
+await messenger.update({
+  staleChannelSeconds: 30 * 24 * 60 * 60,
+  identityStorageRetentionSeconds: 90 * 24 * 60 * 60
+})
+```
+
+The policies are persisted per principal identity. If multiple instances use
+the same identity, the last confirmed policy update wins and is propagated to
+the others. A zero policy disables durable recovery immediately. Identity
+storage itself remains protected until the final active lease closes.
+
 Set a channel's `offlineRecoverySeconds` to `0` to disable durable recovery for
 that channel. The messenger then stores no recovery seeds, tracks no offline
 ranges, contacts no seeders, publishes no seeder presence, and uses no recovery
@@ -222,6 +245,87 @@ 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.
 
+## Nostr primitives
+
+The modern stack can use the package without `nostr-tools`. Its intentionally
+small public surface includes strict, non-caching NIP-01 helpers, NIP-04 for
+legacy interoperability, NIP-44 v2, key helpers, event-kind classification,
+NIP-05 lookup, NIP-96 compatibility, NIP-98 authorization, Nostr Web Tokens,
+and relay URL normalization:
+
+```js
+import {
+  assertSerializableEvent,
+  assertValidEvent,
+  finalizeEvent,
+  isSerializableEvent,
+  isValidEvent
+} from 'libp2r2p/event'
+import { generateSecretKey, getPublicKey } from 'libp2r2p/key'
+import { eventKinds, classifyKind } from 'libp2r2p/kind'
+import * as nip44 from 'libp2r2p/nip44'
+import { assertValidPublicRelayUrl, normalizeRelayUrl } from 'libp2r2p/url'
+```
+
+`classifyEvent()` from `libp2r2p/event` combines the exact NIP-01 kind
+ranges with tag-defined behavior. The first `d` tag may add `replaceable` or
+`addressable`, while an `expiration` tag equal to `created_at` adds
+`ephemeral`. An event is also regular when it is neither replaceable nor
+addressable. Classifications are additive and callers can disable the legacy
+kind ranges with `{ includeLegacyKindRanges: false }`.
+
+NIP-44 v2 uses the interoperable `nip44-v2` salt by default. A custom UTF-8
+salt of at most 32 bytes may be passed to `getConversationKey()`, but messages
+derived with it are not interoperable with standard NIP-44 implementations.
+
+Nostr Web Tokens are available from `libp2r2p/nwt`. Creation returns a signed
+kind `27519` event, while transport encoding is kept separate:
+
+```js
+import { createToken, encodeToken, validateToken } from 'libp2r2p/nwt'
+
+const event = await createToken({
+  signEvent,
+  audience: ['api.example.com'],
+  expiration: Math.floor(Date.now() / 1000) + 300,
+  claims: [['action', 'upload']],
+  content: 'Authorize an upload'
+})
+const authorization = encodeToken(event, { includeAuthorizationScheme: true })
+const claims = validateToken(authorization, { audience: 'api.example.com' })
+```
+
+Transport decoding requires canonical unpadded Base64URL. Validation verifies
+the Nostr signature on every call, enforces registered-claim cardinality and
+time bounds, and requires the verifier to provide its identity whenever an
+`aud` claim is present. Tokens without `aud` or `exp` retain the draft
+specification's public/unbounded defaults; servers can reject those forms with
+`requireAudience` and `requireExpiration`.
+
+The NIP-96 module is provided only for interoperability with older file
+servers. New applications should prefer NIP-B7. Its upload API accepts an
+`AbortSignal` and a ProgressEvent-compatible callback; browsers use XHR for
+real upload progress when available, while the fetch fallback reports only
+estimated start and successful completion.
+
+`isSerializableEvent()` checks only the NIP-01 fields used during
+serialization. `isValidEvent()` additionally recalculates the ID and verifies
+the Schnorr signature on every call; it never adds a cache marker to the
+event. Their `assert…` counterparts return the original event or throw a
+`ValidationError` with a stable code.
+
+Public validity checks consistently use a non-throwing `is…` predicate plus an
+`assert…` counterpart when callers need the exact reason. Strict codecs,
+decoders, token validation, and malformed public arguments also throw
+`ValidationError` from `libp2r2p/error`. Network, timeout, abort, quota, and
+closed-state failures remain ordinary operational errors.
+
+NIP-04 remains available at
+`libp2r2p/nip04` only for compatibility with older Nostr applications.
+Low-level relay sockets, subscriptions, message parsing, and serialization are
+internal implementation details; use `RelayPool` or the `relayPool` singleton
+from `libp2r2p/relay`.
+
 ## Internationalization
 
 The dependency-free `libp2r2p/i18n` subpath exposes locale detection and a

package/base16/index.js

@@ -1,13 +1,16 @@
+import { ValidationError } from '../error/index.js'
+
 export function bytesToBase16 (bytes) {
+  if (!bytes || typeof bytes[Symbol.iterator] !== 'function') throw new ValidationError('INVALID_BYTE_ARRAY')
   let s = ''
   for (const b of bytes) s += b.toString(16).padStart(2, '0')
   return s
 }
 
 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')
+  if (typeof base16 !== 'string') throw new ValidationError('INVALID_BASE16_TYPE', { message: 'Base16 value should be a string' })
+  if (base16.length % 2 !== 0) throw new ValidationError('INVALID_BASE16_LENGTH', { message: 'Invalid Base16 length' })
+  if (!/^[0-9a-f]*$/i.test(base16)) throw new ValidationError('INVALID_BASE16_CHARACTER', { message: 'Invalid Base16 character' })
   const out = new Uint8Array(base16.length / 2)
   for (let i = 0; i < out.length; i++) {
     out[i] = Number.parseInt(base16.slice(i * 2, i * 2 + 2), 16)

package/base36/index.js

@@ -1,4 +1,5 @@
 import { base16ToBytes, bytesToBase16 } from '../base16/index.js'
+import { ValidationError } from '../error/index.js'
 
 export const BASE36_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
 
@@ -30,7 +31,7 @@ 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)
+    if (digit === undefined) throw new ValidationError('INVALID_BASE36_CHARACTER', { message: 'Invalid Base36 character: ' + character })
     number = number * BASE + digit
   }
   return number
@@ -49,6 +50,9 @@ function integerToMinimalBytes (number) {
 // 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 || !Number.isSafeInteger(bytes.length) || typeof bytes[Symbol.iterator] !== 'function') {
+    throw new ValidationError('INVALID_BYTE_ARRAY')
+  }
   if (bytes.length === 0) return ''
 
   const number = bytesToInteger(bytes)
@@ -60,7 +64,7 @@ export function bytesToBase36 (bytes) {
 }
 
 export function base36ToBytes (value) {
-  if (typeof value !== 'string') throw new TypeError('Base36 value should be a string')
+  if (typeof value !== 'string') throw new ValidationError('INVALID_BASE36_TYPE', { message: 'Base36 value should be a string' })
   if (value.length === 0) return new Uint8Array()
 
   let leadingZeros = 0
@@ -84,21 +88,21 @@ export function base36ToBase16 (value) {
 // 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 bytesToBase36Nsite (bytes) {
-  if (bytes.length !== NSITE_BYTE_LENGTH) {
-    throw new Error('Nsite Base36 input should be ' + NSITE_BYTE_LENGTH + ' bytes')
+  if (!bytes || bytes.length !== NSITE_BYTE_LENGTH || typeof bytes[Symbol.iterator] !== 'function') {
+    throw new ValidationError('INVALID_NSITE_BASE36_BYTE_LENGTH', { message: 'Nsite Base36 input should be ' + NSITE_BYTE_LENGTH + ' bytes' })
   }
   return integerToBase36(bytesToInteger(bytes)).padStart(NSITE_TEXT_LENGTH, LEADER)
 }
 
 export function base36NsiteToBytes (value) {
-  if (typeof value !== 'string') throw new TypeError('Nsite Base36 value should be a string')
+  if (typeof value !== 'string') throw new ValidationError('INVALID_NSITE_BASE36_TYPE', { message: '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')
+    throw new ValidationError('INVALID_NSITE_BASE36_LENGTH', { message: 'Nsite Base36 value should be ' + NSITE_TEXT_LENGTH + ' characters' })
   }
-  if (!/^[0-9a-z]+$/.test(value)) throw new Error('Invalid Nsite Base36 character')
+  if (!/^[0-9a-z]+$/.test(value)) throw new ValidationError('INVALID_NSITE_BASE36_CHARACTER', { message: 'Invalid Nsite Base36 character' })
 
   const number = parseBase36Integer(value)
-  if (number > MAX_NSITE_VALUE) throw new Error('Nsite Base36 value exceeds 32 bytes')
+  if (number > MAX_NSITE_VALUE) throw new ValidationError('NSITE_BASE36_OVERFLOW', { message: '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)

package/base62/index.js

@@ -1,4 +1,5 @@
 import { base16ToBytes, bytesToBase16 } from '../base16/index.js'
+import { ValidationError } from '../error/index.js'
 
 export const BASE62_ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
 
@@ -11,16 +12,16 @@ const CHAR_MAP = new Map(
 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')
+    throw new ValidationError('INVALID_BASE62_OPTIONS', { message: 'Base62 options should be an object' })
   }
   for (const key of Object.keys(options)) {
-    if (!allowedKeys.includes(key)) throw new Error('Unknown Base62 option: ' + key)
+    if (!allowedKeys.includes(key)) throw new ValidationError('UNKNOWN_BASE62_OPTION', { message: 'Unknown Base62 option: ' + key })
   }
   return options
 }
 
 function readMode (mode = 'bytes') {
-  if (mode !== 'bytes' && mode !== 'integer') throw new Error('Invalid Base62 mode: ' + mode)
+  if (mode !== 'bytes' && mode !== 'integer') throw new ValidationError('INVALID_BASE62_MODE', { message: 'Invalid Base62 mode: ' + mode })
   return mode
 }
 
@@ -28,7 +29,7 @@ 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')
+    throw new ValidationError('INVALID_BASE62_LENGTH', { message: 'Base62 ' + name + ' should be a ' + qualifier + ' safe integer' })
   }
   return value
 }
@@ -52,7 +53,7 @@ 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)
+    if (digit === undefined) throw new ValidationError('INVALID_BASE62_CHARACTER', { message: 'Invalid Base62 character: ' + character })
     number = number * BASE + digit
   }
   return number
@@ -71,13 +72,16 @@ function integerToMinimalBytes (number) {
 // 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) {
+  if (!bytes || !Number.isSafeInteger(bytes.length) || typeof bytes[Symbol.iterator] !== 'function') {
+    throw new ValidationError('INVALID_BYTE_ARRAY')
+  }
   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')
+    throw new ValidationError('INVALID_BASE62_MIN_LENGTH_MODE', { message: 'Base62 minLength requires integer mode' })
   }
   if (mode === 'integer') {
-    if (bytes.length === 0) throw new Error('Base62 integer input should not be empty')
+    if (bytes.length === 0) throw new ValidationError('EMPTY_BASE62_INTEGER', { message: 'Base62 integer input should not be empty' })
     const minLength = readLength(rawMinLength, 'minLength', 0)
     return integerToBase62(bytesToInteger(bytes)).padStart(minLength, LEADER)
   }
@@ -92,18 +96,18 @@ export function bytesToBase62 (bytes, options) {
 }
 
 export function base62ToBytes (value, options) {
-  if (typeof value !== 'string') throw new TypeError('Base62 value should be a string')
+  if (typeof value !== 'string') throw new ValidationError('INVALID_BASE62_TYPE', { message: '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')
+    throw new ValidationError('INVALID_BASE62_BYTE_LENGTH_MODE', { message: 'Base62 byteLength requires integer mode' })
   }
   if (mode === 'integer') {
-    if (value.length === 0) throw new Error('Base62 integer value should not be empty')
+    if (value.length === 0) throw new ValidationError('EMPTY_BASE62_INTEGER', { message: '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')
+    if (bytes.length > byteLength) throw new ValidationError('BASE62_INTEGER_OVERFLOW', { message: 'Base62 integer exceeds ' + byteLength + ' bytes' })
     const result = new Uint8Array(byteLength)
     result.set(bytes, byteLength - bytes.length)
     return result

package/base64/index.js

@@ -2,7 +2,12 @@
 // Plain base64 is used where a protocol expects standard base64. URL-safe
 // base64 is useful for WebAuthn credential IDs and URL/query-string material.
 
+import { ValidationError } from '../error/index.js'
+
 export function bytesToBase64 (bytes) {
+  if (!bytes || !Number.isSafeInteger(bytes.length) || typeof bytes[Symbol.iterator] !== 'function') {
+    throw new ValidationError('INVALID_BYTE_ARRAY')
+  }
   if (typeof Buffer === 'function' && typeof Buffer.from === 'function') {
     return Buffer.from(bytes).toString('base64')
   }
@@ -12,7 +17,13 @@ export function bytesToBase64 (bytes) {
 }
 
 export function base64ToBytes (b64) {
-  const bin = atob(b64)
+  if (typeof b64 !== 'string') throw new ValidationError('INVALID_BASE64_TYPE', { message: 'Base64 value should be a string' })
+  let bin
+  try {
+    bin = atob(b64)
+  } catch (cause) {
+    throw new ValidationError('INVALID_BASE64', { cause })
+  }
   const out = new Uint8Array(bin.length)
   for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
   return out
@@ -26,7 +37,12 @@ export function bytesToBase64Url (bytes) {
 }
 
 export function base64UrlToBytes (base64url) {
+  if (typeof base64url !== 'string') throw new ValidationError('INVALID_BASE64URL_TYPE', { message: 'Base64URL value should be a string' })
   const value = String(base64url)
   const pad = value.length % 4 === 0 ? '' : '='.repeat(4 - (value.length % 4))
-  return base64ToBytes(value.replace(/-/g, '+').replace(/_/g, '/') + pad)
+  try {
+    return base64ToBytes(value.replace(/-/g, '+').replace(/_/g, '/') + pad)
+  } catch (cause) {
+    throw new ValidationError('INVALID_BASE64URL', { cause })
+  }
 }

package/base93/index.js

@@ -2,6 +2,8 @@
 // Apache-2.0. JSON-safe alphabet: space is included; double quote and
 // backslash are intentionally excluded.
 
+import { ValidationError } from '../error/index.js'
+
 export const BASE93_ALPHABET =
   "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!#$%&'()*+,-./:;<=>?@[]^_`{|}~ "
 
@@ -34,7 +36,11 @@ function asBytes (bytes) {
   if (bytes instanceof Uint8Array) return bytes
   if (ArrayBuffer.isView(bytes)) return new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength)
   if (bytes instanceof ArrayBuffer) return new Uint8Array(bytes)
-  return Uint8Array.from(bytes)
+  try {
+    return Uint8Array.from(bytes)
+  } catch (cause) {
+    throw new ValidationError('INVALID_BYTE_ARRAY', { cause })
+  }
 }
 
 export class Base93Encoder {
@@ -110,7 +116,7 @@ function decodeUnchecked (value) {
   for (let i = 0; i < value.length; i++) {
     const code = value.charCodeAt(i)
     if (code >= DECODING_TABLE.length || DECODING_TABLE[code] < 0) {
-      throw new Error(`Invalid Base93 character at offset ${i}.`)
+      throw new ValidationError('INVALID_BASE93_CHARACTER', { message: `Invalid Base93 character at offset ${i}.` })
     }
     const decoded = DECODING_TABLE[code]
     if (first === -1) {
@@ -134,14 +140,20 @@ function decodeUnchecked (value) {
 }
 
 export function decode (text, offset = 0, length = -1) {
-  if (typeof text !== 'string') throw new TypeError('Base93 input must be a string.')
-  if (!Number.isSafeInteger(offset) || offset < 0 || offset > text.length) throw new RangeError('Invalid Base93 offset.')
-  if (!Number.isSafeInteger(length) || length < -1) throw new RangeError('Invalid Base93 length.')
+  if (typeof text !== 'string') throw new ValidationError('INVALID_BASE93_TYPE', { message: 'Base93 input must be a string.' })
+  if (!Number.isSafeInteger(offset) || offset < 0 || offset > text.length) {
+    throw new ValidationError('INVALID_BASE93_OFFSET', { message: 'Invalid Base93 offset.' })
+  }
+  if (!Number.isSafeInteger(length) || length < -1) {
+    throw new ValidationError('INVALID_BASE93_LENGTH', { message: 'Invalid Base93 length.' })
+  }
 
   const end = length < 0 ? text.length : Math.min(text.length, offset + length)
   const encoded = text.slice(offset, end)
   const bytes = decodeUnchecked(encoded)
-  if (encode(bytes) !== encoded) throw new Error('Non-canonical or truncated Base93 input.')
+  if (encode(bytes) !== encoded) {
+    throw new ValidationError('NON_CANONICAL_BASE93', { message: 'Non-canonical or truncated Base93 input.' })
+  }
   return bytes
 }
 
@@ -149,7 +161,7 @@ function normalizeSource (source) {
   if (typeof source === 'function') source = source()
   if (typeof source === 'string') return [source]
   if (source?.[Symbol.asyncIterator] || source?.[Symbol.iterator]) return source
-  throw new TypeError('Base93 stream source must be iterable.')
+  throw new ValidationError('INVALID_BASE93_STREAM_SOURCE', { message: 'Base93 stream source must be iterable.' })
 }
 
 export class Base93Decoder {

package/content-key/event/index.js

@@ -1,8 +1,9 @@
-import { getEventHash, verifyEvent } from 'nostr-tools'
+import { ValidationError } from '../../error/index.js'
+import { getEventHash, isValidEvent } from '../../event/index.js'
 
 export const CONTENT_KEY_KIND = 18716
 
-const HEX_PUBKEY = /^[0-9a-f]{64}$/i
+const HEX_PUBKEY = /^[0-9a-f]{64}$/
 const HEX_SIG = /^[0-9a-f]{128}$/i
 
 function nowSeconds () {
@@ -10,8 +11,8 @@ function nowSeconds () {
 }
 
 export async function makeContentKeyEventForPubkey ({ userSigner, contentPubkey, createdAt = nowSeconds() }) {
-  if (!userSigner?.getPublicKey || !userSigner?.signEvent) throw new Error('USER_SIGNER_REQUIRED')
-  if (!HEX_PUBKEY.test(contentPubkey || '')) throw new Error('CONTENT_PUBKEY_REQUIRED')
+  if (!userSigner?.getPublicKey || !userSigner?.signEvent) throw new ValidationError('USER_SIGNER_REQUIRED')
+  if (!HEX_PUBKEY.test(contentPubkey || '')) throw new ValidationError('CONTENT_PUBKEY_REQUIRED')
 
   return userSigner.signEvent({
     kind: CONTENT_KEY_KIND,
@@ -22,7 +23,7 @@ export async function makeContentKeyEventForPubkey ({ userSigner, contentPubkey,
 }
 
 export async function makeContentKeyEvent ({ userSigner, contentKeySigner, createdAt = nowSeconds() }) {
-  if (!contentKeySigner?.getPublicKey) throw new Error('CONTENT_KEY_SIGNER_REQUIRED')
+  if (!contentKeySigner?.getPublicKey) throw new ValidationError('CONTENT_KEY_SIGNER_REQUIRED')
   return makeContentKeyEventForPubkey({
     userSigner,
     contentPubkey: await contentKeySigner.getPublicKey(),
@@ -34,7 +35,7 @@ export function parseContentKeyEvent (event) {
   if (!event || event.kind !== CONTENT_KEY_KIND || event.content !== '') return null
   if (!HEX_PUBKEY.test(event.pubkey) || !Number.isSafeInteger(event.created_at)) return null
   if (!Array.isArray(event.tags) || event.tags.length !== 1) return null
-  if (event.id !== getEventHash(event) || !verifyEvent(event)) return null
+  if (!isValidEvent(event)) return null
 
   const [name, contentPubkey, ...rest] = event.tags[0] || []
   if (name !== 'cp' || rest.length || !HEX_PUBKEY.test(contentPubkey || '')) return null
@@ -59,10 +60,11 @@ function parseContentKeyProof (proof) {
   return { created_at, sig }
 }
 
-export function verifyContentKeyProof ({ ownerPubkey, contentPubkey, proof }) {
-  if (!HEX_PUBKEY.test(ownerPubkey || '') || !HEX_PUBKEY.test(contentPubkey || '')) return false
+function contentKeyProofError ({ ownerPubkey, contentPubkey, proof }) {
+  if (!HEX_PUBKEY.test(ownerPubkey || '')) return 'INVALID_CONTENT_KEY_OWNER_PUBKEY'
+  if (!HEX_PUBKEY.test(contentPubkey || '')) return 'INVALID_CONTENT_KEY_PUBKEY'
   const parsed = parseContentKeyProof(proof)
-  if (!parsed) return false
+  if (!parsed) return 'INVALID_CONTENT_KEY_PROOF'
 
   const event = {
     kind: CONTENT_KEY_KIND,
@@ -73,13 +75,39 @@ export function verifyContentKeyProof ({ ownerPubkey, contentPubkey, proof }) {
     sig: parsed.sig
   }
   event.id = getEventHash(event)
-  return verifyEvent(event)
+  return isValidEvent(event) ? null : 'INVALID_CONTENT_KEY_PROOF_SIGNATURE'
 }
 
-export function verifyIykcProof ({ receiverPubkey, iykcPubkey, iykcProof }) {
-  return verifyContentKeyProof({
+function iykcProofError ({ receiverPubkey, iykcPubkey, iykcProof }) {
+  const error = contentKeyProofError({
     ownerPubkey: receiverPubkey,
     contentPubkey: iykcPubkey,
     proof: iykcProof
   })
+  return {
+    INVALID_CONTENT_KEY_OWNER_PUBKEY: 'INVALID_IYKC_RECEIVER_PUBKEY',
+    INVALID_CONTENT_KEY_PUBKEY: 'INVALID_IYKC_PUBKEY',
+    INVALID_CONTENT_KEY_PROOF: 'INVALID_IYKC_PROOF',
+    INVALID_CONTENT_KEY_PROOF_SIGNATURE: 'INVALID_IYKC_PROOF_SIGNATURE'
+  }[error] ?? null
+}
+
+export function isValidContentKeyProof (value) {
+  return contentKeyProofError(value ?? {}) === null
+}
+
+export function assertValidContentKeyProof (value) {
+  const code = contentKeyProofError(value ?? {})
+  if (code) throw new ValidationError(code)
+  return value
+}
+
+export function isValidIykcProof (value) {
+  return iykcProofError(value ?? {}) === null
+}
+
+export function assertValidIykcProof (value) {
+  const code = iykcProofError(value ?? {})
+  if (code) throw new ValidationError(code)
+  return value
 }

package/double-dh/index.js

@@ -1,7 +1,9 @@
+import { secp256k1 } from '@noble/curves/secp256k1.js'
 import { extract, expand } from '@noble/hashes/hkdf.js'
 import { sha256 } from '@noble/hashes/sha2.js'
 import { concatBytes } from '@noble/hashes/utils.js'
 import { sharedXOnlySecret } from '../ecdh/index.js'
+import { ValidationError } from '../error/index.js'
 
 const textEncoder = new TextEncoder()
 
@@ -57,7 +59,7 @@ function u32be (n) {
 
 function normalizeKind (kind) {
   const n = typeof kind === 'string' && kind.trim() !== '' ? Number(kind) : kind
-  if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) throw new Error('INVALID_KIND')
+  if (!Number.isInteger(n) || n < 0 || n > 0xffffffff) throw new ValidationError('INVALID_KIND')
   return n
 }
 
@@ -119,8 +121,21 @@ export function deriveDoubleDhConversationKey ({
   kind,
   scope = ''
 }) {
-  if (role !== 'sender' && role !== 'receiver') throw new Error('INVALID_DOUBLE_DH_ROLE')
-  if (!identitySecretKey || !identityPubkey || !peerIdentityPubkey) throw new Error('DOUBLE_DH_IDENTITY_REQUIRED')
+  if (role !== 'sender' && role !== 'receiver') throw new ValidationError('INVALID_DOUBLE_DH_ROLE')
+  if (!identitySecretKey || !identityPubkey || !peerIdentityPubkey) throw new ValidationError('DOUBLE_DH_IDENTITY_REQUIRED')
+  if (!(identitySecretKey instanceof Uint8Array) || !secp256k1.utils.isValidSecretKey(identitySecretKey)) {
+    throw new ValidationError('INVALID_SECRET_KEY')
+  }
+  for (const pubkey of [identityPubkey, peerIdentityPubkey, contentPubkey, peerContentPubkey]) {
+    if (pubkey && (typeof pubkey !== 'string' || !/^[0-9a-f]{64}$/.test(pubkey))) {
+      throw new ValidationError('INVALID_PUBLIC_KEY')
+    }
+  }
+  if (contentSecretKey != null &&
+      (!(contentSecretKey instanceof Uint8Array) || !secp256k1.utils.isValidSecretKey(contentSecretKey))) {
+    throw new ValidationError('INVALID_CONTENT_SECRET_KEY')
+  }
+  if (typeof scope !== 'string') throw new ValidationError('INVALID_SCOPE')
 
   const isSender = role === 'sender'
   const senderContentPubkey = isSender ? contentPubkey : peerContentPubkey
@@ -128,8 +143,8 @@ export function deriveDoubleDhConversationKey ({
   const mode = modeFor({ senderContentPubkey, receiverContentPubkey })
 
   if (mode === 'identity') return { mode, conversationKey: null }
-  if (isSender && senderContentPubkey && !contentSecretKey) throw new Error('SENDER_CONTENT_KEY_REQUIRED')
-  if (!isSender && receiverContentPubkey && !contentSecretKey) throw new Error('RECEIVER_CONTENT_KEY_REQUIRED')
+  if (isSender && senderContentPubkey && !contentSecretKey) throw new ValidationError('SENDER_CONTENT_KEY_REQUIRED')
+  if (!isSender && receiverContentPubkey && !contentSecretKey) throw new ValidationError('RECEIVER_CONTENT_KEY_REQUIRED')
 
   const [a, b] = orderedPair({ identityPubkey, contentPubkey, peerIdentityPubkey, peerContentPubkey })
   const steps = []
@@ -137,7 +152,7 @@ export function deriveDoubleDhConversationKey ({
   if (identityPubkey === peerIdentityPubkey) {
     const ownContentPubkey = contentPubkey || peerContentPubkey
     if (ownContentPubkey && !contentSecretKey) {
-      throw new Error(isSender ? 'SENDER_CONTENT_KEY_REQUIRED' : 'RECEIVER_CONTENT_KEY_REQUIRED')
+      throw new ValidationError(isSender ? 'SENDER_CONTENT_KEY_REQUIRED' : 'RECEIVER_CONTENT_KEY_REQUIRED')
     }
     // In self-encryption, DH(identitySecret, contentPubkey) could be computed
     // with either single secret plus the other public key. The two self-DH

package/ecdh/index.js

@@ -1,8 +1,19 @@
 import { secp256k1 } from '@noble/curves/secp256k1.js'
 import { hexToBytes } from '../base16/index.js'
+import { ValidationError } from '../error/index.js'
 
 export function sharedXOnlySecret (seckey, pubkey) {
+  if (!(seckey instanceof Uint8Array) || seckey.length !== 32 || !secp256k1.utils.isValidSecretKey(seckey)) {
+    throw new ValidationError('INVALID_SECRET_KEY')
+  }
+  if (typeof pubkey !== 'string' || !/^[0-9a-f]{64}$/.test(pubkey)) {
+    throw new ValidationError('INVALID_PUBLIC_KEY')
+  }
   // Nostr pubkeys are x-only. secp256k1 ECDH expects a compressed point, so
   // use the even-y prefix and drop the returned parity byte.
-  return secp256k1.getSharedSecret(seckey, hexToBytes(`02${pubkey}`)).subarray(1, 33)
+  try {
+    return secp256k1.getSharedSecret(seckey, hexToBytes(`02${pubkey}`)).subarray(1, 33)
+  } catch (cause) {
+    throw new ValidationError('INVALID_PUBLIC_KEY', { cause })
+  }
 }

package/error/index.js

@@ -0,0 +1,32 @@
+const ERROR_CODE = /^[A-Z][A-Z0-9_]*$/
+
+export class ValidationError extends Error {
+  constructor (code, messageOrOptions = code, causeOrOptions) {
+    if (typeof code !== 'string' || !ERROR_CODE.test(code)) {
+      throw new TypeError('Validation error code should be uppercase snake case')
+    }
+    const objectOptions = messageOrOptions && typeof messageOrOptions === 'object'
+      ? messageOrOptions
+      : null
+    const message = objectOptions === messageOrOptions
+      ? (objectOptions.message ?? code)
+      : (messageOrOptions ?? code)
+    const cause = objectOptions
+      ? objectOptions.cause
+      : (causeOrOptions && typeof causeOrOptions === 'object' && Object.hasOwn(causeOrOptions, 'cause')
+          ? causeOrOptions.cause
+          : causeOrOptions)
+    super(message, cause === undefined ? undefined : { cause })
+    Object.defineProperty(this, 'name', {
+      configurable: true,
+      value: 'ValidationError',
+      writable: true
+    })
+    Object.defineProperty(this, 'code', {
+      configurable: false,
+      enumerable: true,
+      value: code,
+      writable: false
+    })
+  }
+}