@cero-base/cero 0.4.0

package/src/index.js

@@ -0,0 +1,170 @@
+import HypercoreStorage from 'hypercore-storage'
+import Corestore from 'corestore'
+import fs from 'fs'
+
+import { Identity } from '@cero-base/core/identity'
+import { Network } from '@cero-base/core/network'
+import { CeroError } from '@cero-base/core/errors'
+
+import { Handle, Ref } from './handle/index.js'
+import { Local } from './local/index.js'
+import { put, set, get, del, count, watch, call, open } from './lib/operators.js'
+import { peek } from './lib/peek.js'
+import { t, schema } from './lib/spec.js'
+
+export { Handle, Ref, Local }
+export { put, set, get, del, count, watch, call, open } from './lib/operators.js'
+export { peek } from './lib/peek.js'
+export { t, schema } from './lib/spec.js'
+
+/**
+ * @typedef {object} CeroOpts
+ * @property {Identity} [identity]                     Pre-resolved identity. If absent, derived from `seed`/`phrase` or generated.
+ * @property {Uint8Array} [seed]                       16- or 32-byte seed entropy.
+ * @property {string} [phrase]                         BIP-39 mnemonic — alternative to `seed`.
+ * @property {12 | 24} [words]                         Mnemonic length when generating a fresh identity.
+ * @property {string | null} [name]                    Friendly device name persisted on the identity claim.
+ * @property {boolean} [isMobile]                      Marks this device as mobile.
+ * @property {Array<{ host: string, port: number }>} [bootstrap]  Custom DHT bootstrap nodes.
+ * @property {Uint8Array} [key]                        Pre-existing database key (skip bootstrap).
+ * @property {Uint8Array} [encryptionKey]              Pre-existing encryption key.
+ * @property {Record<string, Function>} [routes]       Custom RPC routes for the database dispatcher.
+ * @property {(err: any) => void} [onerror]            Background-task error handler.
+ * @property {boolean} [recovery]                      Recovery flow — wipe local state and re-claim a writer slot.
+ * @property {number} [recoveryTimeout]                Max wait for writer capability during recovery.
+ */
+
+/**
+ * Open (or create) a cero handle at `dir`. Sets up storage, network and
+ * identity, then returns a ready root `Handle` with all schema refs
+ * attached as properties.
+ *
+ * @param {string} dir       Data directory.
+ * @param {any} spec         Built spec — output of `cero/build`.
+ * @param {CeroOpts} [opts]
+ * @returns {Promise<Handle>}
+ */
+export async function cero(dir, spec, opts = {}) {
+  if (typeof dir !== 'string' || !dir) throw CeroError.INVALID('dir must be a non-empty string')
+  if (!spec) throw CeroError.REQUIRED('spec')
+
+  const storage = new HypercoreStorage(`${dir}/main`)
+  await storage.ready()
+  const store = new Corestore(storage, { manifestVersion: 2 })
+  await store.ready()
+
+  let local = null
+  if (spec.local && spec.meta?.local) {
+    local = new Local(null, spec, { store })
+    await local.ready()
+  }
+
+  const identity = await resolveIdentity(opts, local)
+  const writer = local ? (await local.store.get('keypair')).data : null
+
+  const network = new Network({ bootstrap: opts.bootstrap })
+  await network.ready()
+  const discovery = network.join(identity.topic)
+  await Promise.race([discovery.flush(), new Promise((r) => setTimeout(r, 500))])
+
+  const me = new Handle({
+    storage,
+    store,
+    local,
+    discovery,
+    identity,
+    network,
+    spec,
+    opts,
+    dir,
+    routes: opts.routes,
+    key: opts.key,
+    encryptionKey: opts.encryptionKey,
+    keyPair: writer ? { publicKey: writer.publicKey, secretKey: writer.secretKey } : undefined,
+    pair: false
+  })
+  await me.ready()
+
+  if (!writer && me.store.length === 0 && (!opts.key || opts.recovery)) {
+    const result = await me.bootstrap({
+      name: opts.name || null,
+      isMobile: opts.isMobile === true,
+      recovering: opts.recovery === true
+    })
+    if (local && result?.writer) {
+      await local.store.set('keypair', {
+        publicKey: result.writer.publicKey,
+        secretKey: result.writer.secretKey
+      })
+    }
+    if (!opts.recovery) {
+      const ts = Date.now()
+      await me.store.call('add-member', {
+        id: identity.id,
+        key: me.store.writerKey,
+        role: 'owner',
+        name: opts.name || null,
+        createdAt: ts,
+        updatedAt: ts
+      })
+    }
+  }
+  if (opts.recovery)
+    await me.recover({
+      timeout: opts.recoveryTimeout,
+      name: opts.name || null,
+      isMobile: opts.isMobile === true
+    })
+
+  return me
+}
+
+/**
+ * Restore a cero instance from a mnemonic phrase. Closes the running
+ * instance, wipes the on-disk `main/` tree and re-opens with `recovery: true`
+ * so the writer slot is re-claimed.
+ *
+ * @param {Handle} me   Existing root handle to restore.
+ * @param {string} phrase   BIP-39 mnemonic phrase.
+ * @returns {Promise<Handle>}  Freshly restored root handle.
+ */
+export async function restore(me, phrase) {
+  if (!me?._dir) throw CeroError.INVALID('me must be a cero instance')
+  if (!phrase || typeof phrase !== 'string') throw CeroError.INVALID('phrase must be a string')
+
+  const { _dir: dir, spec, _opts: opts } = me
+  const { name, bootstrap, isMobile, onerror, routes, recoveryTimeout } = opts
+
+  await me.close()
+  await fs.promises.rm(`${dir}/main`, { recursive: true, force: true })
+
+  return cero(dir, spec, {
+    name,
+    bootstrap,
+    isMobile,
+    onerror,
+    routes,
+    recoveryTimeout,
+    phrase,
+    recovery: true
+  })
+}
+
+Object.assign(cero, { put, set, get, del, count, watch, call, open, peek, restore, t, schema })
+
+async function resolveIdentity(opts, local) {
+  if (opts.identity) return opts.identity
+
+  const provided = opts.seed || (opts.phrase && Identity.toSeed(opts.phrase))
+  if (provided) {
+    if (local) await local.store.set('master', { seed: provided })
+    return Identity.fromSeed(provided)
+  }
+
+  const stored = local && (await local.store.get('master')).data?.seed
+  if (stored) return Identity.fromSeed(stored)
+
+  const fresh = await Identity.generate({ words: opts.words })
+  if (local) await local.store.set('master', { seed: fresh.seed })
+  return fresh
+}

package/src/lib/CLAUDE.md

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

package/src/lib/builtins.js

@@ -0,0 +1,410 @@
+/**
+ * Builtin type/collection/dispatch/rpc definitions used by the builder.
+ * Every cero schema includes these; user-defined refs are added on top.
+ *
+ * @typedef {{ name: string, type: string, verb?: string, kind?: string }} BuiltinRef
+ * @typedef {{ name: string, type: string, required: boolean }} FieldDesc
+ * @typedef {{ name: string, compact: boolean, fields: FieldDesc[] }} TypeDesc
+ * @typedef {{ name: string, schema: string, key: string[] }} CollectionDesc
+ * @typedef {{ name: string, requestType: string }} DispatchDesc
+ * @typedef {{
+ *   name: string,
+ *   request: { name: string },
+ *   response: { name: string, stream?: boolean }
+ * }} CommandDesc
+ */
+
+/**
+ * Refs that exist on every main (Handle) schema.
+ *
+ * @type {BuiltinRef[]}
+ */
+export const BUILTINS = [
+  { name: 'members', type: 'member', verb: 'member' },
+  { name: 'devices', type: 'device', verb: 'device' },
+  { name: 'invites', type: 'invite', verb: 'invite' },
+  { name: 'handles', type: 'handle', verb: 'handle' }
+]
+
+/**
+ * Refs that exist on every local schema.
+ *
+ * @type {BuiltinRef[]}
+ */
+export const LOCAL_BUILTINS = [
+  { name: 'master', type: 'master', kind: 'single' },
+  { name: 'keypair', type: 'keypair', kind: 'single' },
+  { name: 'handle-keypairs', type: 'handle-keypair', kind: 'collection' }
+]
+
+const HYPERDB_TYPE = {
+  string: 'string',
+  uint: 'uint',
+  int: 'int',
+  bool: 'bool',
+  bytes: 'buffer',
+  json: 'json',
+  fixed32: 'fixed32',
+  fixed64: 'fixed64'
+}
+
+/**
+ * Map a schema-DSL primitive name to its HyperDB type name.
+ *
+ * @param {string} prim
+ * @returns {string}
+ */
+export function hyperdbType(prim) {
+  return HYPERDB_TYPE[prim] || 'string'
+}
+
+/**
+ * Type descriptors registered into every main schema.
+ *
+ * @returns {TypeDesc[]}
+ */
+export function builtinTypes() {
+  return [
+    { name: 'del-by-id', compact: false, fields: [{ name: 'id', type: 'string', required: true }] },
+    {
+      name: 'writer',
+      compact: false,
+      fields: [
+        { name: 'master', type: 'buffer', required: true },
+        { name: 'writer', type: 'buffer', required: true },
+        { name: 'sig', type: 'buffer', required: true },
+        { name: 'name', type: 'string', required: false },
+        { name: 'isMobile', type: 'bool', required: false },
+        { name: 'isIndexer', type: 'bool', required: false }
+      ]
+    },
+    {
+      name: 'counter',
+      compact: false,
+      fields: [
+        { name: 'name', type: 'string', required: true },
+        { name: 'value', type: 'uint', required: true }
+      ]
+    },
+    {
+      name: 'member',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'key', type: 'buffer', required: true },
+        { name: 'role', type: 'string', required: true },
+        { name: 'name', type: 'string', required: false },
+        { name: 'createdAt', type: 'int', required: false },
+        { name: 'updatedAt', type: 'int', required: false },
+        { name: 'sig', type: 'buffer', required: false },
+        { name: 'index', type: 'uint', required: false }
+      ]
+    },
+    {
+      name: 'device',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'memberId', type: 'string', required: false },
+        { name: 'name', type: 'string', required: false },
+        { name: 'isMobile', type: 'bool', required: false },
+        { name: 'createdAt', type: 'int', required: false },
+        { name: 'updatedAt', type: 'int', required: false },
+        { name: 'index', type: 'uint', required: false }
+      ]
+    },
+    {
+      name: 'invite',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'invite', type: 'buffer', required: true },
+        { name: 'publicKey', type: 'buffer', required: true },
+        { name: 'data', type: 'buffer', required: false },
+        { name: 'sig', type: 'buffer', required: false },
+        { name: 'role', type: 'string', required: true },
+        { name: 'expires', type: 'int', required: false },
+        { name: 'createdAt', type: 'int', required: false },
+        { name: 'index', type: 'uint', required: false }
+      ]
+    },
+    {
+      name: 'handle',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'type', type: 'string', required: true },
+        { name: 'key', type: 'buffer', required: true },
+        { name: 'encryptionKey', type: 'buffer', required: false },
+        { name: 'name', type: 'string', required: false },
+        { name: 'createdAt', type: 'int', required: false },
+        { name: 'updatedAt', type: 'int', required: false },
+        { name: 'index', type: 'uint', required: false }
+      ]
+    },
+    {
+      name: 'claim',
+      compact: false,
+      fields: [
+        { name: 'identity', type: 'buffer', required: true },
+        { name: 'writer', type: 'buffer', required: true },
+        { name: 'sig', type: 'buffer', required: true },
+        { name: 'name', type: 'string', required: false },
+        { name: 'isMobile', type: 'bool', required: false }
+      ]
+    }
+  ]
+}
+
+/** Collection name for the internal counters table. */
+export const COUNTERS = 'counters'
+
+/**
+ * Collection descriptors for every main schema, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {CollectionDesc[]}
+ */
+export function builtinCollections(ns) {
+  const out = BUILTINS.map((b) => ({ name: b.name, schema: `@${ns}/${b.type}`, key: ['id'] }))
+  out.push({ name: COUNTERS, schema: `@${ns}/counter`, key: ['name'] })
+  return out
+}
+
+/**
+ * Dispatch (mutation) descriptors for every main schema, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {DispatchDesc[]}
+ */
+export function builtinDispatches(ns) {
+  const at = (n) => `@${ns}/${n}`
+  const out = [
+    { name: 'add-writer', requestType: at('writer') },
+    { name: 'del-writer', requestType: at('writer') },
+    { name: 'claim-writer', requestType: at('claim') }
+  ]
+  for (const b of BUILTINS) {
+    out.push({ name: `add-${b.verb}`, requestType: at(b.type) })
+    out.push({ name: `set-${b.verb}`, requestType: at(b.type) })
+    out.push({ name: `del-${b.verb}`, requestType: at('del-by-id') })
+  }
+  return out
+}
+
+/**
+ * Type descriptors registered into every local schema.
+ *
+ * @returns {TypeDesc[]}
+ */
+export function localBuiltinTypes() {
+  return [
+    { name: 'master', compact: false, fields: [{ name: 'seed', type: 'buffer', required: true }] },
+    {
+      name: 'keypair',
+      compact: false,
+      fields: [
+        { name: 'publicKey', type: 'buffer', required: true },
+        { name: 'secretKey', type: 'buffer', required: true }
+      ]
+    },
+    {
+      name: 'handle-keypair',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'publicKey', type: 'buffer', required: true },
+        { name: 'secretKey', type: 'buffer', required: true },
+        { name: 'encryptionKey', type: 'buffer', required: false }
+      ]
+    }
+  ]
+}
+
+/**
+ * Collection descriptors for every local schema, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {CollectionDesc[]}
+ */
+export function localBuiltinCollections(ns) {
+  return [
+    { name: 'master', schema: `@${ns}/master`, key: [] },
+    { name: 'keypair', schema: `@${ns}/keypair`, key: [] },
+    { name: 'handle-keypairs', schema: `@${ns}/handle-keypair`, key: ['id'] }
+  ]
+}
+
+/**
+ * Request/response type descriptors for the RPC facade.
+ *
+ * @returns {TypeDesc[]}
+ */
+export function rpcTypes() {
+  return [
+    { name: 'req-empty', compact: false, fields: [{ name: 'ok', type: 'bool', required: false }] },
+    {
+      name: 'req-restore',
+      compact: false,
+      fields: [{ name: 'phrase', type: 'string', required: true }]
+    },
+    {
+      name: 'req-row',
+      compact: false,
+      fields: [
+        { name: 'handle', type: 'string', required: true },
+        { name: 'ref', type: 'string', required: true },
+        { name: 'data', type: 'buffer', required: true }
+      ]
+    },
+    {
+      name: 'req-id',
+      compact: false,
+      fields: [
+        { name: 'handle', type: 'string', required: true },
+        { name: 'ref', type: 'string', required: true },
+        { name: 'id', type: 'string', required: true }
+      ]
+    },
+    {
+      name: 'req-query',
+      compact: false,
+      fields: [
+        { name: 'handle', type: 'string', required: true },
+        { name: 'ref', type: 'string', required: true },
+        { name: 'query', type: 'buffer', required: false }
+      ]
+    },
+    {
+      name: 'req-call',
+      compact: false,
+      fields: [
+        { name: 'handle', type: 'string', required: true },
+        { name: 'op', type: 'string', required: true },
+        { name: 'data', type: 'buffer', required: false }
+      ]
+    },
+    {
+      name: 'req-invite',
+      compact: false,
+      fields: [
+        { name: 'handle', type: 'string', required: true },
+        { name: 'role', type: 'string', required: false }
+      ]
+    },
+    {
+      name: 'req-revoke',
+      compact: false,
+      fields: [
+        { name: 'handle', type: 'string', required: true },
+        { name: 'invite', type: 'string', required: true }
+      ]
+    },
+    {
+      name: 'req-join',
+      compact: false,
+      fields: [
+        { name: 'parent', type: 'string', required: true },
+        { name: 'ref', type: 'string', required: true },
+        { name: 'invite', type: 'string', required: true }
+      ]
+    },
+    {
+      name: 'req-open',
+      compact: false,
+      fields: [
+        { name: 'parent', type: 'string', required: true },
+        { name: 'row', type: 'string', required: true }
+      ]
+    },
+    {
+      name: 'req-handle',
+      compact: false,
+      fields: [{ name: 'handle', type: 'string', required: true }]
+    },
+    {
+      name: 'res-data',
+      compact: false,
+      fields: [{ name: 'data', type: 'buffer', required: false }]
+    },
+    {
+      name: 'res-rows',
+      compact: false,
+      fields: [
+        { name: 'data', type: 'buffer', required: true },
+        { name: 'total', type: 'int', required: true },
+        { name: 'size', type: 'int', required: true }
+      ]
+    },
+    { name: 'res-count', compact: false, fields: [{ name: 'count', type: 'int', required: true }] },
+    {
+      name: 'res-invite',
+      compact: false,
+      fields: [{ name: 'invite', type: 'string', required: true }]
+    },
+    {
+      name: 'res-handle',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'type', type: 'string', required: true },
+        { name: 'name', type: 'string', required: false }
+      ]
+    },
+    {
+      name: 'res-identity',
+      compact: false,
+      fields: [
+        { name: 'id', type: 'string', required: true },
+        { name: 'deviceId', type: 'string', required: false },
+        { name: 'phrase', type: 'string', required: false }
+      ]
+    },
+    { name: 'res-ok', compact: false, fields: [{ name: 'ok', type: 'bool', required: false }] }
+  ]
+}
+
+/**
+ * RPC command (verb) descriptors for the cero server, namespaced under `ns`.
+ *
+ * @param {string} ns
+ * @returns {CommandDesc[]}
+ */
+export function rpcCommands(ns) {
+  const at = (n) => `@${ns}/${n}`
+  return [
+    {
+      name: 'init',
+      request: { name: at('req-empty') },
+      response: { name: at('res-identity') }
+    },
+    {
+      name: 'restore',
+      request: { name: at('req-restore') },
+      response: { name: at('res-identity') }
+    },
+    { name: 'add-row', request: { name: at('req-row') }, response: { name: at('res-data') } },
+    { name: 'add-handle', request: { name: at('req-row') }, response: { name: at('res-handle') } },
+    { name: 'set', request: { name: at('req-row') }, response: { name: at('res-data') } },
+    { name: 'get', request: { name: at('req-query') }, response: { name: at('res-rows') } },
+    { name: 'get-one', request: { name: at('req-id') }, response: { name: at('res-data') } },
+    { name: 'del', request: { name: at('req-id') }, response: { name: at('res-ok') } },
+    { name: 'count', request: { name: at('req-query') }, response: { name: at('res-count') } },
+    {
+      name: 'watch',
+      request: { name: at('req-query') },
+      response: { name: at('res-rows'), stream: true }
+    },
+    { name: 'call', request: { name: at('req-call') }, response: { name: at('res-data') } },
+    { name: 'invite', request: { name: at('req-invite') }, response: { name: at('res-invite') } },
+    { name: 'revoke', request: { name: at('req-revoke') }, response: { name: at('res-ok') } },
+    { name: 'join', request: { name: at('req-join') }, response: { name: at('res-handle') } },
+    {
+      name: 'open-handle',
+      request: { name: at('req-open') },
+      response: { name: at('res-handle') }
+    },
+    { name: 'close-handle', request: { name: at('req-handle') }, response: { name: at('res-ok') } },
+    { name: 'leave', request: { name: at('req-handle') }, response: { name: at('res-ok') } }
+  ]
+}