trac-msb 0.2.17 → 0.2.19

package/src/core/network/protocols/v1/validators/V1BaseOperation.js

@@ -0,0 +1,212 @@
+import V1ValidationSchema from "./V1ValidationSchema.js";
+import {NetworkOperationType, ResultCode} from "../../../../../utils/constants.js";
+import tracCryptoApi from "trac-crypto-api";
+import b4a from "b4a";
+import {
+    createMessage,
+    encodeCapabilities,
+    idToBuffer,
+    safeWriteUInt32BE,
+    timestampToBuffer
+} from "../../../../../utils/buffer.js";
+import {
+    V1ProtocolError,
+} from "../V1ProtocolError.js";
+import _ from 'lodash';
+
+class V1BaseOperation {
+    #v1ValidationSchema
+
+    constructor(_config) {
+        this.#v1ValidationSchema = new V1ValidationSchema();
+    }
+
+    async validate(_payload, _connection, _pendingRequestServiceEntry) {
+        throw new Error("Method 'validate()' must be implemented.");
+    }
+
+    isPayloadSchemaValid(payload) {
+        if (_.isNil(payload?.type)) {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD,'Payload or payload type is missing.');
+        }
+
+        const selectedValidator = this.#selectCheckSchemaValidator(payload.type);
+        const isPayloadValid = selectedValidator(payload);
+        if (!isPayloadValid) {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Payload is invalid.');
+        }
+    }
+
+    async validateSignature(payload, remotePublicKey) {
+        let signature;
+        let message;
+        try {
+            const result = this.#buildSignatureMessage(payload);
+            signature = result.signature;
+            message = result.message;
+        } catch (error) {
+            if (error instanceof V1ProtocolError) {
+                throw error;
+            }
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, `Failed to build signature message: ${error.message}`);
+        }
+
+        let hash;
+        try {
+            hash = await tracCryptoApi.hash.blake3(message);
+        } catch {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Failed to hash signature message.');
+        }
+
+        let verified = false;
+        try {
+            verified = tracCryptoApi.signature.verify(signature, hash, remotePublicKey);
+        } catch {
+            verified = false;
+        }
+        if (!verified) {
+            throw new V1ProtocolError(ResultCode.SIGNATURE_INVALID, 'signature verification failed.');
+        }
+    }
+
+    #buildSignatureMessage(payload) {
+        if (!Number.isInteger(payload.type)) {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Operation type must be an integer.');
+        }
+        if (payload.type === 0) {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Operation type is unspecified.');
+        }
+
+        const idBuf = idToBuffer(payload.id);
+        const tsBuf = timestampToBuffer(payload.timestamp);
+        const capsBuf = encodeCapabilities(payload.capabilities ?? []);
+
+        switch (payload.type) {
+            case NetworkOperationType.LIVENESS_REQUEST: {
+                const nonce = payload.liveness_request.nonce;
+                const signature = payload.liveness_request.signature;
+                const message = createMessage(payload.type, idBuf, tsBuf, nonce, capsBuf);
+                return {signature, message};
+            }
+            case NetworkOperationType.LIVENESS_RESPONSE: {
+                const nonce = payload.liveness_response.nonce;
+                const signature = payload.liveness_response.signature;
+                const result = payload.liveness_response.result;
+                const message = createMessage(payload.type, idBuf, tsBuf, nonce, safeWriteUInt32BE(result, 0), capsBuf);
+                return {signature, message};
+            }
+            case NetworkOperationType.BROADCAST_TRANSACTION_REQUEST: {
+                const data = payload.broadcast_transaction_request.data;
+                const nonce = payload.broadcast_transaction_request.nonce;
+                const signature = payload.broadcast_transaction_request.signature;
+                const message = createMessage(payload.type, idBuf, tsBuf, data, nonce, capsBuf);
+                return {signature, message};
+            }
+            case NetworkOperationType.BROADCAST_TRANSACTION_RESPONSE: {
+                const nonce = payload.broadcast_transaction_response.nonce;
+                const signature = payload.broadcast_transaction_response.signature;
+                const result = payload.broadcast_transaction_response.result;
+                const proofRaw = payload.broadcast_transaction_response.proof;
+                const proof = b4a.isBuffer(proofRaw) ? proofRaw : b4a.alloc(0);
+                const hasProof = proof.length > 0;
+                const timestampRaw = payload.broadcast_transaction_response.timestamp;
+                const timestamp = Number.isSafeInteger(timestampRaw) ? timestampRaw : 0;
+                const hasTimestamp = timestamp > 0;
+
+                if (result === ResultCode.OK) {
+                    if (!hasProof || !hasTimestamp) {
+                        throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Result code OK requires non-empty proof and timestamp > 0.');
+                    }
+                } else if (result === ResultCode.TX_ACCEPTED_PROOF_UNAVAILABLE) {
+                    if (hasProof) {
+                        throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Result code TX_ACCEPTED_PROOF_UNAVAILABLE requires empty proof.');
+                    }
+                    if (!hasTimestamp) {
+                        throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Result code TX_ACCEPTED_PROOF_UNAVAILABLE requires timestamp > 0.');
+                    }
+                } else {
+                    if (hasProof) {
+                        throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Non-OK result code requires empty proof.');
+                    }
+                    if (timestamp !== 0) {
+                        throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Non-OK result code requires timestamp to be 0, except TX_ACCEPTED_PROOF_UNAVAILABLE.');
+                    }
+                }
+
+                const message = createMessage(
+                    payload.type,
+                    idBuf,
+                    tsBuf,
+                    nonce,
+                    proof,
+                    timestampToBuffer(timestamp),
+                    safeWriteUInt32BE(result, 0),
+                    capsBuf
+                );
+
+                return {signature, message};
+            }
+            default:
+                throw new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, `Unknown operation type: ${payload.type}`);
+        }
+    }
+
+    #selectCheckSchemaValidator(type) {
+        if (!Number.isInteger(type)) {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Operation type must be an integer.');
+        }
+        if (type === 0) {
+            throw new V1ProtocolError(ResultCode.INVALID_PAYLOAD, 'Operation type is unspecified.');
+        }
+
+        switch (type) {
+            case NetworkOperationType.LIVENESS_REQUEST:
+                return this.#v1ValidationSchema.validateV1LivenessRequest.bind(this.#v1ValidationSchema);
+            case NetworkOperationType.LIVENESS_RESPONSE:
+                return this.#v1ValidationSchema.validateV1LivenessResponse.bind(this.#v1ValidationSchema);
+            case NetworkOperationType.BROADCAST_TRANSACTION_REQUEST:
+                return this.#v1ValidationSchema.validateV1BroadcastTransactionRequest.bind(this.#v1ValidationSchema);
+            case NetworkOperationType.BROADCAST_TRANSACTION_RESPONSE:
+                return this.#v1ValidationSchema.validateV1BroadcastTransactionResponse.bind(this.#v1ValidationSchema);
+            default:
+                throw new V1ProtocolError(ResultCode.UNEXPECTED_ERROR, `Unknown operation type: ${type}`);
+        }
+    }
+
+    validatePeerCorrectness(remotePublicKey, pendingRequestServiceEntry) {
+        const senderPublicKeyHex = b4a.toString(remotePublicKey, 'hex');
+        if (senderPublicKeyHex !== pendingRequestServiceEntry.requestedTo) {
+            throw new V1ProtocolError(
+                ResultCode.INVALID_PAYLOAD,
+                `Response sender mismatch. Expected ${pendingRequestServiceEntry.requestedTo}, got ${senderPublicKeyHex}.`
+            );
+        }
+    }
+
+    validateResponseType(payload, pendingRequestServiceEntry) {
+        let expectedResponseType;
+        switch (pendingRequestServiceEntry.requestType) {
+            case NetworkOperationType.LIVENESS_REQUEST:
+                expectedResponseType = NetworkOperationType.LIVENESS_RESPONSE;
+                break;
+            case NetworkOperationType.BROADCAST_TRANSACTION_REQUEST:
+                expectedResponseType = NetworkOperationType.BROADCAST_TRANSACTION_RESPONSE;
+                break;
+            default:
+                throw new V1ProtocolError(
+                    ResultCode.UNEXPECTED_ERROR,
+                    `Unsupported pending request type: ${pendingRequestServiceEntry.requestType}.`
+                );
+        }
+
+        if (payload.type !== expectedResponseType) {
+            throw new V1ProtocolError(
+                ResultCode.INVALID_PAYLOAD,
+                `Response type mismatch for id ${pendingRequestServiceEntry.id}. Expected ${expectedResponseType}, got ${payload.type}.`
+            );
+        }
+    }
+
+}
+
+export default V1BaseOperation;

package/src/core/network/protocols/v1/validators/V1BroadcastTransactionRequest.js

@@ -0,0 +1,28 @@
+import V1BaseOperation from "./V1BaseOperation.js";
+import b4a from "b4a";
+import {MAX_PARTIAL_TX_PAYLOAD_BYTE_SIZE, ResultCode} from '../../../../../utils/constants.js';
+import {V1ProtocolError} from "../V1ProtocolError.js";
+
+class V1BroadcastTransactionRequest extends V1BaseOperation {
+    constructor(config) {
+        super(config);
+    }
+
+    async validate(payload, remotePublicKey) {
+        this.isPayloadSchemaValid(payload);
+        this.isDataPropertySizeValid(payload);
+        await this.validateSignature(payload, remotePublicKey);
+        return true;
+    }
+
+    isDataPropertySizeValid(payload) {
+        if (b4a.byteLength(payload.broadcast_transaction_request.data) > MAX_PARTIAL_TX_PAYLOAD_BYTE_SIZE) {
+            throw new V1ProtocolError(
+                ResultCode.INVALID_PAYLOAD,
+                `The 'data' field exceeds the maximum allowed byte size of ${MAX_PARTIAL_TX_PAYLOAD_BYTE_SIZE}. Actual size: ${b4a.byteLength(payload.broadcast_transaction_request.data)}`);
+        }
+    }
+
+}
+
+export default V1BroadcastTransactionRequest;

package/src/core/network/protocols/v1/validators/V1BroadcastTransactionResponse.js

@@ -0,0 +1,260 @@
+import Autobase from "autobase";
+import b4a from "b4a";
+import Hypercore from 'hypercore';
+import V1BaseOperation from "./V1BaseOperation.js";
+import {unsafeDecodeApplyOperation} from "../../../../../utils/protobuf/operationHelpers.js";
+import {isDeepEqualApplyPayload} from "../../../../../utils/deepEqualApplyPayload.js";
+import {addressToBuffer, bufferToAddress} from "../../../../state/utils/address.js";
+import {publicKeyToAddress} from "../../../../../utils/helpers.js";
+import Check from "../../../../../utils/check.js";
+import {OperationType, ResultCode} from "../../../../../utils/constants.js";
+import {V1ProtocolError} from "../V1ProtocolError.js";
+
+const VALIDATOR_METADATA_FIELDS = new Set(["va", "vn", "vs"]);
+
+const stripValidatorMetadata = (value) => {
+
+    if (value === null || value === undefined) return value;
+    if (b4a.isBuffer(value)) return value;
+    if (Array.isArray(value)) return value.map(stripValidatorMetadata);
+    if (typeof value !== "object") return value;
+
+    const result = {};
+    for (const [key, nestedValue] of Object.entries(value)) {
+        if (VALIDATOR_METADATA_FIELDS.has(key)) {
+            result[key] = null;
+            continue;
+        }
+        result[key] = stripValidatorMetadata(nestedValue);
+    }
+    return result;
+};
+
+class V1BroadcastTransactionResponse extends V1BaseOperation {
+    #config;
+    #check;
+    #state;
+
+    constructor(state, config) {
+        super(config);
+        this.#state = state;
+        this.#config = config;
+        this.#check = new Check(config);
+    }
+
+    async validate(payload, connection, pendingRequestServiceEntry) {
+        this.isPayloadSchemaValid(payload);
+        this.validateResponseType(payload, pendingRequestServiceEntry);
+        this.validatePeerCorrectness(connection.remotePublicKey, pendingRequestServiceEntry);
+        await this.validateSignature(payload, connection.remotePublicKey);
+        const resultCode = payload.broadcast_transaction_response.result;
+        // if result code is not OK, we can skip the rest of the validations.
+        this.validateIfResultCodeIsValidatorInternalError(resultCode);
+        if (resultCode === ResultCode.OK) {
+            const proofResult = await this.verifyProofOfPublication(payload);
+            const {
+                validatorDecodedTx,
+                manifest
+            } = await this.assertProofPayloadMatchesRequestPayload(proofResult, pendingRequestServiceEntry);
+            this.validateDecodedCompletePayloadSchema(validatorDecodedTx);
+            const {
+                writerKeyFromManifest,
+                validatorAddressCorrelatedWithManifest
+            } = await this.validateWritingKey(validatorDecodedTx, manifest);
+            await this.validateValidatorCorrectness(
+                validatorDecodedTx,
+                connection.remotePublicKey,
+                writerKeyFromManifest,
+                validatorAddressCorrelatedWithManifest,
+            );
+        }
+
+        return true;
+    }
+
+    validateDecodedCompletePayloadSchema(validatorDecodedTx) {
+        const type = validatorDecodedTx?.type;
+        if (!Number.isInteger(type)) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_RESPONSE_TX_TYPE_INVALID,
+                'Decoded validator transaction type is missing or invalid.'
+            );
+        }
+
+        if (!Object.values(OperationType).includes(type)) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_RESPONSE_TX_TYPE_UNKNOWN,
+                `Decoded validator transaction type ${type} is not defined in OperationType constants.`
+            );
+        }
+
+        let isValid = false;
+        switch (type) {
+            case OperationType.ADD_WRITER:
+            case OperationType.REMOVE_WRITER:
+            case OperationType.ADMIN_RECOVERY:
+                isValid =  this.#check.validateRoleAccessOperation(validatorDecodedTx);
+                break;
+            case OperationType.BOOTSTRAP_DEPLOYMENT:
+                isValid =  this.#check.validateBootstrapDeploymentOperation(validatorDecodedTx);
+                break;
+            case OperationType.TX:
+                isValid = this.#check.validateTransactionOperation(validatorDecodedTx);
+                break;
+            case OperationType.TRANSFER:
+                isValid = this.#check.validateTransferOperation(validatorDecodedTx);
+                break;
+            default:
+                throw new V1ProtocolError(
+                    ResultCode.VALIDATOR_RESPONSE_TX_TYPE_UNSUPPORTED,
+                    `Unsupported decoded validator transaction type: ${type}`
+                );
+        }
+
+        if (!isValid) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_RESPONSE_SCHEMA_INVALID,
+                `Decoded validator transaction schema validation failed for type ${type}.`
+            );
+        }
+    }
+
+    async verifyProofOfPublication(payload) {
+        const proof = payload.broadcast_transaction_response.proof;
+        return this.#state.verifyProofOfPublication(proof);
+    }
+
+    async assertProofPayloadMatchesRequestPayload(proofResult, pendingRequestServiceEntry) {
+        const stateTxEncodedFromRequest = pendingRequestServiceEntry.requestTxData;
+        if (!b4a.isBuffer(stateTxEncodedFromRequest) || stateTxEncodedFromRequest.length === 0) {
+            throw new V1ProtocolError(
+                ResultCode.PENDING_REQUEST_MISSING_TX_DATA,
+                'Missing transaction data in pending request entry.'
+            );
+        }
+        const provenBlock = proofResult.proof.block.value;
+        const manifest = proofResult.proof.manifest;
+        const stateTxEncodedFromResponse = await Autobase.decodeValue(provenBlock);
+
+        const stateTxDecodedFromRequest = unsafeDecodeApplyOperation(stateTxEncodedFromRequest);
+        const stateTxDecodedFromResponse = unsafeDecodeApplyOperation(stateTxEncodedFromResponse);
+        const strippedValidatorPayload = stripValidatorMetadata(stateTxDecodedFromResponse);
+
+        if (!isDeepEqualApplyPayload(stateTxDecodedFromRequest, strippedValidatorPayload)) {
+            throw new V1ProtocolError(
+                ResultCode.PROOF_PAYLOAD_MISMATCH,
+                'Decoded transaction payload mismatch after removing validator metadata fields.'
+            );
+        }
+        return {validatorDecodedTx: stateTxDecodedFromResponse, manifest};
+    }
+
+    async validateWritingKey(validatorDecodedTx, manifest) {
+        const writerKeyFromManifest = Hypercore.key(manifest);
+        const writerKeyFromManifestHex = b4a.toString(writerKeyFromManifest, "hex");
+
+        const validatorAddressBuffer = await this.#state.getRegisteredWriterKey(writerKeyFromManifestHex);
+        if (!b4a.isBuffer(validatorAddressBuffer) || validatorAddressBuffer.length === 0) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_WRITER_KEY_NOT_REGISTERED,
+                `Validator with writer key ${writerKeyFromManifestHex} is not registered.`
+            );
+        }
+
+        return {
+            writerKeyFromManifest,
+            validatorAddressCorrelatedWithManifest: validatorAddressBuffer
+        };
+    }
+
+    async validateValidatorCorrectness(validatorDecodedTx, connectionRemotePublicKey, writerKeyFromManifest, validatorAddressCorrelatedWithManifest) {
+        const validatorAddressFromTx = extractRequiredVaFromDecodedTx(validatorDecodedTx);
+        const validatorAddressFromConnectionPublicKey = addressToBuffer(
+            publicKeyToAddress(connectionRemotePublicKey, this.#config),
+            this.#config.addressPrefix
+        );
+
+        if (!b4a.equals(validatorAddressFromTx, validatorAddressFromConnectionPublicKey)) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_ADDRESS_MISMATCH,
+                `Validator address from transaction (${bufferToAddress(validatorAddressFromTx, this.#config.addressPrefix)}) does not match address derived from connection public key (${bufferToAddress(validatorAddressFromConnectionPublicKey, this.#config.addressPrefix)}).`
+            );
+        }
+
+        if (!b4a.equals(validatorAddressFromTx, validatorAddressCorrelatedWithManifest)) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_ADDRESS_MISMATCH,
+                `Validator address from transaction (${bufferToAddress(validatorAddressFromTx, this.#config.addressPrefix)}) does not match address correlated with manifest writer key (${bufferToAddress(validatorAddressCorrelatedWithManifest, this.#config.addressPrefix)}).`
+            );
+        }
+
+        if (!b4a.equals(validatorAddressCorrelatedWithManifest, validatorAddressFromConnectionPublicKey)) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_ADDRESS_MISMATCH,
+                `Validator address correlated with manifest writer key (${bufferToAddress(validatorAddressCorrelatedWithManifest, this.#config.addressPrefix)}) does not match address derived from connection public key (${bufferToAddress(validatorAddressFromConnectionPublicKey, this.#config.addressPrefix)}).`
+            );
+        }
+
+        const validatorAddressFromConnection = bufferToAddress(validatorAddressFromConnectionPublicKey, this.#config.addressPrefix);
+        const account = await this.#state.getNodeEntry(validatorAddressFromConnection);
+
+        if (!account) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_NODE_ENTRY_NOT_FOUND,
+                `No node entry found in state for validator address derived from connection public key (${validatorAddressFromConnection}).`
+            );
+        }
+
+        if (!account.isWriter) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_NODE_NOT_WRITER,
+                `Node entry found for validator address derived from connection public key (${validatorAddressFromConnection}), but it is not registered as a writer.`
+            );
+        }
+
+        if (!b4a.isBuffer(account.wk) || !b4a.equals(account.wk, writerKeyFromManifest)) {
+            throw new V1ProtocolError(
+                ResultCode.VALIDATOR_WRITER_KEY_MISMATCH,
+                `Writer key from manifest (${b4a.toString(writerKeyFromManifest, "hex")}) does not match writer key in state for validator address derived from connection public key (${validatorAddressFromConnection}).`
+            );
+        }
+    }
+
+    validateIfResultCodeIsValidatorInternalError(resultCode) {
+        if (resultCode === ResultCode.TX_COMMITTED_RECEIPT_MISSING) {
+            throw new V1ProtocolError(
+                resultCode,
+                `Validator response indicates an error with result code ${resultCode}, which is an internal error code.`
+            )
+        }
+    }
+}
+
+export function extractRequiredVaFromDecodedTx(validatorDecodedTx) {
+    if (!validatorDecodedTx || typeof validatorDecodedTx !== 'object') {
+        throw new V1ProtocolError(
+            ResultCode.VALIDATOR_TX_OBJECT_INVALID,
+            'Invalid decoded transaction: expected object'
+        );
+    }
+
+    const operationPayload = Object.values(validatorDecodedTx).find((value) =>
+        value &&
+        typeof value === 'object' &&
+        !Array.isArray(value) &&
+        !b4a.isBuffer(value) &&
+        Object.prototype.hasOwnProperty.call(value, 'va')
+    );
+
+    const va = operationPayload?.va;
+
+    if (!b4a.isBuffer(va)) {
+        throw new V1ProtocolError(
+            ResultCode.VALIDATOR_VA_MISSING,
+            'Missing validator address (va) in decoded transaction'
+        );
+    }
+    return va;
+}
+
+export default V1BroadcastTransactionResponse;

package/src/core/network/protocols/v1/validators/V1LivenessRequest.js

@@ -0,0 +1,15 @@
+import V1BaseOperation from "./V1BaseOperation.js";
+
+class V1LivenessRequest extends V1BaseOperation {
+    constructor(config) {
+        super(config);
+    }
+
+    async validate(payload, remotePublicKey) {
+        this.isPayloadSchemaValid(payload);
+        await this.validateSignature(payload, remotePublicKey);
+        return true;
+    }
+}
+
+export default V1LivenessRequest;

package/src/core/network/protocols/v1/validators/V1LivenessResponse.js

@@ -0,0 +1,17 @@
+import V1BaseOperation from "./V1BaseOperation.js";
+
+class V1LivenessResponse extends V1BaseOperation {
+    constructor(config) {
+        super(config);
+    }
+
+    async validate(payload, connection, pendingRequestServiceEntry) {
+        this.isPayloadSchemaValid(payload);
+        this.validateResponseType(payload, pendingRequestServiceEntry);
+        this.validatePeerCorrectness(connection.remotePublicKey, pendingRequestServiceEntry);
+        await this.validateSignature(payload, connection.remotePublicKey);
+        return true;
+    }
+}
+
+export default V1LivenessResponse;