chore: updated documentation

Author: aryanjassal

src/nodes/NodeConnectionManager.ts

@@ -1628,7 +1628,7 @@ class NodeManager {
     }
 
     if (!success) {
-      throw new agentErrors.ErrorNodesClaimNetworkVerificationFailed();
+      throw new nodesErrors.ErrorNodeClaimNetworkVerificationFailed();
     }
 
     return {

src/nodes/NodeManager.ts

@@ -8,35 +8,4 @@ class ErrorAgentNodeIdMissing<T> extends ErrorAgent<T> {
   exitCode = sysexits.UNAVAILABLE;
 }
 
-// NOTE: NEEDS REVIEW
-class ErrorNodesConnectionSignalRequestVerificationFailed<
-  T,
-> extends ErrorAgent<T> {
-  static description = 'Failed to verify request message signature';
-  exitCode = sysexits.UNAVAILABLE;
-}
-
-class ErrorNodesConnectionSignalRelayVerificationFailed<
-  T,
-> extends ErrorAgent<T> {
-  static description = 'Failed to verify relay message signature';
-  exitCode = sysexits.UNAVAILABLE;
-}
-
-class ErrorNodesClaimNetworkVerificationFailed<T> extends ErrorAgent<T> {
-  static description = 'Failed to verify claim network message';
-  exitCode = sysexits.UNAVAILABLE;
-}
-
-class ErrorAgentAuthenticationFailed<T> extends ErrorAgent<T> {
-  static description = 'Failed to authenticate a node connection';
-  exitCode = sysexits.SOFTWARE;
-}
-
-export {
-  ErrorAgentNodeIdMissing,
-  ErrorNodesConnectionSignalRequestVerificationFailed,
-  ErrorNodesConnectionSignalRelayVerificationFailed,
-  ErrorNodesClaimNetworkVerificationFailed,
-  ErrorAgentAuthenticationFailed,
-};
+export { ErrorAgentNodeIdMissing };

src/nodes/agent/errors.ts

@@ -10,7 +10,6 @@ import type { JSONValue } from '../../../types.js';
 import { DuplexHandler } from '@matrixai/rpc';
 import * as agentErrors from '../errors.js';
 import * as agentUtils from '../utils.js';
-import * as utils from '../../../utils/index.js';
 
 class NodesAuthenticateConnection extends DuplexHandler<
   {
@@ -43,53 +42,13 @@ class NodesAuthenticateConnection extends DuplexHandler<
       throw new agentErrors.ErrorAgentNodeIdMissing();
     }
 
-    // Process incoming forward authentication
-    const reverseMessageInPair = await utils.valueOrTimeout(input.next(), ctx);
-    const reverseMessageIn:
-      | SuccessMessage
-      | NodesAuthenticateConnectionMessage = reverseMessageInPair.value;
-    if (reverseMessageIn.type === 'success') {
-      throw new agentErrors.ErrorAgentAuthenticationFailed(
-        'Expected authentication message but got success message',
-      );
-    }
-    const forwardMessageOut = await nodeConnectionManager.handleAuthentication(
+    // This async generator handles the back-and-forth communication to
+    // authenticate a connection.
+    yield* nodeConnectionManager.handleAuthentication(
       requestingNodeId,
-      reverseMessageIn,
+      input,
       ctx,
     );
-    yield {
-      type: 'success',
-      success: true,
-    };
-
-    // Send forward authentication message from this node
-    yield forwardMessageOut;
-    const forwardMessageResultPair = await utils.valueOrTimeout(
-      input.next(),
-      ctx,
-    );
-    const forwardMessageResult:
-      | SuccessMessage
-      | NodesAuthenticateConnectionMessage = forwardMessageResultPair.value;
-    if (forwardMessageResult.type !== 'success') {
-      throw new agentErrors.ErrorAgentAuthenticationFailed(
-        'Expected success message but got authentication message',
-      );
-    }
-
-    // Update internal state to finalize authentication
-    nodeConnectionManager.finalizeAuthentication(
-      requestingNodeId,
-      forwardMessageResult.success,
-    );
-
-    // Return final acknowledgement. Once this has been returned, all
-    // connections are guaranteed to be authenticated from both sides.
-    yield {
-      type: 'success',
-      success: true,
-    };
   };
 }
 

src/nodes/agent/handlers/NodesAuthenticateConnection.ts

@@ -15,6 +15,7 @@ import * as keysUtils from '../../../keys/utils/index.js';
 import * as ids from '../../../ids/index.js';
 import * as agentErrors from '../errors.js';
 import * as agentUtils from '../utils.js';
+import * as nodesErrors from '../../errors.js';
 
 class NodesConnectionSignalFinal extends UnaryHandler<
   {
@@ -68,7 +69,7 @@ class NodesConnectionSignalFinal extends UnaryHandler<
         requestSignature,
       )
     ) {
-      throw new agentErrors.ErrorNodesConnectionSignalRequestVerificationFailed();
+      throw new nodesErrors.ErrorNodeConnectionSignalRequestVerificationFailed();
     }
     // Checking relay message relaySignature.
     // relayData is just `<sourceNodeId><targetNodeId><Address><requestSignature>` concatenated.
@@ -83,7 +84,7 @@ class NodesConnectionSignalFinal extends UnaryHandler<
     if (
       !keysUtils.verifyWithPublicKey(relayPublicKey, relayData, relaySignature)
     ) {
-      throw new agentErrors.ErrorNodesConnectionSignalRelayVerificationFailed();
+      throw new nodesErrors.ErrorNodeConnectionSignalRelayVerificationFailed();
     }
 
     const host = input.address.host as Host;

src/nodes/agent/handlers/NodesConnectionSignalFinal.ts

@@ -14,6 +14,7 @@ import { matchSync } from '../../../utils/index.js';
 import { never } from '../../../utils/index.js';
 import * as agentErrors from '../errors.js';
 import * as agentUtils from '../utils.js';
+import * as nodesErrors from '../../errors.js';
 import * as keysUtils from '../../../keys/utils/index.js';
 import * as ids from '../../../ids/index.js';
 
@@ -55,7 +56,7 @@ class NodesConnectionSignalInitial extends UnaryHandler<
     const data = Buffer.concat([requestingNodeId, targetNodeId]);
     const sourcePublicKey = keysUtils.publicKeyFromNodeId(requestingNodeId);
     if (!keysUtils.verifyWithPublicKey(sourcePublicKey, data, signature)) {
-      throw new agentErrors.ErrorNodesConnectionSignalRelayVerificationFailed();
+      throw new nodesErrors.ErrorNodeConnectionSignalRelayVerificationFailed();
     }
     if (meta == null) never('Missing metadata from stream');
     const remoteHost = meta.remoteHost;

src/nodes/agent/handlers/NodesConnectionSignalInitial.ts

@@ -48,17 +48,17 @@ class ErrorNodeManagerAuthenticationFailed<T> extends ErrorNodeManager<T> {
   exitCode = sysexits.NOPERM;
 }
 
-class ErrorNodeManagerAuthenticationFailedForward<T> extends ErrorNodes<T> {
+class ErrorNodeManagerAuthenticationFailedForward<T> extends ErrorNodeManager<T> {
   static description = 'Failed to complete forward authentication';
   exitCode = sysexits.USAGE;
 }
 
-class ErrorNodeManagerAuthenticationFailedReverse<T> extends ErrorNodes<T> {
+class ErrorNodeManagerAuthenticationFailedReverse<T> extends ErrorNodeManager<T> {
   static description = 'Failed to complete reverse authentication';
   exitCode = sysexits.USAGE;
 }
 
-class ErrorNodeManagerAuthenticatonTimedOut<T> extends ErrorNodes<T> {
+class ErrorNodeManagerAuthenticationTimedOut<T> extends ErrorNodeManager<T> {
   static description = 'Failed to complete authentication before timing out';
   exitCode = sysexits.USAGE;
 }
@@ -154,7 +154,7 @@ class ErrorNodeConnectionTransportGenericError<
   exitCode = sysexits.USAGE;
 }
 
-class ErrorConnectionNodesEmpty<T> extends ErrorNodeConnection<T> {
+class ErrorNodeConnectionEmpty<T> extends ErrorNodeConnection<T> {
   static description = 'Nodes list to verify against was empty';
   exitCode = sysexits.USAGE;
 }
@@ -256,6 +256,30 @@ class ErrorNodeAuthenticationFailed<T> extends ErrorNodes<T> {
   exitCode = sysexits.NOPERM;
 }
 
+class ErrorNodeAuthenticationInvalidProtocol<T> extends ErrorNodes<T> {
+  static description = 'Invalid protocol used for node authentication';
+  exitCode = sysexits.USAGE;
+}
+
+class ErrorNodeConnectionSignalRequestVerificationFailed<
+  T,
+> extends ErrorNodeConnection<T> {
+  static description = 'Failed to verify request message signature';
+  exitCode = sysexits.UNAVAILABLE;
+}
+
+class ErrorNodeConnectionSignalRelayVerificationFailed<
+  T,
+> extends ErrorNodeConnection<T> {
+  static description = 'Failed to verify relay message signature';
+  exitCode = sysexits.UNAVAILABLE;
+}
+
+class ErrorNodeClaimNetworkVerificationFailed<T> extends ErrorNodes<T> {
+  static description = 'Failed to verify claim network message';
+  exitCode = sysexits.UNAVAILABLE;
+}
+
 export {
   ErrorNodes,
   ErrorNodeManager,
@@ -269,7 +293,7 @@ export {
   ErrorNodeManagerAuthenticationFailed,
   ErrorNodeManagerAuthenticationFailedForward,
   ErrorNodeManagerAuthenticationFailedReverse,
-  ErrorNodeManagerAuthenticatonTimedOut,
+  ErrorNodeManagerAuthenticationTimedOut,
   ErrorNodeGraph,
   ErrorNodeGraphRunning,
   ErrorNodeGraphNotRunning,
@@ -288,7 +312,7 @@ export {
   ErrorNodeConnectionInternalError,
   ErrorNodeConnectionTransportUnknownError,
   ErrorNodeConnectionTransportGenericError,
-  ErrorConnectionNodesEmpty,
+  ErrorNodeConnectionEmpty,
   ErrorNodeConnectionManager,
   ErrorNodeConnectionManagerNotRunning,
   ErrorNodeConnectionManagerStopping,
@@ -304,4 +328,8 @@ export {
   ErrorNodePermissionDenied,
   ErrorNodeLookupNotFound,
   ErrorNodeAuthenticationFailed,
+  ErrorNodeAuthenticationInvalidProtocol,
+  ErrorNodeClaimNetworkVerificationFailed,
+  ErrorNodeConnectionSignalRelayVerificationFailed,
+  ErrorNodeConnectionSignalRequestVerificationFailed,
 };

src/nodes/errors.ts

@@ -566,7 +566,7 @@ async function verifyServerCertificateChain(
     };
   }
   if (nodeIds.length === 0) {
-    throw new nodesErrors.ErrorConnectionNodesEmpty();
+    throw new nodesErrors.ErrorNodeConnectionEmpty();
   }
   const certChain: Array<Readonly<X509Certificate>> = [];
   for (const certPEM of certPEMChain) {

src/nodes/utils.ts

@@ -547,10 +547,19 @@ async function importFS(fs?: FileSystem): Promise<FileSystem> {
   return fsImported;
 }
 
-async function valueOrTimeout<T>(
+/**
+ * Races a promise against a context. If the context is aborted, then the promise
+ * rejects with the reason. Otherwise, the original value is returned upon
+ * resolving.
+ * @param prom The promise to resolve
+ * @param ctx The ctx with which to race the promise against
+ * @returns A promise which resolves to the prom value or errors if ctx aborts
+ */
+async function resultOrAbort<T>(
   prom: Promise<T>,
   ctx: ContextTimed,
 ): Promise<T> {
+  // Create an abort promise which rejects when ctx is aborted
   const { p: abortP, rejectP: rejectAbortP } = promise<never>();
   const abortHandler = () => {
     rejectAbortP(ctx.signal.reason);
@@ -560,6 +569,10 @@ async function valueOrTimeout<T>(
   } else {
     ctx.signal.addEventListener('abort', abortHandler, { once: true });
   }
+
+  // Race the original promise and abortP. If the original promise resolves
+  // first, then it is returned. If the context aborts first, then the
+  // promise is rejected.
   try {
     return await Promise.race([prom, abortP]);
   } catch (e) {
@@ -611,5 +624,5 @@ export {
   yieldMicro,
   setMaxListeners,
   importFS,
-  valueOrTimeout,
+  resultOrAbort,
 };

src/utils/utils.ts

@@ -211,7 +211,7 @@ describe(`${NodeConnection.name}`, () => {
       nodesUtils.encodeNodeId(nodeConnection.nodeId),
     );
   });
-  test('Should fail due to server rejecting client certificate (no certs)', async () => {
+  test('should fail due to server rejecting client certificate (no certs)', async () => {
     const nodeConnection = await NodeConnection.createNodeConnection({
       handleStream: () => {},
       targetNodeIds: [serverNodeId],
@@ -237,7 +237,7 @@ describe(`${NodeConnection.name}`, () => {
       quicErrors.ErrorQUICConnectionPeerTLS,
     );
   });
-  test('Should fail due to client rejecting server certificate (missing NodeId)', async () => {
+  test('should fail due to client rejecting server certificate (missing NodeId)', async () => {
     const nodeConnectionProm = NodeConnection.createNodeConnection({
       targetNodeIds: [clientNodeId],
       targetHost: localHost as Host,
@@ -249,7 +249,7 @@ describe(`${NodeConnection.name}`, () => {
     }).then(extractNodeConnection);
     await expect(nodeConnectionProm).rejects.toThrow();
   });
-  test('Should fail and destroy due to connection failure', async () => {
+  test('should fail and destroy due to connection failure', async () => {
     const nodeConnection = await NodeConnection.createNodeConnection(
       {
         targetNodeIds: [serverNodeId],
@@ -271,7 +271,7 @@ describe(`${NodeConnection.name}`, () => {
     await serverSocket.stop({ force: true });
     await destroyP;
   });
-  test('Should fail and destroy due to connection ending local', async () => {
+  test('should fail and destroy due to connection ending local', async () => {
     const nodeConnection = await NodeConnection.createNodeConnection(
       {
         targetNodeIds: [serverNodeId],
@@ -297,7 +297,7 @@ describe(`${NodeConnection.name}`, () => {
     });
     await destroyP;
   });
-  test('Should fail and destroy due to connection ending remote', async () => {
+  test('should fail and destroy due to connection ending remote', async () => {
     const nodeConnection = await NodeConnection.createNodeConnection(
       {
         targetNodeIds: [serverNodeId],