@brightchain/brightchain-api-lib 0.24.0 → 0.25.0

package/src/lib/auth/writeAclApiRouter.js

@@ -0,0 +1,348 @@
+"use strict";
+/**
+ * @fileoverview WriteAclApiRouter - Express router for Write ACL management endpoints.
+ *
+ * Provides REST API endpoints for managing Write ACLs, mounted alongside
+ * the existing `createDbRouter`. All mutating endpoints require
+ * `X-Acl-Admin-Signature` (hex-encoded ECDSA signature) and
+ * `X-Acl-Admin-PublicKey` headers from an ACL administrator.
+ *
+ * @see BrightDB Write ACLs design, WriteAclApiRouter section
+ * @see Requirements 9.1, 9.2, 9.3, 9.4, 9.5, 9.6
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createWriteAclApiRouter = createWriteAclApiRouter;
+const express_1 = require("express");
+/**
+ * Extract and validate admin credentials from request headers.
+ * Returns the admin signature and public key as Uint8Arrays, or
+ * sends HTTP 403 and returns undefined.
+ */
+function extractAdminCredentials(req, res) {
+    const signatureHex = req.headers['x-acl-admin-signature'];
+    const publicKeyHex = req.headers['x-acl-admin-publickey'];
+    if (!signatureHex || !publicKeyHex) {
+        res.status(403).json({
+            error: 'Missing admin credentials',
+            message: 'X-Acl-Admin-Signature and X-Acl-Admin-PublicKey headers are required for this operation',
+        });
+        return undefined;
+    }
+    try {
+        const adminSignature = Uint8Array.from(Buffer.from(signatureHex, 'hex'));
+        const adminPublicKey = Uint8Array.from(Buffer.from(publicKeyHex, 'hex'));
+        return { adminSignature, adminPublicKey };
+    }
+    catch {
+        res.status(403).json({
+            error: 'Invalid admin credentials',
+            message: 'X-Acl-Admin-Signature and X-Acl-Admin-PublicKey must be valid hex-encoded values',
+        });
+        return undefined;
+    }
+}
+/**
+ * Factory function that creates an Express router for Write ACL management.
+ *
+ * @param aclManager - The WriteAclManager (or any IWriteAclApiManager) to delegate to
+ * @param auditLogger - Optional WriteAclAuditLogger for logging ACL events
+ * @returns An Express Router with ACL management endpoints
+ */
+function createWriteAclApiRouter(aclManager, auditLogger) {
+    const router = (0, express_1.Router)();
+    // ─── GET endpoints: Retrieve current Write_ACL ──────────────────────
+    /** GET /acl/:dbName — Get database-level Write_ACL. @see Requirement 9.1 */
+    router.get('/acl/:dbName', (req, res) => {
+        try {
+            const dbName = req.params['dbName'];
+            const aclDoc = aclManager.getAclDocument(dbName);
+            if (!aclDoc) {
+                res.status(404).json({
+                    error: 'ACL not found',
+                    message: `No Write_ACL configured for database "${dbName}"`,
+                });
+                return;
+            }
+            res.json(serializeAclForResponse(aclDoc));
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    });
+    /** GET /acl/:dbName/:collectionName — Get collection-level Write_ACL. @see Requirement 9.1 */
+    router.get('/acl/:dbName/:collectionName', (req, res) => {
+        try {
+            const dbName = req.params['dbName'];
+            const collectionName = req.params['collectionName'];
+            const aclDoc = aclManager.getAclDocument(dbName, collectionName);
+            if (!aclDoc) {
+                res.status(404).json({
+                    error: 'ACL not found',
+                    message: `No Write_ACL configured for "${dbName}/${collectionName}"`,
+                });
+                return;
+            }
+            res.json(serializeAclForResponse(aclDoc));
+        }
+        catch (error) {
+            res.status(500).json({ error: error.message });
+        }
+    });
+    // ─── PUT endpoints: Set/update Write_ACL ────────────────────────────
+    /** PUT /acl/:dbName — Set/update database-level Write_ACL. @see Requirements 9.2, 9.6 */
+    router.put('/acl/:dbName', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const aclDoc = parseAclFromRequest(req.body, dbName);
+            const key = await aclManager.setAcl(aclDoc, credentials.adminSignature, credentials.adminPublicKey);
+            if (auditLogger) {
+                auditLogger.logAclModification(Buffer.from(credentials.adminPublicKey).toString('hex'), 'setAcl', 'database', dbName);
+            }
+            res.json({ success: true, key });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    /** PUT /acl/:dbName/:collectionName — Set/update collection-level Write_ACL. @see Requirements 9.2, 9.6 */
+    router.put('/acl/:dbName/:collectionName', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const collectionName = req.params['collectionName'];
+            const aclDoc = parseAclFromRequest(req.body, dbName, collectionName);
+            const key = await aclManager.setAcl(aclDoc, credentials.adminSignature, credentials.adminPublicKey);
+            if (auditLogger) {
+                auditLogger.logAclModification(Buffer.from(credentials.adminPublicKey).toString('hex'), 'setAcl', 'collection', dbName, collectionName);
+            }
+            res.json({ success: true, key });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    // ─── POST endpoints: Add authorized writer ──────────────────────────
+    /** POST /acl/:dbName/writers — Add an Authorized_Writer (database). @see Requirements 9.3, 9.6 */
+    router.post('/acl/:dbName/writers', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const writerPublicKeyHex = req.body?.publicKeyHex;
+            if (!writerPublicKeyHex) {
+                res
+                    .status(400)
+                    .json({ error: 'Missing publicKeyHex in request body' });
+                return;
+            }
+            const writerPublicKey = Uint8Array.from(Buffer.from(writerPublicKeyHex, 'hex'));
+            const key = await aclManager.addWriter(dbName, undefined, writerPublicKey, credentials.adminSignature, credentials.adminPublicKey);
+            if (auditLogger) {
+                auditLogger.logAclModification(Buffer.from(credentials.adminPublicKey).toString('hex'), 'addWriter', writerPublicKeyHex, dbName);
+            }
+            res.json({ success: true, key });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    /** POST /acl/:dbName/:collectionName/writers — Add an Authorized_Writer (collection). @see Requirements 9.3, 9.6 */
+    router.post('/acl/:dbName/:collectionName/writers', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const collectionName = req.params['collectionName'];
+            const writerPublicKeyHex = req.body?.publicKeyHex;
+            if (!writerPublicKeyHex) {
+                res
+                    .status(400)
+                    .json({ error: 'Missing publicKeyHex in request body' });
+                return;
+            }
+            const writerPublicKey = Uint8Array.from(Buffer.from(writerPublicKeyHex, 'hex'));
+            const key = await aclManager.addWriter(dbName, collectionName, writerPublicKey, credentials.adminSignature, credentials.adminPublicKey);
+            if (auditLogger) {
+                auditLogger.logAclModification(Buffer.from(credentials.adminPublicKey).toString('hex'), 'addWriter', writerPublicKeyHex, dbName, collectionName);
+            }
+            res.json({ success: true, key });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    // ─── DELETE endpoints: Remove authorized writer ─────────────────────
+    /** DELETE /acl/:dbName/writers/:publicKeyHex — Remove an Authorized_Writer (database). @see Requirements 9.4, 9.6 */
+    router.delete('/acl/:dbName/writers/:publicKeyHex', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const publicKeyHex = req.params['publicKeyHex'];
+            const writerPublicKey = Uint8Array.from(Buffer.from(publicKeyHex, 'hex'));
+            const key = await aclManager.removeWriter(dbName, undefined, writerPublicKey, credentials.adminSignature, credentials.adminPublicKey);
+            if (auditLogger) {
+                auditLogger.logAclModification(Buffer.from(credentials.adminPublicKey).toString('hex'), 'removeWriter', publicKeyHex, dbName);
+            }
+            res.json({ success: true, key });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    /** DELETE /acl/:dbName/:collectionName/writers/:publicKeyHex — Remove an Authorized_Writer (collection). @see Requirements 9.4, 9.6 */
+    router.delete('/acl/:dbName/:collectionName/writers/:publicKeyHex', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const collectionName = req.params['collectionName'];
+            const publicKeyHex = req.params['publicKeyHex'];
+            const writerPublicKey = Uint8Array.from(Buffer.from(publicKeyHex, 'hex'));
+            const key = await aclManager.removeWriter(dbName, collectionName, writerPublicKey, credentials.adminSignature, credentials.adminPublicKey);
+            if (auditLogger) {
+                auditLogger.logAclModification(Buffer.from(credentials.adminPublicKey).toString('hex'), 'removeWriter', publicKeyHex, dbName, collectionName);
+            }
+            res.json({ success: true, key });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    // ─── POST endpoints: Issue capability token ─────────────────────────
+    /** POST /acl/:dbName/tokens — Issue a Capability_Token (database). @see Requirements 9.5, 9.6 */
+    router.post('/acl/:dbName/tokens', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const token = parseCapabilityTokenFromRequest(req.body, dbName);
+            const issuedToken = await aclManager.issueCapabilityToken(token, credentials.adminSignature);
+            if (auditLogger) {
+                auditLogger.logCapabilityTokenIssued(Buffer.from(token.granteePublicKey).toString('hex'), token.scope, token.expiresAt, Buffer.from(credentials.adminPublicKey).toString('hex'));
+            }
+            res.json({
+                success: true,
+                token: serializeTokenForResponse(issuedToken),
+            });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    /** POST /acl/:dbName/:collectionName/tokens — Issue a Capability_Token (collection). @see Requirements 9.5, 9.6 */
+    router.post('/acl/:dbName/:collectionName/tokens', async (req, res) => {
+        const credentials = extractAdminCredentials(req, res);
+        if (!credentials)
+            return;
+        try {
+            const dbName = req.params['dbName'];
+            const collectionName = req.params['collectionName'];
+            const token = parseCapabilityTokenFromRequest(req.body, dbName, collectionName);
+            const issuedToken = await aclManager.issueCapabilityToken(token, credentials.adminSignature);
+            if (auditLogger) {
+                auditLogger.logCapabilityTokenIssued(Buffer.from(token.granteePublicKey).toString('hex'), token.scope, token.expiresAt, Buffer.from(credentials.adminPublicKey).toString('hex'));
+            }
+            res.json({
+                success: true,
+                token: serializeTokenForResponse(issuedToken),
+            });
+        }
+        catch (error) {
+            handleAclError(error, res);
+        }
+    });
+    return router;
+}
+// ─── Helper functions ───────────────────────────────────────────────
+/** Map known ACL error types to appropriate HTTP status codes. */
+function handleAclError(error, res) {
+    const name = error.constructor.name;
+    if (name === 'AclAdminRequiredError' ||
+        name === 'CapabilityTokenInvalidError' ||
+        name === 'CapabilityTokenExpiredError' ||
+        name === 'AclSignatureVerificationError') {
+        res.status(403).json({ error: name, message: error.message });
+        return;
+    }
+    if (name === 'AclVersionConflictError') {
+        res.status(409).json({ error: name, message: error.message });
+        return;
+    }
+    if (name === 'LastAdministratorError' || name === 'WriterNotInPoolError') {
+        res.status(400).json({ error: name, message: error.message });
+        return;
+    }
+    res.status(500).json({ error: 'InternalError', message: error.message });
+}
+/** Parse an ACL document from a request body, injecting scope from URL params. */
+function parseAclFromRequest(body, dbName, collectionName) {
+    return {
+        documentId: body['documentId'] ?? '',
+        writeMode: body['writeMode'],
+        authorizedWriters: (body['authorizedWriters'] ?? []).map((hex) => Uint8Array.from(Buffer.from(hex, 'hex'))),
+        aclAdministrators: (body['aclAdministrators'] ?? []).map((hex) => Uint8Array.from(Buffer.from(hex, 'hex'))),
+        scope: { dbName, collectionName },
+        version: body['version'] ?? 1,
+        createdAt: body['createdAt']
+            ? new Date(body['createdAt'])
+            : new Date(),
+        updatedAt: body['updatedAt']
+            ? new Date(body['updatedAt'])
+            : new Date(),
+        creatorPublicKey: body['creatorPublicKey']
+            ? Uint8Array.from(Buffer.from(body['creatorPublicKey'], 'hex'))
+            : new Uint8Array(0),
+        creatorSignature: body['creatorSignature']
+            ? Uint8Array.from(Buffer.from(body['creatorSignature'], 'hex'))
+            : new Uint8Array(0),
+        previousVersionBlockId: body['previousVersionBlockId'],
+    };
+}
+/** Parse a capability token from a request body, injecting scope from URL params. */
+function parseCapabilityTokenFromRequest(body, dbName, collectionName) {
+    return {
+        granteePublicKey: Uint8Array.from(Buffer.from(body['granteePublicKey'] ?? '', 'hex')),
+        scope: { dbName, collectionName },
+        expiresAt: new Date(body['expiresAt'] ?? new Date().toISOString()),
+        grantorSignature: Uint8Array.from(Buffer.from(body['grantorSignature'] ?? '', 'hex')),
+        grantorPublicKey: Uint8Array.from(Buffer.from(body['grantorPublicKey'] ?? '', 'hex')),
+    };
+}
+/** Serialize an ACL document for JSON response (Uint8Array → hex strings). */
+function serializeAclForResponse(aclDoc) {
+    return {
+        documentId: aclDoc.documentId,
+        writeMode: aclDoc.writeMode,
+        authorizedWriters: aclDoc.authorizedWriters.map((w) => Buffer.from(w).toString('hex')),
+        aclAdministrators: aclDoc.aclAdministrators.map((a) => Buffer.from(a).toString('hex')),
+        scope: aclDoc.scope,
+        version: aclDoc.version,
+        createdAt: aclDoc.createdAt.toISOString(),
+        updatedAt: aclDoc.updatedAt.toISOString(),
+        creatorPublicKey: Buffer.from(aclDoc.creatorPublicKey).toString('hex'),
+        creatorSignature: Buffer.from(aclDoc.creatorSignature).toString('hex'),
+        previousVersionBlockId: aclDoc.previousVersionBlockId,
+    };
+}
+/** Serialize a capability token for JSON response (Uint8Array → hex strings). */
+function serializeTokenForResponse(token) {
+    return {
+        granteePublicKey: Buffer.from(token.granteePublicKey).toString('hex'),
+        scope: token.scope,
+        expiresAt: token.expiresAt.toISOString(),
+        grantorSignature: Buffer.from(token.grantorSignature).toString('hex'),
+        grantorPublicKey: Buffer.from(token.grantorPublicKey).toString('hex'),
+    };
+}
+//# sourceMappingURL=writeAclApiRouter.js.map

package/src/lib/auth/writeAclApiRouter.js.map

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

package/src/lib/auth/writeAclAuditLogger.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Write ACL Audit Logger implementation for BrightDB
+ *
+ * Structured audit logging for all write ACL events: authorized writes,
+ * rejected writes, ACL modifications, capability token issuance,
+ * capability token usage, and security events.
+ *
+ * Each log entry includes the actor's public key, operation type,
+ * target scope, and timestamp.
+ *
+ * @see BrightDB Write ACLs design, WriteAclAuditLogger section
+ * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+import type { IAclScope, IWriteAclAuditLogger } from '@brightchain/brightchain-lib';
+/**
+ * Operation types for audit log entries.
+ */
+export declare enum AuditOperationType {
+    AuthorizedWrite = "authorized_write",
+    RejectedWrite = "rejected_write",
+    AclModification = "acl_modification",
+    CapabilityTokenIssued = "capability_token_issued",
+    CapabilityTokenUsed = "capability_token_used",
+    SecurityEvent = "security_event"
+}
+/**
+ * A single audit log entry.
+ */
+export interface IAuditLogEntry {
+    /** Timestamp when the event was recorded */
+    timestamp: Date;
+    /** The type of operation */
+    operationType: AuditOperationType;
+    /** The actor's public key (hex-encoded), or empty for security events */
+    actorPublicKey: string;
+    /** Target scope (database and optional collection) */
+    targetScope: IAclScope;
+    /** Additional structured details about the event */
+    details: Record<string, unknown>;
+}
+/**
+ * Structured audit logger for write ACL events.
+ *
+ * Implements `IWriteAclAuditLogger` from brightchain-lib.
+ * Stores log entries in an in-memory array for testability,
+ * and provides retrieval methods for inspection.
+ *
+ * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+export declare class WriteAclAuditLogger implements IWriteAclAuditLogger {
+    private readonly entries;
+    /**
+     * Retrieve all audit log entries.
+     */
+    getEntries(): ReadonlyArray<IAuditLogEntry>;
+    /**
+     * Get the total number of audit log entries.
+     */
+    getEntryCount(): number;
+    /**
+     * Clear all audit log entries.
+     */
+    clear(): void;
+    /**
+     * Log a successful authorized write in Restricted_Mode.
+     * @see Requirements 11.1
+     */
+    logAuthorizedWrite(writerPublicKey: string, dbName: string, collectionName: string, blockId: string): void;
+    /**
+     * Log a rejected write due to authorization failure.
+     * @see Requirements 11.2
+     */
+    logRejectedWrite(requesterPublicKey: string, dbName: string, collectionName: string, reason: string): void;
+    /**
+     * Log a Write ACL modification.
+     * @see Requirements 11.3
+     */
+    logAclModification(adminPublicKey: string, changeType: string, affectedMember: string, dbName: string, collectionName?: string): void;
+    /**
+     * Log the issuance of a capability token.
+     * @see Requirements 11.4
+     */
+    logCapabilityTokenIssued(granteePublicKey: string, scope: IAclScope, expiresAt: Date, grantorPublicKey: string): void;
+    /**
+     * Log the usage of a capability token for a write operation.
+     * @see Requirements 11.5
+     */
+    logCapabilityTokenUsed(granteePublicKey: string, scope: IAclScope, dbName: string, collectionName: string, blockId: string): void;
+    /**
+     * Log a security-relevant event.
+     */
+    logSecurityEvent(event: string, details: Record<string, unknown>): void;
+}
+//# sourceMappingURL=writeAclAuditLogger.d.ts.map

package/src/lib/auth/writeAclAuditLogger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writeAclAuditLogger.d.ts","sourceRoot":"","sources":["../../../../../brightchain-api-lib/src/lib/auth/writeAclAuditLogger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,SAAS,EACT,oBAAoB,EACrB,MAAM,8BAA8B,CAAC;AAEtC;;GAEG;AACH,oBAAY,kBAAkB;IAC5B,eAAe,qBAAqB;IACpC,aAAa,mBAAmB;IAChC,eAAe,qBAAqB;IACpC,qBAAqB,4BAA4B;IACjD,mBAAmB,0BAA0B;IAC7C,aAAa,mBAAmB;CACjC;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,4CAA4C;IAC5C,SAAS,EAAE,IAAI,CAAC;IAChB,4BAA4B;IAC5B,aAAa,EAAE,kBAAkB,CAAC;IAClC,yEAAyE;IACzE,cAAc,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,WAAW,EAAE,SAAS,CAAC;IACvB,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAED;;;;;;;;GAQG;AACH,qBAAa,mBAAoB,YAAW,oBAAoB;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD;;OAEG;IACH,UAAU,IAAI,aAAa,CAAC,cAAc,CAAC;IAI3C;;OAEG;IACH,aAAa,IAAI,MAAM;IAIvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,kBAAkB,CAChB,eAAe,EAAE,MAAM,EACvB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,IAAI;IAUP;;;OAGG;IACH,gBAAgB,CACd,kBAAkB,EAAE,MAAM,EAC1B,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,IAAI;IAUP;;;OAGG;IACH,kBAAkB,CAChB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,MAAM,GACtB,IAAI;IAUP;;;OAGG;IACH,wBAAwB,CACtB,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,IAAI,EACf,gBAAgB,EAAE,MAAM,GACvB,IAAI;IAUP;;;OAGG;IACH,sBAAsB,CACpB,gBAAgB,EAAE,MAAM,EACxB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,MAAM,GACd,IAAI;IAaP;;OAEG;IACH,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAYxE"}

package/src/lib/auth/writeAclAuditLogger.js

@@ -0,0 +1,143 @@
+"use strict";
+/**
+ * @fileoverview Write ACL Audit Logger implementation for BrightDB
+ *
+ * Structured audit logging for all write ACL events: authorized writes,
+ * rejected writes, ACL modifications, capability token issuance,
+ * capability token usage, and security events.
+ *
+ * Each log entry includes the actor's public key, operation type,
+ * target scope, and timestamp.
+ *
+ * @see BrightDB Write ACLs design, WriteAclAuditLogger section
+ * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WriteAclAuditLogger = exports.AuditOperationType = void 0;
+/**
+ * Operation types for audit log entries.
+ */
+var AuditOperationType;
+(function (AuditOperationType) {
+    AuditOperationType["AuthorizedWrite"] = "authorized_write";
+    AuditOperationType["RejectedWrite"] = "rejected_write";
+    AuditOperationType["AclModification"] = "acl_modification";
+    AuditOperationType["CapabilityTokenIssued"] = "capability_token_issued";
+    AuditOperationType["CapabilityTokenUsed"] = "capability_token_used";
+    AuditOperationType["SecurityEvent"] = "security_event";
+})(AuditOperationType || (exports.AuditOperationType = AuditOperationType = {}));
+/**
+ * Structured audit logger for write ACL events.
+ *
+ * Implements `IWriteAclAuditLogger` from brightchain-lib.
+ * Stores log entries in an in-memory array for testability,
+ * and provides retrieval methods for inspection.
+ *
+ * @see Requirements 11.1, 11.2, 11.3, 11.4, 11.5
+ */
+class WriteAclAuditLogger {
+    entries = [];
+    /**
+     * Retrieve all audit log entries.
+     */
+    getEntries() {
+        return this.entries;
+    }
+    /**
+     * Get the total number of audit log entries.
+     */
+    getEntryCount() {
+        return this.entries.length;
+    }
+    /**
+     * Clear all audit log entries.
+     */
+    clear() {
+        this.entries.length = 0;
+    }
+    /**
+     * Log a successful authorized write in Restricted_Mode.
+     * @see Requirements 11.1
+     */
+    logAuthorizedWrite(writerPublicKey, dbName, collectionName, blockId) {
+        this.entries.push({
+            timestamp: new Date(),
+            operationType: AuditOperationType.AuthorizedWrite,
+            actorPublicKey: writerPublicKey,
+            targetScope: { dbName, collectionName },
+            details: { blockId },
+        });
+    }
+    /**
+     * Log a rejected write due to authorization failure.
+     * @see Requirements 11.2
+     */
+    logRejectedWrite(requesterPublicKey, dbName, collectionName, reason) {
+        this.entries.push({
+            timestamp: new Date(),
+            operationType: AuditOperationType.RejectedWrite,
+            actorPublicKey: requesterPublicKey,
+            targetScope: { dbName, collectionName },
+            details: { reason },
+        });
+    }
+    /**
+     * Log a Write ACL modification.
+     * @see Requirements 11.3
+     */
+    logAclModification(adminPublicKey, changeType, affectedMember, dbName, collectionName) {
+        this.entries.push({
+            timestamp: new Date(),
+            operationType: AuditOperationType.AclModification,
+            actorPublicKey: adminPublicKey,
+            targetScope: { dbName, collectionName },
+            details: { changeType, affectedMember },
+        });
+    }
+    /**
+     * Log the issuance of a capability token.
+     * @see Requirements 11.4
+     */
+    logCapabilityTokenIssued(granteePublicKey, scope, expiresAt, grantorPublicKey) {
+        this.entries.push({
+            timestamp: new Date(),
+            operationType: AuditOperationType.CapabilityTokenIssued,
+            actorPublicKey: grantorPublicKey,
+            targetScope: scope,
+            details: { granteePublicKey, expiresAt: expiresAt.toISOString() },
+        });
+    }
+    /**
+     * Log the usage of a capability token for a write operation.
+     * @see Requirements 11.5
+     */
+    logCapabilityTokenUsed(granteePublicKey, scope, dbName, collectionName, blockId) {
+        this.entries.push({
+            timestamp: new Date(),
+            operationType: AuditOperationType.CapabilityTokenUsed,
+            actorPublicKey: granteePublicKey,
+            targetScope: { dbName, collectionName },
+            details: {
+                tokenScope: scope,
+                blockId,
+            },
+        });
+    }
+    /**
+     * Log a security-relevant event.
+     */
+    logSecurityEvent(event, details) {
+        this.entries.push({
+            timestamp: new Date(),
+            operationType: AuditOperationType.SecurityEvent,
+            actorPublicKey: details['actorPublicKey'] ?? '',
+            targetScope: {
+                dbName: details['dbName'] ?? '',
+                collectionName: details['collectionName'],
+            },
+            details: { event, ...details },
+        });
+    }
+}
+exports.WriteAclAuditLogger = WriteAclAuditLogger;
+//# sourceMappingURL=writeAclAuditLogger.js.map

package/src/lib/auth/writeAclAuditLogger.js.map

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

package/src/lib/auth/writeProofMiddleware.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview ACL middleware for extracting Write_Proof from data route requests.
+ *
+ * Extracts the `X-Write-Proof` header (JSON-serialized IWriteProof) on
+ * existing data routes and passes the write proof through to collection
+ * operations for head registry enforcement.
+ *
+ * @see BrightDB Write ACLs design, ACL Express Middleware section
+ * @see Requirements 5.5, 3.1
+ */
+import type { IWriteProof } from '@brightchain/brightchain-lib';
+import type { NextFunction, Request, Response } from 'express';
+/**
+ * Key used to attach the parsed write proof to the Express request object.
+ */
+export declare const WRITE_PROOF_KEY = "writeProof";
+/**
+ * Augment Express Request to carry an optional write proof.
+ */
+declare global {
+    namespace Express {
+        interface Request {
+            writeProof?: IWriteProof;
+        }
+    }
+}
+/**
+ * Express middleware that extracts a Write_Proof from the `X-Write-Proof`
+ * request header. If the header is present, it is parsed from JSON and
+ * attached to `req.writeProof`. If the header is absent, the request
+ * proceeds without a proof (Open_Mode collections don't require one).
+ *
+ * Binary fields (`signerPublicKey`, `signature`) are expected as hex strings
+ * in the JSON and are converted to Uint8Array.
+ *
+ * @see Requirements 5.5, 3.1
+ */
+export declare function extractWriteProof(req: Request, res: Response, next: NextFunction): void;
+//# sourceMappingURL=writeProofMiddleware.d.ts.map