@brightchain/brightchain-lib 0.13.0 → 0.15.0

package/src/lib/services/identity/publicKeyDirectoryService.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Public Key Directory Service for the BrightChain identity system.
+ *
+ * Provides an in-memory searchable directory of member public profiles.
+ * Supports search by display name, social username, or member ID with
+ * relevance ranking, pagination, and platform filtering. Members may
+ * opt out of directory listing via privacy mode.
+ *
+ * Follows the same stateful-service pattern used by
+ * {@link MemberPaperKeyService}, {@link ConversationService}, and other
+ * BrightChain services that manage in-memory state with `Map`s.
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.6, 5.9
+ */
+import { ProofPlatform } from '../../enumerations/proofPlatform';
+import { IPublicProfile } from '../../interfaces/identity/publicProfile';
+/**
+ * Error thrown when a profile operation references a member that does not exist.
+ */
+export declare class ProfileNotFoundError extends Error {
+    constructor(memberId: string);
+}
+/**
+ * Error thrown when a profile update is missing required fields.
+ */
+export declare class InvalidProfileError extends Error {
+    constructor(message: string);
+}
+/**
+ * Options for controlling directory search behaviour.
+ *
+ * Supports pagination (Requirement 5.5) and platform filtering
+ * (Requirement 5.10).
+ */
+export interface ISearchOptions {
+    /** Maximum number of results to return. Defaults to 20. */
+    limit?: number;
+    /** Zero-based offset for pagination. Defaults to 0. */
+    offset?: number;
+    /**
+     * Filter results to only include profiles with a verified proof
+     * on the specified platform (Requirement 5.10).
+     */
+    platformFilter?: ProofPlatform;
+}
+/**
+ * A single search result with its relevance score.
+ *
+ * Requirement 5.3: Search results include relevance ranking.
+ */
+export interface ISearchResult {
+    /** The matched public profile */
+    profile: IPublicProfile;
+    /** Relevance score (higher is more relevant). Used for ranking. */
+    relevanceScore: number;
+}
+/**
+ * Paginated search response.
+ */
+export interface ISearchResponse {
+    /** The matched profiles, ordered by descending relevance score */
+    results: ISearchResult[];
+    /** Total number of matching profiles (before pagination) */
+    totalCount: number;
+    /** Whether there are more results beyond the current page */
+    hasMore: boolean;
+}
+/**
+ * In-memory public key directory for searching and managing member profiles.
+ *
+ * The directory stores {@link IPublicProfile} records keyed by member ID
+ * and provides full-text search across display names, social usernames,
+ * and member IDs with relevance-based ranking.
+ *
+ * Privacy mode (Requirement 5.6, 5.9): Profiles with `privacyMode: true`
+ * are excluded from search results but can still be accessed directly
+ * via {@link getProfile}.
+ *
+ * @example
+ * ```typescript
+ * const directory = new PublicKeyDirectoryService();
+ *
+ * // Add a profile
+ * directory.updateProfile({
+ *   memberId: 'member-xyz',
+ *   displayName: 'Alice',
+ *   publicKey: '04abcdef...',
+ *   identityProofs: [],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ *   privacyMode: false,
+ * });
+ *
+ * // Search for profiles
+ * const results = directory.search('Alice');
+ *
+ * // Toggle privacy mode
+ * directory.togglePrivacyMode('member-xyz');
+ * ```
+ */
+export declare class PublicKeyDirectoryService {
+    /**
+     * Profile storage keyed by member ID.
+     */
+    private readonly profiles;
+    /**
+     * Search the directory for profiles matching the given query.
+     *
+     * Searches across display names, social usernames from identity proofs,
+     * and member IDs. Results are ranked by relevance score (Requirement 5.3).
+     *
+     * Profiles in privacy mode are excluded from results (Requirement 5.9).
+     * Only verified identity proofs are considered for username matching
+     * (Requirement 5.4).
+     *
+     * **Validates: Requirements 5.2, 5.3, 5.5, 5.9, 5.10**
+     *
+     * @param query   - The search query string (case-insensitive)
+     * @param options - Optional search parameters (pagination, filtering)
+     * @returns Paginated search results ordered by descending relevance
+     */
+    search(query: string, options?: ISearchOptions): ISearchResponse;
+    /**
+     * Get a profile by member ID.
+     *
+     * Unlike {@link search}, this method returns profiles regardless of
+     * privacy mode. This allows existing contacts to look up a member
+     * directly even when the member has opted out of directory listing.
+     *
+     * **Validates: Requirements 5.1, 5.9**
+     *
+     * @param memberId - The member ID to look up
+     * @returns The public profile
+     * @throws {ProfileNotFoundError} If no profile exists for the member ID
+     */
+    getProfile(memberId: string): IPublicProfile;
+    /**
+     * Add or update a profile in the directory.
+     *
+     * If a profile already exists for the member ID, it is replaced.
+     * The `updatedAt` timestamp is set to the current time on update.
+     *
+     * **Validates: Requirements 5.1, 5.8**
+     *
+     * @param profile - The public profile to store
+     * @throws {InvalidProfileError} If required fields are missing
+     */
+    updateProfile(profile: IPublicProfile): void;
+    /**
+     * Toggle privacy mode for a member's profile.
+     *
+     * When privacy mode is enabled, the profile is excluded from search
+     * results (Requirement 5.9) but can still be accessed directly via
+     * {@link getProfile}.
+     *
+     * **Validates: Requirements 5.6, 5.9**
+     *
+     * @param memberId - The member whose privacy mode to toggle
+     * @returns The new privacy mode state (`true` = private, `false` = public)
+     * @throws {ProfileNotFoundError} If no profile exists for the member ID
+     */
+    togglePrivacyMode(memberId: string): boolean;
+    /**
+     * Get the total number of profiles in the directory.
+     */
+    get size(): number;
+    /**
+     * Check whether a profile exists for the given member ID.
+     */
+    hasProfile(memberId: string): boolean;
+    /**
+     * Remove a profile from the directory.
+     *
+     * @param memberId - The member whose profile to remove
+     * @returns `true` if a profile was removed, `false` if none existed
+     */
+    removeProfile(memberId: string): boolean;
+    /**
+     * Remove all profiles from the directory.
+     * Useful for testing.
+     */
+    clear(): void;
+    /**
+     * Calculate the relevance score for a profile against a search query.
+     *
+     * Scoring strategy (Requirement 5.3):
+     * - Exact member ID match: highest score
+     * - Exact display name match: high score
+     * - Display name prefix match: medium-high score
+     * - Exact social username match: high score
+     * - Social username prefix match: medium score
+     * - Substring matches: lower scores
+     * - Bonus for each verified identity proof
+     *
+     * Only verified proofs are considered for username matching
+     * (Requirement 5.4).
+     *
+     * @param profile         - The profile to score
+     * @param normalizedQuery - The lowercase, trimmed search query
+     * @returns The relevance score (0 means no match)
+     */
+    private calculateRelevanceScore;
+    /**
+     * Validate that a profile has all required fields.
+     *
+     * @throws {InvalidProfileError} If validation fails
+     */
+    private validateProfile;
+}
+//# sourceMappingURL=publicKeyDirectoryService.d.ts.map

package/src/lib/services/identity/publicKeyDirectoryService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"publicKeyDirectoryService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/publicKeyDirectoryService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAIzE;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,QAAQ,EAAE,MAAM;CAI7B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,EAAE,MAAM;CAI5B;AAID;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,2DAA2D;IAC3D,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf,uDAAuD;IACvD,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,cAAc,CAAC,EAAE,aAAa,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,OAAO,EAAE,cAAc,CAAC;IAExB,mEAAmE;IACnE,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,OAAO,EAAE,aAAa,EAAE,CAAC;IAEzB,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAC;IAEnB,6DAA6D;IAC7D,OAAO,EAAE,OAAO,CAAC;CAClB;AA8BD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,qBAAa,yBAAyB;IACpC;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAqC;IAE9D;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,eAAe;IAkDhE;;;;;;;;;;;;OAYG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,cAAc;IAQ5C;;;;;;;;;;OAUG;IACH,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI;IAiB5C;;;;;;;;;;;;OAYG;IACH,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAY5C;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIrC;;;;;OAKG;IACH,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO;IAIxC;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,uBAAuB;IAiD/B;;;;OAIG;IACH,OAAO,CAAC,eAAe;CAaxB"}

package/src/lib/services/identity/publicKeyDirectoryService.js

@@ -0,0 +1,328 @@
+"use strict";
+/**
+ * Public Key Directory Service for the BrightChain identity system.
+ *
+ * Provides an in-memory searchable directory of member public profiles.
+ * Supports search by display name, social username, or member ID with
+ * relevance ranking, pagination, and platform filtering. Members may
+ * opt out of directory listing via privacy mode.
+ *
+ * Follows the same stateful-service pattern used by
+ * {@link MemberPaperKeyService}, {@link ConversationService}, and other
+ * BrightChain services that manage in-memory state with `Map`s.
+ *
+ * Requirements: 5.1, 5.2, 5.3, 5.6, 5.9
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PublicKeyDirectoryService = exports.InvalidProfileError = exports.ProfileNotFoundError = void 0;
+const verificationStatus_1 = require("../../enumerations/verificationStatus");
+// ─── Error classes ──────────────────────────────────────────────────────────
+/**
+ * Error thrown when a profile operation references a member that does not exist.
+ */
+class ProfileNotFoundError extends Error {
+    constructor(memberId) {
+        super(`Profile not found for member: ${memberId}`);
+        this.name = 'ProfileNotFoundError';
+    }
+}
+exports.ProfileNotFoundError = ProfileNotFoundError;
+/**
+ * Error thrown when a profile update is missing required fields.
+ */
+class InvalidProfileError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidProfileError';
+    }
+}
+exports.InvalidProfileError = InvalidProfileError;
+// ─── Relevance scoring constants ────────────────────────────────────────────
+/** Score awarded for an exact member ID match */
+const SCORE_EXACT_MEMBER_ID = 100;
+/** Score awarded for an exact display name match (case-insensitive) */
+const SCORE_EXACT_DISPLAY_NAME = 80;
+/** Score awarded when the display name starts with the query */
+const SCORE_DISPLAY_NAME_PREFIX = 60;
+/** Score awarded when the display name contains the query */
+const SCORE_DISPLAY_NAME_CONTAINS = 40;
+/** Score awarded for an exact social username match */
+const SCORE_EXACT_USERNAME = 70;
+/** Score awarded when a social username starts with the query */
+const SCORE_USERNAME_PREFIX = 50;
+/** Score awarded when a social username contains the query */
+const SCORE_USERNAME_CONTAINS = 30;
+/** Bonus score per verified identity proof on the profile */
+const SCORE_VERIFIED_PROOF_BONUS = 5;
+// ─── Service ────────────────────────────────────────────────────────────────
+/**
+ * In-memory public key directory for searching and managing member profiles.
+ *
+ * The directory stores {@link IPublicProfile} records keyed by member ID
+ * and provides full-text search across display names, social usernames,
+ * and member IDs with relevance-based ranking.
+ *
+ * Privacy mode (Requirement 5.6, 5.9): Profiles with `privacyMode: true`
+ * are excluded from search results but can still be accessed directly
+ * via {@link getProfile}.
+ *
+ * @example
+ * ```typescript
+ * const directory = new PublicKeyDirectoryService();
+ *
+ * // Add a profile
+ * directory.updateProfile({
+ *   memberId: 'member-xyz',
+ *   displayName: 'Alice',
+ *   publicKey: '04abcdef...',
+ *   identityProofs: [],
+ *   createdAt: new Date(),
+ *   updatedAt: new Date(),
+ *   privacyMode: false,
+ * });
+ *
+ * // Search for profiles
+ * const results = directory.search('Alice');
+ *
+ * // Toggle privacy mode
+ * directory.togglePrivacyMode('member-xyz');
+ * ```
+ */
+class PublicKeyDirectoryService {
+    constructor() {
+        /**
+         * Profile storage keyed by member ID.
+         */
+        this.profiles = new Map();
+    }
+    /**
+     * Search the directory for profiles matching the given query.
+     *
+     * Searches across display names, social usernames from identity proofs,
+     * and member IDs. Results are ranked by relevance score (Requirement 5.3).
+     *
+     * Profiles in privacy mode are excluded from results (Requirement 5.9).
+     * Only verified identity proofs are considered for username matching
+     * (Requirement 5.4).
+     *
+     * **Validates: Requirements 5.2, 5.3, 5.5, 5.9, 5.10**
+     *
+     * @param query   - The search query string (case-insensitive)
+     * @param options - Optional search parameters (pagination, filtering)
+     * @returns Paginated search results ordered by descending relevance
+     */
+    search(query, options) {
+        const limit = options?.limit ?? 20;
+        const offset = options?.offset ?? 0;
+        const platformFilter = options?.platformFilter;
+        if (!query || query.trim().length === 0) {
+            return { results: [], totalCount: 0, hasMore: false };
+        }
+        const normalizedQuery = query.trim().toLowerCase();
+        const scoredResults = [];
+        for (const profile of this.profiles.values()) {
+            // Requirement 5.9: Skip profiles in privacy mode
+            if (profile.privacyMode) {
+                continue;
+            }
+            // Requirement 5.10: Apply platform filter
+            if (platformFilter) {
+                const hasVerifiedProofOnPlatform = profile.identityProofs.some((proof) => proof.platform === platformFilter &&
+                    proof.verificationStatus === verificationStatus_1.VerificationStatus.VERIFIED);
+                if (!hasVerifiedProofOnPlatform) {
+                    continue;
+                }
+            }
+            const score = this.calculateRelevanceScore(profile, normalizedQuery);
+            if (score > 0) {
+                scoredResults.push({ profile, relevanceScore: score });
+            }
+        }
+        // Requirement 5.3: Sort by relevance score descending
+        scoredResults.sort((a, b) => b.relevanceScore - a.relevanceScore);
+        const totalCount = scoredResults.length;
+        const paginatedResults = scoredResults.slice(offset, offset + limit);
+        const hasMore = offset + limit < totalCount;
+        return {
+            results: paginatedResults,
+            totalCount,
+            hasMore,
+        };
+    }
+    /**
+     * Get a profile by member ID.
+     *
+     * Unlike {@link search}, this method returns profiles regardless of
+     * privacy mode. This allows existing contacts to look up a member
+     * directly even when the member has opted out of directory listing.
+     *
+     * **Validates: Requirements 5.1, 5.9**
+     *
+     * @param memberId - The member ID to look up
+     * @returns The public profile
+     * @throws {ProfileNotFoundError} If no profile exists for the member ID
+     */
+    getProfile(memberId) {
+        const profile = this.profiles.get(memberId);
+        if (!profile) {
+            throw new ProfileNotFoundError(memberId);
+        }
+        return profile;
+    }
+    /**
+     * Add or update a profile in the directory.
+     *
+     * If a profile already exists for the member ID, it is replaced.
+     * The `updatedAt` timestamp is set to the current time on update.
+     *
+     * **Validates: Requirements 5.1, 5.8**
+     *
+     * @param profile - The public profile to store
+     * @throws {InvalidProfileError} If required fields are missing
+     */
+    updateProfile(profile) {
+        this.validateProfile(profile);
+        const existing = this.profiles.get(profile.memberId);
+        if (existing) {
+            // Preserve createdAt from the original profile
+            const updated = {
+                ...profile,
+                createdAt: existing.createdAt,
+                updatedAt: new Date(),
+            };
+            this.profiles.set(profile.memberId, updated);
+        }
+        else {
+            this.profiles.set(profile.memberId, { ...profile });
+        }
+    }
+    /**
+     * Toggle privacy mode for a member's profile.
+     *
+     * When privacy mode is enabled, the profile is excluded from search
+     * results (Requirement 5.9) but can still be accessed directly via
+     * {@link getProfile}.
+     *
+     * **Validates: Requirements 5.6, 5.9**
+     *
+     * @param memberId - The member whose privacy mode to toggle
+     * @returns The new privacy mode state (`true` = private, `false` = public)
+     * @throws {ProfileNotFoundError} If no profile exists for the member ID
+     */
+    togglePrivacyMode(memberId) {
+        const profile = this.profiles.get(memberId);
+        if (!profile) {
+            throw new ProfileNotFoundError(memberId);
+        }
+        profile.privacyMode = !profile.privacyMode;
+        profile.updatedAt = new Date();
+        return profile.privacyMode;
+    }
+    /**
+     * Get the total number of profiles in the directory.
+     */
+    get size() {
+        return this.profiles.size;
+    }
+    /**
+     * Check whether a profile exists for the given member ID.
+     */
+    hasProfile(memberId) {
+        return this.profiles.has(memberId);
+    }
+    /**
+     * Remove a profile from the directory.
+     *
+     * @param memberId - The member whose profile to remove
+     * @returns `true` if a profile was removed, `false` if none existed
+     */
+    removeProfile(memberId) {
+        return this.profiles.delete(memberId);
+    }
+    /**
+     * Remove all profiles from the directory.
+     * Useful for testing.
+     */
+    clear() {
+        this.profiles.clear();
+    }
+    /**
+     * Calculate the relevance score for a profile against a search query.
+     *
+     * Scoring strategy (Requirement 5.3):
+     * - Exact member ID match: highest score
+     * - Exact display name match: high score
+     * - Display name prefix match: medium-high score
+     * - Exact social username match: high score
+     * - Social username prefix match: medium score
+     * - Substring matches: lower scores
+     * - Bonus for each verified identity proof
+     *
+     * Only verified proofs are considered for username matching
+     * (Requirement 5.4).
+     *
+     * @param profile         - The profile to score
+     * @param normalizedQuery - The lowercase, trimmed search query
+     * @returns The relevance score (0 means no match)
+     */
+    calculateRelevanceScore(profile, normalizedQuery) {
+        let score = 0;
+        // Check member ID match
+        const normalizedMemberId = profile.memberId.toLowerCase();
+        if (normalizedMemberId === normalizedQuery) {
+            score = Math.max(score, SCORE_EXACT_MEMBER_ID);
+        }
+        else if (normalizedMemberId.includes(normalizedQuery)) {
+            // Partial member ID match gets a moderate score
+            score = Math.max(score, SCORE_DISPLAY_NAME_CONTAINS);
+        }
+        // Check display name match
+        const normalizedDisplayName = profile.displayName.toLowerCase();
+        if (normalizedDisplayName === normalizedQuery) {
+            score = Math.max(score, SCORE_EXACT_DISPLAY_NAME);
+        }
+        else if (normalizedDisplayName.startsWith(normalizedQuery)) {
+            score = Math.max(score, SCORE_DISPLAY_NAME_PREFIX);
+        }
+        else if (normalizedDisplayName.includes(normalizedQuery)) {
+            score = Math.max(score, SCORE_DISPLAY_NAME_CONTAINS);
+        }
+        // Check social usernames from verified proofs (Requirement 5.4)
+        const verifiedProofs = profile.identityProofs.filter((proof) => proof.verificationStatus === verificationStatus_1.VerificationStatus.VERIFIED);
+        for (const proof of verifiedProofs) {
+            const normalizedUsername = proof.username.toLowerCase();
+            if (normalizedUsername === normalizedQuery) {
+                score = Math.max(score, SCORE_EXACT_USERNAME);
+            }
+            else if (normalizedUsername.startsWith(normalizedQuery)) {
+                score = Math.max(score, SCORE_USERNAME_PREFIX);
+            }
+            else if (normalizedUsername.includes(normalizedQuery)) {
+                score = Math.max(score, SCORE_USERNAME_CONTAINS);
+            }
+        }
+        // Bonus for verified proofs (more verified = more trustworthy)
+        if (score > 0) {
+            score += verifiedProofs.length * SCORE_VERIFIED_PROOF_BONUS;
+        }
+        return score;
+    }
+    /**
+     * Validate that a profile has all required fields.
+     *
+     * @throws {InvalidProfileError} If validation fails
+     */
+    validateProfile(profile) {
+        if (!profile.memberId || profile.memberId.trim().length === 0) {
+            throw new InvalidProfileError('Profile must have a non-empty memberId');
+        }
+        if (!profile.displayName || profile.displayName.trim().length === 0) {
+            throw new InvalidProfileError('Profile must have a non-empty displayName');
+        }
+        if (!profile.publicKey || profile.publicKey.trim().length === 0) {
+            throw new InvalidProfileError('Profile must have a non-empty publicKey');
+        }
+    }
+}
+exports.PublicKeyDirectoryService = PublicKeyDirectoryService;
+//# sourceMappingURL=publicKeyDirectoryService.js.map

package/src/lib/services/identity/publicKeyDirectoryService.js.map

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

package/src/lib/services/identity/splitPaperKeyService.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Split Paper Key Service for the BrightChain identity system.
+ *
+ * Splits a 24-word BIP39 paper key into N Shamir's Secret Sharing
+ * shares with a configurable threshold T. Any T shares can reconstruct
+ * the original paper key; fewer than T shares reveal nothing.
+ *
+ * Each share is encoded as a human-readable word sequence using the
+ * BIP39 English wordlist as a dictionary (11 bits per word). Because
+ * Shamir shares include metadata (bit-width, share index) and internal
+ * padding, they are larger than the original 32-byte entropy, so they
+ * cannot be represented as standard BIP39 mnemonics. Instead, the
+ * service uses a raw 11-bit-per-word encoding that preserves the full
+ * share hex string for lossless round-trip reconstruction.
+ *
+ * Requirements: 2.1, 2.2, 2.3, 2.4, 2.7
+ */
+import { ISplitPaperKeyShare } from '../../interfaces/identity/splitPaperKey';
+/**
+ * Service for splitting and reconstructing BIP39 paper keys using
+ * Shamir's Secret Sharing.
+ *
+ * All methods are static — the service is stateless and safe to call
+ * from any context (browser or Node.js).
+ *
+ * @example
+ * ```typescript
+ * // Split a 24-word paper key into 5 shares, requiring 3 to reconstruct
+ * const shares = SplitPaperKeyService.split(paperKey, 5, 3);
+ *
+ * // Reconstruct from any 3 shares
+ * const recovered = SplitPaperKeyService.reconstruct(shares, 5);
+ *
+ * // Generate a printable template for share #1
+ * const template = await SplitPaperKeyService.generateShareTemplate(
+ *   shares[0], 1, 5, 3,
+ * );
+ * ```
+ */
+export declare class SplitPaperKeyService {
+    /**
+     * Split a 24-word BIP39 paper key into N Shamir shares.
+     *
+     * The paper key mnemonic is converted to its 32-byte entropy, then
+     * the entropy hex is split using Shamir's Secret Sharing. Each
+     * resulting share hex is encoded as human-readable words using the
+     * BIP39 wordlist (11 bits per word).
+     *
+     * **Validates: Requirements 2.1, 2.2, 2.3**
+     *
+     * @param paperKey - A valid 24-word BIP39 mnemonic
+     * @param shares  - Total number of shares to generate (2–1,048,575)
+     * @param threshold - Minimum shares needed to reconstruct (2–shares)
+     * @returns Array of word-encoded share strings (space-separated words)
+     * @throws {Error} If the paper key is invalid or parameters are out of range
+     */
+    static split(paperKey: string, shares: number, threshold: number): string[];
+    /**
+     * Reconstruct a paper key from T or more Shamir shares.
+     *
+     * The word-encoded shares are decoded back to hex, combined using
+     * Shamir's Secret Sharing, and the resulting entropy is converted
+     * back to a 24-word BIP39 mnemonic.
+     *
+     * **Validates: Requirement 2.4**
+     *
+     * @param shares - Array of word-encoded share strings (at least threshold count)
+     * @param totalShares - The total number of shares originally created
+     *                      (needed to re-initialise the secrets library with
+     *                      the correct Galois Field bit-width)
+     * @returns The original 24-word BIP39 paper key
+     * @throws {Error} If shares are invalid or reconstruction fails
+     */
+    static reconstruct(shares: string[], totalShares: number): string;
+    /**
+     * Generate a printable template for a single share.
+     *
+     * Produces an {@link ISplitPaperKeyShare} containing the share words,
+     * a QR code data URL for mobile scanning, and human-readable
+     * instructions with share number, total count, and threshold.
+     *
+     * **Validates: Requirement 2.7**
+     *
+     * @param share       - Space-separated word-encoded share string
+     * @param shareNumber - 1-based index of this share
+     * @param totalShares - Total number of shares created
+     * @param threshold   - Minimum shares needed to reconstruct
+     * @returns A promise resolving to the complete {@link ISplitPaperKeyShare}
+     */
+    static generateShareTemplate(share: string, shareNumber: number, totalShares: number, threshold: number): Promise<ISplitPaperKeyShare>;
+}
+//# sourceMappingURL=splitPaperKeyService.d.ts.map

package/src/lib/services/identity/splitPaperKeyService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"splitPaperKeyService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/splitPaperKeyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAaH,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAuL9E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,oBAAoB;IAC/B;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE;IA4B3E;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM;IAqDjE;;;;;;;;;;;;;;OAcG;WACU,qBAAqB,CAChC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,mBAAmB,CAAC;CAgBhC"}