@cero-base/core 0.0.5 → 0.4.0

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)
+  }
+}

package/src/lib/schema.js

@@ -1,203 +1,68 @@
-import { singular, toFields, scopeNs, isLocal, isPrivate, isShared } from './utils.js'
-import { SCOPE_LOCAL, SCOPE_PRIVATE, SCOPE_SHARED } from './constants.js'
+import { CeroError } from './errors.js'
+import { SINGLE, COLLECTION, ACTION } from './constants.js'
 
 /**
- * Type helpers for defining schema fields
- * Usage: { name: t.string, count: t.int, active: t.bool }
+ * @typedef {{ prim: string }} Prim
+ * @typedef {{ kind: 'single' | 'collection' | 'action', fields: Record<string, Prim> }} TypeDef
+ * @typedef {{ [name: string]: TypeDef | Record<string, TypeDef> } & { local?: Record<string, TypeDef> }} SchemaDefs
+ * @typedef {{ defs: SchemaDefs }} Schema
  */
-export const t = {
-  string: { type: 'string', required: true },
-  int: { type: 'int', required: true },
-  uint: { type: 'uint', required: true },
-  float: { type: 'float', required: true },
-  bool: { type: 'bool', required: true },
-  buffer: { type: 'buffer', required: true },
-  fixed32: { type: 'fixed32', required: true },
-  json: { type: 'json', required: true },
 
-  optional: (field) => ({ ...field, required: false }),
-  array: (field) => ({ ...field, array: true }),
-  ref: (collection) => ({ type: 'string', required: true, ref: collection })
-}
+/** @param {string} name @returns {Prim} */
+const prim = (name) => ({ prim: name })
 
-function schemaFields(def) {
-  const fields = toFields(def.fields)
-  // every type gets index for range queries / pagination (assigned by cero's Base)
-  fields.push({ name: 'index', type: 'uint', required: false })
-  if (def.timestamps) {
-    fields.push({ name: 'createdAt', type: 'uint', required: true })
-    fields.push({ name: 'updatedAt', type: 'uint', required: false })
+/**
+ * Schema DSL. Primitive field types and kind-constructors used to describe
+ * a database's tables before the builder turns them into a wire spec.
+ */
+export const t = {
+  string: prim('string'),
+  uint: prim('uint'),
+  int: prim('int'),
+  bool: prim('bool'),
+  bytes: prim('bytes'),
+  json: prim('json'),
+  fixed32: prim('fixed32'),
+  fixed64: prim('fixed64'),
+
+  /**
+   * Single-row table (one record, set/get by name).
+   *
+   * @param {Record<string, Prim>} fields
+   * @returns {TypeDef}
+   */
+  single(fields) {
+    return { kind: SINGLE, fields }
+  },
+
+  /**
+   * Multi-row table keyed by `id`.
+   *
+   * @param {Record<string, Prim>} fields
+   * @returns {TypeDef}
+   */
+  collection(fields) {
+    return { kind: COLLECTION, fields }
+  },
+
+  /**
+   * RPC-style mutation that doesn't persist a row.
+   *
+   * @param {Record<string, Prim>} fields
+   * @returns {TypeDef}
+   */
+  action(fields) {
+    return { kind: ACTION, fields }
   }
-  return fields
-}
-
-function inputFields(def) {
-  return toFields(def.fields).map((f) => ({ ...f, required: false }))
-}
-
-function delFields(def) {
-  const keys = {}
-  for (const k of def.key || ['id']) keys[k] = def.fields[k]
-  return toFields(keys)
 }
 
-t.schema = defineSchema
-
-export function defineSchema(collections, opts = {}) {
-  const entries = Object.entries(collections)
-  const types = new Map(entries.map(([name]) => [name, singular(name)]))
-
-  const getScope = ([, def]) => def.scope || SCOPE_PRIVATE
-  const localEntries = entries.filter((e) => getScope(e) === SCOPE_LOCAL)
-  const privateEntries = entries.filter((e) => getScope(e) === SCOPE_PRIVATE)
-  const sharedEntries = entries.filter((e) => getScope(e) === SCOPE_SHARED)
-
-  const nsFor = (scope) => (scope === SCOPE_SHARED && opts.namespace) || scopeNs(scope)
-
-  return {
-    namespace: opts.namespace || null,
-    collections,
-    types,
-
-    getScope(collection) {
-      const def = collections[collection]
-      return def ? def.scope || SCOPE_PRIVATE : null
-    },
-
-    isLocal(collection) {
-      return isLocal(this.getScope(collection))
-    },
-    isPrivate(collection) {
-      return isPrivate(this.getScope(collection))
-    },
-    isShared(collection) {
-      return isShared(this.getScope(collection))
-    },
-
-    hasTimestamps(collection) {
-      return collections[collection]?.timestamps === true
-    },
-
-    hasCounter(collection) {
-      return collections[collection]?.counter === true
-    },
-
-    counterNames(scope) {
-      const items =
-        scope === SCOPE_SHARED
-          ? sharedEntries
-          : scope === SCOPE_LOCAL
-            ? localEntries
-            : privateEntries
-      // map: type name (singular) → collection name (plural)
-      const map = {}
-      for (const [name, def] of items) {
-        if (def.counter) map[types.get(name)] = name
-      }
-      return map
-    },
-
-    resolve(collection, prefix) {
-      const scope = this.getScope(collection)
-      const type = types.get(collection)
-      const name = prefix ? `${prefix}-${type}` : type
-      return { spec: scopeNs(scope), path: `@${nsFor(scope)}/${name}` }
-    },
-
-    require(collection, context) {
-      const scope = this.getScope(collection)
-      if (!scope) throw new Error(`Unknown collection: '${collection}'`)
-      if (context === 'db' && scope === SCOPE_SHARED) {
-        throw new Error(`'${collection}' is shared — use room.collection('${collection}')`)
-      }
-      if (context === 'room' && scope !== SCOPE_SHARED) {
-        throw new Error(`'${collection}' is ${scope} — use db.collection('${collection}')`)
-      }
-      return scope
-    },
-
-    getPath(collection) {
-      const scope = this.getScope(collection)
-      return `@${nsFor(scope)}/${collection}`
-    },
-
-    build(scope, register, nsName) {
-      const items =
-        scope === SCOPE_SHARED
-          ? sharedEntries
-          : scope === SCOPE_LOCAL
-            ? localEntries
-            : privateEntries
-      const local = scope === SCOPE_LOCAL
-      const ns = nsName || scopeNs(scope)
-      for (const [name, def] of items) {
-        const type = types.get(name)
-        const fields = schemaFields(def)
-        const typePath = `@${ns}/${type}`
-
-        register.type({ name: type, compact: false, fields })
-        register.type({ name: `input-${type}`, compact: false, fields: inputFields(def) })
-        if (!local) register.type({ name: `del-${type}`, compact: false, fields: delFields(def) })
-
-        register.collection({
-          name,
-          schema: typePath,
-          key: def.key || ['id'],
-          counter: !!def.counter
-        })
-
-        if (def.indexes) {
-          for (const [idx, idxFields] of Object.entries(def.indexes)) {
-            register.index({ name: `${name}-${idx}`, collection: `@${ns}/${name}`, key: idxFields })
-          }
-        }
-
-        if (!local) {
-          register.dispatch({ name: `add-${type}`, requestType: typePath })
-          register.dispatch({ name: `set-${type}`, requestType: typePath })
-          register.dispatch({ name: `del-${type}`, requestType: `@${ns}/del-${type}` })
-        }
-      }
-    },
-
-    routes(scope) {
-      const items = scope === SCOPE_PRIVATE ? privateEntries : sharedEntries
-      const handlers = {}
-      const p = (name) => `@${nsFor(scope)}/${name}`
-      for (const [name, def] of items) {
-        const type = types.get(name)
-        const path = p(name)
-        const keys = def.key || ['id']
-
-        handlers[p(`add-${type}`)] = async (op, ctx) => {
-          const counterPath = p('counters')
-          const counter = (await ctx.view.get(counterPath, { name })) || { name, value: 0 }
-          op.index = counter.value
-          counter.value++
-          await ctx.view.insert(counterPath, counter)
-          await ctx.view.insert(path, op)
-        }
-
-        handlers[p(`set-${type}`)] = (op, ctx) => ctx.view.insert(path, op)
-        handlers[p(`del-${type}`)] = async (op, ctx) => {
-          await ctx.view.delete(
-            path,
-            keys.reduce((acc, k) => ((acc[k] = op[k]), acc), {})
-          )
-          const counterPath = p('counters')
-          const counter = (await ctx.view.get(counterPath, { name })) || { name, value: 0 }
-          counter.value = Math.max(0, counter.value - 1)
-          await ctx.view.insert(counterPath, counter)
-        }
-
-        if (def.handlers) {
-          for (const [op, handler] of Object.entries(def.handlers)) {
-            handlers[p(op)] = handler
-          }
-        }
-      }
-
-      return handlers
-    }
-  }
+/**
+ * Wrap a definitions object so the builder can recognise it as a schema.
+ *
+ * @param {SchemaDefs} defs
+ * @returns {Schema}
+ */
+export function schema(defs) {
+  if (!defs || typeof defs !== 'object') throw CeroError.INVALID('schema(defs) must be an object')
+  return { defs }
 }