@cero-base/cero 1.1.1 → 1.3.0

package/README.md

@@ -46,18 +46,19 @@ Ships with TypeScript declarations (`.d.ts`) generated from JSDoc.
 
 ## `cero(dir, spec, opts?)`
 
-| Opt                 | Meaning                                                                                                                                                                                                                                                |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `bootstrap`         | Hyperswarm bootstrap nodes.                                                                                                                                                                                                                            |
-| `channel`           | Optional network-isolation label. Peers connect only to peers on the **same** channel (it salts every swarm topic); omit it for the global network. A storage remembers its channel and refuses to reopen under a different one. Any string works.     |
-| `name` / `isMobile` | Stamped on the device's `add-writer` event.                                                                                                                                                                                                            |
-| `seed` / `phrase`   | Restore from explicit 16-/32-byte entropy or a BIP-39 mnemonic. Without either, a stored identity is loaded if present, else a fresh one is generated.                                                                                                 |
-| `key`               | Open against an existing bee key (multi-device flow).                                                                                                                                                                                                  |
-| `recovery`          | `true` triggers `bootstrap({ recovering: true })` — for a second device opening with `key` + the same identity. Needed under autobee 1.0.3 so the second device swaps off the identity-keyed bootstrap-writer slot and starts applying remote appends. |
-| `recoveryTimeout`   | Bound on the recovery wait.                                                                                                                                                                                                                            |
-| `routes`            | Custom action handlers keyed by route name.                                                                                                                                                                                                            |
-| `encryptionKey`     | Override the per-identity encryption key.                                                                                                                                                                                                              |
-| `onerror`           | Called with background/async failures that would otherwise be swallowed (failed after-hooks, `onApply` callbacks, pairing candidate errors); the app decides how to log or report them.                                                                |
+| Opt                 | Meaning                                                                                                                                                                                                                                                                |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `bootstrap`         | Hyperswarm bootstrap nodes.                                                                                                                                                                                                                                            |
+| `channel`           | Optional network-isolation label. Peers connect only to peers on the **same** channel (it salts every swarm topic); omit it for the global network. A storage remembers its channel and refuses to reopen under a different one. Any string works.                     |
+| `name` / `isMobile` | Stamped on the device's `add-writer` event.                                                                                                                                                                                                                            |
+| `seed` / `phrase`   | Restore from explicit 16-/32-byte entropy or a BIP-39 mnemonic. Without either, a stored identity is loaded if present, else a fresh one is generated.                                                                                                                 |
+| `key`               | Open against an existing bee key (multi-device flow).                                                                                                                                                                                                                  |
+| `recovery`          | `true` triggers `bootstrap({ recovering: true })` — for a second device opening with `key` + the same identity. Needed under autobee 1.0.3 so the second device swaps off the identity-keyed bootstrap-writer slot and starts applying remote appends.                 |
+| `recoveryTimeout`   | Bound on the recovery wait.                                                                                                                                                                                                                                            |
+| `routes`            | Custom action handlers keyed by route name.                                                                                                                                                                                                                            |
+| `encryptionKey`     | Override the per-identity encryption key.                                                                                                                                                                                                                              |
+| `storageKey`        | 32-byte key encrypting local key material (master seed, device keypairs) at rest. Source it from the OS keychain — cero never stores it, and the same key must be passed on every open. Without it, key material sits plaintext on disk: rely on full-disk encryption. |
+| `onerror`           | Called with background/async failures that would otherwise be swallowed (failed after-hooks, `onApply` callbacks, pairing candidate errors); the app decides how to log or report them.                                                                                |
 
 Reads `me.id`, `me.device`, `me.identity` for canonical metadata. `me.identity.toPhrase()` renders the seed phrase.
 
@@ -240,11 +241,11 @@ cero.watch(me.files).on('data', ({ data }) => render(data)) // live
 
 ### The `file()` column type
 
-For a file referenced from a row — an avatar, a room icon, a message attachment — declare the field `cero.t.file()`. Store the file's `id`; read it back already resolved to `{ id, name, type, size, url }`, with **no extra lookup**:
+For a file referenced from a row — an avatar, a room icon, a message attachment — declare the field `cero.t.file` (a bare marker, not a call). Store the file's `id`; read it back already resolved to `{ id, name, type, size, url }`, with **no extra lookup**:
 
 ```js
 // schema.js
-profile: cero.t.single({ name: cero.t.string, avatar: cero.t.file() })
+profile: cero.t.single({ name: cero.t.string, avatar: cero.t.file })
 
 // save: upload, then store the id on the row
 const { data: pic } = await cero.put(me.files, { data: bytes, type: 'image/png' })
@@ -255,8 +256,6 @@ const { data: profile } = await cero.get(me.profile)
 img.src = profile.avatar.url
 ```
 
-`cero.t.file({ embed: true })` also stores the file's `name` inline — handy for a list of named attachments, so rendering needs no per-item lookup.
-
 ### URLs are local and ephemeral
 
 A `.url` points at a localhost server this device runs, with a per-session token — it changes across restarts and is **not** shareable to other peers. Never persist a `.url`: store the **id** (cero does), and re-read to get a current one. Each member derives their own url from the same id, and the bytes download on demand when the url is first fetched.
@@ -309,12 +308,14 @@ Non-functions in the map are skipped; the handle is returned.
 
 ## Extensions
 
-An extension bundles **schema** (build-time) with **behavior** (runtime). Register it with `cero.use()` — `build()` folds in its schema and `cero()` runs its `setup` once the handle is ready. cero core stays schema-agnostic; apps opt into the behaviors they want.
+An extension bundles **schema** (build-time) with **behavior** (runtime). Register it with `cero.use()` — `build()` folds in its schema and `cero()` runs its `setup` once the handle is ready.
+
+The two bundled extensions (`profileSync`, `handleSync`) are **on by default** — no `cero.use()` needed. To reconfigure one, `cero.use(profileSync({ fields }))` replaces the default (named extensions replace by name, so double registration is harmless). To leave them out entirely, pass `{ extensions: false }` to **both** `build()` and `cero()` — the built spec and the runtime must agree.
 
 ```js
 import { profileSync } from '@cero-base/cero/extensions'
 
-cero.use(profileSync()) // before build() (for the schema) and before cero() (for the behavior)
+cero.use(profileSync({ fields: { status: cero.t.string } })) // reconfigure the default
 await build('./spec', schema)
 ```
 
@@ -373,10 +374,9 @@ setup(me) {
 
 ### `profileSync` (bundled)
 
-Mirrors your `profile` onto your `member` row in every room, so others see your name and avatar. It **declares its own `profile` single** (`name` + the synced fields) and extends `member` with them — no app schema required. Defaults to syncing `avatar`:
+On by default. Mirrors your `profile` onto your `member` row in every room, so others see your name and avatar. It **declares its own `profile` single** (`name` + the synced fields) and extends `member` with them — no app schema required. Defaults to syncing `avatar`:
 
 ```js
-cero.use(profileSync())
 cero.use(profileSync({ fields: { status: cero.t.string } })) // sync extra fields
 ```
 
@@ -384,11 +384,9 @@ Want a richer profile (e.g. a `bio` that doesn't sync)? Declare your own `profil
 
 ### `handleSync` (bundled)
 
-Mirrors a child handle's `profile` (name + avatar) onto its row in the parent's `handles` list — so a handle/room list renders names and photos without opening each handle. Adds `avatar` (or your `fields`) to the `handle` builtin and reflects the handle's own `profile` (which your app owns) onto the row.
+On by default. Mirrors a child handle's `profile` (name + avatar) onto its row in the parent's `handles` list — so a handle/room list renders names and photos without opening each handle. Adds `avatar` (or your `fields`) to the `handle` builtin and reflects the handle's own `profile` (which your app owns) onto the row.
 
 ```js
-cero.use(handleSync())
-
 // your handle type declares a `profile`; your app sets it:
 const room = await cero.open(me.room)
 await cero.set(room.profile, { name: 'general', avatar: 'pic.png' })
@@ -412,7 +410,7 @@ import { spec } from './spec/index.js'
 
 // serve builds and owns the root cero — pass storage + the built spec, not a handle.
 // Returns a Server instance (call server.close() to shut down).
-const server = await serve(Bare.IPC, { storage: './data', spec, seed: '…' })
+const server = await serve(Bare.IPC, { storage: './data', spec, phrase: '…' })
 ```
 
 ### Client (the UI process)
@@ -486,6 +484,37 @@ await serve(s, { storage: './data', spec })
 const remote = await connect(c, spec)
 ```
 
+## Nearby sync (Bluetooth)
+
+Sync with no internet at all. Bluetooth is a transport, not a parallel API — it only changes _how peers meet and carry bytes_; the same refs, guards, roles, and reactivity ride over it unchanged. Volunteers in range converge; hop-by-hop gossip heals partitions as people move.
+
+```js
+const me = await cero(dir, spec, { channel, bluetooth: true })
+
+me.bluetooth.state // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'on'
+await me.bluetooth.start() // runtime toggle
+await me.bluetooth.stop()
+me.bluetooth.peers // Map of live BLE links
+me.bluetooth.on('update', () => {}) // state / peer changes
+```
+
+Inherited for free from the stack: `channel` isolation (the BLE service UUID is derived from the channel, so only same-channel devices discover each other), capability-gated replication (a connected stranger syncs nothing), and offline invite→join. Requires `bare-bluetooth` (an optional peer dep, bundled into the mobile/desktop worklet); absent it, `state` is `'unsupported'` — loud, never silent. macOS + iOS + Android; Linux desktop has no BLE backend today.
+
+**Offline join** — a late volunteer incorporates on the spot, zero internet. Both sides derive a rendezvous UUID from the invite itself; the join side is automatic:
+
+```js
+// organizer, while the invite QR is on screen:
+const invite = await room.invite({ role: 'member', expiresIn: 3600_000 })
+const stop = me.bluetooth.announce(invite)
+// … QR closed:
+stop() // stops the rendezvous; an established link stays and carries the initial replication
+
+// late volunteer — the exact same code as online:
+const room = await cero.open(me.room, invite) // rendezvouses over BLE automatically
+```
+
+The advertisement auto-stops at the invite's `expiresIn` — a photographed QR must not stay an ambient admission ticket.
+
 ## Exports
 
 | Path                         | What you get                                                             |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -18,7 +18,8 @@
     "src",
     "types",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "!**/CLAUDE.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -80,16 +81,17 @@
     "build:types": "rm -rf types && tsc -p .",
     "pretest": "npm run build:test",
     "prepublishOnly": "npm run build:types",
-    "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
+    "test": "ls test/*.test.js | xargs -P1 -n1 brittle-node",
+    "pretest:bare": "npm run build:test",
+    "test:bare": "npx bare test/bare-smoke.js"
   },
   "dependencies": {
-    "@cero-base/core": "^1.1.1",
+    "@cero-base/core": "^1.3.0",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.7.2",
     "bare-path": "^3.0.1",
-    "blind-pairing": "^2.3.1",
     "compact-encoding": "^3.2.0",
     "corestore": "^7.10.1",
     "hrpc": "^4.3.0",
@@ -107,7 +109,16 @@
   "devDependencies": {
     "@hyperswarm/testnet": "^3.1.4",
     "brittle": "^4.0.2",
-    "typescript": "^6.0.3"
+    "typescript": "^5.9.3"
   },
-  "license": "Apache-2.0"
+  "license": "Apache-2.0",
+  "x": 1,
+  "peerDependencies": {
+    "bare-bluetooth": ">=0.2.0"
+  },
+  "peerDependenciesMeta": {
+    "bare-bluetooth": {
+      "optional": true
+    }
+  }
 }

package/src/bluetooth.js

@@ -0,0 +1,190 @@
+import ReadyResource from 'ready-resource'
+import safetyCatch from 'safety-catch'
+
+import { BluetoothTransport } from '@cero-base/core/network/bluetooth'
+import { Pairing } from '@cero-base/core/pairing'
+import { Invite } from '@cero-base/core/invite'
+
+/**
+ * Lazily resolve the bare-bluetooth backend. Absent (Linux, or dep not
+ * bundled) → null, which the facade reports as `state: 'unsupported'`.
+ * Never throws — a missing optional dep is a state, not a crash.
+ *
+ * @returns {Promise<any | null>}
+ */
+async function loadBackend() {
+  try {
+    return await import('bare-bluetooth')
+  } catch {
+    return null
+  }
+}
+
+/**
+ * `me.bluetooth` — the whole app-facing surface for nearby (Bluetooth) sync.
+ * Bluetooth is a cero feature, not a parallel API: it only changes how peers
+ * meet and carry bytes; capability-gated replication still decides what syncs.
+ *
+ * ```js
+ * const me = await cero(dir, spec, { channel, bluetooth: true })
+ * me.bluetooth.state          // 'unsupported' | 'unauthorized' | 'off' | 'waiting' | 'on'
+ * await me.bluetooth.start()
+ * me.bluetooth.peers          // Map of live BLE links
+ * me.bluetooth.on('update', () => {})
+ * ```
+ *
+ * @extends ReadyResource
+ */
+export class Bluetooth extends ReadyResource {
+  /**
+   * @param {object} handle           Root cero Handle (network + identity + channel).
+   * @param {object} [opts]
+   * @param {any} [opts.backend]      Injected bare-bluetooth-shaped backend (tests); lazy-loaded when absent.
+   * @param {boolean} [opts.autoStart]  Start on handle open (from `cero({ bluetooth: true })`).
+   */
+  constructor(handle, { backend, autoStart } = {}) {
+    super()
+    this._handle = handle
+    this._backend = backend || null
+    this._autoStart = autoStart === true
+    this._transport = null
+    this._name = null
+    this._announces = new Set()
+    /** @type {'unsupported'|'unauthorized'|'off'|'waiting'|'starting'|'on'} */
+    this.state = 'off'
+  }
+
+  /**
+   * Offline join rendezvous. Both sides derive the same BLE service UUID from
+   * the invite, so they find each other with zero DHT: the host calls this
+   * while the invite QR is on screen; the joiner's `open(me.room, invite)`
+   * calls it automatically for the duration of the join. Returns a stop
+   * function — closing the QR must stop the advertisement so a photographed
+   * invite doesn't stay an ambient admission ticket. Auto-stops at the
+   * invite's expiry, on `bluetooth.stop()`, and on close.
+   *
+   * @param {string} invite  Z32 invite string.
+   * @returns {() => void}
+   */
+  announce(invite) {
+    if (!this._backend || this.state === 'unsupported') return () => {}
+    const topic = Pairing.inviteTopic(invite)
+    if (!topic) return () => {}
+
+    const transport = new BluetoothTransport({
+      backend: this._backend,
+      network: this._handle.network,
+      uuid: topic,
+      nodeId: this._handle.identity.publicKey,
+      tag: 'cero-ble-invite',
+      // the QR closing stops the rendezvous, not the just-established link —
+      // that link carries the joiner's initial replication
+      keepLinks: true
+    })
+    transport.ready().catch(safetyCatch)
+    this._announces.add(transport)
+
+    const { expires } = Invite.parse(invite)
+    const timer = expires > 0 ? setTimeout(() => stop(), Math.max(0, expires - Date.now())) : null
+
+    const stop = () => {
+      if (timer) clearTimeout(timer)
+      if (!this._announces.delete(transport)) return
+      transport.close().catch(safetyCatch)
+    }
+    return stop
+  }
+
+  /** @returns {Map<string, any>} Live BLE links, keyed by peer node id. */
+  get peers() {
+    return this._transport ? this._transport.peers : new Map()
+  }
+
+  async _open() {
+    if (this._backend === null) this._backend = await loadBackend()
+    if (!this._backend) {
+      this.state = 'unsupported'
+      return
+    }
+    if (this._autoStart) await this.start()
+  }
+
+  /**
+   * Begin advertising + scanning on the channel-derived UUID. Idempotent.
+   * No-op (stays `unsupported`) when no backend is present.
+   *
+   * @returns {Promise<void>}
+   */
+  async start({ name } = {}) {
+    if (name !== undefined) this._name = name
+    if (this.state === 'unsupported') return
+    if (this._transport) {
+      // reuse one transport across toggles — recreating leaks iOS CoreBluetooth
+      // managers (can't destroy()) and their stale GATT service
+      this._transport.name = this._name || ''
+      this._transport.resume()
+      this.state = this._transport.state
+      this.emit('update')
+      return
+    }
+    const handle = this._handle
+
+    this._transport = new BluetoothTransport({
+      backend: this._backend,
+      network: handle.network,
+      // channel isolation for free: same channel → same UUID, like the swarm.
+      // No channel → the identity topic (unchanged global-mesh semantics).
+      uuid: handle.network.channel
+        ? Buffer.from(handle.network.channel)
+        : handle.identity.publicKey,
+      nodeId: handle.identity.publicKey,
+      name: this._name || ''
+    })
+    this._transport.on('update', () => {
+      this.state = this._transport.state
+      this.emit('update')
+    })
+    try {
+      await this._transport.ready()
+      this.state = this._transport.state
+    } catch (err) {
+      this._transport = null
+      this.state = 'off'
+      throw err
+    }
+    this.emit('update')
+  }
+
+  /**
+   * Stop advertising/scanning and drop links. Idempotent. Sync stops; local
+   * data and the rest of the network (DHT) are untouched.
+   *
+   * @returns {Promise<void>}
+   */
+  async stop() {
+    for (const t of [...this._announces]) {
+      this._announces.delete(t)
+      await t.close().catch(safetyCatch)
+    }
+    if (!this._transport) return
+    // suspend, don't close: keep the transport (and its GATT service) so a later
+    // start() resumes the same instance instead of leaking a new one. suspend()
+    // is async (it says goodbye + drains before hanging up); await it.
+    await this._transport.suspend()
+    this.state = 'off'
+    this.emit('update')
+  }
+
+  async _close() {
+    for (const t of [...this._announces]) {
+      this._announces.delete(t)
+      await t.close().catch(safetyCatch)
+    }
+    if (this._transport) {
+      await this._transport.close().catch(safetyCatch)
+      this._transport = null
+    }
+    this.state = 'off'
+    this.emit('update')
+  }
+}

package/src/build/index.js

@@ -44,7 +44,7 @@ import {
  */
 export { getHyperdbType } from './builtins.js'
 
-export async function build(specDir, schema, { ns = NS } = {}) {
+export async function build(specDir, schema, { ns = NS, extensions = true } = {}) {
   const raw = /** @type {SchemaDefs & { local?: SchemaDefs }} */ (schema?.defs || schema)
   if (!raw || typeof raw !== 'object') throw CeroError.REQUIRED('schema')
 
@@ -57,14 +57,18 @@ export async function build(specDir, schema, { ns = NS } = {}) {
       if (v && v.kind === 'extend') {
         const type = refs.main[k]?.type
         if (!type) throw CeroError.INVALID(`'${k}' is not an extendable builtin`)
-        extend[type] = { ...extend[type], ...v.fields }
+        // app schema wins on field conflicts, extensions only add new fields
+        extend[type] = fromExt ? { ...v.fields, ...extend[type] } : { ...extend[type], ...v.fields }
       } else if (!fromExt || !(k in defs)) {
         defs[k] = v // app schema wins over an extension's default
       }
     }
   }
   collect(raw)
-  for (const ext of internal.extensions) if (ext.schema) collect(ext.schema, true)
+  for (const ext of internal.extensions) {
+    if (ext.bundled && extensions === false) continue
+    if (ext.schema) collect(ext.schema, true)
+  }
 
   const main = compile(splitMain(defs), ns, 'main')
   const local = compile(defs.local || {}, ns, 'local')
@@ -128,7 +132,8 @@ function compile(root, ns, scope = 'main') {
     dispatches: [],
     indexes: [],
     meta: { ns, refs: {} },
-    ns
+    ns,
+    scope
   }
 
   Object.assign(ctx.meta.refs, builtinRefs(ns, scope))
@@ -207,6 +212,14 @@ function register(name, node, ctx) {
       }
       ctx.meta.refs[name].indexes = node.indexes
     }
+    // implicit secondary index on the auto-increment `index` — lets reads push
+    // reverse/limit down to hyperdb instead of scanning the whole collection.
+    // main scope only: local (Storage) rows never get `index` stamped, and an
+    // undefined index key crashes the encoder on insert.
+    if (ctx.scope === 'main' && !node.indexes?.index) {
+      ctx.indexes.push({ name: `${name}-index`, collection: fqn, key: ['index'] })
+      refEntry.orderIndex = true
+    }
   }
 }
 

package/src/build/schemas.js

@@ -126,7 +126,9 @@ export const rpc = {
   },
   'req-invite': {
     handle: required(string),
-    role: string
+    role: string,
+    expiresIn: uint,
+    multiUse: bool
   },
   'req-revoke': {
     handle: required(string),

package/src/extensions/handle-sync.js

@@ -1,5 +1,5 @@
 import { t } from '../lib/spec.js'
-import { set, watch } from '../lib/operators.js'
+import { get, set, watch } from '../lib/operators.js'
 
 /**
  * Mirror a child handle's `profile` (name + avatar) onto its row in the parent's
@@ -14,15 +14,26 @@ import { set, watch } from '../lib/operators.js'
  */
 export function handleSync({ fields = { avatar: t.string } } = {}) {
   return {
+    name: 'handle-sync',
+    bundled: true,
     schema: { handles: t.extend(fields) },
     setup(me) {
+      const keys = ['name', ...Object.keys(fields)]
+      // skip the write when the row already mirrors the profile — every open
+      // re-emits the watch snapshot, and an unconditional set is a new op in
+      // the replicated log forever
+      const reflect = async (child, data) => {
+        child.name = data.name
+        const { data: row } = await get(me.handles, child.id)
+        if (row && keys.every((k) => row[k] === data[k])) return
+        await set(me.handles, { id: child.id, ...data }, { upsert: false })
+      }
       const onHandle = (child, opts) => {
         if (!child.profile) return
         if (opts.name) set(child.profile, { name: opts.name }).catch(me._onerror)
         watch(child.profile).on('data', ({ data }) => {
           if (!data?.name) return
-          child.name = data.name
-          set(me.handles, { id: child.id, ...data }, { upsert: false }).catch(me._onerror)
+          reflect(child, data).catch(me._onerror)
         })
       }
       me.on('handle', onHandle, { signal: me.signal })

package/src/extensions/profile-sync.js

@@ -12,24 +12,32 @@ import { get, set, after } from '../lib/operators.js'
  */
 export function profileSync({ fields = { avatar: t.string } } = {}) {
   return {
+    name: 'profile-sync',
+    bundled: true,
     schema: {
       profile: t.single({ name: t.string, ...fields }),
       members: t.extend(fields)
     },
     setup(me) {
+      const keys = ['name', ...Object.keys(fields)]
       const publish = (child, profile) =>
         set(child.members, { id: me.identity.id, ...profile }, { upsert: false }).catch(me._onerror)
 
+      // skip the broadcast when the member row already mirrors the profile —
+      // an unconditional set on every open is a room-wide op forever
       const onHandle = async (child) => {
         const { data: profile } = await get(me.profile)
-        if (profile) publish(child, profile)
+        if (!profile) return
+        const { data: member } = await get(child.members, me.identity.id)
+        if (member && keys.every((k) => member[k] === profile[k])) return
+        publish(child, profile)
       }
 
       const onProfile = (ctx) => {
         if (ctx.row) me.children.forEach((child) => publish(child, ctx.row))
       }
 
-      me.on('handle', onHandle, { signal: me.signal })
+      me.on('handle', (child) => onHandle(child).catch(me._onerror), { signal: me.signal })
       after(me.profile, onProfile, { signal: me.signal })
     }
   }