@brightchain/brightchain-lib 0.14.0 → 0.16.0

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

@@ -0,0 +1,279 @@
+"use strict";
+/**
+ * Member Paper Key Service for the BrightChain identity system.
+ *
+ * Manages paper key metadata lifecycle for members. Since {@link Member}
+ * is an external class from `@digitaldefiance/ecies-lib` and cannot be
+ * modified directly, this service acts as a companion that tracks paper
+ * key metadata (creation, usage, revocation) keyed by member ID.
+ *
+ * Follows the same stateful-service pattern used by
+ * {@link ConversationService}, {@link PermissionService}, and other
+ * BrightChain services that manage in-memory state with `Map`s.
+ *
+ * Requirements: 1.5, 1.6, 1.7
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemberPaperKeyService = exports.PaperKeyAlreadyUsedError = exports.PaperKeyRevokedError = exports.PaperKeyNotFoundError = void 0;
+const uuid_1 = require("uuid");
+/**
+ * Error thrown when a paper key operation references a key that does not exist.
+ */
+class PaperKeyNotFoundError extends Error {
+    constructor(paperKeyId) {
+        super(`Paper key not found: ${paperKeyId}`);
+        this.name = 'PaperKeyNotFoundError';
+    }
+}
+exports.PaperKeyNotFoundError = PaperKeyNotFoundError;
+/**
+ * Error thrown when attempting to use or modify an already-revoked paper key.
+ */
+class PaperKeyRevokedError extends Error {
+    constructor(paperKeyId) {
+        super(`Paper key has been revoked: ${paperKeyId}`);
+        this.name = 'PaperKeyRevokedError';
+    }
+}
+exports.PaperKeyRevokedError = PaperKeyRevokedError;
+/**
+ * Error thrown when attempting to mark an already-used paper key as used again.
+ */
+class PaperKeyAlreadyUsedError extends Error {
+    constructor(paperKeyId) {
+        super(`Paper key has already been used: ${paperKeyId}`);
+        this.name = 'PaperKeyAlreadyUsedError';
+    }
+}
+exports.PaperKeyAlreadyUsedError = PaperKeyAlreadyUsedError;
+/**
+ * Service that manages paper key metadata for members.
+ *
+ * Since {@link Member} from `@digitaldefiance/ecies-lib` is an external
+ * class, this service provides the `addPaperKey()`, `markPaperKeyUsed()`,
+ * and `revokePaperKey()` operations specified in the task, tracking
+ * metadata externally keyed by member ID.
+ *
+ * The generic `TId` parameter follows the project convention of allowing
+ * `string` for frontend DTOs and `GuidV4Buffer` for backend usage.
+ *
+ * @example
+ * ```typescript
+ * const service = new MemberPaperKeyService();
+ *
+ * // Add a paper key for a member
+ * const metadata = service.addPaperKey(memberId, PaperKeyPurpose.BACKUP);
+ *
+ * // Mark it as used during device provisioning
+ * service.markPaperKeyUsed(memberId, metadata.id, 'device-abc');
+ *
+ * // Revoke it
+ * service.revokePaperKey(memberId, metadata.id, 'Compromised');
+ *
+ * // Query audit trail
+ * const auditLog = service.getAuditLog(memberId);
+ * ```
+ */
+class MemberPaperKeyService {
+    constructor(idFactory) {
+        /**
+         * Paper key metadata keyed by member ID.
+         * Each member can have multiple paper keys.
+         */
+        this.paperKeysByMember = new Map();
+        /**
+         * Append-only audit log keyed by member ID.
+         * Satisfies Requirement 1.7 (audit logging) and 1.9 (recovery event logging).
+         */
+        this.auditLogByMember = new Map();
+        this.idFactory = idFactory ?? (() => (0, uuid_1.v4)());
+    }
+    /**
+     * Register a new paper key for a member.
+     *
+     * Creates an {@link IPaperKeyMetadata} record and appends a 'created'
+     * entry to the audit log.
+     *
+     * **Validates: Requirement 1.5** — Track paper key metadata
+     *
+     * @param memberId - The member this paper key belongs to
+     * @param purpose  - The intended purpose of the paper key
+     * @returns The newly created paper key metadata
+     */
+    addPaperKey(memberId, purpose) {
+        const metadata = {
+            id: this.idFactory(),
+            createdAt: new Date(),
+            purpose,
+        };
+        const existing = this.paperKeysByMember.get(memberId) ?? [];
+        existing.push(metadata);
+        this.paperKeysByMember.set(memberId, existing);
+        this.appendAuditEntry(memberId, metadata.id, 'created');
+        return metadata;
+    }
+    /**
+     * Mark a paper key as used (e.g. after device provisioning).
+     *
+     * Sets the `usedAt` timestamp and optionally associates a device ID.
+     * A paper key can only be marked as used once and must not be revoked.
+     *
+     * **Validates: Requirement 1.6** — Mark paper keys as used after device provisioning
+     *
+     * @param memberId   - The member who owns the paper key
+     * @param paperKeyId - The paper key to mark as used
+     * @param deviceId   - Optional device ID that was provisioned
+     * @throws {PaperKeyNotFoundError} If the paper key does not exist for this member
+     * @throws {PaperKeyRevokedError} If the paper key has been revoked
+     * @throws {PaperKeyAlreadyUsedError} If the paper key has already been used
+     */
+    markPaperKeyUsed(memberId, paperKeyId, deviceId) {
+        const metadata = this.findPaperKey(memberId, paperKeyId);
+        if (metadata.revokedAt) {
+            throw new PaperKeyRevokedError(String(paperKeyId));
+        }
+        if (metadata.usedAt) {
+            throw new PaperKeyAlreadyUsedError(String(paperKeyId));
+        }
+        metadata.usedAt = new Date();
+        if (deviceId !== undefined) {
+            metadata.deviceId = deviceId;
+        }
+        this.appendAuditEntry(memberId, paperKeyId, 'used', undefined, deviceId);
+    }
+    /**
+     * Revoke a paper key with audit logging.
+     *
+     * Sets the `revokedAt` timestamp and records the revocation reason
+     * in the audit log. A revoked paper key cannot be used for recovery
+     * or device provisioning.
+     *
+     * **Validates: Requirement 1.7** — Support paper key revocation with audit logging
+     *
+     * @param memberId   - The member who owns the paper key
+     * @param paperKeyId - The paper key to revoke
+     * @param reason     - Human-readable reason for revocation
+     * @throws {PaperKeyNotFoundError} If the paper key does not exist for this member
+     * @throws {PaperKeyRevokedError} If the paper key has already been revoked
+     */
+    revokePaperKey(memberId, paperKeyId, reason) {
+        const metadata = this.findPaperKey(memberId, paperKeyId);
+        if (metadata.revokedAt) {
+            throw new PaperKeyRevokedError(String(paperKeyId));
+        }
+        metadata.revokedAt = new Date();
+        this.appendAuditEntry(memberId, paperKeyId, 'revoked', reason);
+    }
+    /**
+     * Get all paper key metadata for a member.
+     *
+     * Returns a shallow copy of the array to prevent external mutation.
+     *
+     * @param memberId - The member to query
+     * @returns Array of paper key metadata (empty if none registered)
+     */
+    getPaperKeys(memberId) {
+        return [...(this.paperKeysByMember.get(memberId) ?? [])];
+    }
+    /**
+     * Get active (non-revoked) paper keys for a member.
+     *
+     * @param memberId - The member to query
+     * @returns Array of active paper key metadata
+     */
+    getActivePaperKeys(memberId) {
+        return this.getPaperKeys(memberId).filter((pk) => !pk.revokedAt);
+    }
+    /**
+     * Get a single paper key by ID.
+     *
+     * @param memberId   - The member who owns the paper key
+     * @param paperKeyId - The paper key to retrieve
+     * @returns The paper key metadata
+     * @throws {PaperKeyNotFoundError} If the paper key does not exist
+     */
+    getPaperKey(memberId, paperKeyId) {
+        return this.findPaperKey(memberId, paperKeyId);
+    }
+    /**
+     * Get the full audit log for a member's paper keys.
+     *
+     * Returns a shallow copy of the array to prevent external mutation.
+     *
+     * **Validates: Requirement 1.7** — Audit logging
+     *
+     * @param memberId - The member to query
+     * @returns Array of audit entries (empty if none recorded)
+     */
+    getAuditLog(memberId) {
+        return [...(this.auditLogByMember.get(memberId) ?? [])];
+    }
+    /**
+     * Check whether a specific paper key is revoked.
+     *
+     * @param memberId   - The member who owns the paper key
+     * @param paperKeyId - The paper key to check
+     * @returns `true` if the paper key has been revoked
+     * @throws {PaperKeyNotFoundError} If the paper key does not exist
+     */
+    isRevoked(memberId, paperKeyId) {
+        return this.findPaperKey(memberId, paperKeyId).revokedAt !== undefined;
+    }
+    /**
+     * Check whether a specific paper key has been used.
+     *
+     * @param memberId   - The member who owns the paper key
+     * @param paperKeyId - The paper key to check
+     * @returns `true` if the paper key has been used
+     * @throws {PaperKeyNotFoundError} If the paper key does not exist
+     */
+    isUsed(memberId, paperKeyId) {
+        return this.findPaperKey(memberId, paperKeyId).usedAt !== undefined;
+    }
+    /**
+     * Remove all paper key data for a member.
+     *
+     * Useful for testing or when a member is deleted.
+     *
+     * @param memberId - The member whose data should be cleared
+     */
+    clearMemberData(memberId) {
+        this.paperKeysByMember.delete(memberId);
+        this.auditLogByMember.delete(memberId);
+    }
+    /**
+     * Look up a paper key by member ID and paper key ID.
+     *
+     * @throws {PaperKeyNotFoundError} If not found
+     */
+    findPaperKey(memberId, paperKeyId) {
+        const keys = this.paperKeysByMember.get(memberId);
+        if (!keys) {
+            throw new PaperKeyNotFoundError(String(paperKeyId));
+        }
+        const found = keys.find((pk) => pk.id === paperKeyId);
+        if (!found) {
+            throw new PaperKeyNotFoundError(String(paperKeyId));
+        }
+        return found;
+    }
+    /**
+     * Append an entry to the member's audit log.
+     */
+    appendAuditEntry(memberId, paperKeyId, action, reason, deviceId) {
+        const entry = {
+            id: (0, uuid_1.v4)(),
+            paperKeyId,
+            memberId,
+            action,
+            timestamp: new Date(),
+            reason,
+            deviceId,
+        };
+        const existing = this.auditLogByMember.get(memberId) ?? [];
+        existing.push(entry);
+        this.auditLogByMember.set(memberId, existing);
+    }
+}
+exports.MemberPaperKeyService = MemberPaperKeyService;
+//# sourceMappingURL=memberPaperKeyService.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memberPaperKeyService.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/memberPaperKeyService.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,+BAAoC;AAKpC;;GAEG;AACH,MAAa,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,UAAkB;QAC5B,KAAK,CAAC,wBAAwB,UAAU,EAAE,CAAC,CAAC;QAC5C,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AALD,sDAKC;AAED;;GAEG;AACH,MAAa,oBAAqB,SAAQ,KAAK;IAC7C,YAAY,UAAkB;QAC5B,KAAK,CAAC,+BAA+B,UAAU,EAAE,CAAC,CAAC;QACnD,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AALD,oDAKC;AAED;;GAEG;AACH,MAAa,wBAAyB,SAAQ,KAAK;IACjD,YAAY,UAAkB;QAC5B,KAAK,CAAC,oCAAoC,UAAU,EAAE,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AALD,4DAKC;AAiCD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAa,qBAAqB;IAuBhC,YAAY,SAAqB;QAtBjC;;;WAGG;QACc,sBAAiB,GAAG,IAAI,GAAG,EAAiC,CAAC;QAE9E;;;WAGG;QACc,qBAAgB,GAAG,IAAI,GAAG,EAGxC,CAAC;QAUF,IAAI,CAAC,SAAS,GAAG,SAAS,IAAI,CAAC,GAAG,EAAE,CAAC,IAAA,SAAM,GAAS,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAa,EAAE,OAAwB;QACjD,MAAM,QAAQ,GAA2B;YACvC,EAAE,EAAE,IAAI,CAAC,SAAS,EAAE;YACpB,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,OAAO;SACR,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC5D,QAAQ,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACxB,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;QAE/C,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;QAExD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,QAAa,EAAE,UAAe,EAAE,QAAc;QAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAEzD,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACrD,CAAC;QAED,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;YACpB,MAAM,IAAI,wBAAwB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,QAAQ,CAAC,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QAC7B,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;YAC3B,QAAQ,CAAC,QAAQ,GAAG,QAAQ,CAAC;QAC/B,CAAC;QAED,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC3E,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,QAAa,EAAE,UAAe,EAAE,MAAe;QAC5D,MAAM,QAAQ,GAAG,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;QAEzD,IAAI,QAAQ,CAAC,SAAS,EAAE,CAAC;YACvB,MAAM,IAAI,oBAAoB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACrD,CAAC;QAED,QAAQ,CAAC,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC;QAEhC,IAAI,CAAC,gBAAgB,CAAC,QAAQ,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAC;IACjE,CAAC;IAED;;;;;;;OAOG;IACH,YAAY,CAAC,QAAa;QACxB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC;IAED;;;;;OAKG;IACH,kBAAkB,CAAC,QAAa;QAC9B,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;IACnE,CAAC;IAED;;;;;;;OAOG;IACH,WAAW,CAAC,QAAa,EAAE,UAAe;QACxC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACjD,CAAC;IAED;;;;;;;;;OASG;IACH,WAAW,CAAC,QAAa;QACvB,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;OAOG;IACH,SAAS,CAAC,QAAa,EAAE,UAAe;QACtC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,SAAS,KAAK,SAAS,CAAC;IACzE,CAAC;IAED;;;;;;;OAOG;IACH,MAAM,CAAC,QAAa,EAAE,UAAe;QACnC,OAAO,IAAI,CAAC,YAAY,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC,MAAM,KAAK,SAAS,CAAC;IACtE,CAAC;IAED;;;;;;OAMG;IACH,eAAe,CAAC,QAAa;QAC3B,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACxC,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED;;;;OAIG;IACK,YAAY,CAAC,QAAa,EAAE,UAAe;QACjD,MAAM,IAAI,GAAG,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,CAAC;QAED,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,EAAE,KAAK,UAAU,CAAC,CAAC;QACtD,IAAI,CAAC,KAAK,EAAE,CAAC;YACX,MAAM,IAAI,qBAAqB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC;QACtD,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;OAEG;IACK,gBAAgB,CACtB,QAAa,EACb,UAAe,EACf,MAA0C,EAC1C,MAAe,EACf,QAAc;QAEd,MAAM,KAAK,GAA6B;YACtC,EAAE,EAAE,IAAA,SAAM,GAAE;YACZ,UAAU;YACV,QAAQ;YACR,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,MAAM;YACN,QAAQ;SACT,CAAC;QAEF,MAAM,QAAQ,GAAG,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,CAAC;QAC3D,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACrB,IAAI,CAAC,gBAAgB,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAChD,CAAC;CACF;AAnPD,sDAmPC"}

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

@@ -0,0 +1,106 @@
+/**
+ * Paper Key Service for the BrightChain identity system.
+ *
+ * Provides generation, validation, recovery, and template creation
+ * for 24-word BIP39 mnemonic paper keys. Paper keys serve as the
+ * primary mechanism for account backup, device provisioning, and
+ * account recovery.
+ *
+ * This service wraps the existing BIP39/ECIES infrastructure from
+ * {@link @digitaldefiance/ecies-lib} and exposes a focused API for
+ * paper key operations.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.8
+ */
+import { ECIESService, Member, PlatformID, SecureString } from '@digitaldefiance/ecies-lib';
+import { IPaperKeyTemplate } from '../../interfaces/identity/paperKey';
+/**
+ * Service for generating, validating, and recovering from BIP39 paper keys.
+ *
+ * All methods require an {@link ECIESService} instance, which is obtained
+ * from {@link ServiceProvider}. This keeps the service stateless and
+ * compatible with the existing dependency-injection pattern used
+ * throughout BrightChain.
+ *
+ * @example
+ * ```typescript
+ * const eciesService = ServiceProvider.getInstance().eciesService;
+ *
+ * // Generate a new paper key
+ * const paperKey = PaperKeyService.generatePaperKey(eciesService);
+ *
+ * // Validate it
+ * const isValid = PaperKeyService.validatePaperKey(paperKey, eciesService);
+ *
+ * // Recover a member from it
+ * const member = PaperKeyService.recoverFromPaperKey(paperKey, eciesService);
+ *
+ * // Generate a printable template
+ * const template = await PaperKeyService.generateTemplate(
+ *   paperKey,
+ *   member.id.toString(),
+ * );
+ * ```
+ */
+export declare class PaperKeyService {
+    /**
+     * Generate a new 24-word BIP39 mnemonic paper key (256-bit entropy).
+     *
+     * Uses the ECIESService's mnemonic generator which internally calls
+     * `@scure/bip39.generateMnemonic(wordlist, 256)`.
+     *
+     * **Validates: Requirement 1.1** — Generate 24-word BIP39 mnemonics
+     *
+     * @param eciesService - The ECIES service instance for key generation
+     * @returns A {@link SecureString} containing the 24-word mnemonic
+     */
+    static generatePaperKey<TID extends PlatformID = Uint8Array>(eciesService: ECIESService<TID>): SecureString;
+    /**
+     * Validate that a paper key is a well-formed BIP39 mnemonic.
+     *
+     * Checks both structural validity (24 words, valid BIP39 checksum)
+     * by attempting to derive a wallet from the mnemonic. If derivation
+     * succeeds the mnemonic is valid; if it throws, the mnemonic is invalid.
+     *
+     * **Validates: Requirement 1.2** — Validate paper key format using BIP39 validation
+     *
+     * @param paperKey - The mnemonic string to validate
+     * @param eciesService - The ECIES service instance for validation
+     * @returns `true` if the paper key is a valid 24-word BIP39 mnemonic, `false` otherwise
+     */
+    static validatePaperKey<TID extends PlatformID = Uint8Array>(paperKey: string, eciesService: ECIESService<TID>): boolean;
+    /**
+     * Recover a {@link Member} identity from a paper key mnemonic.
+     *
+     * Reconstructs the full member (with private key and wallet loaded)
+     * from the BIP39 mnemonic. The recovered member can immediately
+     * perform cryptographic operations (sign, encrypt, etc.).
+     *
+     * **Validates: Requirement 1.3** — Recover Member identity from a valid paper key
+     *
+     * @param paperKey - The 24-word BIP39 mnemonic
+     * @param eciesService - The ECIES service instance for key derivation
+     * @param name - Optional display name for the recovered member (default: 'Recovered User')
+     * @returns A fully-initialised {@link Member} with wallet and private key loaded
+     * @throws {Error} If the paper key is invalid or key derivation fails
+     */
+    static recoverFromPaperKey<TID extends PlatformID = Uint8Array>(paperKey: string, eciesService: ECIESService<TID>, name?: string): Member<TID>;
+    /**
+     * Generate a printable paper key template.
+     *
+     * Produces an {@link IPaperKeyTemplate} containing the mnemonic words,
+     * a QR code data URL for mobile scanning, creation timestamp,
+     * storage instructions, and security warnings.
+     *
+     * The QR code encodes the full mnemonic string and is generated
+     * using the `qrcode` library (same pattern as {@link TOTPEngine}).
+     *
+     * **Validates: Requirements 1.4, 1.8, 1.10** — Printable template with QR code and warnings
+     *
+     * @param paperKey - The 24-word BIP39 mnemonic to template
+     * @param memberId - The member ID to associate with the template
+     * @returns A promise resolving to the complete {@link IPaperKeyTemplate}
+     */
+    static generateTemplate(paperKey: string, memberId: string): Promise<IPaperKeyTemplate>;
+}
+//# sourceMappingURL=paperKeyService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paperKeyService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/paperKeyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EACL,YAAY,EACZ,MAAM,EACN,UAAU,EACV,YAAY,EACb,MAAM,4BAA4B,CAAC;AAGpC,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAyBvE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,eAAe;IAC1B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,EACzD,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,GAC9B,YAAY;IAIf;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,gBAAgB,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,EACzD,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,GAC9B,OAAO;IAkBV;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,mBAAmB,CAAC,GAAG,SAAS,UAAU,GAAG,UAAU,EAC5D,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,YAAY,CAAC,GAAG,CAAC,EAC/B,IAAI,CAAC,EAAE,MAAM,GACZ,MAAM,CAAC,GAAG,CAAC;IAUd;;;;;;;;;;;;;;;OAeG;WACU,gBAAgB,CAC3B,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,iBAAiB,CAAC;CAa9B"}

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

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * Paper Key Service for the BrightChain identity system.
+ *
+ * Provides generation, validation, recovery, and template creation
+ * for 24-word BIP39 mnemonic paper keys. Paper keys serve as the
+ * primary mechanism for account backup, device provisioning, and
+ * account recovery.
+ *
+ * This service wraps the existing BIP39/ECIES infrastructure from
+ * {@link @digitaldefiance/ecies-lib} and exposes a focused API for
+ * paper key operations.
+ *
+ * Requirements: 1.1, 1.2, 1.3, 1.4, 1.8
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaperKeyService = void 0;
+const ecies_lib_1 = require("@digitaldefiance/ecies-lib");
+const QRCode = require("qrcode");
+/**
+ * Default security warnings displayed on every paper key template.
+ *
+ * These warnings are mandated by Requirement 1.10 and must appear
+ * on every printed template.
+ */
+const PAPER_KEY_WARNINGS = [
+    'Anyone with this paper key can access your account',
+    'Do not store digitally or photograph',
+    'Consider splitting among trusted parties',
+];
+/**
+ * Default instructions for paper key storage.
+ */
+const PAPER_KEY_INSTRUCTIONS = 'Store this paper key in a secure location. You will need it to recover your account.';
+/**
+ * Expected word count for a 256-bit entropy BIP39 mnemonic.
+ */
+const PAPER_KEY_WORD_COUNT = 24;
+/**
+ * Service for generating, validating, and recovering from BIP39 paper keys.
+ *
+ * All methods require an {@link ECIESService} instance, which is obtained
+ * from {@link ServiceProvider}. This keeps the service stateless and
+ * compatible with the existing dependency-injection pattern used
+ * throughout BrightChain.
+ *
+ * @example
+ * ```typescript
+ * const eciesService = ServiceProvider.getInstance().eciesService;
+ *
+ * // Generate a new paper key
+ * const paperKey = PaperKeyService.generatePaperKey(eciesService);
+ *
+ * // Validate it
+ * const isValid = PaperKeyService.validatePaperKey(paperKey, eciesService);
+ *
+ * // Recover a member from it
+ * const member = PaperKeyService.recoverFromPaperKey(paperKey, eciesService);
+ *
+ * // Generate a printable template
+ * const template = await PaperKeyService.generateTemplate(
+ *   paperKey,
+ *   member.id.toString(),
+ * );
+ * ```
+ */
+class PaperKeyService {
+    /**
+     * Generate a new 24-word BIP39 mnemonic paper key (256-bit entropy).
+     *
+     * Uses the ECIESService's mnemonic generator which internally calls
+     * `@scure/bip39.generateMnemonic(wordlist, 256)`.
+     *
+     * **Validates: Requirement 1.1** — Generate 24-word BIP39 mnemonics
+     *
+     * @param eciesService - The ECIES service instance for key generation
+     * @returns A {@link SecureString} containing the 24-word mnemonic
+     */
+    static generatePaperKey(eciesService) {
+        return eciesService.generateNewMnemonic();
+    }
+    /**
+     * Validate that a paper key is a well-formed BIP39 mnemonic.
+     *
+     * Checks both structural validity (24 words, valid BIP39 checksum)
+     * by attempting to derive a wallet from the mnemonic. If derivation
+     * succeeds the mnemonic is valid; if it throws, the mnemonic is invalid.
+     *
+     * **Validates: Requirement 1.2** — Validate paper key format using BIP39 validation
+     *
+     * @param paperKey - The mnemonic string to validate
+     * @param eciesService - The ECIES service instance for validation
+     * @returns `true` if the paper key is a valid 24-word BIP39 mnemonic, `false` otherwise
+     */
+    static validatePaperKey(paperKey, eciesService) {
+        // Quick structural check: must be exactly 24 words
+        const words = paperKey.trim().split(/\s+/);
+        if (words.length !== PAPER_KEY_WORD_COUNT) {
+            return false;
+        }
+        try {
+            // Attempt wallet derivation — this internally calls
+            // @scure/bip39.validateMnemonic and throws on invalid input
+            const secureString = new ecies_lib_1.SecureString(paperKey);
+            eciesService.walletAndSeedFromMnemonic(secureString);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Recover a {@link Member} identity from a paper key mnemonic.
+     *
+     * Reconstructs the full member (with private key and wallet loaded)
+     * from the BIP39 mnemonic. The recovered member can immediately
+     * perform cryptographic operations (sign, encrypt, etc.).
+     *
+     * **Validates: Requirement 1.3** — Recover Member identity from a valid paper key
+     *
+     * @param paperKey - The 24-word BIP39 mnemonic
+     * @param eciesService - The ECIES service instance for key derivation
+     * @param name - Optional display name for the recovered member (default: 'Recovered User')
+     * @returns A fully-initialised {@link Member} with wallet and private key loaded
+     * @throws {Error} If the paper key is invalid or key derivation fails
+     */
+    static recoverFromPaperKey(paperKey, eciesService, name) {
+        const secureString = new ecies_lib_1.SecureString(paperKey);
+        return ecies_lib_1.Member.fromMnemonic(secureString, eciesService, undefined, name ?? 'Recovered User');
+    }
+    /**
+     * Generate a printable paper key template.
+     *
+     * Produces an {@link IPaperKeyTemplate} containing the mnemonic words,
+     * a QR code data URL for mobile scanning, creation timestamp,
+     * storage instructions, and security warnings.
+     *
+     * The QR code encodes the full mnemonic string and is generated
+     * using the `qrcode` library (same pattern as {@link TOTPEngine}).
+     *
+     * **Validates: Requirements 1.4, 1.8, 1.10** — Printable template with QR code and warnings
+     *
+     * @param paperKey - The 24-word BIP39 mnemonic to template
+     * @param memberId - The member ID to associate with the template
+     * @returns A promise resolving to the complete {@link IPaperKeyTemplate}
+     */
+    static async generateTemplate(paperKey, memberId) {
+        const words = paperKey.trim().split(/\s+/);
+        const qrCode = await QRCode.toDataURL(paperKey);
+        return {
+            words,
+            qrCode,
+            createdAt: new Date(),
+            memberId,
+            instructions: PAPER_KEY_INSTRUCTIONS,
+            warnings: [...PAPER_KEY_WARNINGS],
+        };
+    }
+}
+exports.PaperKeyService = PaperKeyService;
+//# sourceMappingURL=paperKeyService.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"paperKeyService.js","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/paperKeyService.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AAEH,0DAKoC;AACpC,iCAAiC;AAIjC;;;;;GAKG;AACH,MAAM,kBAAkB,GAAsB;IAC5C,oDAAoD;IACpD,sCAAsC;IACtC,0CAA0C;CAClC,CAAC;AAEX;;GAEG;AACH,MAAM,sBAAsB,GAC1B,sFAAsF,CAAC;AAEzF;;GAEG;AACH,MAAM,oBAAoB,GAAG,EAAE,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAa,eAAe;IAC1B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,gBAAgB,CACrB,YAA+B;QAE/B,OAAO,YAAY,CAAC,mBAAmB,EAAE,CAAC;IAC5C,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,gBAAgB,CACrB,QAAgB,EAChB,YAA+B;QAE/B,mDAAmD;QACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3C,IAAI,KAAK,CAAC,MAAM,KAAK,oBAAoB,EAAE,CAAC;YAC1C,OAAO,KAAK,CAAC;QACf,CAAC;QAED,IAAI,CAAC;YACH,oDAAoD;YACpD,4DAA4D;YAC5D,MAAM,YAAY,GAAG,IAAI,wBAAY,CAAC,QAAQ,CAAC,CAAC;YAChD,YAAY,CAAC,yBAAyB,CAAC,YAAY,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,mBAAmB,CACxB,QAAgB,EAChB,YAA+B,EAC/B,IAAa;QAEb,MAAM,YAAY,GAAG,IAAI,wBAAY,CAAC,QAAQ,CAAC,CAAC;QAChD,OAAO,kBAAM,CAAC,YAAY,CACxB,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,IAAI,IAAI,gBAAgB,CACzB,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,KAAK,CAAC,gBAAgB,CAC3B,QAAgB,EAChB,QAAgB;QAEhB,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC3C,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC;QAEhD,OAAO;YACL,KAAK;YACL,MAAM;YACN,SAAS,EAAE,IAAI,IAAI,EAAE;YACrB,QAAQ;YACR,YAAY,EAAE,sBAAsB;YACpC,QAAQ,EAAE,CAAC,GAAG,kBAAkB,CAAC;SAClC,CAAC;IACJ,CAAC;CACF;AAjHD,0CAiHC"}