NAT Signalling (Hole Punching) should be Fire & Forget, Coalesced, and Secured with Signatures

src/nodes/agent/callers/index.ts

@@ -1,7 +1,8 @@
 import nodesClaimsGet from './nodesClaimsGet';
 import nodesClosestLocalNodesGet from './nodesClosestLocalNodesGet';
+import nodesConnectionSignalFinal from './nodesConnectionSignalFinal';
+import nodesConnectionSignalInitial from './nodesConnectionSignalInitial';
 import nodesCrossSignClaim from './nodesCrossSignClaim';
-import nodesHolePunchMessageSend from './nodesHolePunchMessageSend';
 import notificationsSend from './notificationsSend';
 import vaultsGitInfoGet from './vaultsGitInfoGet';
 import vaultsGitPackGet from './vaultsGitPackGet';
@@ -13,8 +14,9 @@ import vaultsScan from './vaultsScan';
 const manifestClient = {
  nodesClaimsGet,
  nodesClosestLocalNodesGet,
+ nodesConnectionSignalFinal,
+ nodesConnectionSignalInitial,
  nodesCrossSignClaim,
- nodesHolePunchMessageSend,
  notificationsSend,
  vaultsGitInfoGet,
  vaultsGitPackGet,
@@ -26,8 +28,9 @@ export default manifestClient;
 export {
  nodesClaimsGet,
  nodesClosestLocalNodesGet,
+ nodesConnectionSignalFinal,
+ nodesConnectionSignalInitial,
  nodesCrossSignClaim,
- nodesHolePunchMessageSend,
  notificationsSend,
  vaultsGitInfoGet,
  vaultsGitPackGet,

src/nodes/agent/callers/nodesConnectionSignalFinal.ts

@@ -0,0 +1,12 @@
+import type { HandlerTypes } from '@matrixai/rpc';
+import type NodesConnectionSignalFinal from '../handlers/NodesConnectionSignalFinal';
+import { UnaryCaller } from '@matrixai/rpc';
+
+type CallerTypes = HandlerTypes<NodesConnectionSignalFinal>;
+
+const nodesConnectionSignalFinal = new UnaryCaller<
+ CallerTypes['input'],
+ CallerTypes['output']
+>();
+
+export default nodesConnectionSignalFinal;

src/nodes/agent/callers/nodesConnectionSignalInitial.ts

@@ -0,0 +1,12 @@
+import type { HandlerTypes } from '@matrixai/rpc';
+import type NodesConnectionSignalInitial from '../handlers/NodesConnectionSignalInitial';
+import { UnaryCaller } from '@matrixai/rpc';
+
+type CallerTypes = HandlerTypes<NodesConnectionSignalInitial>;
+
+const nodesConnectionSignalInitial = new UnaryCaller<
+ CallerTypes['input'],
+ CallerTypes['output']
+>();
+
+export default nodesConnectionSignalInitial;

src/nodes/agent/errors.ts

@@ -8,4 +8,22 @@ class ErrorAgentNodeIdMissing<T> extends ErrorAgent<T> {
  exitCode = sysexits.UNAVAILABLE;
 }
 
-export { ErrorAgentNodeIdMissing };
+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;
+}
+
+export {
+ ErrorAgentNodeIdMissing,
+ ErrorNodesConnectionSignalRequestVerificationFailed,
+ ErrorNodesConnectionSignalRelayVerificationFailed,
+};

src/nodes/agent/handlers/NodesConnectionSignalFinal.ts

@@ -0,0 +1,73 @@
+import type Logger from '@matrixai/logger';
+import type {
+ AgentRPCRequestParams,
+ AgentRPCResponseResult,
+ HolePunchRequestMessage,
+} from '../types';
+import type NodeConnectionManager from '../../NodeConnectionManager';
+import type { Host, Port } from '../../../network/types';
+import { UnaryHandler } from '@matrixai/rpc';
+import * as keysUtils from '../../../keys/utils';
+import * as ids from '../../../ids';
+import * as agentErrors from '../errors';
+import * as agentUtils from '../utils';
+
+class NodesConnectionSignalFinal extends UnaryHandler<
+ {
+ nodeConnectionManager: NodeConnectionManager;
+ logger: Logger;
+ },
+ AgentRPCRequestParams<HolePunchRequestMessage>,
+ AgentRPCResponseResult
+> {
+ public handle = async (
+ input: AgentRPCRequestParams<HolePunchRequestMessage>,
+ _cancel,
+ meta,
+ ): Promise<AgentRPCResponseResult> => {
+ const { nodeConnectionManager, logger } = this.container;
+ // Connections should always be validated
+ const sourceNodeId = ids.parseNodeId(input.sourceNodeIdEncoded);
+ const targetNodeId = ids.parseNodeId(input.targetNodeIdEncoded);
+ const relayingNodeId = agentUtils.nodeIdFromMeta(meta);
+ if (relayingNodeId == null) {
+ throw new agentErrors.ErrorAgentNodeIdMissing();
+ }
+ const requestSignature = Buffer.from(input.requestSignature, 'base64url');
+ // Checking request requestSignature, requestData is just `<sourceNodeId><targetNodeId>` concatenated
+ const requestData = Buffer.concat([sourceNodeId, targetNodeId]);
+ const sourcePublicKey = keysUtils.publicKeyFromNodeId(sourceNodeId);
+ if (
+ !keysUtils.verifyWithPublicKey(
+ sourcePublicKey,
+ requestData,
+ requestSignature,
+ )
+ ) {
+ throw new agentErrors.ErrorNodesConnectionSignalRequestVerificationFailed();
+ }
+ // Checking relay message relaySignature.
+ // relayData is just `<sourceNodeId><targetNodeId><Address><requestSignature>` concatenated.
+ const relayData = Buffer.concat([
+ sourceNodeId,
+ targetNodeId,
+ Buffer.from(JSON.stringify(input.address), 'utf-8'),
+ requestSignature,
+ ]);
+ const relayPublicKey = keysUtils.publicKeyFromNodeId(relayingNodeId);
+ const relaySignature = Buffer.from(input.relaySignature, 'base64url');
+ if (
+ !keysUtils.verifyWithPublicKey(relayPublicKey, relayData, relaySignature)
+ ) {
+ throw new agentErrors.ErrorNodesConnectionSignalRelayVerificationFailed();
+ }
+
+ const host = input.address.host as Host;
+ const port = input.address.port as Port;
+ logger.debug(`Received signaling message to target ${host}:${port}`);
+ nodeConnectionManager.handleNodesConnectionSignalFinal(host, port);
+ return {};
+ };
+}
+
+export default NodesConnectionSignalFinal;

src/nodes/agent/handlers/NodesConnectionSignalInitial.ts

@@ -0,0 +1,66 @@
+import type {
+ AgentRPCRequestParams,
+ AgentRPCResponseResult,
+ HolePunchSignalMessage,
+} from '../types';
+import type NodeConnectionManager from '../../../nodes/NodeConnectionManager';
+import type { Host, Port } from '../../../network/types';
+import type { NodeAddress } from '../../../nodes/types';
+import type { JSONValue } from '../../../types';
+import { UnaryHandler } from '@matrixai/rpc';
+import * as agentErrors from '../errors';
+import * as agentUtils from '../utils';
+import { never } from '../../../utils';
+import * as keysUtils from '../../../keys/utils';
+import * as ids from '../../../ids';
+
+class NodesConnectionSignalInitial extends UnaryHandler<
+ {
+ nodeConnectionManager: NodeConnectionManager;
+ },
+ AgentRPCRequestParams<HolePunchSignalMessage>,
+ AgentRPCResponseResult
+> {
+ public handle = async (
+ input: AgentRPCRequestParams<HolePunchSignalMessage>,
+ _cancel,
+ meta: Record<string, JSONValue> | undefined,
+ ): Promise<AgentRPCResponseResult> => {
+ const { nodeConnectionManager } = this.container;
+ // Connections should always be validated
+ const requestingNodeId = agentUtils.nodeIdFromMeta(meta);
+ if (requestingNodeId == null) {
+ throw new agentErrors.ErrorAgentNodeIdMissing();
+ }
+ const targetNodeId = ids.parseNodeId(input.targetNodeIdEncoded);
+ const signature = Buffer.from(input.signature, 'base64url');
+ // Checking signature, data is just `<sourceNodeId><targetNodeId>` concatenated
+ const data = Buffer.concat([requestingNodeId, targetNodeId]);
+ const sourcePublicKey = keysUtils.publicKeyFromNodeId(requestingNodeId);
+ if (!keysUtils.verifyWithPublicKey(sourcePublicKey, data, signature)) {
+ throw new agentErrors.ErrorNodesConnectionSignalRelayVerificationFailed();
+ }
+ if (meta == null) never('Missing metadata from stream');
+ const remoteHost = meta.remoteHost;
+ const remotePort = meta.remotePort;
+ if (remoteHost == null || typeof remoteHost !== 'string') {
+ never('Missing or invalid remoteHost');
+ }
+ if (remotePort == null || typeof remotePort !== 'number') {
+ never('Missing or invalid remotePort');
+ }
+ const address: NodeAddress = {
+ host: remoteHost as Host,
+ port: remotePort as Port,
+ };
+ nodeConnectionManager.handleNodesConnectionSignalInitial(
+ requestingNodeId,
+ targetNodeId,
+ address,
+ input.signature,
+ );
+ return {};
+ };
+}
+
+export default NodesConnectionSignalInitial;

src/nodes/agent/handlers/index.ts

@@ -10,8 +10,9 @@ import type NotificationsManager from '../../../notifications/NotificationsManag
 import type VaultManager from '../../../vaults/VaultManager';
 import NodesClaimsGet from './NodesClaimsGet';
 import NodesClosestLocalNodesGet from './NodesClosestLocalNodesGet';
+import NodesConnectionSignalFinal from './NodesConnectionSignalFinal';
+import NodesConnectionSignalInitial from './NodesConnectionSignalInitial';
 import NodesCrossSignClaim from './NodesCrossSignClaim';
-import NodesHolePunchMessageSend from './NodesHolePunchMessageSend';
 import NotificationsSend from './NotificationsSend';
 import VaultsGitInfoGet from './VaultsGitInfoGet';
 import VaultsGitPackGet from './VaultsGitPackGet';
@@ -35,8 +36,9 @@ const manifestServer = (container: {
  return {
  nodesClaimsGet: new NodesClaimsGet(container),
  nodesClosestLocalNodesGet: new NodesClosestLocalNodesGet(container),
+ nodesConnectionSignalFinal: new NodesConnectionSignalFinal(container),
+ nodesConnectionSignalInitial: new NodesConnectionSignalInitial(container),
  nodesCrossSignClaim: new NodesCrossSignClaim(container),
- nodesHolePunchMessageSend: new NodesHolePunchMessageSend(container),
  notificationsSend: new NotificationsSend(container),
  vaultsGitInfoGet: new VaultsGitInfoGet(container),
  vaultsGitPackGet: new VaultsGitPackGet(container),
@@ -49,8 +51,9 @@ export default manifestServer;
 export {
  NodesClaimsGet,
  NodesClosestLocalNodesGet,
+ NodesConnectionSignalFinal,
+ NodesConnectionSignalInitial,
  NodesCrossSignClaim,
- NodesHolePunchMessageSend,
  NotificationsSend,
  VaultsGitInfoGet,
  VaultsGitPackGet,