@cero-base/core 1.5.2 → 1.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cero-base/core",
-  "version": "1.5.2",
+  "version": "1.7.0",
   "description": "cero p2p primitives — identity, storage, network, database, blobs, rpc, pairing.",
   "type": "module",
   "sideEffects": false,
@@ -53,6 +53,10 @@
       "types": "./types/database/index.d.ts",
       "default": "./src/database/index.js"
     },
+    "./database/encryption": {
+      "types": "./types/database/encryption.d.ts",
+      "default": "./src/database/encryption.js"
+    },
     "./blobs": {
       "types": "./types/blobs/index.d.ts",
       "default": "./src/blobs/index.js"
@@ -140,7 +144,8 @@
   },
   "dependencies": {
     "@hyperswarm/secret-stream": "^6.9.1",
-    "autobee": "^1.0.10",
+    "autobee": "1.0.10",
+    "autobee-encryption": "0.1.3",
     "b4a": "^1.8.1",
     "bare-crypto": "^1.15.3",
     "bare-fs": "^4.7.4",
@@ -179,7 +184,8 @@
     "bare-url": "^2.4.6",
     "blind-peer": "^3.12.3",
     "brittle": "^4.1.0",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3",
+    "which-runtime": "^1.4.0"
   },
   "license": "Apache-2.0"
 }

package/src/blobs/index.js

@@ -23,7 +23,7 @@ const NS = `${NAMESPACE}/blobs`
 /** Thin wrapper over a single Hyperblobs core; deals only in raw blobIds. */
 export class Blobs extends ReadyResource {
   /** @param {BlobsOpts} [opts] */
-  constructor({ store, identity, network, key, encryptionKey } = {}) {
+  constructor({ store, identity, network, key, encryptionKey, name } = {}) {
     super()
     if (!store) throw CeroError.REQUIRED('store')
     if (!identity && !encryptionKey) throw CeroError.REQUIRED('identity or encryptionKey')
@@ -32,6 +32,7 @@ export class Blobs extends ReadyResource {
     this.identity = identity || null
     this.network = network || null
     this.encryptionKey = encryptionKey || (identity && identity.encryptionKey) || null
+    this.name = name || 'blobs'
 
     this._coreKey = key || null
     this.core = null
@@ -72,7 +73,7 @@ export class Blobs extends ReadyResource {
 
     const opts = { encryptionKey: this.encryptionKey }
     if (this._coreKey) opts.key = this._coreKey
-    else opts.name = 'blobs'
+    else opts.name = this.name
 
     const ns = this.store.namespace(NS)
     this.core = ns.get(opts)

package/src/database/bootstrap.js

@@ -133,6 +133,7 @@ async function saveWriter(db, writerKey, { name, isMobile }) {
 async function swapWriter(db, keyPair, manifest) {
   const head = await db.bee.local.getUserData('autobee/head')
   const enc = await db.bee.local.getUserData('autobee/encryption')
+  const epochs = await db.bee.local.getUserData('cero/epochs')
 
   if (db.network) db.network.detach(db.bee)
   await db.bee.close()
@@ -142,6 +143,7 @@ async function swapWriter(db, keyPair, manifest) {
   await deviceCore.ready()
   if (head) await deviceCore.setUserData('autobee/head', head)
   if (enc) await deviceCore.setUserData('autobee/encryption', enc)
+  if (epochs) await deviceCore.setUserData('cero/epochs', epochs)
   await deviceCore.close()
 
   db.keyPair = keyPair

package/src/database/dispatch.js

@@ -6,6 +6,7 @@ import {
   COLLECTION,
   ACTION,
   COUNTERS,
+  EPOCHS,
   INVITE,
   REMOVE,
   ASSIGN,
@@ -45,9 +46,18 @@ const isSig = (b) => b?.byteLength === 64
  * @param {string} ns  Namespace prefix for collection and op names.
  * @param {Record<string, Function>} routes  Custom action handlers keyed by route name.
  * @param {(err: Error) => void} [onerror]  Called when a malformed node is skipped.
+ * @param {() => Uint8Array | null} [getDbKey]
+ * @param {{ onEpoch?: (row: { epoch: number, wrapped: Uint8Array, createdAt: number }) => Promise<void> }} [hooks]  Per-peer side effects fired after an op applies (skipped in dry runs).
  * @returns {{ dispatcher: object, apply: (nodes: Array<{ value: Buffer, key: Buffer }>, view: object, host: object) => Promise<void> }}
  */
-export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey = () => null) {
+export function makeDispatcher(
+  spec,
+  ns,
+  routes,
+  onerror = safetyCatch,
+  getDbKey = () => null,
+  hooks = {}
+) {
   const dispatcher = new spec.dispatch.Router()
 
   const countersCol = `@${ns}/${COUNTERS}`
@@ -181,9 +191,63 @@ export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey
       if (!can(r, REMOVE) || !outranks(r, existing.role)) return
     }
     if (existing.key) await ctx.host.removeWriter(existing.key)
+    // every device of the member goes with them — a removed member must not
+    // leave writers admitted or stale device rows behind
+    for (const device of await ctx.view.find(`@${ns}/devices`, {}).toArray()) {
+      if (device.memberId !== op.id) continue
+      await ctx.host.removeWriter(toKey(device.id))
+      await ctx.view.delete(`@${ns}/devices`, { id: device.id })
+    }
     await ctx.view.delete(`@${ns}/members`, op)
   })
 
+  // specs built before rotation have no rotate-key route — Router.add throws
+  // NONEXISTENT_ROUTE, and the op stays unavailable until the app rebuilds
+  try {
+    add('rotate-key', async (op, ctx) => {
+      if (!op.wrapped?.byteLength) return
+      // the commitment lets every member verify the secret their envelope
+      // opened to — without it a rotator could seal different secrets to
+      // different members and split the room
+      if (op.commit?.byteLength !== 32) return
+      // the stamp is the content-addressed uint32 written into block headers.
+      // The rotator picks it before writing any block, so linearization can
+      // reorder epochs freely without ever changing which key a block header
+      // points at. Uniqueness is enforced here, deterministically.
+      if (!Number.isInteger(op.stamp) || op.stamp <= 0 || op.stamp > 0xffffffff) return
+      if (!can(await getSignerRole(ctx.view, ctx.key), REMOVE)) return
+      const rows = await ctx.view.find(`@${ns}/${EPOCHS}`, {}).toArray()
+      if (rows.some((r) => r.stamp === op.stamp)) return
+      // sequence numbers order epochs; concurrent rotations linearize as
+      // consecutive sequences with distinct stamps — both remain readable
+      const counter = (await ctx.view.get(countersCol, { name: EPOCHS })) ?? {
+        name: EPOCHS,
+        value: 0
+      }
+      const epoch = counter.value + 1
+      await ctx.view.insert(countersCol, { name: EPOCHS, value: epoch })
+      const row = {
+        epoch,
+        stamp: op.stamp,
+        wrapped: op.wrapped,
+        createdAt: op.createdAt || 0,
+        commit: op.commit
+      }
+      await ctx.view.insert(`@${ns}/${EPOCHS}`, row)
+      // per-peer hydration (unseal own envelope → keyring) — never in a dry
+      // run: the announcement itself must be appended under the OLD epoch
+      if (hooks.onEpoch && !ctx.dryRun) {
+        try {
+          await hooks.onEpoch(row)
+        } catch (err) {
+          onerror(err)
+        }
+      }
+    })
+  } catch {
+    // pre-rotation spec
+  }
+
   add('del-device', async (op, ctx) => {
     const existing = await getDevice(ctx.view, op.id)
     if (!existing) return
@@ -217,7 +281,12 @@ export function makeDispatcher(spec, ns, routes, onerror = safetyCatch, getDbKey
       add('add-file', async (op, ctx) => {
         if (!can(await getSignerRole(ctx.view, ctx.key), WRITE)) return
         const memberId = await getSignerMember(ctx.view, ctx.key)
-        await insert(ctx.view, b.name, col, { id: op.id, name: op.name ?? null, memberId })
+        await insert(ctx.view, b.name, col, {
+          id: op.id,
+          name: op.name ?? null,
+          memberId,
+          stamp: op.stamp ?? 0
+        })
       })
     } else {
       add(`add-${b.verb}`, upsert(b.name, col, COLLECTION))

package/src/database/encryption.js

@@ -0,0 +1,303 @@
+import Autobee from 'autobee'
+import autobeeEncryption from 'autobee-encryption'
+import crypto from 'hypercore-crypto'
+import c from 'compact-encoding'
+import b4a from 'b4a'
+
+import { CeroError } from '../lib/errors.js'
+
+const { AutobeeEncryption, WriterEncryption } = autobeeEncryption
+
+// same derivation constant autobee-encryption uses internally (index 2 of the
+// 'autobase' namespace) — epoch keys must hash with the identical hash-key ns
+const NS_HASH_KEY = crypto.namespace('autobase', 4)[2]
+
+const NS_BLOBS = crypto.namespace('cero/blobs', 1)[0]
+
+/**
+ * Encryption key for a rotation epoch's blob cores. New files land in a core
+ * keyed by the epoch entropy, so file confidentiality rotates with the room:
+ * only holders of the epoch secret can derive the core key.
+ *
+ * @param {Uint8Array} entropy
+ * @returns {Uint8Array}
+ */
+export function blobEpochKey(entropy) {
+  return crypto.hash([NS_BLOBS, entropy])
+}
+
+// autobee constructs WriterEncryption in four places, and one of them
+// (ActiveWriters.add, lib/writers.js) news the class directly — no factory to
+// override. The only injection point that covers every remote writer core is
+// the provider base class itself, so the epoch awareness is patched onto the
+// autobee-encryption prototype. The pin MUST stay on the version autobee's own
+// range resolves to — pin them apart and npm installs two copies, autobee uses
+// the unpatched one, and every rotation silently writes epoch-0 blocks that a
+// removed member can still read. Epoch 0 keeps the upstream
+// GENESIS_ENTROPY derivation byte-for-byte; epoch n derives from the
+// keyring's entropy. Without a keyring (auto.keyring unset) behavior is
+// identical to upstream. Removable once autobee accepts a provider factory.
+const baseGetKeys = AutobeeEncryption.prototype.getKeys
+
+AutobeeEncryption.prototype.getKeys = async function (id, ctx) {
+  if (!id) return baseGetKeys.call(this, id, ctx)
+
+  const keyring = this.auto?.keyring
+  if (!keyring) throw CeroError.UNKNOWN_EPOCH(id)
+
+  let entropy = keyring.entropy(id)
+  if (!entropy && !keyring.primed && this.auto.local) {
+    // first epoch miss of a session may happen inside autobee's own boot
+    // (reading back this device's post-rotation state) — prime lazily from
+    // the local core's userData, once
+    keyring.primed = true
+    await primeKeyring(keyring, this.auto.local)
+    entropy = keyring.entropy(id)
+  }
+  if (!entropy) throw CeroError.UNKNOWN_EPOCH(id)
+
+  const block = this.blockKey(entropy, ctx)
+  return { id, block, hash: crypto.hash([NS_HASH_KEY, block]) }
+}
+
+async function primeKeyring(keyring, local) {
+  const saved = await local.getUserData('cero/epochs').catch(() => null)
+  if (!saved) return
+  try {
+    for (const e of c.decode(epochEntries, saved)) keyring.add(e.stamp, e.entropy, e.epoch)
+  } catch {
+    // corrupt userData — epochs re-hydrate from announcements
+  }
+}
+
+AutobeeEncryption.prototype.update = async function (ctx) {
+  const current = this.auto?.keyring ? this.auto.keyring.current : 0
+  if (!this.keys || this.keys.id !== current) this.keys = await this.get(current, ctx)
+}
+
+/**
+ * Wire codec for a rotation announcement's envelope list — one sealed box
+ * per remaining member, addressed by member id.
+ */
+export const wraps = c.array({
+  preencode(state, w) {
+    c.string.preencode(state, w.id)
+    c.buffer.preencode(state, w.box)
+  },
+  encode(state, w) {
+    c.string.encode(state, w.id)
+    c.buffer.encode(state, w.box)
+  },
+  decode(state) {
+    return { id: c.string.decode(state), box: c.buffer.decode(state) }
+  }
+})
+
+/**
+ * Wire codec for locally persisted / pairing-delivered epoch secrets.
+ * `epoch` is the apply-order sequence; `stamp` is the content-addressed
+ * uint32 written into block headers.
+ */
+export const epochEntries = c.array({
+  preencode(state, e) {
+    c.uint.preencode(state, e.epoch)
+    c.uint.preencode(state, e.stamp)
+    c.fixed32.preencode(state, e.entropy)
+  },
+  encode(state, e) {
+    c.uint.encode(state, e.epoch)
+    c.uint.encode(state, e.stamp)
+    c.fixed32.encode(state, e.entropy)
+  },
+  decode(state) {
+    return {
+      epoch: c.uint.decode(state),
+      stamp: c.uint.decode(state),
+      entropy: c.fixed32.decode(state)
+    }
+  }
+})
+
+/**
+ * Per-database registry of rotation epochs. Stamp 0 is the base key era
+ * (no entry needed — it derives from the upstream GENESIS_ENTROPY path).
+ * Every rotation adds an entry keyed by its content-addressed `stamp` (the
+ * uint32 written into block headers, chosen randomly by the rotator and
+ * validated unique at apply) alongside its apply-order `seq`. Because the
+ * stamp is chosen before any block is written and can never be renumbered
+ * by linearization, a block's header always identifies its true key —
+ * concurrent rotations cannot make blocks undecryptable.
+ */
+export class Keyring {
+  constructor() {
+    /** @type {Map<number, Uint8Array>} stamp → entropy */
+    this.entropies = new Map()
+    /** @type {Map<number, number>} stamp → apply-order sequence */
+    this.seqs = new Map()
+    /** stamp used for new blocks — the adopted epoch with the highest seq */
+    this.current = 0
+    /** highest adopted apply-order sequence (0 = base era) */
+    this.seq = 0
+    /** bumped on every add/remove — cheap change detection for retries */
+    this.version = 0
+    this.primed = false
+  }
+
+  /** @returns {Array<{ epoch: number, stamp: number, entropy: Uint8Array }>} ascending by seq */
+  all() {
+    return [...this.entropies]
+      .map(([stamp, entropy]) => ({ epoch: this.seqs.get(stamp) || 0, stamp, entropy }))
+      .sort((a, b) => a.epoch - b.epoch)
+  }
+
+  /**
+   * @param {number} stamp
+   * @param {Uint8Array} entropy
+   * @param {number} [seq]  Apply-order sequence; drives `current` selection.
+   */
+  add(stamp, entropy, seq = 0) {
+    if (!Number.isInteger(stamp) || stamp <= 0 || stamp > 0xffffffff) {
+      throw CeroError.INVALID(`epoch stamp: ${stamp}`)
+    }
+    if (!b4a.isBuffer(entropy) || entropy.byteLength !== 32) {
+      throw CeroError.INVALID('epoch entropy must be 32 bytes')
+    }
+    this.entropies.set(stamp, entropy)
+    if (seq) this.seqs.set(stamp, seq)
+    const effective = this.seqs.get(stamp) || 0
+    if (this.current === 0 || (effective > 0 && effective >= this.seq)) {
+      this.seq = effective
+      this.current = stamp
+    }
+    this.version++
+  }
+
+  /**
+   * @param {number} stamp
+   * @returns {Uint8Array | null}
+   */
+  entropy(stamp) {
+    return this.entropies.get(stamp) || null
+  }
+
+  /**
+   * Forget an epoch (used to undo an add whose persistence failed).
+   *
+   * @param {number} stamp
+   */
+  remove(stamp) {
+    this.entropies.delete(stamp)
+    this.seqs.delete(stamp)
+    this.current = 0
+    this.seq = 0
+    for (const [s, q] of this.seqs) {
+      if (q >= this.seq) {
+        this.seq = q
+        this.current = s
+      }
+    }
+    this.version++
+  }
+}
+
+/**
+ * The epoch-aware provider — the class itself is upstream WriterEncryption;
+ * the epoch behavior lives on the (patched) base prototype above. Named for
+ * call sites and tests.
+ */
+export class EpochEncryption extends WriterEncryption {}
+
+/**
+ * Autobee with a rotation keyring. Every provider autobee constructs
+ * (view/system factory, foreign cores, ActiveWriters) picks the epochs up
+ * through the patched base class and this `keyring` property.
+ */
+export class EpochAutobee extends Autobee {
+  constructor(store, key, handlers = {}) {
+    super(store, key, handlers)
+    this.keyring = handlers.keyring || null
+    this._epochRetry = null
+    this._epochRetryDelay = 1000
+    this._epochRetrySeen = 0
+  }
+
+  // Prime the keyring from local userData as soon as boot resolves the local
+  // core (in-boot epoch misses are covered by the provider's lazy prime).
+  async _bootState() {
+    await super._bootState()
+    if (!this.keyring || this.keyring.primed || !this.local) return
+    this.keyring.primed = true
+    await primeKeyring(this.keyring, this.local)
+  }
+
+  // Upstream's drain body with one change: a writer whose next block sits at
+  // an epoch we haven't learned yet parks (stays pending, so every later
+  // bump re-examines it) instead of aborting the whole drain — the
+  // announcement carrying that epoch lives in another writer's core and
+  // applies on this or a later bump. The catch wraps the whole per-writer
+  // step so an UNKNOWN_EPOCH surfacing from batch processing parks too
+  // instead of crashing the bee.
+  async _bumpPendingWriters() {
+    let updated = false
+
+    const pending = this.writers.pending.slice()
+
+    for (let i = pending.length - 1; i >= 0; i--) {
+      const w = pending[i]
+
+      try {
+        const batch = await w.next()
+        if (batch === null) continue
+
+        if (w.isAdded || (w.isRemoved && w.hasReferrals())) {
+          await this._processBatch(batch)
+          w.notify(batch)
+          updated = true
+          continue
+        }
+
+        if (this.optimistic && !w.isRemoved && batch[0].optimistic) {
+          if (!(await this._optimisticBatch(batch))) {
+            w.removePending()
+            continue
+          }
+          w.notify(batch)
+          updated = true
+          continue
+        }
+      } catch (err) {
+        if (err?.code !== 'UNKNOWN_EPOCH') throw err
+        this._scheduleEpochRetry()
+        continue
+      }
+    }
+
+    return updated
+  }
+
+  // a parked writer produces no wake-up of its own — poke the bee until the
+  // pending announcement applies and the parked blocks decrypt. Exponential
+  // backoff (reset when the keyring advances) so a removed member, who will
+  // never learn the epoch, settles into a slow idle poll instead of a hot loop
+  _scheduleEpochRetry() {
+    if (this._epochRetry || this.closing) return
+    const version = this.keyring ? this.keyring.version : 0
+    if (version !== this._epochRetrySeen) {
+      this._epochRetrySeen = version
+      this._epochRetryDelay = 1000
+    }
+    this._epochRetry = setTimeout(() => {
+      this._epochRetry = null
+      if (!this.closing) this.update().catch(noop)
+    }, this._epochRetryDelay)
+    this._epochRetryDelay = Math.min(this._epochRetryDelay * 2, 60000)
+  }
+
+  async _close() {
+    if (this._epochRetry) clearTimeout(this._epochRetry)
+    this._epochRetry = null
+    return super._close()
+  }
+}
+
+function noop() {}

package/src/database/index.js

@@ -1,14 +1,24 @@
-import Autobee from 'autobee'
 import HyperDB from 'hyperdb'
 import c from 'compact-encoding'
+import crypto from 'hypercore-crypto'
 import Hypercore from 'hypercore'
 import ReadyResource from 'ready-resource'
 import safetyCatch from 'safety-catch'
 import b4a from 'b4a'
 
-import { NAMESPACE, SINGLE, COLLECTION, ACTION, ACTIVE, PASSIVE } from '../lib/constants.js'
-import { genId, subscribe, addWriterPayload, claimWriterPayload } from '../lib/utils.js'
+import { NAMESPACE, SINGLE, COLLECTION, ACTION, ACTIVE, PASSIVE, REMOVE } from '../lib/constants.js'
+import {
+  genId,
+  toId,
+  toKey,
+  can,
+  subscribe,
+  addWriterPayload,
+  claimWriterPayload
+} from '../lib/utils.js'
 import { wrap, unwrap } from './envelope.js'
+import { EpochAutobee, Keyring, wraps, epochEntries } from './encryption.js'
+import { Identity } from '../identity/index.js'
 import { CeroError } from '../lib/errors.js'
 import { bootstrap } from './bootstrap.js'
 import { makeChanges } from './changes.js'
@@ -23,6 +33,7 @@ import { makeDispatcher } from './dispatch.js'
  * @property {Record<string, Function>} [routes]                      Custom action handlers keyed by route name.
  * @property {string} [namespace]                                     Corestore namespace; defaults to `cero`.
  * @property {Uint8Array | null} [encryptionKey]                      Optional encryption key; falls back to identity's key.
+ * @property {Array<{ epoch: number, entropy: Uint8Array }> | null} [epochs]  Rotation epochs to prime the keyring with (delivered at join).
  * @property {(nodes: any, view: any, host: any) => Promise<void>} [apply]  Override the default apply function.
  * @property {Uint8Array | null} [key]                                Existing autobee key to reopen.
  * @property {boolean} [passive]                                      Join discovery server-only (reachable but not searching). Flip at runtime with `setActive`.
@@ -65,6 +76,15 @@ export class Database extends ReadyResource {
     this.routes = opts.routes || {}
     this.namespace = opts.namespace || NAMESPACE
     this.encryptionKey = opts.encryptionKey || opts.identity.encryptionKey || null
+    this.keyring = new Keyring()
+    if (opts.epochs) for (const e of opts.epochs) this.keyring.add(e.stamp, e.entropy, e.epoch)
+    this._rotation = null
+    this._healTimer = null
+    this._healedFor = null
+    // membership and epochs both change through apply — after each update,
+    // REMOVE-capable devices verify the current epoch still matches the
+    // member set and re-key when it does not (see _healEpochs)
+    this.on('update', () => this._scheduleHeal())
     this.applyOverride = opts.apply || null
     this.key = opts.key || null
     this.passive = opts.passive === true
@@ -94,6 +114,10 @@ export class Database extends ReadyResource {
   }
 
   async _close() {
+    if (this._healTimer) {
+      clearTimeout(this._healTimer)
+      this._healTimer = null
+    }
     if (this._discovery) {
       await this._discovery.destroy()
       this._discovery = null
@@ -109,7 +133,14 @@ export class Database extends ReadyResource {
 
   /** Open the underlying autobee, wire dispatcher + apply, attach to network. */
   async openBee() {
-    this.dispatcher = makeDispatcher(this.spec, this.ns, this.routes, this._onerror, () => this.key)
+    this.dispatcher = makeDispatcher(
+      this.spec,
+      this.ns,
+      this.routes,
+      this._onerror,
+      () => this.key,
+      { onEpoch: (row) => this._onEpoch(row) }
+    )
 
     // autobee-wakeup destroys whatever wakeup it is handed (its _owner guard is
     // computed but never consulted upstream) — closing one bee must not tear
@@ -122,9 +153,10 @@ export class Database extends ReadyResource {
       destroy: () => {}
     }
 
-    const bee = new Autobee(this.store.namespace(this.namespace), this.key, {
+    const bee = new EpochAutobee(this.store.namespace(this.namespace), this.key, {
       keyPair: this.keyPair,
       encryptionKey: this.encryptionKey,
+      keyring: this.keyring,
       optimistic: true,
       wakeup: wakeup || undefined,
       open: (b) => HyperDB.bee2(b, this.spec.database, { autoUpdate: true }),
@@ -161,10 +193,11 @@ export class Database extends ReadyResource {
     })
 
     await bee.ready()
-    await bee.update()
-
+    // assigned before the first update: apply-time hooks (_onEpoch's save,
+    // _onFuture) dereference this.bee and must never see it null mid-drain
     this.bee = bee
     this.key = bee.key
+    await bee.update()
 
     const behind = await bee.local.getUserData('cero/behind')
     this.behind = behind ? c.decode(c.uint, behind) : null
@@ -181,7 +214,15 @@ export class Database extends ReadyResource {
       return
     }
 
+    // prime the keyring from local userData before replication can deliver
+    // blocks at epochs this session hasn't learned yet
+    await this._loadEpochs()
+
     bee.on('writable', () => this.emit('writable'))
+    // the falling edge: this device's writer was removed (or its member was).
+    // Apps need it to freeze a UI the moment access ends, rather than
+    // discovering it from a failed write or by scanning `members`.
+    bee.on('unwritable', () => this.emit('unwritable'))
     // without a listener autobee escalates apply/view errors to a process crash
     bee.on('error', this._onerror)
 
@@ -486,6 +527,213 @@ export class Database extends ReadyResource {
     await this.write([[op, data]])
   }
 
+  /**
+   * Rotate the encryption epoch: generate a fresh 32-byte secret, seal it to
+   * every current member's identity key, and announce it through the log.
+   * The announcement is appended under the current epoch (so every member —
+   * even one offline for several rotations — can walk the chain forward),
+   * and blocks written after it use the new one. Members absent from the
+   * envelope set (removed before the rotation) never learn the new key.
+   *
+   * @returns {Promise<{ epoch: number }>}
+   */
+  async rotate(retried = false) {
+    this.guard()
+    if (!this.writable) throw CeroError.NOT_WRITABLE('Database')
+    // inside tx() the op would only be queued — the epoch could never be
+    // observed before returning, and batching a rekey with app writes would
+    // blur which epoch those writes land in
+    if (this.txQueue) throw CeroError.INVALID('rotate() cannot run inside tx()')
+    if (this._rotation) throw CeroError.INVALID('a rotation is already in progress')
+    // compat-path (manifest v1) blocks carry no key id — rotation would be a
+    // silent downgrade there, so refuse deterministically
+    if (this.bee.local.manifest?.version < 2) {
+      throw CeroError.INVALID('rotation requires manifest v2 cores')
+    }
+    // claimed synchronously — no await may separate the check from the claim
+    this._rotation = { entropy: null, stamp: 0, epoch: 0 }
+    try {
+      const { data: members } = await this.get('members')
+      if (!Array.isArray(members) || members.length === 0) {
+        throw CeroError.INVALID('cannot rotate a database with no members')
+      }
+      const entropy = Identity.randomBytes(32)
+      const stamp = this._randomStamp()
+      const wrapped = []
+      for (const m of members) {
+        let key
+        try {
+          key = toKey(m.id)
+        } catch {
+          throw CeroError.INVALID(`member id is not an identity key: ${m.id}`)
+        }
+        wrapped.push({ id: m.id, box: Identity.seal(key, entropy) })
+      }
+      // Defer our own hydration until the append has flushed: the local block
+      // is encrypted at drain time, AFTER our optimistic apply runs — advancing
+      // the keyring there would encrypt the announcement itself under the new
+      // epoch, which nobody else could read (the chain rule would break).
+      this._rotation.entropy = entropy
+      this._rotation.stamp = stamp
+      const appendedFrom = this.bee.local.length
+      await this.call('rotate-key', {
+        epoch: 0, // sequence assigned deterministically at apply time
+        stamp,
+        wrapped: c.encode(wraps, wrapped),
+        createdAt: Date.now(),
+        commit: crypto.hash(entropy)
+      })
+      await this.bee.update()
+      const { epoch } = this._rotation
+      if (!epoch) {
+        // distinguish a stamp collision (another epoch owns our random stamp
+        // — ~2^-32, or an adversarial pre-claim) from a permission rejection
+        const rows = await this.view.find(`@${this.ns}/epochs`, {}).toArray()
+        if (!retried && rows.some((r) => r.stamp === stamp)) {
+          this._rotation = null
+          return this.rotate(true)
+        }
+        throw CeroError.INVALID('rotation was not applied — requires the remove permission')
+      }
+      // Invariant check, not an assumption: no block appended during this
+      // rotation may carry the stamp it announces — that would make the
+      // announcement unreadable to every other member.
+      for (let i = appendedFrom; i < this.bee.local.length; i++) {
+        const raw = await this.bee.local.get(i, { raw: true })
+        const id = c.uint32.decode({ start: 4, end: 8, buffer: raw.subarray(0, 8) })
+        if (id === stamp) {
+          throw CeroError.INVALID('announcement encrypted under its own epoch — aborting rotation')
+        }
+      }
+      this.keyring.add(stamp, entropy, epoch)
+      await this._saveEpochs()
+      return { epoch }
+    } finally {
+      this._rotation = null
+    }
+  }
+
+  /** Fresh nonzero uint32 block-header stamp not already used by a known epoch. */
+  _randomStamp() {
+    for (;;) {
+      const buf = Identity.randomBytes(4)
+      const stamp = ((buf[0] << 24) | (buf[1] << 16) | (buf[2] << 8) | buf[3]) >>> 0
+      if (stamp !== 0 && !this.keyring.entropy(stamp)) return stamp
+    }
+  }
+
+  /**
+   * Per-peer side of an applied rotation: open our envelope, learn the epoch
+   * secret, persist it locally. Peers without an envelope (removed members)
+   * simply stop here — every block after the announcement is noise to them.
+   * Our own in-flight rotation is deferred to `rotate()` (see above).
+   *
+   * @param {{ epoch: number, wrapped: Uint8Array, createdAt: number }} row
+   */
+  async _onEpoch(row) {
+    if (this.keyring.entropy(row.stamp)) {
+      // idempotent re-apply — but record the sequence if it was unknown
+      this.keyring.add(row.stamp, this.keyring.entropy(row.stamp), row.epoch)
+      this._scheduleHeal()
+      return
+    }
+    for (const w of c.decode(wraps, row.wrapped)) {
+      if (w.id !== this.identity.id) continue
+      const entropy = this.identity.unseal(w.box)
+      // skip malformed or mis-sealed envelopes and keep scanning — a bad
+      // envelope ahead of a good one must not lock this member out
+      if (entropy?.byteLength !== 32) continue
+      // the secret must match the row's public commitment — otherwise a
+      // rotator sealed different secrets to different members
+      if (!row.commit || !b4a.equals(crypto.hash(entropy), row.commit)) {
+        this._onerror(CeroError.INVALID(`epoch ${row.epoch} envelope fails its commitment`))
+        continue
+      }
+      if (this._rotation?.entropy && b4a.equals(entropy, this._rotation.entropy)) {
+        this._rotation.epoch = row.epoch
+      } else {
+        this.keyring.add(row.stamp, entropy, row.epoch)
+        try {
+          await this._saveEpochs()
+        } catch (err) {
+          // an epoch this device cannot reload after a restart must not be
+          // used for writes — undo the add and surface the storage failure
+          this.keyring.remove(row.stamp)
+          this._onerror(err)
+        }
+      }
+      break
+    }
+    this._scheduleHeal()
+  }
+
+  /**
+   * Safety net after boot (userData priming happens in EpochAutobee's
+   * `_bootState`): scan the epochs collection for anything applied but never
+   * hydrated — e.g. a crash between a rotation's append and its save.
+   */
+  async _loadEpochs() {
+    try {
+      const rows = await this.view.find(`@${this.ns}/epochs`, {}).toArray()
+      for (const row of rows) {
+        if (this.keyring.entropy(row.epoch)) continue
+        await this._onEpoch(row)
+      }
+    } catch {
+      // pre-rotation spec (no epochs collection), or rows beyond our newest
+      // known epoch — those hydrate through apply when announcements sync
+    }
+  }
+
+  /** Persist known epoch secrets to local userData (device-only, never replicates). */
+  _saveEpochs() {
+    return this.bee.local.setUserData('cero/epochs', c.encode(epochEntries, this.keyring.all()))
+  }
+
+  /** Debounced trigger for the epoch/membership consistency check. */
+  _scheduleHeal() {
+    if (this._healTimer || this.closing || this.closed) return
+    this._healTimer = setTimeout(() => {
+      this._healTimer = null
+      this._healEpochs().catch(this._onerror)
+    }, 500)
+  }
+
+  /**
+   * Convergence rotation: rotations author their envelope set against the
+   * rotator's possibly-stale local view, so after linearization the current
+   * epoch may include a since-removed member (who then still holds the
+   * current key) or miss a since-added one (who is locked out). Every
+   * REMOVE-capable writable device audits the current epoch's recipients
+   * against canonical membership and re-keys on mismatch. Only rooms that
+   * have rotated at least once are audited — rotation stays opt-in.
+   */
+  async _healEpochs() {
+    if (this.closing || this.closed || !this.writable || this._rotation) return
+    if (!this.keyring.current) return
+    const { data: device } = await this.get('devices', toId(this.writerKey))
+    const me = device?.memberId ? (await this.get('members', device.memberId)).data : null
+    if (!can(me?.role, REMOVE)) return
+
+    const rows = await this.view.find(`@${this.ns}/epochs`, {}).toArray()
+    if (!rows.length) return
+    const top = rows.reduce((a, b) => (b.epoch > a.epoch ? b : a))
+    const recipients = new Set(c.decode(wraps, top.wrapped).map((w) => w.id))
+    const { data: members } = await this.get('members')
+    const ids = new Set(members.map((m) => m.id))
+    const clean = recipients.size === ids.size && [...recipients].every((id) => ids.has(id))
+    if (clean) {
+      this._healedFor = null
+      return
+    }
+    // one attempt per (epoch, membership) state — a failing rotate (e.g. a
+    // permission race) must not loop; any state change re-arms the audit
+    const state = `${top.stamp}:${[...ids].sort().join(',')}`
+    if (this._healedFor === state) return
+    this._healedFor = state
+    await this.rotate()
+  }
+
   /**
    * Batch every write performed inside `fn` into a single autobee append.
    * Nested calls reuse the outer queue.
@@ -572,7 +820,8 @@ export class Database extends ReadyResource {
           view: tx,
           host,
           key: this.writerKey,
-          dbKey: this.key
+          dbKey: this.key,
+          dryRun: true
         })
       }
     } finally {

package/src/identity/index.js

@@ -89,6 +89,25 @@ export class Identity {
     return sodium.crypto_sign_verify_detached(signature, message, this.publicKey)
   }
 
+  /**
+   * Open a sealed box addressed to this identity (any device holding the
+   * seed-derived keypair can open it). Returns null when the box is not ours
+   * or is corrupt — callers treat that as "not addressed to me".
+   *
+   * @param {Uint8Array} sealed
+   * @returns {Uint8Array | null}
+   */
+  unseal(sealed) {
+    if (!b4a.isBuffer(sealed) || sealed.byteLength <= sodium.crypto_box_SEALBYTES) return null
+    const publicKey = b4a.alloc(sodium.crypto_box_PUBLICKEYBYTES)
+    const secretKey = b4a.alloc(sodium.crypto_box_SECRETKEYBYTES)
+    sodium.crypto_sign_ed25519_pk_to_curve25519(publicKey, this.publicKey)
+    sodium.crypto_sign_ed25519_sk_to_curve25519(secretKey, this.secretKey)
+    const message = b4a.alloc(sealed.byteLength - sodium.crypto_box_SEALBYTES)
+    const opened = sodium.crypto_box_seal_open(message, sealed, publicKey, secretKey)
+    return opened ? message : null
+  }
+
   /**
    * Render the underlying seed as a BIP-39 mnemonic phrase.
    *
@@ -203,6 +222,23 @@ export class Identity {
     return sodium.crypto_sign_verify_detached(signature, message, publicKey)
   }
 
+  /**
+   * Seal a message to an identity's Ed25519 public key (sealed box over the
+   * curve25519 conversion). Only the holder of the matching secret key —
+   * i.e. any of that identity's devices — can open it.
+   *
+   * @param {Uint8Array} publicKey
+   * @param {Uint8Array} message
+   * @returns {Uint8Array}
+   */
+  static seal(publicKey, message) {
+    const curve = b4a.alloc(sodium.crypto_box_PUBLICKEYBYTES)
+    sodium.crypto_sign_ed25519_pk_to_curve25519(curve, publicKey)
+    const sealed = b4a.alloc(message.byteLength + sodium.crypto_box_SEALBYTES)
+    sodium.crypto_box_seal(sealed, message, curve)
+    return sealed
+  }
+
   /**
    * Generate a fresh Ed25519 keypair (for devices, blind invites, etc.).
    *

package/src/lib/constants.js

@@ -42,3 +42,5 @@ export const NAMESPACE = 'cero'
 
 // Internal counter collection (assigns monotonic `index` to every row in every collection)
 export const COUNTERS = 'counters'
+// Internal key-rotation epoch collection (rotation announcements with sealed envelopes)
+export const EPOCHS = 'epochs'

package/src/lib/errors.js

@@ -163,4 +163,13 @@ export class CeroError extends Error {
   static NETWORK_ERROR(msg = 'network error') {
     return new CeroError('NETWORK_ERROR', msg)
   }
+  /**
+   * A block references a rotation epoch this peer hasn't learned yet —
+   * resolves once the announcement carrying the epoch secret syncs in.
+   *
+   * @param {number} epoch
+   */
+  static UNKNOWN_EPOCH(epoch) {
+    return new CeroError('UNKNOWN_EPOCH', `unknown encryption epoch: ${epoch}`)
+  }
 }

package/types/blobs/index.d.ts

@@ -11,11 +11,12 @@
 /** Thin wrapper over a single Hyperblobs core; deals only in raw blobIds. */
 export class Blobs extends ReadyResource {
     /** @param {BlobsOpts} [opts] */
-    constructor({ store, identity, network, key, encryptionKey }?: BlobsOpts);
+    constructor({ store, identity, network, key, encryptionKey, name }?: BlobsOpts);
     store: any;
     identity: import("../index.js").Identity;
     network: import("../index.js").Network;
     encryptionKey: Uint8Array<ArrayBufferLike>;
+    name: any;
     _coreKey: Uint8Array<ArrayBufferLike>;
     core: any;
     hyperblobs: any;

package/types/database/dispatch.d.ts

@@ -6,6 +6,8 @@
  * @param {string} ns  Namespace prefix for collection and op names.
  * @param {Record<string, Function>} routes  Custom action handlers keyed by route name.
  * @param {(err: Error) => void} [onerror]  Called when a malformed node is skipped.
+ * @param {() => Uint8Array | null} [getDbKey]
+ * @param {{ onEpoch?: (row: { epoch: number, wrapped: Uint8Array, createdAt: number }) => Promise<void> }} [hooks]  Per-peer side effects fired after an op applies (skipped in dry runs).
  * @returns {{ dispatcher: object, apply: (nodes: Array<{ value: Buffer, key: Buffer }>, view: object, host: object) => Promise<void> }}
  */
 export function makeDispatcher(spec: {
@@ -19,7 +21,13 @@ export function makeDispatcher(spec: {
             verb?: string;
         }>;
     };
-}, ns: string, routes: Record<string, Function>, onerror?: (err: Error) => void, getDbKey?: () => any): {
+}, ns: string, routes: Record<string, Function>, onerror?: (err: Error) => void, getDbKey?: () => Uint8Array | null, hooks?: {
+    onEpoch?: (row: {
+        epoch: number;
+        wrapped: Uint8Array;
+        createdAt: number;
+    }) => Promise<void>;
+}): {
     dispatcher: object;
     apply: (nodes: Array<{
         value: Buffer;

package/types/database/encryption.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Encryption key for a rotation epoch's blob cores. New files land in a core
+ * keyed by the epoch entropy, so file confidentiality rotates with the room:
+ * only holders of the epoch secret can derive the core key.
+ *
+ * @param {Uint8Array} entropy
+ * @returns {Uint8Array}
+ */
+export function blobEpochKey(entropy: Uint8Array): Uint8Array;
+/**
+ * Wire codec for a rotation announcement's envelope list — one sealed box
+ * per remaining member, addressed by member id.
+ */
+export const wraps: any;
+/**
+ * Wire codec for locally persisted / pairing-delivered epoch secrets.
+ * `epoch` is the apply-order sequence; `stamp` is the content-addressed
+ * uint32 written into block headers.
+ */
+export const epochEntries: any;
+/**
+ * Per-database registry of rotation epochs. Stamp 0 is the base key era
+ * (no entry needed — it derives from the upstream GENESIS_ENTROPY path).
+ * Every rotation adds an entry keyed by its content-addressed `stamp` (the
+ * uint32 written into block headers, chosen randomly by the rotator and
+ * validated unique at apply) alongside its apply-order `seq`. Because the
+ * stamp is chosen before any block is written and can never be renumbered
+ * by linearization, a block's header always identifies its true key —
+ * concurrent rotations cannot make blocks undecryptable.
+ */
+export class Keyring {
+    /** @type {Map<number, Uint8Array>} stamp → entropy */
+    entropies: Map<number, Uint8Array>;
+    /** @type {Map<number, number>} stamp → apply-order sequence */
+    seqs: Map<number, number>;
+    /** stamp used for new blocks — the adopted epoch with the highest seq */
+    current: number;
+    /** highest adopted apply-order sequence (0 = base era) */
+    seq: number;
+    /** bumped on every add/remove — cheap change detection for retries */
+    version: number;
+    primed: boolean;
+    /** @returns {Array<{ epoch: number, stamp: number, entropy: Uint8Array }>} ascending by seq */
+    all(): Array<{
+        epoch: number;
+        stamp: number;
+        entropy: Uint8Array;
+    }>;
+    /**
+     * @param {number} stamp
+     * @param {Uint8Array} entropy
+     * @param {number} [seq]  Apply-order sequence; drives `current` selection.
+     */
+    add(stamp: number, entropy: Uint8Array, seq?: number): void;
+    /**
+     * @param {number} stamp
+     * @returns {Uint8Array | null}
+     */
+    entropy(stamp: number): Uint8Array | null;
+    /**
+     * Forget an epoch (used to undo an add whose persistence failed).
+     *
+     * @param {number} stamp
+     */
+    remove(stamp: number): void;
+}
+/**
+ * The epoch-aware provider — the class itself is upstream WriterEncryption;
+ * the epoch behavior lives on the (patched) base prototype above. Named for
+ * call sites and tests.
+ */
+export class EpochEncryption {
+}
+/**
+ * Autobee with a rotation keyring. Every provider autobee constructs
+ * (view/system factory, foreign cores, ActiveWriters) picks the epochs up
+ * through the patched base class and this `keyring` property.
+ */
+export class EpochAutobee {
+    constructor(store: any, key: any, handlers?: {});
+    keyring: any;
+    _epochRetry: any;
+    _epochRetryDelay: number;
+    _epochRetrySeen: number;
+    _bootState(): Promise<void>;
+    _bumpPendingWriters(): Promise<boolean>;
+    _scheduleEpochRetry(): void;
+    _close(): Promise<any>;
+}

package/types/database/index.d.ts

@@ -7,6 +7,7 @@
  * @property {Record<string, Function>} [routes]                      Custom action handlers keyed by route name.
  * @property {string} [namespace]                                     Corestore namespace; defaults to `cero`.
  * @property {Uint8Array | null} [encryptionKey]                      Optional encryption key; falls back to identity's key.
+ * @property {Array<{ epoch: number, entropy: Uint8Array }> | null} [epochs]  Rotation epochs to prime the keyring with (delivered at join).
  * @property {(nodes: any, view: any, host: any) => Promise<void>} [apply]  Override the default apply function.
  * @property {Uint8Array | null} [key]                                Existing autobee key to reopen.
  * @property {boolean} [passive]                                      Join discovery server-only (reachable but not searching). Flip at runtime with `setActive`.
@@ -29,7 +30,7 @@ export class Database extends ReadyResource {
     /** @param {Partial<DatabaseOpts>} [opts] */
     constructor(opts?: Partial<DatabaseOpts>);
     store: any;
-    identity: import("../index.js").Identity;
+    identity: Identity;
     network: import("../index.js").Network;
     spec: {
         database: any;
@@ -59,6 +60,14 @@ export class Database extends ReadyResource {
     routes: Record<string, Function>;
     namespace: string;
     encryptionKey: Uint8Array<ArrayBufferLike>;
+    keyring: Keyring;
+    _rotation: {
+        entropy: any;
+        stamp: number;
+        epoch: number;
+    };
+    _healTimer: any;
+    _healedFor: any;
     applyOverride: (nodes: any, view: any, host: any) => Promise<void>;
     key: Uint8Array<ArrayBufferLike>;
     passive: boolean;
@@ -67,7 +76,7 @@ export class Database extends ReadyResource {
         secretKey: Uint8Array<ArrayBufferLike>;
     };
     _onerror: any;
-    bee: any;
+    bee: EpochAutobee;
     dispatcher: {
         dispatcher: object;
         apply: (nodes: Array<{
@@ -200,6 +209,54 @@ export class Database extends ReadyResource {
      * @returns {Promise<void>}
      */
     call(op: string, data?: Record<string, any>): Promise<void>;
+    /**
+     * Rotate the encryption epoch: generate a fresh 32-byte secret, seal it to
+     * every current member's identity key, and announce it through the log.
+     * The announcement is appended under the current epoch (so every member —
+     * even one offline for several rotations — can walk the chain forward),
+     * and blocks written after it use the new one. Members absent from the
+     * envelope set (removed before the rotation) never learn the new key.
+     *
+     * @returns {Promise<{ epoch: number }>}
+     */
+    rotate(retried?: boolean): Promise<{
+        epoch: number;
+    }>;
+    /** Fresh nonzero uint32 block-header stamp not already used by a known epoch. */
+    _randomStamp(): number;
+    /**
+     * Per-peer side of an applied rotation: open our envelope, learn the epoch
+     * secret, persist it locally. Peers without an envelope (removed members)
+     * simply stop here — every block after the announcement is noise to them.
+     * Our own in-flight rotation is deferred to `rotate()` (see above).
+     *
+     * @param {{ epoch: number, wrapped: Uint8Array, createdAt: number }} row
+     */
+    _onEpoch(row: {
+        epoch: number;
+        wrapped: Uint8Array;
+        createdAt: number;
+    }): Promise<void>;
+    /**
+     * Safety net after boot (userData priming happens in EpochAutobee's
+     * `_bootState`): scan the epochs collection for anything applied but never
+     * hydrated — e.g. a crash between a rotation's append and its save.
+     */
+    _loadEpochs(): Promise<void>;
+    /** Persist known epoch secrets to local userData (device-only, never replicates). */
+    _saveEpochs(): any;
+    /** Debounced trigger for the epoch/membership consistency check. */
+    _scheduleHeal(): void;
+    /**
+     * Convergence rotation: rotations author their envelope set against the
+     * rotator's possibly-stale local view, so after linearization the current
+     * epoch may include a since-removed member (who then still holds the
+     * current key) or miss a since-added one (who is locked out). Every
+     * REMOVE-capable writable device audits the current epoch's recipients
+     * against canonical membership and re-keys on mismatch. Only rooms that
+     * have rotated at least once are audited — rotation stays opt-in.
+     */
+    _healEpochs(): Promise<void>;
     /**
      * Batch every write performed inside `fn` into a single autobee append.
      * Nested calls reuse the outer queue.
@@ -401,6 +458,13 @@ export type DatabaseOpts = {
      * Optional encryption key; falls back to identity's key.
      */
     encryptionKey?: Uint8Array | null;
+    /**
+     * Rotation epochs to prime the keyring with (delivered at join).
+     */
+    epochs?: Array<{
+        epoch: number;
+        entropy: Uint8Array;
+    }> | null;
     /**
      * Override the default apply function.
      */
@@ -451,3 +515,6 @@ export type Ref = {
 };
 export type HookFn = (ctx: any) => any | Promise<any>;
 import ReadyResource from 'ready-resource';
+import { Identity } from '../identity/index.js';
+import { Keyring } from './encryption.js';
+import { EpochAutobee } from './encryption.js';

package/types/identity/index.d.ts

@@ -75,6 +75,16 @@ export class Identity {
      * @returns {boolean}
      */
     static verify(publicKey: Uint8Array, message: Uint8Array, signature: Uint8Array): boolean;
+    /**
+     * Seal a message to an identity's Ed25519 public key (sealed box over the
+     * curve25519 conversion). Only the holder of the matching secret key —
+     * i.e. any of that identity's devices — can open it.
+     *
+     * @param {Uint8Array} publicKey
+     * @param {Uint8Array} message
+     * @returns {Uint8Array}
+     */
+    static seal(publicKey: Uint8Array, message: Uint8Array): Uint8Array;
     /**
      * Generate a fresh Ed25519 keypair (for devices, blind invites, etc.).
      *
@@ -149,6 +159,15 @@ export class Identity {
      * @returns {boolean}
      */
     verify(message: Uint8Array, signature: Uint8Array): boolean;
+    /**
+     * Open a sealed box addressed to this identity (any device holding the
+     * seed-derived keypair can open it). Returns null when the box is not ours
+     * or is corrupt — callers treat that as "not addressed to me".
+     *
+     * @param {Uint8Array} sealed
+     * @returns {Uint8Array | null}
+     */
+    unseal(sealed: Uint8Array): Uint8Array | null;
     /**
      * Render the underlying seed as a BIP-39 mnemonic phrase.
      *

package/types/lib/constants.d.ts

@@ -34,3 +34,4 @@ export namespace RANK {
 }
 export const NAMESPACE: "cero";
 export const COUNTERS: "counters";
+export const EPOCHS: "epochs";

package/types/lib/errors.d.ts

@@ -110,6 +110,13 @@ export class CeroError extends Error {
      * @param {string} [msg]
      */
     static NETWORK_ERROR(msg?: string): CeroError;
+    /**
+     * A block references a rotation epoch this peer hasn't learned yet —
+     * resolves once the announcement carrying the epoch secret syncs in.
+     *
+     * @param {number} epoch
+     */
+    static UNKNOWN_EPOCH(epoch: number): CeroError;
     /**
      * @param {string} code            Stable identifier (e.g. `REQUIRED`, `EXPIRED`).
      * @param {string} [message]       Human-readable detail; appended after the code.