@brightchain/brightchain-lib 0.18.0 → 0.20.0

package/src/lib/services/quorumStateMachine.d.ts

@@ -0,0 +1,336 @@
+/**
+ * @fileoverview QuorumStateMachine implementation.
+ *
+ * Central coordinator for the quorum system. Manages operational mode,
+ * epoch lifecycle, proposal/vote orchestration, and delegates to
+ * SealingService for cryptographic operations.
+ *
+ * @see Requirements 1-8, 10-13
+ */
+import { Member, PlatformID, ShortHexGuid } from '@digitaldefiance/ecies-lib';
+import { QuorumOperationalMode } from '../enumerations/quorumOperationalMode';
+import { IGossipService } from '../interfaces/availability/gossipService';
+import { Proposal, ProposalInput } from '../interfaces/proposal';
+import { QuorumEpoch } from '../interfaces/quorumEpoch';
+import { QuorumMetrics } from '../interfaces/quorumMetrics';
+import { IQuorumDatabase } from '../interfaces/services/quorumDatabase';
+import { QuorumMemberMetadata, SealedDocumentResult } from '../interfaces/services/quorumService';
+import { IQuorumStateMachine } from '../interfaces/services/quorumStateMachine';
+import { RedistributionConfig } from '../interfaces/services/redistributionConfig';
+import { VoteInput } from '../interfaces/vote';
+import { AliasRegistry } from './aliasRegistry';
+import { AuditLogService } from './auditLogService';
+import { SealingService } from './sealing.service';
+/**
+ * QuorumStateMachine is the central coordinator for the quorum system.
+ *
+ * It manages:
+ * - Operational mode (Bootstrap / Quorum / TransitionInProgress)
+ * - Epoch lifecycle
+ * - Document sealing/unsealing with mode-aware delegation
+ * - Metrics collection
+ *
+ * @template TID - Platform ID type for frontend/backend DTO compatibility
+ */
+export declare class QuorumStateMachine<TID extends PlatformID = Uint8Array> implements IQuorumStateMachine<TID> {
+    private readonly db;
+    private readonly sealingService;
+    private readonly gossipService;
+    private readonly auditLogService?;
+    private readonly aliasRegistry?;
+    private mode;
+    private currentEpochData;
+    private configuredThreshold;
+    private initialized;
+    private readonly checksumService;
+    private metricsData;
+    constructor(db: IQuorumDatabase<TID>, sealingService: SealingService<TID>, gossipService: IGossipService, auditLogService?: AuditLogService<TID> | undefined, aliasRegistry?: AliasRegistry<TID> | undefined);
+    /**
+     * Initialize the quorum system.
+     *
+     * - Checks for persisted operational state first (restore on restart).
+     * - If TransitionInProgress is detected, triggers rollback recovery.
+     * - Otherwise, determines mode based on member count vs threshold.
+     * - Persists the operational state and creates epoch 1.
+     */
+    initialize(members: Member<TID>[], threshold: number): Promise<QuorumEpoch<TID>>;
+    /**
+     * Rollback a transition that was interrupted (crash recovery or failure).
+     *
+     * For each journal entry, restores the document's old shares, member IDs,
+     * and threshold from the journal. Then deletes all journal entries and
+     * resets operational state to Bootstrap mode.
+     *
+     * @param epochNumber - The epoch number to rollback
+     * @param emitAudit - Whether to emit a transition_ceremony_failed audit entry (false during crash recovery in initialize)
+     */
+    private rollbackTransition;
+    /** Ensure the state machine is initialized before operations. */
+    private ensureInitialized;
+    /** Ensure operations are not blocked by a transition ceremony. */
+    private ensureNotTransitioning;
+    /**
+     * Create the next epoch with incremented epoch number.
+     *
+     * 1. Gets the current epoch number
+     * 2. Creates a new epoch with epochNumber = current + 1
+     * 3. Saves the epoch to the database
+     * 4. Updates the operational state with the new epoch number
+     * 5. Updates the cached currentEpochData
+     * 6. Returns the new epoch
+     *
+     * @param memberIds - Active member IDs for the new epoch
+     * @param threshold - Threshold for the new epoch
+     * @param mode - Operational mode for the new epoch
+     * @param previousEpochNumber - Optional override for the previous epoch number
+     * @returns The newly created QuorumEpoch
+     */
+    private createNextEpoch;
+    /**
+     * Emit an audit log entry.
+     *
+     * If an AuditLogService is configured, routes through it for chain linking
+     * and signing. Otherwise, writes directly to the database.
+     *
+     * @param eventType - The type of audit event
+     * @param details - Additional event-specific details
+     * @param targetMemberId - Optional target member ID
+     */
+    private emitAuditEntry;
+    /**
+     * Resolve IQuorumMember records into Member objects suitable for SealingService.
+     *
+     * Creates Member instances with only public keys (no private keys) from
+     * the database member records. These are sufficient for encrypting new shares.
+     *
+     * @param quorumMembers - Database member records to resolve
+     * @returns Array of Member objects with public keys
+     */
+    private resolveMembersFromRecords;
+    /**
+     * Perform batched share redistribution for all documents in a given epoch.
+     *
+     * Processes documents in pages using `listDocumentsByEpoch`, decrypts shares
+     * from threshold members, calls `redistributeShares`, updates documents,
+     * and saves them back to the database.
+     *
+     * @param fromEpochNumber - The epoch whose documents need redistribution
+     * @param thresholdMembers - Members with private keys to decrypt existing shares
+     * @param newMembers - The new member set for re-encryption
+     * @param newThreshold - The new threshold for shares
+     * @param oldSharingConfig - The old sharing configuration (totalShares, threshold)
+     * @param config - Redistribution configuration (batch size, progress, continue-on-failure)
+     * @returns Array of failed document IDs
+     */
+    private redistributeDocuments;
+    /**
+     * Get the current operational mode.
+     * Restores from persisted state on first call if needed.
+     */
+    getMode(): Promise<QuorumOperationalMode>;
+    /**
+     * Initiate a transition ceremony from Bootstrap to Quorum mode.
+     *
+     * Flow:
+     * 1. Verify members >= threshold, set mode to TransitionInProgress
+     * 2. Emit transition_ceremony_started audit entry
+     * 3. Block seal/unseal/submitProposal (via ensureNotTransitioning)
+     * 4. For each bootstrap-sealed document (paginated):
+     *    a. Save journal entry with old shares/members/threshold/epoch
+     *    b. Redistribute shares to full member set with configured threshold
+     *    c. Update document in database
+     * 5. On success: create new epoch in Quorum mode, delete journal entries,
+     *    emit transition_ceremony_completed, unblock
+     * 6. On failure: rollback from journal, reset to Bootstrap, delete journal
+     *    entries, emit transition_ceremony_failed
+     */
+    initiateTransition(): Promise<void>;
+    /**
+     * Create a new epoch for a completed transition ceremony.
+     *
+     * Called by the transition ceremony logic (Task 10) when all documents
+     * have been successfully re-split. Creates a new epoch in Quorum mode
+     * with the full member set and configured threshold.
+     *
+     * @param memberIds - The full member set after transition
+     * @param threshold - The configured quorum threshold
+     * @returns The new QuorumEpoch in Quorum mode
+     */
+    createTransitionEpoch(memberIds: ShortHexGuid[], threshold: number): Promise<QuorumEpoch<TID>>;
+    /**
+     * Add a new member to the quorum.
+     *
+     * Saves the member, increments the epoch, triggers batched share
+     * redistribution for all documents in the previous epoch, and emits
+     * audit entries for member_added and share_redistribution_*.
+     *
+     * @param member - The member to add
+     * @param metadata - Metadata for the member
+     * @param redistributionConfig - Optional redistribution configuration
+     * @returns The new QuorumEpoch after member addition
+     */
+    addMember(member: Member<TID>, metadata: QuorumMemberMetadata, redistributionConfig?: Partial<RedistributionConfig>): Promise<QuorumEpoch<TID>>;
+    /**
+     * Remove a member from the quorum.
+     *
+     * Validates remaining count >= threshold, removes the member,
+     * increments the epoch, triggers share redistribution with fresh
+     * polynomial coefficients, and emits audit entries for member_removed
+     * and share_redistribution_*.
+     *
+     * @param memberId - ID of the member to remove
+     * @param redistributionConfig - Optional redistribution configuration
+     * @returns The new QuorumEpoch after member removal
+     * @throws QuorumError with InsufficientRemainingMembers if removal would drop below threshold
+     * @throws QuorumError with MemberNotFound if the member is not in the current epoch
+     */
+    removeMember(memberId: ShortHexGuid, redistributionConfig?: Partial<RedistributionConfig>): Promise<QuorumEpoch<TID>>;
+    /**
+     * Maximum allowed description length for proposals.
+     */
+    private static readonly MAX_DESCRIPTION_LENGTH;
+    /**
+     * Member count threshold above which inner quorum routing is used.
+     */
+    private static readonly INNER_QUORUM_MEMBER_THRESHOLD;
+    /**
+     * Action types considered routine for inner quorum routing.
+     * When member count > 20 and an inner quorum exists, these use the inner quorum threshold.
+     */
+    private static readonly ROUTINE_ACTION_TYPES;
+    /**
+     * Determine the required threshold for a proposal based on inner quorum routing.
+     *
+     * When member count > 20 and the current epoch has innerQuorumMemberIds,
+     * routine operations use the inner quorum size as threshold,
+     * while critical operations use the full membership threshold.
+     *
+     * @param actionType - The proposal action type
+     * @returns The required vote threshold
+     */
+    private getRequiredThreshold;
+    /**
+     * Submit a proposal for quorum voting.
+     *
+     * Validates the proposer is an active member, validates description length,
+     * validates IDENTITY_DISCLOSURE has an attachment, assigns a unique ID,
+     * stores as pending, announces via gossip, and emits audit entry.
+     *
+     * @param proposal - The proposal input
+     * @returns The created Proposal with assigned ID and status
+     * @throws QuorumError with MissingAttachment if IDENTITY_DISCLOSURE lacks attachmentCblId
+     */
+    submitProposal(proposal: ProposalInput<TID>): Promise<Proposal<TID>>;
+    /**
+     * Submit a vote on a pending proposal.
+     *
+     * Validates the proposal exists and is pending, validates the voter is an
+     * active member, checks for duplicate votes, stores the vote, announces
+     * via gossip, emits audit entry, and triggers vote tallying.
+     *
+     * @param vote - The vote input
+     * @throws QuorumError with ProposalExpired if proposal is not pending
+     * @throws QuorumError with DuplicateVote if voter already voted
+     * @throws QuorumError with VoterNotOnProposal if voter is not an active member
+     */
+    submitVote(vote: VoteInput<TID>): Promise<void>;
+    /**
+     * Tally votes for a proposal.
+     *
+     * Counts approve and reject votes. If approve count >= threshold, marks
+     * the proposal as approved and dispatches the action. If reject count
+     * makes approval impossible, marks the proposal as rejected.
+     *
+     * @param proposal - The proposal to tally votes for
+     */
+    private tallyVotes;
+    /**
+     * Mark a proposal as expired and emit audit entry.
+     *
+     * @param proposal - The proposal to expire
+     */
+    private expireProposal;
+    /**
+     * Execute the action associated with an approved proposal.
+     *
+     * Dispatches to the appropriate handler based on ProposalActionType.
+     * Simple actions are fully implemented; complex ones are stubs that log.
+     *
+     * @param proposal - The approved proposal whose action to execute
+     */
+    private executeProposalAction;
+    /**
+     * 11.8.1 ADD_MEMBER — stub that calls addMember with payload data.
+     */
+    private executeAddMember;
+    /**
+     * 11.8.2 REMOVE_MEMBER — stub that calls removeMember with payload data.
+     */
+    private executeRemoveMember;
+    /**
+     * 11.8.3 CHANGE_THRESHOLD — update threshold and trigger share redistribution.
+     */
+    private executeChangeThreshold;
+    /**
+     * 11.8.5 UNSEAL_DOCUMENT — stub (collect shares, unseal).
+     */
+    private executeUnsealDocument;
+    /**
+     * 11.8.6 IDENTITY_DISCLOSURE — check statute of limitations, reject if expired/deleted.
+     *
+     * When the target IdentityRecoveryRecord has expired or been deleted by the
+     * expiration scheduler, throws IdentityPermanentlyUnrecoverable (Req 17.6).
+     */
+    private executeIdentityDisclosure;
+    /**
+     * 11.8.7 REGISTER_ALIAS — delegate to AliasRegistry.registerAlias().
+     */
+    private executeRegisterAlias;
+    /**
+     * 11.8.8 DEREGISTER_ALIAS — delegate to AliasRegistry.deregisterAlias().
+     */
+    private executeDeregisterAlias;
+    /**
+     * 11.8.9 EXTEND_STATUTE — update expiresAt on the target IdentityRecoveryRecord.
+     */
+    private executeExtendStatute;
+    /**
+     * 11.8.10 CHANGE_INNER_QUORUM — update innerQuorumMemberIds on current epoch.
+     */
+    private executeChangeInnerQuorum;
+    /**
+     * 11.8.11 CUSTOM — log approval without automated execution.
+     */
+    private executeCustomAction;
+    /**
+     * Get a proposal by its ID.
+     */
+    getProposal(proposalId: ShortHexGuid): Promise<Proposal<TID> | null>;
+    /**
+     * Seal a document using the appropriate mode (bootstrap or quorum).
+     *
+     * In bootstrap mode: delegates to quorumSealBootstrap with effective threshold = member count.
+     * In quorum mode: delegates to quorumSeal with configured threshold.
+     * Tags document with epoch number and sealedUnderBootstrap flag.
+     *
+     * @throws QuorumError with TransitionInProgress if a transition ceremony is active
+     */
+    sealDocument<T>(agent: Member<TID>, document: T, memberIds: ShortHexGuid[], sharesRequired?: number): Promise<SealedDocumentResult<TID>>;
+    /**
+     * Unseal a document.
+     *
+     * Verifies checksum (SHA-3) and creator signature using constant-time
+     * comparison before delegating to SealingService.
+     * Returns generic error on failure without revealing which check failed (Req 8.4-8.6).
+     */
+    unsealDocument<T>(documentId: ShortHexGuid, membersWithPrivateKey: Member<TID>[]): Promise<T>;
+    /** Get the current epoch. */
+    getCurrentEpoch(): Promise<QuorumEpoch<TID>>;
+    /** Get a specific epoch by number. */
+    getEpoch(epochNumber: number): Promise<QuorumEpoch<TID> | null>;
+    /** Get quorum system metrics for monitoring. */
+    getMetrics(): Promise<QuorumMetrics>;
+    /** Get the configured threshold for this quorum. */
+    getConfiguredThreshold(): number;
+}
+//# sourceMappingURL=quorumStateMachine.d.ts.map

package/src/lib/services/quorumStateMachine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quorumStateMachine.d.ts","sourceRoot":"","sources":["../../../../../brightchain-lib/src/lib/services/quorumStateMachine.ts"],"names":[],"mappings":"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"}