@cero-base/cero 1.5.2 → 1.7.0

package/README.md

@@ -216,6 +216,75 @@ await cero.open(me.room, { id: existingRoomId }) // load an existing room by id
 
 Returns the child handle, ready to operate on (`cero.put(joined.messages, …)` etc.).
 
+### `cero.rotate(handle)`
+
+Rotate the handle's encryption epoch. A fresh secret is sealed to every current
+member and announced through the log — members removed **before** the rotation
+cannot decrypt anything written after it (rows **and** files). Requires the
+`remove` permission (admin or owner). Returns `{ epoch }`.
+
+```js
+await cero.del(room.members, memberId) // revoke write access
+await cero.rotate(room) // revoke read access for everything that follows
+```
+
+Rotation is opt-in per room: without it, `del` alone is a soft removal (write
+revocation only). Once a room has rotated at least once, later removals
+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.5.2",
+  "version": "1.7.0",
   "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.5.2",
+    "@cero-base/core": "^1.7.0",
     "b4a": "^1.8.1",
     "bare-abort-controller": "^1.1.2",
     "bare-crypto": "^1.15.3",

package/src/build/builtins.js

@@ -2,7 +2,7 @@
 // maps into the type / collection / dispatch / command descriptors the builder
 // registers. Every cero schema includes these; app refs are added on top.
 import { CeroError } from '@cero-base/core/errors'
-import { COUNTERS, DB_TYPE } from '../lib/constants.js'
+import { COUNTERS, EPOCHS, DB_TYPE } from '../lib/constants.js'
 import * as schemas from './schemas.js'
 
 // Builtin collections by scope — ref name → { type, kind? }. kind defaults to
@@ -79,7 +79,10 @@ export const builtinCollections = (ns, scope) => {
     schema: at(ns, def.type),
     key: keyOf(def)
   }))
-  if (scope === 'main') out.push({ name: COUNTERS, schema: at(ns, 'counter'), key: ['name'] })
+  if (scope === 'main') {
+    out.push({ name: COUNTERS, schema: at(ns, 'counter'), key: ['name'] })
+    out.push({ name: EPOCHS, schema: at(ns, 'epoch'), key: ['epoch'] })
+  }
   return out
 }
 
@@ -95,6 +98,13 @@ export const builtinDispatches = (ns) => [
   ])
 ]
 
+// Registered AFTER the app's own dispatches (see build/index.js): hyperdispatch
+// numbers routes positionally and persists them, so a spec built before
+// rotation must see rotate-key appended at the end — inserting it into the
+// builtin group would collide with the app's persisted route ids on an
+// incremental rebuild.
+export const rotateDispatch = (ns) => ({ name: 'rotate-key', requestType: at(ns, 'epoch') })
+
 export const rpcCommands = (ns) => {
   const ref = (n) => at(ns, n)
   return [
@@ -145,6 +155,7 @@ export const rpcCommands = (ns) => {
       name: 'changes',
       request: { name: ref('req-query') },
       response: { name: ref('res-changes'), stream: true }
-    }
+    },
+    { name: 'rotate', request: { name: ref('req-handle') }, response: { name: ref('res-epoch') } }
   ]
 }

package/src/build/index.js

@@ -16,6 +16,7 @@ import {
   builtinTypes,
   builtinCollections,
   builtinDispatches,
+  rotateDispatch,
   rpcTypes,
   rpcCommands,
   getHyperdbType
@@ -272,6 +273,7 @@ function emitMain(dir, ns, { types, collections, dispatches, indexes = [] }, { r
   const xns = d.namespace(ns)
   for (const desc of builtinDispatches(ns)) xns.register(desc)
   for (const desc of dispatches) xns.register(desc)
+  xns.register(rotateDispatch(ns))
   Hyperdispatch.toDisk(d, dispatchDir, { esm: true })
 
   if (rpc) {

package/src/build/schemas.js

@@ -66,13 +66,21 @@ export const main = {
     name: string,
     createdAt: int,
     updatedAt: int,
-    index: uint
+    index: uint,
+    stamp: uint
   },
   claim: {
     identity: required(bytes),
     writer: required(bytes),
     sig: required(bytes),
     ts: int
+  },
+  epoch: {
+    epoch: required(uint),
+    wrapped: required(bytes),
+    createdAt: int,
+    commit: bytes,
+    stamp: uint
   }
 }
 
@@ -188,5 +196,8 @@ export const rpc = {
   },
   'res-ok': {
     ok: bool
+  },
+  'res-epoch': {
+    epoch: required(uint)
   }
 }

package/src/handle/index.js

@@ -1,5 +1,6 @@
 import AbortController from 'bare-abort-controller'
 import b4a from 'b4a'
+import c from 'compact-encoding'
 import Hypercore from 'hypercore'
 import { discoveryKey } from 'hypercore-crypto'
 import ReadyResource from 'ready-resource'
@@ -8,6 +9,7 @@ import z32 from 'z32'
 
 import { Identity } from '@cero-base/core/identity'
 import { Database } from '@cero-base/core/database'
+import { epochEntries, blobEpochKey } from '@cero-base/core/database/encryption'
 import { Pairing } from '@cero-base/core/pairing'
 import { toId, grants, addWriterPayload } from '@cero-base/core/utils'
 import { CeroError } from '@cero-base/core/errors'
@@ -40,6 +42,7 @@ export { Ref } from '../lib/utils.js'
  * @property {Record<string, Function>} [routes]
  * @property {Uint8Array} [key]                Existing database key.
  * @property {Uint8Array} [encryptionKey]      Existing encryption key.
+ * @property {Array<{ epoch: number, entropy: Uint8Array }>} [epochs]  Rotation epochs delivered at join.
  * @property {string} [namespace]              Corestore namespace.
  * @property {KeyPair} [keyPair]               Writer keypair.
  * @property {boolean} [passive]               Join discovery server-only; flip later with `setActive`.
@@ -121,6 +124,7 @@ export class Handle extends ReadyResource {
     this._coreKeys = parent ? null : new Map()
     this._fileServer = null
     this._blobs = null
+    this._epochBlobs = null
     this._owned = new Set()
 
     this.store = new Database({
@@ -131,6 +135,7 @@ export class Handle extends ReadyResource {
       routes: opts.routes,
       key: opts.key,
       encryptionKey: opts.encryptionKey,
+      epochs: opts.epochs,
       namespace: opts.namespace,
       keyPair: opts.keyPair,
       passive: opts.passive,
@@ -159,10 +164,15 @@ export class Handle extends ReadyResource {
   async _close() {
     this.root._coreKeys.delete(b4a.toString(this.store.key, 'hex'))
     if (this._blobs?.key) this.root._coreKeys.delete(b4a.toString(this._blobs.key, 'hex'))
+    for (const b of this._epochBlobs?.values() || []) {
+      if (b.key) this.root._coreKeys.delete(b4a.toString(b.key, 'hex'))
+    }
     for (const hex of this._blobKeys || []) this.root._coreKeys.delete(hex)
     for (const r of [...this._owned]) r.destroy?.()
     this._owned.clear()
     if (this._blobs) await this._blobs.close()
+    for (const b of this._epochBlobs?.values() || []) await b.close().catch(safetyCatch)
+    this._epochBlobs = null
     if (this.children) {
       for (const c of [...this.children]) await c.close()
       this.children.clear()
@@ -286,31 +296,49 @@ export class Handle extends ReadyResource {
   }
 
   /**
-   * Lazily-built blob store for THIS handle's writing device. One core per
-   * writer, encrypted with the handle's encryptionKey and attached to the
-   * shared network for replication.
+   * Lazily-built blob store for THIS handle's writing device, at the current
+   * rotation epoch. One core per writer per epoch that writes files: the base
+   * era uses the handle's encryptionKey, rotated epochs use a key derived
+   * from the epoch entropy — so a removed member cannot decrypt files added
+   * after the rotation. Instances carry `.stamp` so the file row records
+   * which era its core belongs to.
    *
    * @returns {Blobs}
    */
   get blobs() {
-    if (!this._blobs) {
-      this._blobs = new Blobs({
-        store: this.store.store,
-        network: this.network,
-        encryptionKey: this.store.encryptionKey
-      })
-      this._blobs
-        .ready()
-        .then(() => {
-          if (this._blobs && this._blobs.key) {
-            this.root._coreKeys.set(b4a.toString(this._blobs.key, 'hex'), this.store.encryptionKey)
-          }
-        })
-        .catch(this._onerror)
+    const stamp = this.store.keyring.current
+    if (!stamp) return this._baseBlobs()
+    let blobs = this._epochBlobs?.get(stamp)
+    if (!blobs) {
+      const entropy = this.store.keyring.entropy(stamp)
+      blobs = this._makeBlobs(`blobs-${stamp}`, blobEpochKey(entropy), stamp)
+      ;(this._epochBlobs ??= new Map()).set(stamp, blobs)
     }
+    return blobs
+  }
+
+  _baseBlobs() {
+    if (!this._blobs) this._blobs = this._makeBlobs('blobs', this.store.encryptionKey, 0)
     return this._blobs
   }
 
+  _makeBlobs(name, encryptionKey, stamp) {
+    const blobs = new Blobs({
+      store: this.store.store,
+      network: this.network,
+      encryptionKey,
+      name
+    })
+    blobs.stamp = stamp
+    blobs
+      .ready()
+      .then(() => {
+        if (blobs.key) this.root._coreKeys.set(b4a.toString(blobs.key, 'hex'), encryptionKey)
+      })
+      .catch(this._onerror)
+    return blobs
+  }
+
   /** Canonical id — identity id for the root handle, store key for children. */
   get id() {
     if (!this.parent) return this.identity.id
@@ -426,7 +454,13 @@ export class Handle extends ReadyResource {
     // joiner times out. So the key is revealed before the membership writes
     // land; if they fail the joiner holds the key un-admitted, which is
     // recoverable (re-pair) and surfaced via onerror in _wireAccept.
-    await candidate.confirm({ key: this.store.key, encryptionKey: this.store.encryptionKey })
+    // Epoch secrets ride along so a post-rotation joiner reads full history.
+    const epochs = this.store.keyring.all()
+    await candidate.confirm({
+      key: this.store.key,
+      encryptionKey: this.store.encryptionKey,
+      additional: epochs.length ? c.encode(epochEntries, epochs) : null
+    })
 
     const ts = Date.now()
     const writerKey = Hypercore.key({ version: 2, signers: [{ publicKey: data.subarray(32, 64) }] })
@@ -487,7 +521,10 @@ export class Handle extends ReadyResource {
         spec: pickHandle(this.spec, type),
         namespace: `${NS}/handle/${type}/${writer.id}`,
         routes,
-        keyPair: writer
+        keyPair: writer,
+        // each room gets its own key — inheriting identity.encryptionKey would let
+        // any member decrypt every room this identity ever created, plus its root db
+        encryptionKey: Identity.randomBytes(32)
       })
     )
     // a failure after the child opens must close it — else it leaks its Database,
@@ -551,15 +588,24 @@ export class Handle extends ReadyResource {
   async _join(invite, type, { routes, timeout } = {}) {
     const deadline = timeout || TIMEOUT
 
-    // Idempotent: if the invite targets a handle we already have, return it —
-    // without pairing, so there's no waiting on a peer to confirm.
+    // Idempotent: if the invite targets a handle we already have AND we are
+    // still a member of it, return it — without pairing, so there's no
+    // waiting on a peer to confirm. If our member row is gone (we were
+    // removed), the stored writer is revoked and the old session can never
+    // become writable again — holding a fresh invite is exactly the
+    // re-admission path, so fall through to a real pairing instead.
     const target = Pairing.inviteTopic(invite)
     if (target) {
       const { data: joined } = await this.store.get('handles')
       const existing = joined.find(
         (h) => h.type === type && b4a.equals(discoveryKey(h.key), target)
       )
-      if (existing) return this._load(type, existing.id)
+      if (existing) {
+        const known = await this._load(type, existing.id)
+        const { data: me } = await known.store.get('members', this.identity.id)
+        if (me) return known
+        await known.close().catch(safetyCatch)
+      }
     }
 
     // offline join: with nearby sync on, also rendezvous on the invite-derived
@@ -724,14 +770,26 @@ export class Handle extends ReadyResource {
     const pair = new Pairing({ network: net, identity: id })
     await pair.ready()
 
-    let key, encryptionKey
+    let key, encryptionKey, additional
     try {
       const userData = b4a.concat([id.publicKey, writer.publicKey])
-      ;({ key, encryptionKey } = await pair.join(invite, { userData, timeout }))
+      ;({ key, encryptionKey, additional } = await pair.join(invite, { userData, timeout }))
     } finally {
       await pair.close()
     }
 
+    let epochs = null
+    if (additional?.byteLength) {
+      // the epoch set is load-bearing for a rotated room — a malformed
+      // delivery must fail the join loudly, not produce a silently inert
+      // member (hosts predating rotation send no additional payload at all)
+      try {
+        epochs = c.decode(epochEntries, additional)
+      } catch {
+        throw CeroError.INVALID('malformed epoch delivery in pairing confirm')
+      }
+    }
+
     return new Handle({
       parent,
       store,
@@ -742,6 +800,7 @@ export class Handle extends ReadyResource {
       routes,
       key,
       encryptionKey,
+      epochs,
       keyPair: writer
     })
   }

package/src/index.js

@@ -20,6 +20,7 @@ import {
   changes,
   call,
   open,
+  rotate,
   before,
   after,
   bind,
@@ -41,6 +42,7 @@ export {
   changes,
   call,
   open,
+  rotate,
   before,
   after,
   bind,
@@ -285,6 +287,7 @@ cero.watch = watch
 cero.changes = changes
 cero.call = call
 cero.open = open
+cero.rotate = rotate
 cero.before = before
 cero.after = after
 cero.peek = peek

package/src/lib/constants.js

@@ -2,6 +2,7 @@
 
 export const NS = 'cero'
 export const COUNTERS = 'counters'
+export const EPOCHS = 'epochs'
 
 // Writer-admission / pairing timeout (ms), and the initial discovery-flush wait (ms).
 export const TIMEOUT = 30000

package/src/lib/operators.js

@@ -2,6 +2,7 @@ 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'
 
@@ -45,10 +46,11 @@ async function putFile(ref, row) {
   const handle = ref.handle
   if (handle.rpc) return handle.put('files', row)
   const { data, type, name = null } = row
-  await handle.blobs.ready()
-  const blobId = await handle.blobs.put(data)
-  const id = encodeId(handle.blobs.key, blobId, type)
-  await handle.store.call('add-file', { id, name })
+  const blobs = handle.blobs // captured once — the instance carries its epoch stamp
+  await blobs.ready()
+  const blobId = await blobs.put(data)
+  const id = encodeId(blobs.key, blobId, type)
+  await handle.store.call('add-file', { id, name, stamp: blobs.stamp || 0 })
   return { data: resolveFile(handle, id, name) }
 }
 
@@ -166,12 +168,12 @@ function resolveRow(ref, row) {
   if (!row || typeof row !== 'object') return 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) => {
-    registerBlobCore(handle, id)
+  const resolve = (id, name, stamp) => {
+    registerBlobCore(handle, id, stamp)
     return resolveFile(handle, id, name)
   }
   if (ref.name === 'files') {
-    return { ...row, ...resolve(row.id, row.name) }
+    return { ...row, ...resolve(row.id, row.name, row.stamp) }
   }
   const fields = handle.store.refs?.[ref.name]?.files
   if (!fields || !fields.length) return row
@@ -184,13 +186,24 @@ function resolveRow(ref, row) {
   return out
 }
 
-function registerBlobCore(handle, id) {
+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)) {
-      handle.root._coreKeys.set(hex, handle.root.store.encryptionKey)
+      // 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)
@@ -200,6 +213,14 @@ function registerBlobCore(handle, id) {
   }
 }
 
+// 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
@@ -360,6 +381,20 @@ export const open = (ref, arg) => {
   return ref.handle._create(ref.name, arg)
 }
 
+/**
+ * Rotate a handle's encryption epoch. A fresh secret is sealed to every
+ * current member and announced through the log — members removed before the
+ * rotation cannot decrypt anything written after it. Requires the remove
+ * permission (admin or owner). Compose with removal:
+ *
+ *   await cero.del(room.members, memberId)
+ *   await cero.rotate(room)
+ *
+ * @param {any} handle
+ * @returns {Promise<{ epoch: number }>}
+ */
+export const rotate = (handle) => handle.store.rotate()
+
 // ─── custom operators ──────────────────────────────────────────────────────
 // App business logic lives as custom operators: pure functions whose first arg
 // is the handle they act on, composed from the operators above. `define`

package/src/rpc/client.js

@@ -5,10 +5,22 @@ import z32 from 'z32'
 import { decodeId } from '@cero-base/core/blobs/codec'
 
 import { attachRefs } from '../lib/utils.js'
-import { put, set, get, del, count, watch, call, open, bind, define } from '../lib/operators.js'
+import {
+  put,
+  set,
+  get,
+  del,
+  count,
+  watch,
+  call,
+  open,
+  rotate,
+  bind,
+  define
+} from '../lib/operators.js'
 import { t, schema } from '../lib/spec.js'
 
-export { put, set, get, del, count, watch, call, open, bind, define, t, schema }
+export { put, set, get, del, count, watch, call, open, rotate, bind, define, t, schema }
 
 /**
  * @typedef {import('@cero-base/core/rpc').RPCClient} BaseRPCClient
@@ -392,6 +404,16 @@ const operators = {
   async revoke(invite) {
     const { ok } = await this.rpc.revoke({ handle: this.id, invite })
     return ok
+  },
+
+  /**
+   * Rotate this handle's encryption epoch on the server.
+   *
+   * @returns {Promise<{ epoch: number }>}
+   */
+  async rotate() {
+    const { epoch } = await this.rpc.rotate({ handle: this.id })
+    return { epoch }
   }
 }
 
@@ -598,6 +620,7 @@ cero.count = count
 cero.watch = watch
 cero.call = call
 cero.open = open
+cero.rotate = rotate
 cero.bind = bind
 cero.define = define
 cero.schema = schema

package/src/rpc/server.js

@@ -117,11 +117,12 @@ export class Server extends RPCServer {
   _wireData() {
     this.rpc.onAddFile(async ({ handle, data, name, type }) => {
       const h = this._resolve(handle)
-      await h.blobs.ready()
-      const blobId = await h.blobs.put(data)
-      const id = encodeId(h.blobs.key, blobId, type || '')
+      const blobs = h.blobs // captured once — the instance carries its epoch stamp
+      await blobs.ready()
+      const blobId = await blobs.put(data)
+      const id = encodeId(blobs.key, blobId, type || '')
       const codec = h.spec.codec
-      await h.store.call('add-file', { id, name: name || null })
+      await h.store.call('add-file', { id, name: name || null, stamp: blobs.stamp || 0 })
       const { data: row } = await get(h.files, id)
       return { data: codec.encodeRow(h.files.schema, row) }
     })
@@ -281,6 +282,14 @@ export class Server extends RPCServer {
       return { ok }
     })
 
+    // specs built before rotation have no rotate command
+    if (typeof this.rpc.onRotate === 'function') {
+      this.rpc.onRotate(async ({ handle }) => {
+        const { epoch } = await this._resolve(handle).store.rotate()
+        return { epoch }
+      })
+    }
+
     this.rpc.onJoin(async ({ parent, ref, invite }) => {
       if (this._resolve(parent) !== this.me) throw CeroError.UNSUPPORTED('nested handles')
       const child = await this.me._join(invite, ref)

package/types/build/builtins.d.ts

@@ -75,6 +75,10 @@ export function builtinDispatches(ns: any): {
     name: string;
     requestType: string;
 }[];
+export function rotateDispatch(ns: any): {
+    name: string;
+    requestType: string;
+};
 export function rpcCommands(ns: any): ({
     name: string;
     request: {

package/types/build/schemas.d.ts

@@ -60,6 +60,7 @@ export const main: {
         createdAt: import("@cero-base/core").Prim;
         updatedAt: import("@cero-base/core").Prim;
         index: import("@cero-base/core").Prim;
+        stamp: import("@cero-base/core").Prim;
     };
     claim: {
         identity: import("@cero-base/core").Prim;
@@ -67,6 +68,13 @@ export const main: {
         sig: import("@cero-base/core").Prim;
         ts: import("@cero-base/core").Prim;
     };
+    epoch: {
+        epoch: import("@cero-base/core").Prim;
+        wrapped: import("@cero-base/core").Prim;
+        createdAt: import("@cero-base/core").Prim;
+        commit: import("@cero-base/core").Prim;
+        stamp: import("@cero-base/core").Prim;
+    };
 };
 export const local: {
     master: {
@@ -180,4 +188,7 @@ export const rpc: {
     'res-ok': {
         ok: import("@cero-base/core").Prim;
     };
+    'res-epoch': {
+        epoch: import("@cero-base/core").Prim;
+    };
 };

package/types/handle/index.d.ts

@@ -18,6 +18,7 @@ export { Ref } from "../lib/utils.js";
  * @property {Record<string, Function>} [routes]
  * @property {Uint8Array} [key]                Existing database key.
  * @property {Uint8Array} [encryptionKey]      Existing encryption key.
+ * @property {Array<{ epoch: number, entropy: Uint8Array }>} [epochs]  Rotation epochs delivered at join.
  * @property {string} [namespace]              Corestore namespace.
  * @property {KeyPair} [keyPair]               Writer keypair.
  * @property {boolean} [passive]               Join discovery server-only; flip later with `setActive`.
@@ -93,6 +94,7 @@ export class Handle extends ReadyResource {
     _coreKeys: Map<any, any>;
     _fileServer: FileServer;
     _blobs: Blobs;
+    _epochBlobs: any;
     _owned: Set<any>;
     store: Database;
     pair: Pairing;
@@ -158,13 +160,18 @@ export class Handle extends ReadyResource {
      */
     getLink(id: string): string;
     /**
-     * Lazily-built blob store for THIS handle's writing device. One core per
-     * writer, encrypted with the handle's encryptionKey and attached to the
-     * shared network for replication.
+     * Lazily-built blob store for THIS handle's writing device, at the current
+     * rotation epoch. One core per writer per epoch that writes files: the base
+     * era uses the handle's encryptionKey, rotated epochs use a key derived
+     * from the epoch entropy — so a removed member cannot decrypt files added
+     * after the rotation. Instances carry `.stamp` so the file row records
+     * which era its core belongs to.
      *
      * @returns {Blobs}
      */
     get blobs(): Blobs;
+    _baseBlobs(): Blobs;
+    _makeBlobs(name: any, encryptionKey: any, stamp: any): Blobs;
     /** Canonical id — identity id for the root handle, store key for children. */
     get id(): any;
     /** This device's id + name. `null` on child handles. */
@@ -370,6 +377,13 @@ export type HandleOpts = {
      * Existing encryption key.
      */
     encryptionKey?: Uint8Array;
+    /**
+     * Rotation epochs delivered at join.
+     */
+    epochs?: Array<{
+        epoch: number;
+        entropy: Uint8Array;
+    }>;
     /**
      * Corestore namespace.
      */

package/types/index.d.ts

@@ -44,6 +44,7 @@ export namespace cero {
     export { changes };
     export { call };
     export { open };
+    export { rotate };
     export { before };
     export { after };
     export { peek };
@@ -158,6 +159,7 @@ import { watch } from './lib/operators.js';
 import { changes } from './lib/operators.js';
 import { call } from './lib/operators.js';
 import { open } from './lib/operators.js';
+import { rotate } from './lib/operators.js';
 import { before } from './lib/operators.js';
 import { after } from './lib/operators.js';
 import { peek } from './lib/peek.js';
@@ -170,5 +172,5 @@ import { Ref } from './handle/index.js';
 import { Local } from './local/index.js';
 import { Identity } from '@cero-base/core/identity';
 export { Handle, Ref, Local };
-export { put, set, get, del, count, watch, changes, call, open, before, after, bind, define } from "./lib/operators.js";
+export { put, set, get, del, count, watch, changes, call, open, rotate, before, after, bind, define } from "./lib/operators.js";
 export { t, schema } from "./lib/spec.js";

package/types/lib/constants.d.ts

@@ -1,5 +1,6 @@
 export const NS: "cero";
 export const COUNTERS: "counters";
+export const EPOCHS: "epochs";
 export const TIMEOUT: 30000;
 export const FLUSH: 500;
 export namespace DB_TYPE {

package/types/lib/operators.d.ts

@@ -81,6 +81,9 @@ export function open(ref: Ref, arg?: string | {
     role?: string;
     accept?: boolean;
 } | undefined): Promise<CeroHandle>;
+export function rotate(handle: any): Promise<{
+    epoch: number;
+}>;
 export type Ref = import("./utils.js").Ref;
 export type CeroHandle = import("../handle/index.js").CeroHandle;
 export type SingleResult = {

package/types/rpc/client.d.ts

@@ -41,6 +41,7 @@ export namespace cero {
     export { watch };
     export { call };
     export { open };
+    export { rotate };
     export { bind };
     export { define };
     export { schema };
@@ -141,6 +142,7 @@ import { count } from '../lib/operators.js';
 import { watch } from '../lib/operators.js';
 import { call } from '../lib/operators.js';
 import { open } from '../lib/operators.js';
+import { rotate } from '../lib/operators.js';
 import { bind } from '../lib/operators.js';
 import { define } from '../lib/operators.js';
 import { schema } from '../lib/spec.js';
@@ -189,4 +191,4 @@ declare class Handle {
     /** Tear down the remote handle and drop membership. */
     leave(): any;
 }
-export { put, set, get, del, count, watch, call, open, bind, define, t, schema };
+export { put, set, get, del, count, watch, call, open, rotate, bind, define, t, schema };