@brightchain/brightchain-lib 0.13.0 → 0.15.0

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

@@ -0,0 +1,179 @@
+/**
+ * MemberIdentityProofService — companion service for managing identity proofs
+ * associated with BrightChain members.
+ *
+ * Since {@link Member} is an external class from `@digitaldefiance/ecies-lib`,
+ * this service follows the same companion-service pattern as
+ * {@link MemberPaperKeyService}: it maintains an in-memory store of identity
+ * proofs keyed by member ID, with full audit logging.
+ *
+ * Requirements: 4.5, 4.7
+ */
+import { VerificationStatus } from '../../enumerations/verificationStatus';
+import { IIdentityProof } from '../../interfaces/identity/identityProof';
+/**
+ * Error thrown when a proof operation references a proof that does not exist.
+ */
+export declare class ProofNotFoundError extends Error {
+    constructor(proofId: string);
+}
+/**
+ * Error thrown when attempting to revoke an already-revoked proof.
+ */
+export declare class ProofAlreadyRevokedError extends Error {
+    constructor(proofId: string);
+}
+/**
+ * Actions that can be recorded in the identity proof audit log.
+ */
+export type ProofAuditAction = 'added' | 'revoked' | 'verified' | 'failed';
+/**
+ * A single entry in the identity proof audit log.
+ *
+ * @remarks
+ * The audit log is append-only and provides a complete history of
+ * proof lifecycle events for a member.
+ */
+export interface IProofAuditEntry<TId = string> {
+    /** Unique identifier for this audit entry */
+    id: TId;
+    /** The proof this entry relates to */
+    proofId: TId;
+    /** The action that was performed */
+    action: ProofAuditAction;
+    /** When the action occurred */
+    timestamp: Date;
+    /** Optional reason or context for the action */
+    reason?: string;
+}
+/**
+ * Companion service for managing identity proofs associated with members.
+ *
+ * Maintains an in-memory store of identity proofs keyed by member ID,
+ * with full audit logging. Provides methods to add, revoke, and query
+ * proofs without modifying the external Member class.
+ *
+ * @example
+ * ```typescript
+ * const service = new MemberIdentityProofService();
+ *
+ * // Add a proof
+ * service.addProof(memberId, proof);
+ *
+ * // Get all verified proofs
+ * const verified = service.getVerifiedProofs(memberId);
+ *
+ * // Revoke a proof
+ * service.revokeProof(memberId, proofId, 'Account compromised');
+ * ```
+ */
+export declare class MemberIdentityProofService<TId = string> {
+    /**
+     * Identity proofs keyed by member ID.
+     */
+    private readonly proofsByMember;
+    /**
+     * Append-only audit log keyed by member ID.
+     */
+    private readonly auditLogByMember;
+    /**
+     * Factory for generating unique IDs.
+     */
+    private readonly idFactory;
+    constructor(idFactory?: () => TId);
+    /**
+     * Add an identity proof for a member.
+     *
+     * Stores the proof and appends an 'added' entry to the audit log.
+     *
+     * **Validates: Requirement 4.5**
+     *
+     * @param memberId - The member this proof belongs to
+     * @param proof    - The identity proof to add
+     */
+    addProof(memberId: TId, proof: IIdentityProof<TId>): void;
+    /**
+     * Revoke an identity proof.
+     *
+     * Sets the proof's verification status to REVOKED and records
+     * a revokedAt timestamp. Appends a 'revoked' entry to the audit log.
+     *
+     * **Validates: Requirement 4.7**
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to revoke
+     * @param reason   - Optional reason for revocation
+     * @throws {ProofNotFoundError} If the proof does not exist
+     * @throws {ProofAlreadyRevokedError} If the proof is already revoked
+     */
+    revokeProof(memberId: TId, proofId: TId, reason?: string): void;
+    /**
+     * Update the verification status of a proof.
+     *
+     * Used after checking a proof URL to record whether verification
+     * succeeded or failed.
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to update
+     * @param verified - Whether verification succeeded
+     */
+    updateVerificationStatus(memberId: TId, proofId: TId, verified: boolean): void;
+    /**
+     * Get all identity proofs for a member.
+     *
+     * @param memberId - The member to query
+     * @returns Read-only array of identity proofs (empty if none exist)
+     */
+    getProofs(memberId: TId): ReadonlyArray<IIdentityProof<TId>>;
+    /**
+     * Get only verified identity proofs for a member.
+     *
+     * **Validates: Requirement 4.5**
+     *
+     * @param memberId - The member to query
+     * @returns Read-only array of verified identity proofs
+     */
+    getVerifiedProofs(memberId: TId): ReadonlyArray<IIdentityProof<TId>>;
+    /**
+     * Get a specific proof by ID.
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to retrieve
+     * @returns The identity proof
+     * @throws {ProofNotFoundError} If the proof does not exist
+     */
+    getProof(memberId: TId, proofId: TId): IIdentityProof<TId>;
+    /**
+     * Get the audit log for a member's identity proofs.
+     *
+     * @param memberId - The member to query
+     * @returns Read-only array of audit entries (empty if none exist)
+     */
+    getAuditLog(memberId: TId): ReadonlyArray<IProofAuditEntry<TId>>;
+    /**
+     * Check whether a proof is revoked.
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to check
+     * @returns `true` if the proof is revoked
+     * @throws {ProofNotFoundError} If the proof does not exist
+     */
+    isRevoked(memberId: TId, proofId: TId): boolean;
+    /**
+     * Get the count of proofs for a member, optionally filtered by status.
+     *
+     * @param memberId - The member to query
+     * @param status   - Optional status filter
+     * @returns The number of matching proofs
+     */
+    getProofCount(memberId: TId, status?: VerificationStatus): number;
+    /**
+     * Remove all data for a member. Useful for testing.
+     *
+     * @param memberId - The member whose data to clear
+     */
+    clearMemberData(memberId: TId): void;
+    private findProof;
+    private appendAuditEntry;
+}
+//# sourceMappingURL=memberIdentityProofService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memberIdentityProofService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/memberIdentityProofService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,uCAAuC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAIzE;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,EAAE,MAAM;CAI5B;AAID;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG,OAAO,GAAG,SAAS,GAAG,UAAU,GAAG,QAAQ,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB,CAAC,GAAG,GAAG,MAAM;IAC5C,6CAA6C;IAC7C,EAAE,EAAE,GAAG,CAAC;IAER,sCAAsC;IACtC,OAAO,EAAE,GAAG,CAAC;IAEb,oCAAoC;IACpC,MAAM,EAAE,gBAAgB,CAAC;IAEzB,+BAA+B;IAC/B,SAAS,EAAE,IAAI,CAAC;IAEhB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,0BAA0B,CAAC,GAAG,GAAG,MAAM;IAClD;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAyC;IAExE;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA2C;IAE5E;;OAEG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,SAAS,CAAC,EAAE,MAAM,GAAG;IAIjC;;;;;;;;;OASG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,KAAK,EAAE,cAAc,CAAC,GAAG,CAAC,GAAG,IAAI;IAQzD;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAa/D;;;;;;;;;OASG;IACH,wBAAwB,CACtB,QAAQ,EAAE,GAAG,EACb,OAAO,EAAE,GAAG,EACZ,QAAQ,EAAE,OAAO,GAChB,IAAI;IAmBP;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IAI5D;;;;;;;OAOG;IACH,iBAAiB,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,cAAc,CAAC,GAAG,CAAC,CAAC;IAOpE;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,GAAG,cAAc,CAAC,GAAG,CAAC;IAI1D;;;;;OAKG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;IAIhE;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,GAAG,OAAO;IAK/C;;;;;;OAMG;IACH,aAAa,CAAC,QAAQ,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,kBAAkB,GAAG,MAAM;IAMjE;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI;IAOpC,OAAO,CAAC,SAAS;IASjB,OAAO,CAAC,gBAAgB;CAgBzB"}

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

@@ -0,0 +1,232 @@
+"use strict";
+/**
+ * MemberIdentityProofService — companion service for managing identity proofs
+ * associated with BrightChain members.
+ *
+ * Since {@link Member} is an external class from `@digitaldefiance/ecies-lib`,
+ * this service follows the same companion-service pattern as
+ * {@link MemberPaperKeyService}: it maintains an in-memory store of identity
+ * proofs keyed by member ID, with full audit logging.
+ *
+ * Requirements: 4.5, 4.7
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemberIdentityProofService = exports.ProofAlreadyRevokedError = exports.ProofNotFoundError = void 0;
+const uuid_1 = require("uuid");
+const verificationStatus_1 = require("../../enumerations/verificationStatus");
+// ─── Error classes ──────────────────────────────────────────────────────────
+/**
+ * Error thrown when a proof operation references a proof that does not exist.
+ */
+class ProofNotFoundError extends Error {
+    constructor(proofId) {
+        super(`Identity proof not found: ${proofId}`);
+        this.name = 'ProofNotFoundError';
+    }
+}
+exports.ProofNotFoundError = ProofNotFoundError;
+/**
+ * Error thrown when attempting to revoke an already-revoked proof.
+ */
+class ProofAlreadyRevokedError extends Error {
+    constructor(proofId) {
+        super(`Identity proof already revoked: ${proofId}`);
+        this.name = 'ProofAlreadyRevokedError';
+    }
+}
+exports.ProofAlreadyRevokedError = ProofAlreadyRevokedError;
+// ─── Service ────────────────────────────────────────────────────────────────
+/**
+ * Companion service for managing identity proofs associated with members.
+ *
+ * Maintains an in-memory store of identity proofs keyed by member ID,
+ * with full audit logging. Provides methods to add, revoke, and query
+ * proofs without modifying the external Member class.
+ *
+ * @example
+ * ```typescript
+ * const service = new MemberIdentityProofService();
+ *
+ * // Add a proof
+ * service.addProof(memberId, proof);
+ *
+ * // Get all verified proofs
+ * const verified = service.getVerifiedProofs(memberId);
+ *
+ * // Revoke a proof
+ * service.revokeProof(memberId, proofId, 'Account compromised');
+ * ```
+ */
+class MemberIdentityProofService {
+    constructor(idFactory) {
+        /**
+         * Identity proofs keyed by member ID.
+         */
+        this.proofsByMember = new Map();
+        /**
+         * Append-only audit log keyed by member ID.
+         */
+        this.auditLogByMember = new Map();
+        this.idFactory = idFactory ?? (() => (0, uuid_1.v4)());
+    }
+    /**
+     * Add an identity proof for a member.
+     *
+     * Stores the proof and appends an 'added' entry to the audit log.
+     *
+     * **Validates: Requirement 4.5**
+     *
+     * @param memberId - The member this proof belongs to
+     * @param proof    - The identity proof to add
+     */
+    addProof(memberId, proof) {
+        const proofs = this.proofsByMember.get(memberId) ?? [];
+        proofs.push({ ...proof });
+        this.proofsByMember.set(memberId, proofs);
+        this.appendAuditEntry(memberId, proof.id, 'added');
+    }
+    /**
+     * Revoke an identity proof.
+     *
+     * Sets the proof's verification status to REVOKED and records
+     * a revokedAt timestamp. Appends a 'revoked' entry to the audit log.
+     *
+     * **Validates: Requirement 4.7**
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to revoke
+     * @param reason   - Optional reason for revocation
+     * @throws {ProofNotFoundError} If the proof does not exist
+     * @throws {ProofAlreadyRevokedError} If the proof is already revoked
+     */
+    revokeProof(memberId, proofId, reason) {
+        const proof = this.findProof(memberId, proofId);
+        if (proof.verificationStatus === verificationStatus_1.VerificationStatus.REVOKED) {
+            throw new ProofAlreadyRevokedError(String(proofId));
+        }
+        proof.verificationStatus = verificationStatus_1.VerificationStatus.REVOKED;
+        proof.revokedAt = new Date();
+        this.appendAuditEntry(memberId, proofId, 'revoked', reason);
+    }
+    /**
+     * Update the verification status of a proof.
+     *
+     * Used after checking a proof URL to record whether verification
+     * succeeded or failed.
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to update
+     * @param verified - Whether verification succeeded
+     */
+    updateVerificationStatus(memberId, proofId, verified) {
+        const proof = this.findProof(memberId, proofId);
+        if (proof.verificationStatus === verificationStatus_1.VerificationStatus.REVOKED) {
+            return; // Don't update revoked proofs
+        }
+        proof.verificationStatus = verified
+            ? verificationStatus_1.VerificationStatus.VERIFIED
+            : verificationStatus_1.VerificationStatus.FAILED;
+        proof.lastCheckedAt = new Date();
+        if (verified) {
+            proof.verifiedAt = new Date();
+        }
+        this.appendAuditEntry(memberId, proofId, verified ? 'verified' : 'failed');
+    }
+    /**
+     * Get all identity proofs for a member.
+     *
+     * @param memberId - The member to query
+     * @returns Read-only array of identity proofs (empty if none exist)
+     */
+    getProofs(memberId) {
+        return this.proofsByMember.get(memberId) ?? [];
+    }
+    /**
+     * Get only verified identity proofs for a member.
+     *
+     * **Validates: Requirement 4.5**
+     *
+     * @param memberId - The member to query
+     * @returns Read-only array of verified identity proofs
+     */
+    getVerifiedProofs(memberId) {
+        const proofs = this.proofsByMember.get(memberId) ?? [];
+        return proofs.filter((p) => p.verificationStatus === verificationStatus_1.VerificationStatus.VERIFIED);
+    }
+    /**
+     * Get a specific proof by ID.
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to retrieve
+     * @returns The identity proof
+     * @throws {ProofNotFoundError} If the proof does not exist
+     */
+    getProof(memberId, proofId) {
+        return this.findProof(memberId, proofId);
+    }
+    /**
+     * Get the audit log for a member's identity proofs.
+     *
+     * @param memberId - The member to query
+     * @returns Read-only array of audit entries (empty if none exist)
+     */
+    getAuditLog(memberId) {
+        return this.auditLogByMember.get(memberId) ?? [];
+    }
+    /**
+     * Check whether a proof is revoked.
+     *
+     * @param memberId - The member who owns the proof
+     * @param proofId  - The proof to check
+     * @returns `true` if the proof is revoked
+     * @throws {ProofNotFoundError} If the proof does not exist
+     */
+    isRevoked(memberId, proofId) {
+        const proof = this.findProof(memberId, proofId);
+        return proof.verificationStatus === verificationStatus_1.VerificationStatus.REVOKED;
+    }
+    /**
+     * Get the count of proofs for a member, optionally filtered by status.
+     *
+     * @param memberId - The member to query
+     * @param status   - Optional status filter
+     * @returns The number of matching proofs
+     */
+    getProofCount(memberId, status) {
+        const proofs = this.proofsByMember.get(memberId) ?? [];
+        if (!status)
+            return proofs.length;
+        return proofs.filter((p) => p.verificationStatus === status).length;
+    }
+    /**
+     * Remove all data for a member. Useful for testing.
+     *
+     * @param memberId - The member whose data to clear
+     */
+    clearMemberData(memberId) {
+        this.proofsByMember.delete(memberId);
+        this.auditLogByMember.delete(memberId);
+    }
+    // ─── Private helpers ────────────────────────────────────────────────
+    findProof(memberId, proofId) {
+        const proofs = this.proofsByMember.get(memberId) ?? [];
+        const proof = proofs.find((p) => p.id === proofId);
+        if (!proof) {
+            throw new ProofNotFoundError(String(proofId));
+        }
+        return proof;
+    }
+    appendAuditEntry(memberId, proofId, action, reason) {
+        const entries = this.auditLogByMember.get(memberId) ?? [];
+        entries.push({
+            id: this.idFactory(),
+            proofId,
+            action,
+            timestamp: new Date(),
+            reason,
+        });
+        this.auditLogByMember.set(memberId, entries);
+    }
+}
+exports.MemberIdentityProofService = MemberIdentityProofService;
+//# sourceMappingURL=memberIdentityProofService.js.map

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

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

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

@@ -0,0 +1,223 @@
+/**
+ * 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
+ */
+import { PaperKeyPurpose } from '../../enumerations/paperKeyPurpose';
+import { IPaperKeyMetadata } from '../../interfaces/identity/paperKey';
+/**
+ * Error thrown when a paper key operation references a key that does not exist.
+ */
+export declare class PaperKeyNotFoundError extends Error {
+    constructor(paperKeyId: string);
+}
+/**
+ * Error thrown when attempting to use or modify an already-revoked paper key.
+ */
+export declare class PaperKeyRevokedError extends Error {
+    constructor(paperKeyId: string);
+}
+/**
+ * Error thrown when attempting to mark an already-used paper key as used again.
+ */
+export declare class PaperKeyAlreadyUsedError extends Error {
+    constructor(paperKeyId: string);
+}
+/**
+ * Immutable audit log entry recorded for every paper key state change.
+ *
+ * @remarks
+ * Audit entries are append-only. They capture who performed the action,
+ * what changed, and when. This satisfies Requirement 1.7 (revocation
+ * with audit logging) and Requirement 1.9 (recovery event logging).
+ */
+export interface IPaperKeyAuditEntry<TId = string> {
+    /** Unique identifier for this audit entry */
+    id: string;
+    /** The paper key this entry relates to */
+    paperKeyId: TId;
+    /** The member who owns the paper key */
+    memberId: TId;
+    /** The action that was performed */
+    action: 'created' | 'used' | 'revoked';
+    /** When the action occurred */
+    timestamp: Date;
+    /** Optional reason for the action (e.g. revocation reason) */
+    reason?: string;
+    /** Optional device ID associated with the action */
+    deviceId?: TId;
+}
+/**
+ * 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);
+ * ```
+ */
+export declare class MemberPaperKeyService<TId = string> {
+    /**
+     * Paper key metadata keyed by member ID.
+     * Each member can have multiple paper keys.
+     */
+    private readonly paperKeysByMember;
+    /**
+     * Append-only audit log keyed by member ID.
+     * Satisfies Requirement 1.7 (audit logging) and 1.9 (recovery event logging).
+     */
+    private readonly auditLogByMember;
+    /**
+     * Factory for generating unique IDs.
+     * Defaults to UUID v4 cast to TId. Can be overridden for testing
+     * or when TId is not a string.
+     */
+    private readonly idFactory;
+    constructor(idFactory?: () => TId);
+    /**
+     * 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: TId, purpose: PaperKeyPurpose): IPaperKeyMetadata<TId>;
+    /**
+     * 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: TId, paperKeyId: TId, deviceId?: TId): void;
+    /**
+     * 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: TId, paperKeyId: TId, reason?: string): void;
+    /**
+     * 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: TId): ReadonlyArray<IPaperKeyMetadata<TId>>;
+    /**
+     * Get active (non-revoked) paper keys for a member.
+     *
+     * @param memberId - The member to query
+     * @returns Array of active paper key metadata
+     */
+    getActivePaperKeys(memberId: TId): ReadonlyArray<IPaperKeyMetadata<TId>>;
+    /**
+     * 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: TId, paperKeyId: TId): IPaperKeyMetadata<TId>;
+    /**
+     * 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: TId): ReadonlyArray<IPaperKeyAuditEntry<TId>>;
+    /**
+     * 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: TId, paperKeyId: TId): boolean;
+    /**
+     * 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: TId, paperKeyId: TId): boolean;
+    /**
+     * 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: TId): void;
+    /**
+     * Look up a paper key by member ID and paper key ID.
+     *
+     * @throws {PaperKeyNotFoundError} If not found
+     */
+    private findPaperKey;
+    /**
+     * Append an entry to the member's audit log.
+     */
+    private appendAuditEntry;
+}
+//# sourceMappingURL=memberPaperKeyService.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memberPaperKeyService.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-lib/src/lib/services/identity/memberPaperKeyService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AAEvE;;GAEG;AACH,qBAAa,qBAAsB,SAAQ,KAAK;gBAClC,UAAU,EAAE,MAAM;CAI/B;AAED;;GAEG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;gBACjC,UAAU,EAAE,MAAM;CAI/B;AAED;;GAEG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,UAAU,EAAE,MAAM;CAI/B;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB,CAAC,GAAG,GAAG,MAAM;IAC/C,6CAA6C;IAC7C,EAAE,EAAE,MAAM,CAAC;IAEX,0CAA0C;IAC1C,UAAU,EAAE,GAAG,CAAC;IAEhB,wCAAwC;IACxC,QAAQ,EAAE,GAAG,CAAC;IAEd,oCAAoC;IACpC,MAAM,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;IAEvC,+BAA+B;IAC/B,SAAS,EAAE,IAAI,CAAC;IAEhB,8DAA8D;IAC9D,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,qBAAqB,CAAC,GAAG,GAAG,MAAM;IAC7C;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA4C;IAE9E;;;OAGG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAG7B;IAEJ;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAY;gBAE1B,SAAS,CAAC,EAAE,MAAM,GAAG;IAIjC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,OAAO,EAAE,eAAe,GAAG,iBAAiB,CAAC,GAAG,CAAC;IAgB5E;;;;;;;;;;;;;;OAcG;IACH,gBAAgB,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI;IAmBtE;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;IAYrE;;;;;;;OAOG;IACH,YAAY,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAIlE;;;;;OAKG;IACH,kBAAkB,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC;IAIxE;;;;;;;OAOG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,GAAG,iBAAiB,CAAC,GAAG,CAAC;IAInE;;;;;;;;;OASG;IACH,WAAW,CAAC,QAAQ,EAAE,GAAG,GAAG,aAAa,CAAC,mBAAmB,CAAC,GAAG,CAAC,CAAC;IAInE;;;;;;;OAOG;IACH,SAAS,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO;IAIlD;;;;;;;OAOG;IACH,MAAM,CAAC,QAAQ,EAAE,GAAG,EAAE,UAAU,EAAE,GAAG,GAAG,OAAO;IAI/C;;;;;;OAMG;IACH,eAAe,CAAC,QAAQ,EAAE,GAAG,GAAG,IAAI;IAKpC;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAcpB;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAqBzB"}