Class: MigrationStateManager
Defined in: migrate.ts:532
Tracks PQC migration state for a collection of keys, with validation, history and an audit trail. Storage-agnostic: you provide the MigrationStore. Convert to and from quantum-safe-py's store layout with exportToPyStore / importFromPyStore.
Valid forward transitions: classical_only → hybrid_transition → pqc_preferred → pqc_only. Backward transitions (hybrid_transition → classical_only, pqc_preferred → hybrid_transition) need allowBackward: true and a reason; pqc_only is terminal.
Concurrency. Each key's whole history is one document, written with a single compare-and-set. With a store that implements compareAndSet atomically, concurrent transitions from any number of processes are safe: exactly one wins and the others get a stale-state error. Without it, the manager only serialises inside this process (see MigrationStateManager.crossProcessSafe).
Each key's history is stored under MIGRATION_DOC_PREFIX + keyId as JSON, at most 10,000 records per key.
Example
const manager = new MigrationStateManager(new MemoryMigrationStore());
await manager.transition({ keyId: 'orders', fromState: 'classical_only', toState: 'hybrid_transition', algorithm: 'X25519+ML-KEM-768' });
await manager.getCurrentState('orders'); // "hybrid_transition"Constructors
Constructor
new MigrationStateManager(
store):MigrationStateManager
Defined in: migrate.ts:537
Parameters
store
The storage backend. Give it an atomic compareAndSet for safety across processes.
Returns
MigrationStateManager
Accessors
crossProcessSafe
Get Signature
get crossProcessSafe():
boolean
Defined in: migrate.ts:542
True if the store provides compare-and-set, so transitions are atomic across processes (given a correct store).
Returns
boolean
Methods
getCurrentRecord()
getCurrentRecord(
keyId):Promise<MigrationRecord|undefined>
Defined in: migrate.ts:644
The latest record of keyId, or undefined when the key has no history.
Parameters
keyId
string
Returns
Promise<MigrationRecord | undefined>
Throws
if the stored document is corrupt.
getCurrentState()
getCurrentState(
keyId):Promise<MigrationState|undefined>
Defined in: migrate.ts:652
The current state of keyId (the toState of its latest record), or undefined when the key has no history.
Parameters
keyId
string
Returns
Promise<MigrationState | undefined>
Throws
if the stored document is corrupt.
getHistory()
getHistory(
keyId):Promise<MigrationRecord[]>
Defined in: migrate.ts:660
Full history, oldest first.
Parameters
keyId
string
Returns
Promise<MigrationRecord[]>
Throws
if the stored document is corrupt.
importHistory()
importHistory(
keyId,records):Promise<void>
Defined in: migrate.ts:617
Imports a complete, previously exported history for a key that has no records yet (used by importFromPyStore). The chain is validated: each record's fromState must equal the previous toState and every step must be a legal transition. Without compareAndSet the check for existing history and the write are two separate store calls.
Parameters
keyId
string
The key the records belong to; every record's keyId must equal it.
records
readonly MigrationRecord[]
The history, oldest first.
Returns
Promise<void>
Throws
for an empty list, an invalid record, an illegal step, a broken chain, or a key that already has history (including one created concurrently).
keyIds()
keyIds():
Promise<string[]>
Defined in: migrate.ts:666
All key ids that have any history, sorted. A full scan: keep a secondary index in production.
Returns
Promise<string[]>
keysByState()
keysByState(
state):Promise<string[]>
Defined in: migrate.ts:676
Key ids currently in state, sorted. A full scan.
Parameters
state
Returns
Promise<string[]>
Throws
if a stored document is corrupt.
migrationProgress()
migrationProgress():
Promise<Record<MigrationState,number>>
Defined in: migrate.ts:694
Counts of keys per state; every state is present, with 0 when no key is in it.
Returns
Promise<Record<MigrationState, number>>
Throws
if a stored document is corrupt.
needsMigration()
needsMigration():
Promise<string[]>
Defined in: migrate.ts:686
Key ids that are still classical_only.
Returns
Promise<string[]>
Throws
if a stored document is corrupt.
transition()
transition(
opts):Promise<MigrationRecord>
Defined in: migrate.ts:558
Records a transition.
The transition must be a legal step from fromState. A key with no history accepts any fromState as its starting point; a key with history must currently be in fromState. A backward step needs allowBackward: true and a non-empty reason. With compareAndSet the write is retried up to 32 times after losing a race; without it the write is a plain set.
Parameters
opts
The key, the expected and new states, the key's algorithm after the change, and optional actor, reason and metadata.
Returns
Promise<MigrationRecord>
The record that was stored.
Throws
for invalid, stale or contended transitions: an empty keyId, an unknown state, an illegal step, a backward step without allowBackward or a reason, a current state other than fromState, a corrupt stored history, a history that already holds 10,000 records, or 32 lost compare-and-set races in a row.