ReEncryptOptions

ReEncryptOptions = object

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:93

Properties

info

readonly info: string

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:109

HKDF info string the corpus was written under — it must match the encrypting store’s EncryptionConfig.info exactly, or every decrypt in the sweep fails. Required since #108: there is no framework-wide default to fall back on any more, and guessing one would silently produce the wrong subkey.

---

keyPrefix

readonly keyPrefix: string

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:95

Common key prefix to sweep (e.g. 'snapshots/' or 'state/').

---

keyring

readonly keyring: MasterKeyRing

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:101

Keyring containing the currently active key plus every retired version the corpus may have been encrypted under. Without a retired entry for a version, that body’s decrypt will fail.

---

newInfo?

readonly optional newInfo?: string

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:124

HKDF info to re-encrypt under. Unset (the normal case) means “same as info” — a pure master-key rotation. Set it to rotate the derivation context itself, e.g. when splitting a shared 'actor-ts/snapshot/v1' into per-environment contexts (#108).

Rotating info changes what the sweep can skip. The key version is stamped in the body manifest; the info is not, so a body at the active key version may still be at the old context and there is no cheap way to tell. The version fast-path is therefore disabled while newInfo differs from info, and every object is decrypted to find out — slower, but the alternative is a sweep that reports success having rewritten nothing.

---

onProgress?

readonly optional onProgress?: (event) => void

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:140

Optional progress hook called after each object is processed. Use it to log to stderr / write a progress file / surface to an operator dashboard for long-running sweeps.

Parameters

event

ReEncryptProgress

Returns

void

---

pidFromKey?

readonly optional pidFromKey?: (key, keyPrefix) => string

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:134

Extracts the persistenceId from a backend key. HKDF uses the pid as a per-pid salt, so the sweep needs to recover it from the key in order to derive the same subkey the original encrypter did.

Default: <keyPrefix><pid>/<rest> — picks the next path segment after the prefix. Works for the layouts both built-in object- storage stores use; override for custom layouts.

Parameters

key

string

keyPrefix

string

Returns

string

---

progress?

readonly optional progress?: ReEncryptProgressStore

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:156

Crash-resume hook (#109). When set, the sweep loads the saved lastKey at start and skips every key ≤ it; after each Nth object (see saveProgressEveryN) the new state is persisted. At successful end the store is cleared so a fresh re-run starts from the beginning. Without this, a crash mid-sweep means the resumed run has to re-list and re-check every key — fine for small buckets, expensive at million-object scale.

---

sampleSize?

readonly optional sampleSize?: number

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:176

Sample size for the completeness check. Default: min(100, total).

---

saveProgressEveryN?

readonly optional saveProgressEveryN?: number

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:163

How often to persist progress. Default: every 50 objects. Lower values trade extra progress.save() writes for shorter potential rewind on crash; higher values reduce overhead at the cost of re-doing more work on resume.

---

skip?

readonly optional skip?: (key) => boolean

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:146

When set, skip objects whose key matches this predicate. Useful for excluding manifest files or other non-body objects that share the prefix. Default: process every key.

Parameters

key

string

Returns

boolean

---

verifyKeyringCompleteness?

readonly optional verifyKeyringCompleteness?: boolean

Defined in: src/persistence/object-storage/reEncryptionSweep.ts:174

When true (default), perform a pre-sweep completeness check on the keyring: sample the first sampleSize encrypted objects in the prefix, gather their key versions, and refuse to start if any version is missing from keyring.active/retired. Catches the “operator dropped the retired key too soon” footgun BEFORE a single decrypt failure (which would otherwise mid-sweep abort, leaving the corpus half-rewritten). Set false to skip — useful when the operator has independent assurance that the keyring is complete.