@wolpertingerlabs/drawlatch 1.0.0-alpha.1

package/dist/shared/protocol/handshake.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Mutual authentication handshake protocol.
+ *
+ * Inspired by the Noise NK pattern — the responder's (remote server's) public
+ * key is known in advance. The initiator (MCP proxy) proves its identity by
+ * signing a challenge, and both sides derive a shared secret via X25519 ECDH.
+ *
+ * Protocol flow:
+ *
+ *   Initiator (MCP Proxy)                    Responder (Remote Server)
+ *   ──────────────────────                    ────────────────────────
+ *
+ *   1. Generate ephemeral X25519 keypair
+ *      Sign(ephemeral_pub || nonce_i) with Ed25519
+ *      ──── HandshakeInit ────────────────►
+ *                                             2. Verify initiator's signature
+ *                                                Check initiator's pubkey is authorized
+ *                                                Generate ephemeral X25519 keypair
+ *                                                Sign(ephemeral_pub || nonce_r || nonce_i)
+ *                                             ◄──── HandshakeReply ──────
+ *   3. Verify responder's signature
+ *      Both: ECDH(ephemeral_i, ephemeral_r) → shared secret
+ *      Both: HKDF(shared_secret, transcript_hash) → session keys
+ *      ──── HandshakeFinish (encrypted "ready") ──►
+ *                                             4. Decrypt and verify "ready"
+ *                                                Session established ✓
+ *
+ * The handshake transcript (all messages concatenated) is hashed and used as
+ * HKDF salt, binding the session keys to the exact handshake that occurred.
+ * This prevents unknown-key-share attacks.
+ */
+import { type KeyBundle, type PublicKeyBundle, type SessionKeys } from '../crypto/index.js';
+export interface HandshakeInit {
+    type: 'handshake_init';
+    /** Initiator's static Ed25519 public key (PEM) */
+    signingPubKey: string;
+    /** Initiator's ephemeral X25519 public key (PEM) */
+    ephemeralPubKey: string;
+    /** Random nonce (32 bytes, hex) */
+    nonceI: string;
+    /** Ed25519 signature over (ephemeralPubKey || nonceI) */
+    signature: string;
+    /** Protocol version */
+    version: 1;
+}
+export interface HandshakeReply {
+    type: 'handshake_reply';
+    /** Responder's ephemeral X25519 public key (PEM) */
+    ephemeralPubKey: string;
+    /** Random nonce (32 bytes, hex) */
+    nonceR: string;
+    /** Ed25519 signature over (ephemeralPubKey || nonceR || nonceI) */
+    signature: string;
+}
+export interface HandshakeFinish {
+    type: 'handshake_finish';
+    /** Encrypted "ready" payload — proves the initiator derived the right keys */
+    payload: string;
+}
+export type HandshakeMessage = HandshakeInit | HandshakeReply | HandshakeFinish;
+export declare class HandshakeInitiator {
+    /** Our full key bundle */
+    private readonly ownKeys;
+    /** The remote server's known public keys */
+    private readonly peerPublicKeys;
+    private ephemeral;
+    private nonceI;
+    private transcript;
+    constructor(
+    /** Our full key bundle */
+    ownKeys: KeyBundle, 
+    /** The remote server's known public keys */
+    peerPublicKeys: PublicKeyBundle);
+    /**
+     * Step 1: Create the initial handshake message.
+     */
+    createInit(): HandshakeInit;
+    /**
+     * Step 3: Process the responder's reply and derive session keys.
+     */
+    processReply(reply: HandshakeReply): SessionKeys;
+    /**
+     * Create the finish message (encrypted with the newly derived keys).
+     */
+    createFinish(keys: SessionKeys): HandshakeFinish;
+}
+export declare class HandshakeResponder {
+    /** Our full key bundle */
+    private readonly ownKeys;
+    /** Set of authorized initiator public keys */
+    private readonly authorizedKeys;
+    private ephemeral;
+    private transcript;
+    constructor(
+    /** Our full key bundle */
+    ownKeys: KeyBundle, 
+    /** Set of authorized initiator public keys */
+    authorizedKeys: PublicKeyBundle[]);
+    /**
+     * Step 2: Process the init message, verify the initiator, and create a reply.
+     */
+    processInit(init: HandshakeInit): {
+        reply: HandshakeReply;
+        initiatorPubKey: PublicKeyBundle;
+    };
+    /**
+     * Derive session keys after sending the reply.
+     * Call this after processInit() and before verifying the finish message.
+     */
+    deriveKeys(init: HandshakeInit): SessionKeys;
+    /**
+     * Step 4: Verify the finish message to confirm the initiator derived the right keys.
+     */
+    verifyFinish(finish: HandshakeFinish, keys: SessionKeys): boolean;
+}
+//# sourceMappingURL=handshake.d.ts.map

package/dist/shared/protocol/handshake.js

@@ -0,0 +1,214 @@
+/**
+ * Mutual authentication handshake protocol.
+ *
+ * Inspired by the Noise NK pattern — the responder's (remote server's) public
+ * key is known in advance. The initiator (MCP proxy) proves its identity by
+ * signing a challenge, and both sides derive a shared secret via X25519 ECDH.
+ *
+ * Protocol flow:
+ *
+ *   Initiator (MCP Proxy)                    Responder (Remote Server)
+ *   ──────────────────────                    ────────────────────────
+ *
+ *   1. Generate ephemeral X25519 keypair
+ *      Sign(ephemeral_pub || nonce_i) with Ed25519
+ *      ──── HandshakeInit ────────────────►
+ *                                             2. Verify initiator's signature
+ *                                                Check initiator's pubkey is authorized
+ *                                                Generate ephemeral X25519 keypair
+ *                                                Sign(ephemeral_pub || nonce_r || nonce_i)
+ *                                             ◄──── HandshakeReply ──────
+ *   3. Verify responder's signature
+ *      Both: ECDH(ephemeral_i, ephemeral_r) → shared secret
+ *      Both: HKDF(shared_secret, transcript_hash) → session keys
+ *      ──── HandshakeFinish (encrypted "ready") ──►
+ *                                             4. Decrypt and verify "ready"
+ *                                                Session established ✓
+ *
+ * The handshake transcript (all messages concatenated) is hashed and used as
+ * HKDF salt, binding the session keys to the exact handshake that occurred.
+ * This prevents unknown-key-share attacks.
+ */
+import crypto from 'node:crypto';
+import { deriveSessionKeys, EncryptedChannel, } from '../crypto/index.js';
+// ── Helpers ────────────────────────────────────────────────────────────────
+function signData(privateKey, ...parts) {
+    const combined = Buffer.concat(parts.map((p) => (typeof p === 'string' ? Buffer.from(p, 'utf-8') : p)));
+    return crypto.sign(null, combined, privateKey);
+}
+function verifySignature(publicKey, signature, ...parts) {
+    const combined = Buffer.concat(parts.map((p) => (typeof p === 'string' ? Buffer.from(p, 'utf-8') : p)));
+    return crypto.verify(null, combined, publicKey, signature);
+}
+// ── Initiator (MCP Proxy side) ─────────────────────────────────────────────
+export class HandshakeInitiator {
+    ownKeys;
+    peerPublicKeys;
+    ephemeral;
+    nonceI;
+    transcript = [];
+    constructor(
+    /** Our full key bundle */
+    ownKeys, 
+    /** The remote server's known public keys */
+    peerPublicKeys) {
+        this.ownKeys = ownKeys;
+        this.peerPublicKeys = peerPublicKeys;
+        this.ephemeral = crypto.generateKeyPairSync('x25519');
+        this.nonceI = crypto.randomBytes(32);
+    }
+    /**
+     * Step 1: Create the initial handshake message.
+     */
+    createInit() {
+        const ephemeralPubPem = this.ephemeral.publicKey.export({
+            type: 'spki',
+            format: 'pem',
+        });
+        const signature = signData(this.ownKeys.signing.privateKey, ephemeralPubPem, this.nonceI);
+        const msg = {
+            type: 'handshake_init',
+            signingPubKey: this.ownKeys.signing.publicKey.export({
+                type: 'spki',
+                format: 'pem',
+            }),
+            ephemeralPubKey: ephemeralPubPem,
+            nonceI: this.nonceI.toString('hex'),
+            signature: signature.toString('hex'),
+            version: 1,
+        };
+        // Record in transcript
+        this.transcript.push(Buffer.from(JSON.stringify(msg), 'utf-8'));
+        return msg;
+    }
+    /**
+     * Step 3: Process the responder's reply and derive session keys.
+     */
+    processReply(reply) {
+        // Record in transcript
+        this.transcript.push(Buffer.from(JSON.stringify(reply), 'utf-8'));
+        // Verify responder's signature over (ephemeralPubKey || nonceR || nonceI)
+        const sigValid = verifySignature(this.peerPublicKeys.signing, Buffer.from(reply.signature, 'hex'), reply.ephemeralPubKey, Buffer.from(reply.nonceR, 'hex'), this.nonceI);
+        if (!sigValid) {
+            throw new Error('Handshake failed: responder signature invalid');
+        }
+        // ECDH to derive shared secret
+        const peerEphemeral = crypto.createPublicKey(reply.ephemeralPubKey);
+        const sharedSecret = crypto.diffieHellman({
+            privateKey: this.ephemeral.privateKey,
+            publicKey: peerEphemeral,
+        });
+        // Hash the full transcript
+        const transcriptHash = crypto
+            .createHash('sha256')
+            .update(Buffer.concat(this.transcript))
+            .digest();
+        return deriveSessionKeys(sharedSecret, true, transcriptHash);
+    }
+    /**
+     * Create the finish message (encrypted with the newly derived keys).
+     */
+    createFinish(keys) {
+        const channel = new EncryptedChannel(keys);
+        const readyPayload = channel.encrypt(Buffer.from(JSON.stringify({ status: 'ready', timestamp: Date.now() }), 'utf-8'));
+        return {
+            type: 'handshake_finish',
+            payload: readyPayload.toString('hex'),
+        };
+    }
+}
+// ── Responder (Remote Server side) ──────────────────────────────────────────
+export class HandshakeResponder {
+    ownKeys;
+    authorizedKeys;
+    ephemeral = null;
+    transcript = [];
+    constructor(
+    /** Our full key bundle */
+    ownKeys, 
+    /** Set of authorized initiator public keys */
+    authorizedKeys) {
+        this.ownKeys = ownKeys;
+        this.authorizedKeys = authorizedKeys;
+    }
+    /**
+     * Step 2: Process the init message, verify the initiator, and create a reply.
+     */
+    processInit(init) {
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- runtime validation for untrusted input regardless of static type
+        if (init.version !== 1) {
+            throw new Error(`Unsupported handshake version: ${String(init.version)}`);
+        }
+        // Record in transcript
+        this.transcript.push(Buffer.from(JSON.stringify(init), 'utf-8'));
+        // Parse the initiator's signing public key
+        const initiatorSigningKey = crypto.createPublicKey(init.signingPubKey);
+        // Check if this key is authorized
+        const authorized = this.authorizedKeys.find((ak) => {
+            const akPem = ak.signing.export({ type: 'spki', format: 'pem' });
+            return akPem === init.signingPubKey;
+        });
+        if (!authorized) {
+            throw new Error('Handshake failed: initiator not authorized');
+        }
+        // Verify initiator's signature over (ephemeralPubKey || nonceI)
+        const sigValid = verifySignature(initiatorSigningKey, Buffer.from(init.signature, 'hex'), init.ephemeralPubKey, Buffer.from(init.nonceI, 'hex'));
+        if (!sigValid) {
+            throw new Error('Handshake failed: initiator signature invalid');
+        }
+        // Generate our ephemeral keypair
+        this.ephemeral = crypto.generateKeyPairSync('x25519');
+        const ephemeralPubPem = this.ephemeral.publicKey.export({
+            type: 'spki',
+            format: 'pem',
+        });
+        const nonceR = crypto.randomBytes(32);
+        // Sign (ephemeralPubKey || nonceR || nonceI)
+        const signature = signData(this.ownKeys.signing.privateKey, ephemeralPubPem, nonceR, Buffer.from(init.nonceI, 'hex'));
+        const reply = {
+            type: 'handshake_reply',
+            ephemeralPubKey: ephemeralPubPem,
+            nonceR: nonceR.toString('hex'),
+            signature: signature.toString('hex'),
+        };
+        // Record in transcript
+        this.transcript.push(Buffer.from(JSON.stringify(reply), 'utf-8'));
+        return { reply, initiatorPubKey: authorized };
+    }
+    /**
+     * Derive session keys after sending the reply.
+     * Call this after processInit() and before verifying the finish message.
+     */
+    deriveKeys(init) {
+        if (!this.ephemeral) {
+            throw new Error('Must call processInit() first');
+        }
+        // ECDH with initiator's ephemeral public key
+        const peerEphemeral = crypto.createPublicKey(init.ephemeralPubKey);
+        const sharedSecret = crypto.diffieHellman({
+            privateKey: this.ephemeral.privateKey,
+            publicKey: peerEphemeral,
+        });
+        // Hash the full transcript
+        const transcriptHash = crypto
+            .createHash('sha256')
+            .update(Buffer.concat(this.transcript))
+            .digest();
+        return deriveSessionKeys(sharedSecret, false, transcriptHash);
+    }
+    /**
+     * Step 4: Verify the finish message to confirm the initiator derived the right keys.
+     */
+    verifyFinish(finish, keys) {
+        const channel = new EncryptedChannel(keys);
+        try {
+            const payload = channel.decrypt(Buffer.from(finish.payload, 'hex'));
+            const parsed = JSON.parse(payload.toString('utf-8'));
+            return parsed.status === 'ready';
+        }
+        catch {
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=handshake.js.map

package/dist/shared/protocol/index.d.ts

@@ -0,0 +1,3 @@
+export { type HandshakeInit, type HandshakeReply, type HandshakeFinish, type HandshakeMessage, HandshakeInitiator, HandshakeResponder, } from './handshake.js';
+export { type ProxyRequest, type ProxyResponse, type PingMessage, type PongMessage, type AppMessage, } from './messages.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/protocol/index.js

@@ -0,0 +1,2 @@
+export { HandshakeInitiator, HandshakeResponder, } from './handshake.js';
+//# sourceMappingURL=index.js.map

package/dist/shared/protocol/messages.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Application-layer message types exchanged over the encrypted channel.
+ *
+ * All messages are JSON-serialized, encrypted with AES-256-GCM, and sent
+ * as hex-encoded payloads over the HTTP transport.
+ */
+/** Request from MCP proxy → remote server */
+export interface ProxyRequest {
+    type: 'proxy_request';
+    /** Unique request ID for correlation */
+    id: string;
+    /** The tool name the MCP client invoked */
+    toolName: string;
+    /** The tool's input parameters */
+    toolInput: Record<string, unknown>;
+    /** Timestamp (ms since epoch) */
+    timestamp: number;
+}
+/** Response from remote server → MCP proxy */
+export interface ProxyResponse {
+    type: 'proxy_response';
+    /** Correlates to ProxyRequest.id */
+    id: string;
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The result payload (tool output) */
+    result?: unknown;
+    /** Error message if success=false */
+    error?: string;
+    /** Timestamp */
+    timestamp: number;
+}
+/** Ping to keep the connection alive / verify the channel */
+export interface PingMessage {
+    type: 'ping';
+    timestamp: number;
+}
+/** Pong response */
+export interface PongMessage {
+    type: 'pong';
+    timestamp: number;
+    /** Echo back the ping timestamp for RTT measurement */
+    echoTimestamp: number;
+}
+export type AppMessage = ProxyRequest | ProxyResponse | PingMessage | PongMessage;
+//# sourceMappingURL=messages.d.ts.map

package/dist/shared/protocol/messages.js

@@ -0,0 +1,8 @@
+/**
+ * Application-layer message types exchanged over the encrypted channel.
+ *
+ * All messages are JSON-serialized, encrypted with AES-256-GCM, and sent
+ * as hex-encoded payloads over the HTTP transport.
+ */
+export {};
+//# sourceMappingURL=messages.js.map

package/package.json

@@ -0,0 +1,105 @@
+{
+  "name": "@wolpertingerlabs/drawlatch",
+  "version": "1.0.0-alpha.1",
+  "description": "Encrypted MCP proxy with mutual authentication. Local MCP server forwards requests through an encrypted channel to a remote secrets-holding server.",
+  "type": "module",
+  "main": "./dist/mcp/server.js",
+  "types": "./dist/mcp/server.d.ts",
+  "files": [
+    "dist",
+    "!dist/**/*.test.*",
+    "!dist/**/*.js.map",
+    "!dist/**/*.d.ts.map",
+    "README.md",
+    "CONNECTIONS.md",
+    "INGESTORS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/mcp/server.d.ts",
+      "import": "./dist/mcp/server.js"
+    },
+    "./shared/crypto": {
+      "types": "./dist/shared/crypto/index.d.ts",
+      "import": "./dist/shared/crypto/index.js"
+    },
+    "./shared/protocol": {
+      "types": "./dist/shared/protocol/index.d.ts",
+      "import": "./dist/shared/protocol/index.js"
+    },
+    "./shared/config": {
+      "types": "./dist/shared/config.d.ts",
+      "import": "./dist/shared/config.js"
+    },
+    "./shared/connections": {
+      "types": "./dist/shared/connections.d.ts",
+      "import": "./dist/shared/connections.js"
+    },
+    "./remote/server": {
+      "types": "./dist/remote/server.d.ts",
+      "import": "./dist/remote/server.js"
+    },
+    "./remote/ingestors": {
+      "types": "./dist/remote/ingestors/index.d.ts",
+      "import": "./dist/remote/ingestors/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc && rm -rf dist/connections && cp -r src/connections dist/connections",
+    "prepare": "npm run build",
+    "dev:remote": "tsx src/remote/server.ts",
+    "dev:mcp": "tsx src/mcp/server.ts",
+    "generate-keys": "tsx src/cli/generate-keys.ts",
+    "start:remote": "NODE_ENV=production node dist/remote/server.js",
+    "start:mcp": "node dist/mcp/server.js",
+    "redeploy:prod": "node start-server.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/",
+    "lint:fix": "eslint src/ --fix",
+    "format": "prettier --write 'src/**/*.ts' '*.{json,ts,js}'",
+    "format:check": "prettier --check 'src/**/*.ts' '*.{json,ts,js}'",
+    "prepublishOnly": "npm run lint && npm test && npm run build",
+    "publish:dry-run": "npm publish --dry-run"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/WolpertingerLabs/drawlatch.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "mcp",
+    "security",
+    "proxy",
+    "encryption",
+    "secrets"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "dotenv": "^17.3.1",
+    "express": "^5.2.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/express": "^5.0.6",
+    "@types/node": "^25.2.2",
+    "@vitest/coverage-v8": "^4.0.18",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "prettier": "^3.8.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.54.0",
+    "vitest": "^4.0.18"
+  }
+}