happy-mcp-server 0.1.0

package/dist/auth/crypto.js

@@ -0,0 +1,249 @@
+import { createHmac, createHash, createCipheriv, createDecipheriv, randomBytes } from 'crypto';
+import nacl from 'tweetnacl';
+// ============================================================
+// Base64 Utilities
+// ============================================================
+export function encodeBase64(buf) {
+    return Buffer.from(buf).toString('base64');
+}
+export function decodeBase64(base64) {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+}
+export function encodeBase64Url(buf) {
+    return Buffer.from(buf).toString('base64url');
+}
+export function decodeBase64Url(base64url) {
+    return new Uint8Array(Buffer.from(base64url, 'base64url'));
+}
+// ============================================================
+// HMAC-SHA512
+// ============================================================
+export function hmacSha512(key, data) {
+    const hmac = createHmac('sha512', key);
+    hmac.update(data);
+    return new Uint8Array(hmac.digest());
+}
+/**
+ * Derive root of key tree.
+ * CRITICAL: key = encode(usage + ' Master Seed'), data = seed
+ * Verified against upstream: packages/happy-agent/src/encryption.ts
+ */
+export function deriveSecretKeyTreeRoot(seed, usage) {
+    const I = hmacSha512(new TextEncoder().encode(usage + ' Master Seed'), seed);
+    return { key: I.slice(0, 32), chainCode: I.slice(32) };
+}
+/**
+ * Derive child key from chain code.
+ * data = [0x00, ...encode(index)]
+ */
+export function deriveSecretKeyTreeChild(chainCode, index) {
+    const indexBytes = new TextEncoder().encode(index);
+    const data = new Uint8Array(1 + indexBytes.length);
+    data[0] = 0x00;
+    data.set(indexBytes, 1);
+    const I = hmacSha512(chainCode, data);
+    return { key: I.slice(0, 32), chainCode: I.slice(32) };
+}
+/**
+ * Derive key at path. Root + iterate children.
+ * Test vectors:
+ *   deriveKey(encode("test seed"), "test usage", [])
+ *     => E6E55652456F9FE47D6FF46CA3614E85B499F77E7B340FBBB1553307CEDC1E74
+ *   deriveKey(encode("test seed"), "test usage", ["child1", "child2"])
+ *     => 1011C097D2105D27362B987A631496BBF68B836124D1D072E9D1613C6028CF75
+ */
+export function deriveKey(seed, usage, path) {
+    let state = deriveSecretKeyTreeRoot(seed, usage);
+    for (const index of path) {
+        state = deriveSecretKeyTreeChild(state.chainCode, index);
+    }
+    return state.key;
+}
+// ============================================================
+// Content Keypair (Curve25519 for NaCl Box)
+// ============================================================
+/**
+ * CRITICAL: Has a SHA-512 step to match libsodium's crypto_box_seed_keypair behavior.
+ * 1. Derive seed via HMAC tree
+ * 2. SHA-512(seed)[0:32] = box secret key
+ * 3. nacl.box.keyPair.fromSecretKey(boxSecretKey)
+ *
+ * Source: packages/happy-agent/src/encryption.ts:deriveContentKeyPair
+ */
+export function deriveContentKeyPair(secret) {
+    const seed = deriveKey(secret, 'Happy EnCoder', ['content']);
+    const hashedSeed = new Uint8Array(createHash('sha512').update(seed).digest());
+    const boxSecretKey = hashedSeed.slice(0, 32);
+    return nacl.box.keyPair.fromSecretKey(boxSecretKey);
+}
+// ============================================================
+// Auth Challenge (Ed25519 signing)
+// ============================================================
+/**
+ * Generate auth challenge for token refresh.
+ * CRITICAL: Uses nacl.sign.keyPair.fromSeed(secret) with the RAW account secret.
+ * NOT the derived content keypair (which is Curve25519, not Ed25519).
+ *
+ * Source: packages/happy-agent/src/encryption.ts:authChallenge
+ */
+export function authChallenge(secret) {
+    const signingKeyPair = nacl.sign.keyPair.fromSeed(secret);
+    const challenge = randomBytes(32);
+    const signature = nacl.sign.detached(challenge, signingKeyPair.secretKey);
+    return { challenge, publicKey: signingKeyPair.publicKey, signature };
+}
+// ============================================================
+// NaCl Box (Key Exchange / Decryption)
+// ============================================================
+/**
+ * Decrypt a NaCl box bundle: [ephemeralPubKey(32)][nonce(24)][ciphertext]
+ * Returns decrypted Uint8Array or null on failure.
+ *
+ * Source: packages/happy-agent/src/encryption.ts
+ */
+export function decryptBoxBundle(bundle, recipientSecretKey) {
+    if (bundle.length < 56)
+        return null; // 32 + 24 minimum
+    const ephemeralPubKey = bundle.slice(0, 32);
+    const nonce = bundle.slice(32, 56);
+    const ciphertext = bundle.slice(56);
+    return nacl.box.open(ciphertext, nonce, ephemeralPubKey, recipientSecretKey);
+}
+/**
+ * Encrypt data for a public key using NaCl box.
+ * Returns: [ephemeralPubKey(32)][nonce(24)][ciphertext]
+ */
+export function encryptForPublicKey(data, recipientPublicKey) {
+    const ephemeral = nacl.box.keyPair();
+    const nonce = randomBytes(24);
+    const encrypted = nacl.box(data, nonce, recipientPublicKey, ephemeral.secretKey);
+    if (!encrypted)
+        throw new Error('NaCl box encryption failed');
+    const result = new Uint8Array(32 + 24 + encrypted.length);
+    result.set(ephemeral.publicKey, 0);
+    result.set(nonce, 32);
+    result.set(encrypted, 56);
+    return result;
+}
+// ============================================================
+// AES-256-GCM (Modern encryption)
+// ============================================================
+/**
+ * Encrypt with AES-256-GCM.
+ * Bundle format: [version(1)=0x00][nonce(12)][ciphertext(N)][authTag(16)]
+ */
+export function encryptAesGcm(key, data) {
+    const nonce = randomBytes(12);
+    const plaintext = Buffer.from(JSON.stringify(data), 'utf-8');
+    const cipher = createCipheriv('aes-256-gcm', key, nonce);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+    const authTag = cipher.getAuthTag();
+    const result = new Uint8Array(1 + 12 + encrypted.length + 16);
+    result[0] = 0x00; // version byte
+    result.set(nonce, 1);
+    result.set(encrypted, 13);
+    result.set(authTag, 13 + encrypted.length);
+    return result;
+}
+/**
+ * Decrypt AES-256-GCM bundle.
+ * Returns parsed JSON or null on failure.
+ */
+export function decryptAesGcm(key, bundle) {
+    if (bundle.length < 29)
+        return null; // 1 + 12 + 16 minimum
+    if (bundle[0] !== 0x00)
+        return null; // version check
+    const nonce = bundle.slice(1, 13);
+    const authTag = bundle.slice(bundle.length - 16);
+    const ciphertext = bundle.slice(13, bundle.length - 16);
+    try {
+        const decipher = createDecipheriv('aes-256-gcm', key, nonce);
+        decipher.setAuthTag(authTag);
+        const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+        return JSON.parse(decrypted.toString('utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+// ============================================================
+// NaCl SecretBox (Legacy encryption)
+// ============================================================
+/**
+ * Encrypt with NaCl SecretBox.
+ * Bundle format: [nonce(24)][ciphertext]
+ */
+export function encryptSecretBox(key, data) {
+    const nonce = randomBytes(24);
+    const plaintext = new TextEncoder().encode(JSON.stringify(data));
+    const encrypted = nacl.secretbox(plaintext, nonce, key);
+    const result = new Uint8Array(24 + encrypted.length);
+    result.set(nonce, 0);
+    result.set(encrypted, 24);
+    return result;
+}
+/**
+ * Decrypt NaCl SecretBox bundle.
+ * Returns parsed JSON or null on failure.
+ */
+export function decryptSecretBox(key, bundle) {
+    if (bundle.length < 24)
+        return null;
+    const nonce = bundle.slice(0, 24);
+    const ciphertext = bundle.slice(24);
+    const decrypted = nacl.secretbox.open(ciphertext, nonce, key);
+    if (!decrypted)
+        return null;
+    try {
+        return JSON.parse(new TextDecoder().decode(decrypted));
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Encrypt data using the appropriate variant.
+ */
+export function encrypt(key, variant, data) {
+    return variant === 'dataKey' ? encryptAesGcm(key, data) : encryptSecretBox(key, data);
+}
+/**
+ * Decrypt data using the appropriate variant.
+ */
+export function decrypt(key, variant, bundle) {
+    return variant === 'dataKey' ? decryptAesGcm(key, bundle) : decryptSecretBox(key, bundle);
+}
+/**
+ * Encrypt data and return base64 string.
+ */
+export function encryptToBase64(encryption, data) {
+    return encodeBase64(encrypt(encryption.key, encryption.variant, data));
+}
+/**
+ * Decrypt base64-encoded data.
+ */
+export function decryptFromBase64(encryption, base64) {
+    return decrypt(encryption.key, encryption.variant, decodeBase64(base64));
+}
+/**
+ * Resolve session encryption key.
+ * CRITICAL: Strip version byte (first byte) before NaCl box decryption.
+ * Pass contentKeyPair.secretKey, NOT the full keypair.
+ *
+ * Source: packages/happy-agent/src/api.ts:resolveSessionEncryption
+ */
+export function resolveSessionEncryption(dataEncryptionKey, credentials) {
+    if (dataEncryptionKey) {
+        const encrypted = decodeBase64(dataEncryptionKey);
+        // CRITICAL: Strip version byte (first byte, always 0x00)
+        const bundle = encrypted.slice(1);
+        const sessionKey = decryptBoxBundle(bundle, credentials.contentKeyPair.secretKey);
+        if (!sessionKey) {
+            throw new Error('Failed to decrypt session encryption key');
+        }
+        return { key: sessionKey, variant: 'dataKey' };
+    }
+    // Legacy: use account secret directly
+    return { key: credentials.secret, variant: 'legacy' };
+}

package/dist/auth/pairing.d.ts

@@ -0,0 +1,16 @@
+import type { Credentials } from './crypto.js';
+import type { Config } from '../config.js';
+/**
+ * Load existing credentials or initiate pairing flow.
+ */
+export declare function loadOrPairCredentials(config: Config): Promise<Credentials>;
+/**
+ * Perform the QR pairing flow.
+ * 1. Generate ephemeral Curve25519 keypair
+ * 2. POST public key to relay
+ * 3. Display QR code on stderr
+ * 4. Poll until authorized
+ * 5. Decrypt account secret
+ * 6. Persist credentials
+ */
+export declare function performPairing(config: Config): Promise<Credentials>;

package/dist/auth/pairing.js

@@ -0,0 +1,90 @@
+import axios from 'axios';
+import nacl from 'tweetnacl';
+import qrcode from 'qrcode-terminal';
+import { encodeBase64, encodeBase64Url, decodeBase64, decryptBoxBundle } from './crypto.js';
+import { writeCredentials, readCredentials, validateFilePermissions } from './credentials.js';
+import { logger } from '../logger.js';
+import { AuthError } from '../errors.js';
+const POLL_INTERVAL = 1000;
+const AUTH_TIMEOUT = 120_000;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Load existing credentials or initiate pairing flow.
+ */
+export async function loadOrPairCredentials(config) {
+    const creds = readCredentials(config.credentialsPath);
+    if (creds) {
+        validateFilePermissions(config.credentialsPath);
+        logger.info('Loaded existing credentials');
+        return creds;
+    }
+    console.error('[happy-mcp] No credentials found. Starting pairing flow...');
+    return performPairing(config);
+}
+/**
+ * Perform the QR pairing flow.
+ * 1. Generate ephemeral Curve25519 keypair
+ * 2. POST public key to relay
+ * 3. Display QR code on stderr
+ * 4. Poll until authorized
+ * 5. Decrypt account secret
+ * 6. Persist credentials
+ */
+export async function performPairing(config) {
+    // 1. Generate ephemeral Curve25519 keypair
+    const seed = nacl.randomBytes(32);
+    const keypair = nacl.box.keyPair.fromSecretKey(seed);
+    const publicKeyBase64 = encodeBase64(keypair.publicKey);
+    const publicKeyBase64Url = encodeBase64Url(keypair.publicKey);
+    // 2. POST to /v1/auth/account/request
+    try {
+        await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
+            publicKey: publicKeyBase64,
+        });
+    }
+    catch (err) {
+        throw new AuthError(`Failed to initiate pairing: ${err.message}`);
+    }
+    // 3. Display QR code on stderr
+    const qrData = `happy:///account?${publicKeyBase64Url}`;
+    console.error('\nScan this QR code with the Happy app to pair:\n');
+    qrcode.generate(qrData, { small: true }, (code) => {
+        console.error(code);
+    });
+    console.error(`\nOr visit: https://app.happy.engineering/account/connect#key=${publicKeyBase64Url}\n`);
+    console.error('Waiting for authorization...');
+    // 4. Poll until authorized (with timeout)
+    const startTime = Date.now();
+    while (Date.now() - startTime < AUTH_TIMEOUT) {
+        await sleep(POLL_INTERVAL);
+        try {
+            const res = await axios.post(`${config.serverUrl}/v1/auth/account/request`, {
+                publicKey: publicKeyBase64,
+            });
+            if (res.data.state === 'authorized') {
+                // 5. Decrypt the account secret
+                const encryptedResponse = decodeBase64(res.data.response);
+                const accountSecret = decryptBoxBundle(encryptedResponse, keypair.secretKey);
+                if (!accountSecret) {
+                    throw new AuthError('Failed to decrypt pairing response');
+                }
+                // 6. Persist credentials
+                writeCredentials(config.credentialsPath, res.data.token, accountSecret, config.serverUrl);
+                console.error('[happy-mcp] Paired successfully!');
+                const creds = readCredentials(config.credentialsPath);
+                if (!creds) {
+                    throw new AuthError('Failed to read back written credentials');
+                }
+                return creds;
+            }
+        }
+        catch (err) {
+            if (err instanceof AuthError)
+                throw err;
+            logger.debug('Polling...', err.message);
+        }
+    }
+    throw new AuthError('Pairing timed out after 2 minutes. Please try again.');
+}

package/dist/auth/refresh.d.ts

@@ -0,0 +1,11 @@
+import type { Credentials } from './crypto.js';
+import type { Config } from '../config.js';
+/**
+ * Refresh the JWT token using Ed25519 challenge-response.
+ * Uses a single-flight mutex so concurrent callers share one refresh.
+ *
+ * Endpoint: POST /v1/auth
+ * Body: { challenge: base64, publicKey: base64, signature: base64 }
+ * Response: { success: boolean, token: string }
+ */
+export declare function refreshToken(credentials: Credentials, config: Config): Promise<string>;

package/dist/auth/refresh.js

@@ -0,0 +1,50 @@
+import axios from 'axios';
+import { authChallenge, encodeBase64 } from './crypto.js';
+import { writeCredentials } from './credentials.js';
+import { logger } from '../logger.js';
+import { AuthError } from '../errors.js';
+let refreshPromise = null;
+/**
+ * Refresh the JWT token using Ed25519 challenge-response.
+ * Uses a single-flight mutex so concurrent callers share one refresh.
+ *
+ * Endpoint: POST /v1/auth
+ * Body: { challenge: base64, publicKey: base64, signature: base64 }
+ * Response: { success: boolean, token: string }
+ */
+export async function refreshToken(credentials, config) {
+    // Single-flight: if a refresh is already in progress, return that promise
+    if (refreshPromise) {
+        return refreshPromise;
+    }
+    refreshPromise = doRefresh(credentials, config).finally(() => {
+        refreshPromise = null;
+    });
+    return refreshPromise;
+}
+async function doRefresh(credentials, config) {
+    logger.info('Refreshing JWT token...');
+    const { challenge, publicKey, signature } = authChallenge(credentials.secret);
+    try {
+        const res = await axios.post(`${config.serverUrl}/v1/auth`, {
+            challenge: encodeBase64(challenge),
+            publicKey: encodeBase64(publicKey),
+            signature: encodeBase64(signature),
+        });
+        if (!res.data.success || !res.data.token) {
+            throw new AuthError('Token refresh failed: server returned unsuccessful response');
+        }
+        const newToken = res.data.token;
+        // Update credentials on disk (preserve serverUrl from config)
+        writeCredentials(config.credentialsPath, newToken, credentials.secret, config.serverUrl);
+        // Update in-memory token
+        credentials.token = newToken;
+        logger.info('Token refreshed successfully');
+        return newToken;
+    }
+    catch (err) {
+        if (err instanceof AuthError)
+            throw err;
+        throw new AuthError(`Token refresh failed: ${err.message}`);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,11 @@
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export interface Config {
+    serverUrl: string;
+    computers: string[];
+    projectPaths: string[];
+    credentialsPath: string;
+    logLevel: LogLevel;
+    sessionCacheTtl: number;
+    enableStart: boolean;
+}
+export declare function loadConfig(): Config;

package/dist/config.js

@@ -0,0 +1,13 @@
+import { hostname } from 'os';
+import { homedir } from 'os';
+import { join } from 'path';
+export function loadConfig() {
+    const serverUrl = (process.env.HAPPY_SERVER_URL ?? 'https://api.cluster-fluster.com').replace(/\/+$/, '');
+    const computers = process.env.HAPPY_MCP_COMPUTERS?.split(',').map(s => s.trim()).filter(Boolean) ?? [hostname()];
+    const projectPaths = process.env.HAPPY_MCP_PROJECT_PATHS?.split(',').map(s => s.trim()).filter(Boolean) ?? [process.cwd()];
+    const credentialsPath = process.env.HAPPY_MCP_CREDENTIALS_PATH ?? join(homedir(), '.happy-mcp', 'credentials.json');
+    const logLevel = (process.env.HAPPY_MCP_LOG_LEVEL ?? 'warn');
+    const sessionCacheTtl = parseInt(process.env.HAPPY_MCP_SESSION_CACHE_TTL ?? '300', 10);
+    const enableStart = process.env.HAPPY_MCP_ENABLE_START !== 'false';
+    return { serverUrl, computers, projectPaths, credentialsPath, logLevel, sessionCacheTtl, enableStart };
+}

package/dist/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class HappyMcpError extends Error {
+    constructor(message: string);
+}
+export declare class CryptoError extends HappyMcpError {
+    constructor(message: string);
+}
+export declare class AuthError extends HappyMcpError {
+    constructor(message: string);
+}
+export declare class RelayError extends HappyMcpError {
+    constructor(message: string);
+}
+export declare class ToolError extends HappyMcpError {
+    constructor(message: string);
+}

package/dist/errors.js

@@ -0,0 +1,30 @@
+export class HappyMcpError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'HappyMcpError';
+    }
+}
+export class CryptoError extends HappyMcpError {
+    constructor(message) {
+        super(message);
+        this.name = 'CryptoError';
+    }
+}
+export class AuthError extends HappyMcpError {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthError';
+    }
+}
+export class RelayError extends HappyMcpError {
+    constructor(message) {
+        super(message);
+        this.name = 'RelayError';
+    }
+}
+export class ToolError extends HappyMcpError {
+    constructor(message) {
+        super(message);
+        this.name = 'ToolError';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};