@cero-base/cero 1.6.0 → 1.7.1

package/README.md

@@ -234,6 +234,57 @@ self-heal — a `del` without an explicit `rotate` triggers an automatic re-key
 from any online admin device. Standalone rotations (no removal) are valid too,
 as periodic key hygiene. Full design: [`docs/key-rotation.md`](../../docs/key-rotation.md).
 
+### Watching removals
+
+There is no separate removal event — `members` is a collection, so the normal
+streams already are the membership feed. A removal arrives as an ordinary
+delete (`next: null`), carrying the row that was removed:
+
+```js
+for await (const { changes } of cero.changes(room.members)) {
+  for (const { prev, next } of changes) {
+    if (next === null) console.log('removed:', prev.name)
+  }
+}
+```
+
+To detect **your own** removal — the signal an app renders as "you were removed
+from this room" — listen for the store losing writability:
+
+```js
+room.store.on('unwritable', () => onRemoved()) // freeze the UI, close the room
+```
+
+This works even when the removal is followed by a rotation: the removal lands
+before the new key, so a removed member always receives it. After that their
+streams stay open but go silent — reads freeze at the moment of removal and
+writes reject with `NOT_WRITABLE`.
+
+### Store events
+
+Beyond the ref streams, the store reports its own lifecycle:
+
+```js
+room.store.on('writable', () => {}) // admitted — this device can write
+room.store.on('unwritable', () => {}) // access ended (removed)
+room.store.on('update', () => {}) // an apply batch committed
+room.store.on('behind', (v) => {}) // ops from a newer app version — see below
+room.store.on('rebuild', () => {}) // view replayed after catching up
+```
+
+`before`/`after` hooks only fire on the device performing the write. To observe
+**every** applied op — local _and_ replicated — use `onApply`, which returns an
+unsubscribe fn:
+
+```js
+const off = room.store.onApply(({ op, name, row, writerKey, seq }) => {
+  if (op === 'del' && name === 'member') auditLog(row)
+})
+```
+
+The callback runs synchronously inside apply, so keep it cheap — enqueue and
+return. It costs nothing when nobody is subscribed.
+
 ### `cero.before(ref, fn, opts?)` / `cero.after(ref, fn, opts?)`
 
 Hook into writes to a ref. `before` runs **in-path** before the write commits — return `false` to cancel, or mutate `ctx.row`. `after` is a non-blocking **event** that fires once the write has committed. Both return an unsubscribe fn — call it to stop early, ignore it for a subscription that lives as long as the handle, or pass `{ signal }` to unsubscribe when an `AbortSignal` fires (e.g. `{ signal: me.signal }` to stop on close).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/cero",
-  "version": "1.6.0",
+  "version": "1.7.1",
   "description": "The ideal p2p API — everything is a handle, handles contain refs, refs contain rows.",
   "type": "module",
   "sideEffects": false,
@@ -95,7 +95,7 @@
     "test:node": "ls test/*.test.js | xargs -P1 -n1 brittle-node"
   },
   "dependencies": {
-    "@cero-base/core": "^1.6.0",
+    "@cero-base/core": "^1.7.1",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",

package/src/handle/index.js

@@ -14,6 +14,7 @@ import { Pairing } from '@cero-base/core/pairing'
 import { toId, grants, addWriterPayload } from '@cero-base/core/utils'
 import { CeroError } from '@cero-base/core/errors'
 import { Blobs } from '@cero-base/core/blobs'
+import { decodeId } from '@cero-base/core/blobs/codec'
 import { FileServer } from '@cero-base/core/blobs/server'
 
 import { NS, TIMEOUT } from '../lib/constants.js'
@@ -339,6 +340,50 @@ export class Handle extends ReadyResource {
     return blobs
   }
 
+  /**
+   * Remember the blob-core key a file id points at so the file server can
+   * open the core. Lives on the Handle (not the shared operators) because the
+   * epoch-key derivation pulls native crypto — the RPC client must stay
+   * bundleable without it.
+   *
+   * @param {string} id
+   * @param {number} [stamp]
+   */
+  _registerBlobCore(id, stamp) {
+    if (!id || !this.root?._coreKeys) return
+    try {
+      const { coreKey } = decodeId(id)
+      const hex = b4a.toString(coreKey, 'hex')
+      if (!this.root._coreKeys.has(hex)) {
+        // a file-field value carries no stamp — look it up from the files row
+        // (fire-and-forget: idempotent, resolution happens again per request)
+        if (stamp === undefined) {
+          this.store
+            .get('files', id)
+            .then(({ data }) => data && this._registerBlobCore(id, data.stamp || 0))
+            .catch(safetyCatch)
+          return
+        }
+        const key = this._blobCoreKey(stamp)
+        if (!key) return // unknown epoch — this device is not entitled to the core
+        this.root._coreKeys.set(hex, key)
+      }
+      // remember which handle read it, so close prunes the entry (re-registered
+      // on the next read if another handle still serves the same core)
+      if (this !== this.root) (this._blobKeys ??= new Set()).add(hex)
+    } catch {
+      // ignore invalid ids
+    }
+  }
+
+  // Base-era blob cores use the OWNING handle's key (not the root's — rooms
+  // have their own keys); rotated-era cores derive from the epoch entropy.
+  _blobCoreKey(stamp) {
+    if (!stamp) return this.store.encryptionKey
+    const entropy = this.store.keyring.entropy(stamp)
+    return entropy ? blobEpochKey(entropy) : null
+  }
+
   /** Canonical id — identity id for the root handle, store key for children. */
   get id() {
     if (!this.parent) return this.identity.id

package/src/lib/operators.js

@@ -2,7 +2,6 @@ import { Readable } from 'streamx'
 import b4a from 'b4a'
 
 import { encodeId, decodeId } from '@cero-base/core/blobs/codec'
-import { blobEpochKey } from '@cero-base/core/database/encryption'
 import { CeroError } from '@cero-base/core/errors'
 import { onAbort } from './utils.js'
 
@@ -169,7 +168,7 @@ function resolveRow(ref, row) {
   if (ref.handle.rpc) return ref.handle._resolveRow(ref.name, ref.handle._refInfo(ref.name), row)
   const handle = ref.handle
   const resolve = (id, name, stamp) => {
-    registerBlobCore(handle, id, stamp)
+    handle._registerBlobCore(id, stamp)
     return resolveFile(handle, id, name)
   }
   if (ref.name === 'files') {
@@ -186,41 +185,6 @@ function resolveRow(ref, row) {
   return out
 }
 
-function registerBlobCore(handle, id, stamp) {
-  if (!id || !handle.root?._coreKeys) return
-  try {
-    const { coreKey } = decodeId(id)
-    const hex = b4a.toString(coreKey, 'hex')
-    if (!handle.root._coreKeys.has(hex)) {
-      // a file-field value carries no stamp — look it up from the files row
-      // (fire-and-forget: idempotent, resolution happens again per request)
-      if (stamp === undefined) {
-        handle.store
-          .get('files', id)
-          .then(({ data }) => data && registerBlobCore(handle, id, data.stamp || 0))
-          .catch(() => {})
-        return
-      }
-      const key = blobCoreKey(handle, stamp)
-      if (!key) return // unknown epoch — this device is not entitled to the core
-      handle.root._coreKeys.set(hex, key)
-    }
-    // remember which handle read it, so close prunes the entry (re-registered
-    // on the next read if another handle still serves the same core)
-    if (handle !== handle.root) (handle._blobKeys ??= new Set()).add(hex)
-  } catch {
-    // ignore invalid ids
-  }
-}
-
-// Base-era blob cores use the OWNING handle's key (not the root's — rooms have
-// their own keys); rotated-era cores derive from the epoch entropy.
-function blobCoreKey(handle, stamp) {
-  if (!stamp) return handle.store.encryptionKey
-  const entropy = handle.store.keyring.entropy(stamp)
-  return entropy ? blobEpochKey(entropy) : null
-}
-
 /**
  * Read from `ref`. For data refs, dispatches to the underlying store. For
  * `handle`-kind refs, lists existing child handles of that type from the

package/types/handle/index.d.ts

@@ -172,6 +172,17 @@ export class Handle extends ReadyResource {
     get blobs(): Blobs;
     _baseBlobs(): Blobs;
     _makeBlobs(name: any, encryptionKey: any, stamp: any): Blobs;
+    /**
+     * Remember the blob-core key a file id points at so the file server can
+     * open the core. Lives on the Handle (not the shared operators) because the
+     * epoch-key derivation pulls native crypto — the RPC client must stay
+     * bundleable without it.
+     *
+     * @param {string} id
+     * @param {number} [stamp]
+     */
+    _registerBlobCore(id: string, stamp?: number): void;
+    _blobCoreKey(stamp: any): Uint8Array<ArrayBufferLike>;
     /** Canonical id — identity id for the root handle, store key for children. */
     get id(): any;
     /** This device's id + name. `null` on child handles. */