@brightchain/brightchain-api-lib 0.2.1 → 0.6.0

package/src/lib/controllers/api/quorum.d.ts

@@ -0,0 +1,369 @@
+import { CanUnlockResult, QuorumDocumentInfo, QuorumMemberMetadata } from '@brightchain/brightchain-lib';
+import { CoreLanguageCode } from '@digitaldefiance/i18n-lib';
+import { PlatformID } from '@digitaldefiance/node-ecies-lib';
+import { ApiErrorResponse, ApiRequestHandler, IApiMessageResponse, TypedHandlers } from '@digitaldefiance/node-express-suite';
+import { IBrightChainApplication } from '../../interfaces/application';
+import { DefaultBackendIdType } from '../../shared-types';
+import { BaseController } from '../base';
+/**
+ * Error codes for quorum API operations
+ * @deprecated Use ErrorCode from '../../utils/errorResponse' instead
+ */
+export declare enum QuorumErrorCode {
+    MEMBER_NOT_FOUND = "MEMBER_NOT_FOUND",
+    DOCUMENT_NOT_FOUND = "DOCUMENT_NOT_FOUND",
+    INSUFFICIENT_SHARES = "INSUFFICIENT_SHARES",
+    SHARE_DECRYPTION_FAILED = "SHARE_DECRYPTION_FAILED",
+    INVALID_MEMBER_COUNT = "INVALID_MEMBER_COUNT",
+    INVALID_THRESHOLD = "INVALID_THRESHOLD",
+    VALIDATION_ERROR = "VALIDATION_ERROR",
+    UNAUTHORIZED = "UNAUTHORIZED",
+    INTERNAL_ERROR = "INTERNAL_ERROR"
+}
+interface AddMemberResponse extends IApiMessageResponse {
+    member: SerializedQuorumMember;
+    mnemonic: string;
+    [key: string]: any;
+}
+interface ListMembersResponse extends IApiMessageResponse {
+    members: SerializedQuorumMember[];
+    [key: string]: any;
+}
+interface RemoveMemberResponse extends IApiMessageResponse {
+    success: boolean;
+    memberId: string;
+    [key: string]: any;
+}
+interface SealDocumentResponse extends IApiMessageResponse {
+    documentId: string;
+    memberIds: string[];
+    sharesRequired: number;
+    createdAt: string;
+    [key: string]: any;
+}
+interface UnsealDocumentResponse extends IApiMessageResponse {
+    document: unknown;
+    [key: string]: any;
+}
+interface GetDocumentResponse extends IApiMessageResponse {
+    document: QuorumDocumentInfo;
+    [key: string]: any;
+}
+interface CanUnlockResponse extends IApiMessageResponse, CanUnlockResult {
+    [key: string]: any;
+}
+/**
+ * Serialized quorum member for API responses
+ */
+interface SerializedQuorumMember {
+    id: string;
+    publicKey: string;
+    metadata: QuorumMemberMetadata;
+    isActive: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+type QuorumApiResponse = AddMemberResponse | ListMembersResponse | RemoveMemberResponse | SealDocumentResponse | UnsealDocumentResponse | GetDocumentResponse | CanUnlockResponse | ApiErrorResponse;
+interface QuorumHandlers extends TypedHandlers {
+    addMember: ApiRequestHandler<AddMemberResponse | ApiErrorResponse>;
+    listMembers: ApiRequestHandler<ListMembersResponse | ApiErrorResponse>;
+    removeMember: ApiRequestHandler<RemoveMemberResponse | ApiErrorResponse>;
+    sealDocument: ApiRequestHandler<SealDocumentResponse | ApiErrorResponse>;
+    unsealDocument: ApiRequestHandler<UnsealDocumentResponse | ApiErrorResponse>;
+    getDocument: ApiRequestHandler<GetDocumentResponse | ApiErrorResponse>;
+    canUnlock: ApiRequestHandler<CanUnlockResponse | ApiErrorResponse>;
+}
+/**
+ * Controller for quorum operations including member management
+ * and document sealing/unsealing.
+ *
+ * Provides REST API endpoints for managing quorum members and performing
+ * secure multi-party document operations using Shamir's Secret Sharing.
+ *
+ * ## Endpoints
+ *
+ * ### Member Management
+ *
+ * #### POST /api/quorum/members
+ * Add a new member to the quorum with generated cryptographic keys.
+ *
+ * **Request Body:**
+ * - `name` (string, required): Member's display name
+ * - `email` (string, optional): Member's email address
+ * - `role` (string, optional): Member's role in the quorum
+ *
+ * **Response:** Member details and mnemonic for key recovery
+ *
+ * #### GET /api/quorum/members
+ * List all active quorum members.
+ *
+ * **Response:** Array of member objects with public keys and metadata
+ *
+ * #### DELETE /api/quorum/members/:memberId
+ * Remove a member from the quorum (deactivate).
+ *
+ * **Parameters:**
+ * - `memberId` (string, required): Member's unique identifier
+ *
+ * **Response:** Success confirmation
+ *
+ * ### Document Operations
+ *
+ * #### POST /api/quorum/documents/seal
+ * Seal a document using Shamir's Secret Sharing.
+ *
+ * **Request Body:**
+ * - `document` (any, required): Document to seal (JSON-serializable)
+ * - `memberIds` (string[], required): Array of member IDs (minimum 2)
+ * - `sharesRequired` (number, optional): Threshold for unsealing (default: all members)
+ *
+ * **Response:** Document ID and sealing metadata
+ *
+ * #### POST /api/quorum/documents/:documentId/unseal
+ * Unseal a document using member shares.
+ *
+ * **Parameters:**
+ * - `documentId` (string, required): Document's unique identifier
+ *
+ * **Request Body:**
+ * - `memberIds` (string[], required): Array of member IDs providing shares
+ *
+ * **Response:** Original document content
+ *
+ * #### GET /api/quorum/documents/:documentId
+ * Get metadata for a sealed document.
+ *
+ * **Parameters:**
+ * - `documentId` (string, required): Document's unique identifier
+ *
+ * **Response:** Document metadata (member IDs, threshold, creation date)
+ *
+ * #### GET /api/quorum/documents/:documentId/can-unlock
+ * Check if a set of members can unlock a document.
+ *
+ * **Parameters:**
+ * - `documentId` (string, required): Document's unique identifier
+ *
+ * **Query Parameters:**
+ * - `memberIds` (string, required): Comma-separated list of member IDs
+ *
+ * **Response:** Unlock status and share count information
+ *
+ * @requirements 7.1, 7.2, 7.3, 7.4, 8.1, 8.2, 8.3, 8.4, 8.5, 8.6, 9.1, 9.2, 9.3, 9.4, 9.5, 9.6, 10.1, 10.2, 10.3, 10.4, 12.1, 12.2, 12.3, 12.4, 12.5, 12.6, 12.7
+ */
+export declare class QuorumController<TID extends PlatformID = DefaultBackendIdType> extends BaseController<TID, QuorumApiResponse, QuorumHandlers, CoreLanguageCode> {
+    private quorumServiceWrapper;
+    constructor(application: IBrightChainApplication<TID>);
+    protected initRouteDefinitions(): void;
+    /**
+     * POST /api/quorum/members
+     * Add a new member to the quorum with generated cryptographic keys.
+     *
+     * Creates a new member with ECIES key pair and adds them to the quorum.
+     * The mnemonic phrase is returned for key recovery - it should be stored
+     * securely by the user as it cannot be retrieved later.
+     *
+     * @param req - Request containing member name and optional metadata
+     * @returns Member details and mnemonic on success
+     *
+     * @example
+     * ```json
+     * // Request
+     * POST /api/quorum/members
+     * {
+     *   "name": "Alice",
+     *   "email": "alice@example.com",
+     *   "role": "admin"
+     * }
+     *
+     * // Response
+     * {
+     *   "message": "Member added successfully",
+     *   "member": {
+     *     "id": "abc123...",
+     *     "publicKey": "04...",
+     *     "metadata": { "name": "Alice", "email": "alice@example.com", "role": "admin" },
+     *     "isActive": true,
+     *     "createdAt": "2025-01-16T10:00:00Z",
+     *     "updatedAt": "2025-01-16T10:00:00Z"
+     *   },
+     *   "mnemonic": "word1 word2 word3..."
+     * }
+     * ```
+     */
+    private handleAddMember;
+    /**
+     * GET /api/quorum/members
+     * List all active quorum members.
+     *
+     * Returns all members that are currently active in the quorum.
+     * Inactive (removed) members are not included in the response.
+     *
+     * @param _req - Request (no parameters required)
+     * @returns Array of member objects on success
+     *
+     * @example
+     * ```json
+     * // Request
+     * GET /api/quorum/members
+     *
+     * // Response
+     * {
+     *   "message": "Members retrieved successfully",
+     *   "members": [
+     *     {
+     *       "id": "abc123...",
+     *       "publicKey": "04...",
+     *       "metadata": { "name": "Alice", "role": "admin" },
+     *       "isActive": true,
+     *       "createdAt": "2025-01-16T10:00:00Z",
+     *       "updatedAt": "2025-01-16T10:00:00Z"
+     *     }
+     *   ]
+     * }
+     * ```
+     */
+    private handleListMembers;
+    /**
+     * DELETE /api/quorum/members/:memberId
+     * Remove a member from the quorum (deactivate).
+     *
+     * Marks the member as inactive. The member's access to existing documents
+     * they are part of is preserved, but they cannot be added to new documents.
+     *
+     * @param req - Request containing the member ID parameter
+     * @returns Success confirmation on success, or 404 if not found
+     *
+     * @example
+     * ```json
+     * // Request
+     * DELETE /api/quorum/members/abc123...
+     *
+     * // Response
+     * {
+     *   "message": "Member removed successfully",
+     *   "success": true,
+     *   "memberId": "abc123..."
+     * }
+     * ```
+     */
+    private handleRemoveMember;
+    /**
+     * POST /api/quorum/documents/seal
+     * Seal a document using Shamir's Secret Sharing.
+     *
+     * Encrypts the document with a randomly generated symmetric key, then splits
+     * the key into shares using Shamir's Secret Sharing. Each share is encrypted
+     * with the corresponding member's public key.
+     *
+     * @param req - Request containing document, member IDs, and optional threshold
+     * @returns Document ID and sealing metadata on success
+     *
+     * @example
+     * ```json
+     * // Request
+     * POST /api/quorum/documents/seal
+     * {
+     *   "document": { "secret": "data", "value": 42 },
+     *   "memberIds": ["member1...", "member2...", "member3..."],
+     *   "sharesRequired": 2
+     * }
+     *
+     * // Response
+     * {
+     *   "message": "Document sealed successfully",
+     *   "documentId": "doc123...",
+     *   "memberIds": ["member1...", "member2...", "member3..."],
+     *   "sharesRequired": 2,
+     *   "createdAt": "2025-01-16T10:00:00Z"
+     * }
+     * ```
+     */
+    private handleSealDocument;
+    /**
+     * POST /api/quorum/documents/:documentId/unseal
+     * Unseal a document using member shares.
+     *
+     * Combines the provided member shares to reconstruct the symmetric key,
+     * then decrypts and returns the original document.
+     *
+     * Note: This endpoint requires members to have their private keys loaded,
+     * which is not yet fully implemented. Currently returns 501 Not Implemented.
+     *
+     * @param req - Request containing document ID and member IDs
+     * @returns Original document on success
+     *
+     * @example
+     * ```json
+     * // Request
+     * POST /api/quorum/documents/doc123.../unseal
+     * {
+     *   "memberIds": ["member1...", "member2..."]
+     * }
+     *
+     * // Response (when implemented)
+     * {
+     *   "message": "Document unsealed successfully",
+     *   "document": { "secret": "data", "value": 42 }
+     * }
+     * ```
+     */
+    private handleUnsealDocument;
+    /**
+     * GET /api/quorum/documents/:documentId
+     * Get metadata for a sealed document.
+     *
+     * Returns information about the document including which members have access
+     * and how many shares are required to unseal it.
+     *
+     * @param req - Request containing the document ID parameter
+     * @returns Document metadata on success, or 404 if not found
+     *
+     * @example
+     * ```json
+     * // Request
+     * GET /api/quorum/documents/doc123...
+     *
+     * // Response
+     * {
+     *   "message": "Document retrieved successfully",
+     *   "document": {
+     *     "id": "doc123...",
+     *     "memberIds": ["member1...", "member2...", "member3..."],
+     *     "sharesRequired": 2,
+     *     "createdAt": "2025-01-16T10:00:00Z",
+     *     "creatorId": "creator..."
+     *   }
+     * }
+     * ```
+     */
+    private handleGetDocument;
+    /**
+     * GET /api/quorum/documents/:documentId/can-unlock
+     * Check if a set of members can unlock a document.
+     *
+     * Determines whether the provided members have enough shares to meet
+     * the threshold required to unseal the document.
+     *
+     * @param req - Request containing document ID and member IDs query parameter
+     * @returns Unlock status and share count information
+     *
+     * @example
+     * ```json
+     * // Request
+     * GET /api/quorum/documents/doc123.../can-unlock?memberIds=member1,member2
+     *
+     * // Response
+     * {
+     *   "message": "Can-unlock check completed",
+     *   "canUnlock": true,
+     *   "sharesProvided": 2,
+     *   "sharesRequired": 2,
+     *   "missingMembers": ["member3..."]
+     * }
+     * ```
+     */
+    private handleCanUnlock;
+}
+export {};
+//# sourceMappingURL=quorum.d.ts.map

package/src/lib/controllers/api/quorum.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"quorum.d.ts","sourceRoot":"","sources":["../../../../../../brightchain-api-lib/src/lib/controllers/api/quorum.ts"],"names":[],"mappings":"AACA,OAAO,EACL,eAAe,EAEf,kBAAkB,EAElB,oBAAoB,EAErB,MAAM,8BAA8B,CAAC;AAQtC,OAAO,EAAE,gBAAgB,EAAE,MAAM,2BAA2B,CAAC;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAC;AAC7D,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EAEnB,aAAa,EACd,MAAM,qCAAqC,CAAC;AAC7C,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAEvE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAU1D,OAAO,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAGzC;;;GAGG;AACH,oBAAY,eAAe;IACzB,gBAAgB,qBAAqB;IACrC,kBAAkB,uBAAuB;IACzC,mBAAmB,wBAAwB;IAC3C,uBAAuB,4BAA4B;IACnD,oBAAoB,yBAAyB;IAC7C,iBAAiB,sBAAsB;IACvC,gBAAgB,qBAAqB;IACrC,YAAY,iBAAiB;IAC7B,cAAc,mBAAmB;CAClC;AAYD,UAAU,iBAAkB,SAAQ,mBAAmB;IACrD,MAAM,EAAE,sBAAsB,CAAC;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED,UAAU,mBAAoB,SAAQ,mBAAmB;IACvD,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAQD,UAAU,oBAAqB,SAAQ,mBAAmB;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAUD,UAAU,oBAAqB,SAAQ,mBAAmB;IACxD,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAWD,UAAU,sBAAuB,SAAQ,mBAAmB;IAC1D,QAAQ,EAAE,OAAO,CAAC;IAClB,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAQD,UAAU,mBAAoB,SAAQ,mBAAmB;IACvD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAWD,UAAU,iBAAkB,SAAQ,mBAAmB,EAAE,eAAe;IACtE,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;CACpB;AAED;;GAEG;AACH,UAAU,sBAAsB;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,oBAAoB,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAkBD,KAAK,iBAAiB,GAClB,iBAAiB,GACjB,mBAAmB,GACnB,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,mBAAmB,GACnB,iBAAiB,GACjB,gBAAgB,CAAC;AAErB,UAAU,cAAe,SAAQ,aAAa;IAC5C,SAAS,EAAE,iBAAiB,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,CAAC;IACnE,WAAW,EAAE,iBAAiB,CAAC,mBAAmB,GAAG,gBAAgB,CAAC,CAAC;IACvE,YAAY,EAAE,iBAAiB,CAAC,oBAAoB,GAAG,gBAAgB,CAAC,CAAC;IACzE,YAAY,EAAE,iBAAiB,CAAC,oBAAoB,GAAG,gBAAgB,CAAC,CAAC;IACzE,cAAc,EAAE,iBAAiB,CAAC,sBAAsB,GAAG,gBAAgB,CAAC,CAAC;IAC7E,WAAW,EAAE,iBAAiB,CAAC,mBAAmB,GAAG,gBAAgB,CAAC,CAAC;IACvE,SAAS,EAAE,iBAAiB,CAAC,iBAAiB,GAAG,gBAAgB,CAAC,CAAC;CACpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6EG;AACH,qBAAa,gBAAgB,CAC3B,GAAG,SAAS,UAAU,GAAG,oBAAoB,CAC7C,SAAQ,cAAc,CACtB,GAAG,EACH,iBAAiB,EACjB,cAAc,EACd,gBAAgB,CACjB;IACC,OAAO,CAAC,oBAAoB,CAA4B;gBAE5C,WAAW,EAAE,uBAAuB,CAAC,GAAG,CAAC;IAKrD,SAAS,CAAC,oBAAoB,IAAI,IAAI;IAsDtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,OAAO,CAAC,eAAe,CAmDrB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,iBAAiB,CAoBvB;IAEF;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,OAAO,CAAC,kBAAkB,CA2BxB;IAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,OAAO,CAAC,kBAAkB,CAiFxB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,oBAAoB,CAkC1B;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2BG;IACH,OAAO,CAAC,iBAAiB,CAgCvB;IAEF;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,eAAe,CAyCrB;CACH"}