@cero-base/core 0.2.0 → 0.4.1

package/src/identity/index.js

@@ -0,0 +1,232 @@
+import sodium from 'sodium-universal'
+import IdentityKey from 'keet-identity-key'
+import bip39 from 'bip39-mnemonic'
+import b4a from 'b4a'
+
+import { CeroError } from '../lib/errors.js'
+import { toId } from '../lib/utils.js'
+
+const DERIVE_PATH = ['SLIP-0021', 'cero', 'v1', 'identity']
+
+/**
+ * @typedef {{ publicKey: Uint8Array, secretKey: Uint8Array, id: string }} KeyPair
+ * @typedef {{ publicKey: Uint8Array, secretKey: Uint8Array, encryptionKey: Uint8Array, seed: Uint8Array }} IdentityFields
+ */
+
+/**
+ * Long-lived user identity derived from a BIP-39 seed phrase. Holds the
+ * sign keypair, a symmetric encryption key and the canonical id/topic used
+ * by every other resource to identify this user.
+ */
+export class Identity {
+  /** @param {IdentityFields} keys */
+  constructor(keys) {
+    /**
+     * Canonical z32-encoded public key.
+     *
+     * @type {string}
+     */
+    this.id = toId(keys.publicKey)
+    /** @type {Uint8Array} */
+    this.publicKey = keys.publicKey
+    /** @type {Uint8Array} */
+    this.secretKey = keys.secretKey
+    /**
+     * Symmetric key for encrypting per-identity payloads.
+     *
+     * @type {Uint8Array}
+     */
+    this.encryptionKey = keys.encryptionKey
+    /**
+     * Hash of the public key — used as the swarm topic.
+     *
+     * @type {Uint8Array}
+     */
+    this.topic = topicOf(keys.publicKey)
+    /**
+     * Original 16- or 32-byte entropy.
+     *
+     * @type {Uint8Array}
+     */
+    this.seed = keys.seed
+    Object.freeze(this)
+  }
+
+  /**
+   * Detached Ed25519 signature over `message`.
+   *
+   * @param {Uint8Array} message
+   * @returns {Uint8Array}
+   */
+  sign(message) {
+    const sig = b4a.alloc(sodium.crypto_sign_BYTES)
+    sodium.crypto_sign_detached(sig, message, this.secretKey)
+    return sig
+  }
+
+  /**
+   * Verify a signature against this identity's public key.
+   *
+   * @param {Uint8Array} message
+   * @param {Uint8Array} signature
+   * @returns {boolean}
+   */
+  verify(message, signature) {
+    return sodium.crypto_sign_verify_detached(signature, message, this.publicKey)
+  }
+
+  /**
+   * Render the underlying seed as a BIP-39 mnemonic phrase.
+   *
+   * @returns {string}
+   */
+  toPhrase() {
+    return bip39.entropyToMnemonic(this.seed)
+  }
+
+  /**
+   * Build an identity from 16- or 32-byte entropy.
+   *
+   * @param {Uint8Array} seed
+   * @returns {Promise<Identity>}
+   */
+  static async fromSeed(seed) {
+    if (!Identity.isSeed(seed)) throw CeroError.INVALID('seed must be a 16- or 32-byte buffer')
+    const mnemonic = bip39.entropyToMnemonic(seed)
+    const id = await IdentityKey.from({ mnemonic })
+    const { publicKey, secretKey } = id.identityKeyPair
+    const encryptionKey = id.keyChain.getSymmetricKey([...DERIVE_PATH, 'encryption'])
+    return new Identity({ publicKey, secretKey, encryptionKey, seed })
+  }
+
+  /**
+   * Build an identity from a BIP-39 mnemonic.
+   *
+   * @param {string} phrase
+   * @returns {Promise<Identity>}
+   */
+  static async fromPhrase(phrase) {
+    if (!Identity.isPhrase(phrase)) throw CeroError.INVALID('phrase must be a valid BIP39 mnemonic')
+    return Identity.fromSeed(bip39.mnemonicToEntropy(phrase))
+  }
+
+  /**
+   * Generate a fresh identity from CSPRNG entropy.
+   *
+   * @param {{ words?: 12 | 24 }} [opts]
+   * @returns {Promise<Identity>}
+   */
+  static async generate({ words = 12 } = {}) {
+    return Identity.fromSeed(Identity.randomSeed(words))
+  }
+
+  /**
+   * Generate a random BIP-39 mnemonic.
+   *
+   * @param {12 | 24} [words]
+   * @returns {string}
+   */
+  static genPhrase(words = 12) {
+    return bip39.entropyToMnemonic(Identity.randomSeed(words))
+  }
+
+  /**
+   * Phrase → seed entropy.
+   *
+   * @param {string} phrase
+   * @returns {Uint8Array}
+   */
+  static toSeed(phrase) {
+    return bip39.mnemonicToEntropy(phrase)
+  }
+
+  /**
+   * Seed entropy → phrase.
+   *
+   * @param {Uint8Array} seed
+   * @returns {string}
+   */
+  static toPhrase(seed) {
+    return bip39.entropyToMnemonic(seed)
+  }
+
+  /**
+   * Validate that a value is a 16- or 32-byte buffer.
+   *
+   * @param {any} x
+   * @returns {x is Uint8Array}
+   */
+  static isSeed(x) {
+    if (!b4a.isBuffer(x) && !(x instanceof Uint8Array)) return false
+    return x.length === 16 || x.length === 32
+  }
+
+  /**
+   * Validate that a string is a BIP-39 mnemonic.
+   *
+   * @param {unknown} x
+   * @returns {x is string}
+   */
+  static isPhrase(x) {
+    if (typeof x !== 'string') return false
+    try {
+      bip39.mnemonicToEntropy(x)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  /**
+   * Verify a signature against an arbitrary public key.
+   *
+   * @param {Uint8Array} publicKey
+   * @param {Uint8Array} message
+   * @param {Uint8Array} signature
+   * @returns {boolean}
+   */
+  static verify(publicKey, message, signature) {
+    return sodium.crypto_sign_verify_detached(signature, message, publicKey)
+  }
+
+  /**
+   * Generate a fresh Ed25519 keypair (for devices, blind invites, etc.).
+   *
+   * @returns {KeyPair}
+   */
+  static randomKeyPair() {
+    const publicKey = b4a.alloc(sodium.crypto_sign_PUBLICKEYBYTES)
+    const secretKey = b4a.alloc(sodium.crypto_sign_SECRETKEYBYTES)
+    sodium.crypto_sign_keypair(publicKey, secretKey)
+    return { publicKey, secretKey, id: toId(publicKey) }
+  }
+
+  /**
+   * N bytes from a CSPRNG.
+   *
+   * @param {number} [n]
+   * @returns {Uint8Array}
+   */
+  static randomBytes(n = 32) {
+    const buf = b4a.alloc(n)
+    sodium.randombytes_buf(buf)
+    return buf
+  }
+
+  /**
+   * Fresh seed entropy sized for the chosen mnemonic length.
+   *
+   * @param {12 | 24} [words]
+   * @returns {Uint8Array}
+   */
+  static randomSeed(words = 12) {
+    if (words !== 12 && words !== 24) throw new RangeError('words must be 12 or 24')
+    return Identity.randomBytes((words / 3) * 4)
+  }
+}
+
+function topicOf(publicKey) {
+  const topic = b4a.alloc(32)
+  sodium.crypto_generichash(topic, publicKey)
+  return topic
+}

package/src/index.js

@@ -1 +1,20 @@
-export * from './lib/index.js'
+/**
+ * @cero-base/core — primitives for building p2p applications. This barrel
+ * re-exports the canonical surface: identity, storage, network, database,
+ * blobs, rpc, pairing, the schema DSL, the error class, and shared utils.
+ *
+ * Tree-shake-friendly: subpath imports (`@cero-base/core/identity`, etc.)
+ * are also available for consumers that need a smaller graph.
+ */
+
+export { Identity } from './identity/index.js'
+export { Storage } from './storage/index.js'
+export { Network } from './network/index.js'
+export { Database } from './database/index.js'
+export { Blobs } from './blobs/index.js'
+export { RPCServer, RPCClient, bindCodec } from './rpc/index.js'
+export { Pairing } from './pairing/index.js'
+export { Invite } from './pairing/invite.js'
+export { t, schema } from './lib/schema.js'
+export { genId, toId, toKey, isKeyId, subscribe } from './lib/utils.js'
+export { CeroError } from './lib/errors.js'

package/src/lib/CLAUDE.md

@@ -0,0 +1,3 @@
+<claude-mem-context>
+
+</claude-mem-context>

package/src/lib/constants.js

@@ -1,4 +1,24 @@
-// User-facing scope names for cero-base schemas
-export const SCOPE_LOCAL = 'local'
-export const SCOPE_PRIVATE = 'private'
-export const SCOPE_SHARED = 'shared'
+// Schema kinds
+export const SINGLE = 'single'
+export const COLLECTION = 'collection'
+export const HANDLE = 'handle'
+export const ACTION = 'action'
+
+// Network topic modes
+export const ACTIVE = 'active'
+export const PASSIVE = 'passive'
+
+// Storage backends
+export const ROCKS = 'rocks'
+export const BEE = 'bee'
+
+// Roles
+export const OWNER = 'owner'
+export const WRITE = 'write'
+export const READ = 'read'
+
+// Identity / hypercore namespace
+export const NAMESPACE = 'cero'
+
+// Internal counter collection (assigns monotonic `index` to every row in every collection)
+export const COUNTERS = 'counters'

package/src/lib/errors.js

@@ -0,0 +1,150 @@
+/**
+ * Canonical error class. Every instance carries a stable `code` field which
+ * is also prefixed to the message, so logs stay self-identifying. Static
+ * factories produce errors with the right code + a sensible message.
+ */
+export class CeroError extends Error {
+  /**
+   * @param {string} code            Stable identifier (e.g. `REQUIRED`, `EXPIRED`).
+   * @param {string} [message]       Human-readable detail; appended after the code.
+   * @param {Record<string, unknown> | null} [extras]  Extra fields copied onto the instance.
+   */
+  constructor(code, message, extras = null) {
+    super(message ? `${code}: ${message}` : code)
+    this.isCeroError = true
+    this.code = code
+    if (extras) Object.assign(this, extras)
+    if (Error.captureStackTrace) Error.captureStackTrace(this, CeroError)
+  }
+
+  get name() {
+    return 'CeroError'
+  }
+
+  /**
+   * Type-guard for `err instanceof CeroError` that survives realm boundaries.
+   *
+   * @param {any} err
+   * @returns {err is CeroError}
+   */
+  static isCeroError(err) {
+    return err?.isCeroError === true
+  }
+
+  /**
+   * Missing required argument.
+   *
+   * @param {string} name
+   */
+  static REQUIRED(name) {
+    return new CeroError('REQUIRED', `${name} is required`)
+  }
+  /**
+   * Argument failed validation.
+   *
+   * @param {string} msg
+   */
+  static INVALID(msg) {
+    return new CeroError('INVALID', msg)
+  }
+  /**
+   * Operation on a closed resource.
+   *
+   * @param {string} resource
+   */
+  static CLOSED(resource) {
+    return new CeroError('CLOSED', `${resource} is closed`)
+  }
+  /**
+   * Operation before `ready()` resolved.
+   *
+   * @param {string} resource
+   * @param {string} name
+   */
+  static NOT_READY(resource, name) {
+    return new CeroError('NOT_READY', `${resource} is not ready — await ${name}.ready() first`)
+  }
+  /**
+   * Resource has been destroyed.
+   *
+   * @param {string} resource
+   */
+  static DESTROYED(resource) {
+    return new CeroError('DESTROYED', `${resource} is destroyed`)
+  }
+  /**
+   * Lookup failed for a typed id.
+   *
+   * @param {string} kind
+   * @param {string} id
+   */
+  static UNKNOWN(kind, id) {
+    return new CeroError('UNKNOWN', `unknown ${kind}: ${id}`)
+  }
+  /**
+   * Write attempted on a read-only handle.
+   *
+   * @param {string} resource
+   */
+  static NOT_WRITABLE(resource) {
+    return new CeroError('NOT_WRITABLE', `${resource} is not writable`)
+  }
+  /**
+   * Async operation exceeded its deadline.
+   *
+   * @param {string} what
+   */
+  static TIMED_OUT(what) {
+    return new CeroError('TIMED_OUT', `${what} timed out`)
+  }
+  /**
+   * Feature is not yet implemented.
+   *
+   * @param {string} what
+   */
+  static UNSUPPORTED(what) {
+    return new CeroError('UNSUPPORTED', `${what} not yet supported`)
+  }
+
+  /**
+   * Invite payload failed to parse or verify.
+   *
+   * @param {string} [msg]
+   */
+  static INVALID_INVITE(msg = 'invalid invite') {
+    return new CeroError('INVALID_INVITE', msg)
+  }
+  /**
+   * Invite is past its TTL.
+   *
+   * @param {string} [msg]
+   */
+  static EXPIRED(msg = 'invite expired') {
+    return new CeroError('EXPIRED', msg)
+  }
+  /**
+   * Host refused the join — `reason` is exposed on the instance.
+   *
+   * @param {string | null} [reason]
+   * @param {string} [msg]
+   */
+  static DENIED(reason = null, msg = 'pairing denied') {
+    return new CeroError('DENIED', msg, { reason })
+  }
+  /**
+   * Pairing handshake did not complete in time.
+   *
+   * @param {string} [msg]
+   */
+  static TIMEOUT(msg = 'pairing timed out') {
+    return new CeroError('TIMEOUT', msg)
+  }
+  /**
+   * Underlying swarm/transport failure.
+   *
+   * @param {string} [msg]
+   */
+  static NETWORK_ERROR(msg = 'network error') {
+    return new CeroError('NETWORK_ERROR', msg)
+  }
+}