@littlebearapps/outlook-assistant 3.3.0

package/outlook-auth-server.js

@@ -0,0 +1,384 @@
+#!/usr/bin/env node
+const http = require('http');
+const crypto = require('crypto');
+const url = require('url');
+const querystring = require('querystring');
+const https = require('https');
+const fs = require('fs');
+
+/**
+ * Escapes HTML special characters to prevent XSS in rendered responses.
+ */
+function escapeHtml(str) {
+  if (typeof str !== 'string') return '';
+  return str
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+// Security headers for all HTML responses
+const SECURITY_HEADERS = {
+  'Content-Type': 'text/html',
+  'X-Content-Type-Options': 'nosniff',
+  'X-Frame-Options': 'DENY',
+  'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'",
+};
+
+// Pending OAuth state tokens for CSRF validation
+const pendingStates = new Map();
+
+// Load environment variables from .env file
+require('dotenv').config();
+
+// Import scopes and token path from central config to stay in sync
+const { AUTH_CONFIG: centralAuth } = require('./config');
+
+// Log to console
+console.log('Starting Outlook Authentication Server');
+
+// Authentication configuration — scopes and tokenStorePath from config.js (single source of truth)
+const AUTH_CONFIG = {
+  clientId: process.env.OUTLOOK_CLIENT_ID || process.env.MS_CLIENT_ID || '',
+  clientSecret:
+    process.env.OUTLOOK_CLIENT_SECRET || process.env.MS_CLIENT_SECRET || '',
+  redirectUri: centralAuth.redirectUri,
+  scopes: centralAuth.scopes,
+  tokenStorePath: centralAuth.tokenStorePath,
+};
+
+// Create HTTP server
+const server = http.createServer((req, res) => {
+  const parsedUrl = url.parse(req.url, true);
+  const pathname = parsedUrl.pathname;
+
+  console.log(`Request received: ${pathname}`);
+
+  if (pathname === '/auth/callback') {
+    const query = parsedUrl.query;
+
+    if (query.error) {
+      console.error(
+        `Authentication error: ${query.error} - ${query.error_description}`
+      );
+      res.writeHead(400, SECURITY_HEADERS);
+      res.end(`
+        <html>
+          <head>
+            <title>Authentication Error</title>
+            <style>
+              body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; }
+              h1 { color: #d9534f; }
+              .error-box { background-color: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 4px; }
+            </style>
+          </head>
+          <body>
+            <h1>Authentication Error</h1>
+            <div class="error-box">
+              <p><strong>Error:</strong> ${escapeHtml(query.error)}</p>
+              <p><strong>Description:</strong> ${escapeHtml(query.error_description || 'No description provided')}</p>
+            </div>
+            <p>Please close this window and try again.</p>
+          </body>
+        </html>
+      `);
+      return;
+    }
+
+    if (query.code) {
+      // Validate OAuth state parameter for CSRF protection
+      if (!query.state || !pendingStates.has(query.state)) {
+        console.error('Invalid or missing OAuth state parameter');
+        res.writeHead(403, SECURITY_HEADERS);
+        res.end(`
+            <html>
+              <head>
+                <title>Invalid State</title>
+                <style>
+                  body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; }
+                  h1 { color: #d9534f; }
+                  .error-box { background-color: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 4px; }
+                </style>
+              </head>
+              <body>
+                <h1>Invalid Request</h1>
+                <div class="error-box">
+                  <p>The OAuth state parameter is invalid or expired. This may indicate a CSRF attempt.</p>
+                </div>
+                <p>Please close this window and try authenticating again.</p>
+              </body>
+            </html>
+          `);
+        return;
+      }
+      pendingStates.delete(query.state);
+
+      console.log('Authorization code received, exchanging for tokens...');
+
+      // Exchange code for tokens
+      exchangeCodeForTokens(query.code)
+        .then((_tokens) => {
+          console.log('Token exchange successful');
+          res.writeHead(200, SECURITY_HEADERS);
+          res.end(`
+            <html>
+              <head>
+                <title>Authentication Successful</title>
+                <style>
+                  body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; }
+                  h1 { color: #5cb85c; }
+                  .success-box { background-color: #d4edda; border: 1px solid #c3e6cb; padding: 15px; border-radius: 4px; }
+                </style>
+              </head>
+              <body>
+                <h1>Authentication Successful!</h1>
+                <div class="success-box">
+                  <p>You have successfully authenticated with Microsoft Graph API.</p>
+                  <p>The access token has been saved securely.</p>
+                </div>
+                <p>You can now close this window and return to your AI assistant.</p>
+              </body>
+            </html>
+          `);
+        })
+        .catch((error) => {
+          console.error(`Token exchange error: ${error.message}`);
+          res.writeHead(500, SECURITY_HEADERS);
+          res.end(`
+            <html>
+              <head>
+                <title>Token Exchange Error</title>
+                <style>
+                  body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; }
+                  h1 { color: #d9534f; }
+                  .error-box { background-color: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 4px; }
+                </style>
+              </head>
+              <body>
+                <h1>Token Exchange Error</h1>
+                <div class="error-box">
+                  <p>Token exchange failed. Please try authenticating again.</p>
+                </div>
+                <p>Please close this window and try again.</p>
+              </body>
+            </html>
+          `);
+        });
+    } else {
+      console.error('No authorization code provided');
+      res.writeHead(400, SECURITY_HEADERS);
+      res.end(`
+        <html>
+          <head>
+            <title>Missing Authorization Code</title>
+            <style>
+              body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; }
+              h1 { color: #d9534f; }
+              .error-box { background-color: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 4px; }
+            </style>
+          </head>
+          <body>
+            <h1>Missing Authorization Code</h1>
+            <div class="error-box">
+              <p>No authorization code was provided in the callback.</p>
+            </div>
+            <p>Please close this window and try again.</p>
+          </body>
+        </html>
+      `);
+    }
+  } else if (pathname === '/auth') {
+    // Handle the /auth route - redirect to Microsoft's OAuth authorization endpoint
+    console.log('Auth request received, redirecting to Microsoft login...');
+
+    // Verify credentials are set
+    if (!AUTH_CONFIG.clientId || !AUTH_CONFIG.clientSecret) {
+      res.writeHead(500, SECURITY_HEADERS);
+      res.end(`
+        <html>
+          <head>
+            <title>Configuration Error</title>
+            <style>
+              body { font-family: Arial, sans-serif; max-width: 600px; margin: 0 auto; padding: 20px; }
+              h1 { color: #d9534f; }
+              .error-box { background-color: #f8d7da; border: 1px solid #f5c6cb; padding: 15px; border-radius: 4px; }
+              code { background: #f4f4f4; padding: 2px 4px; border-radius: 4px; }
+            </style>
+          </head>
+          <body>
+            <h1>Configuration Error</h1>
+            <div class="error-box">
+              <p>Microsoft Graph API credentials are not set. Please set the following environment variables:</p>
+              <ul>
+                <li><code>OUTLOOK_CLIENT_ID</code></li>
+                <li><code>OUTLOOK_CLIENT_SECRET</code></li>
+              </ul>
+              <p style="margin-top: 10px; font-size: 0.9em; color: #666;">Legacy names <code>MS_CLIENT_ID</code> / <code>MS_CLIENT_SECRET</code> are also accepted.</p>
+            </div>
+          </body>
+        </html>
+      `);
+      return;
+    }
+
+    // Get client_id from query parameters or use the default
+    const query = parsedUrl.query;
+    const clientId = query.client_id || AUTH_CONFIG.clientId;
+
+    // Generate cryptographically secure state for CSRF protection
+    const state = crypto.randomUUID();
+    pendingStates.set(state, Date.now());
+
+    // Clean up expired states (older than 10 minutes)
+    const TEN_MINUTES = 10 * 60 * 1000;
+    for (const [key, timestamp] of pendingStates) {
+      if (Date.now() - timestamp > TEN_MINUTES) pendingStates.delete(key);
+    }
+
+    // Build the authorization URL
+    const authParams = {
+      client_id: clientId,
+      response_type: 'code',
+      redirect_uri: AUTH_CONFIG.redirectUri,
+      scope: AUTH_CONFIG.scopes.join(' '),
+      response_mode: 'query',
+      state,
+    };
+
+    const authUrl = `https://login.microsoftonline.com/common/oauth2/v2.0/authorize?${querystring.stringify(authParams)}`;
+    console.log(`Redirecting to: ${authUrl}`);
+
+    // Redirect to Microsoft's login page
+    res.writeHead(302, { Location: authUrl });
+    res.end();
+  } else if (pathname === '/') {
+    // Root path - provide instructions
+    res.writeHead(200, SECURITY_HEADERS);
+    res.end(`
+      <html>
+        <head>
+          <title>Outlook Authentication Server</title>
+          <style>
+            body { font-family: Arial, sans-serif; max-width: 800px; margin: 0 auto; padding: 20px; }
+            h1 { color: #0078d4; }
+            .info-box { background-color: #e7f6fd; border: 1px solid #b3e0ff; padding: 15px; border-radius: 4px; }
+            code { background: #f4f4f4; padding: 2px 4px; border-radius: 4px; }
+          </style>
+        </head>
+        <body>
+          <h1>Outlook Authentication Server</h1>
+          <div class="info-box">
+            <p>This server is running to handle Microsoft Graph API authentication callbacks.</p>
+            <p>Don't navigate here directly. Instead, use the <code>auth</code> tool (with <code>action=authenticate</code>) in your AI assistant to start the authentication process.</p>
+            <p>Make sure you've set the <code>OUTLOOK_CLIENT_ID</code> and <code>OUTLOOK_CLIENT_SECRET</code> environment variables.</p>
+          </div>
+          <p>Server is running at http://localhost:3333</p>
+        </body>
+      </html>
+    `);
+  } else {
+    // Not found
+    res.writeHead(404, { 'Content-Type': 'text/plain' });
+    res.end('Not Found');
+  }
+});
+
+function exchangeCodeForTokens(code) {
+  return new Promise((resolve, reject) => {
+    const postData = querystring.stringify({
+      client_id: AUTH_CONFIG.clientId,
+      client_secret: AUTH_CONFIG.clientSecret,
+      code: code,
+      redirect_uri: AUTH_CONFIG.redirectUri,
+      grant_type: 'authorization_code',
+      scope: AUTH_CONFIG.scopes.join(' '),
+    });
+
+    const options = {
+      hostname: 'login.microsoftonline.com',
+      path: '/common/oauth2/v2.0/token',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'Content-Length': Buffer.byteLength(postData),
+      },
+    };
+
+    const req = https.request(options, (res) => {
+      let data = '';
+
+      res.on('data', (chunk) => {
+        data += chunk;
+      });
+
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try {
+            const tokenResponse = JSON.parse(data);
+
+            // Calculate expiration time (current time + expires_in seconds)
+            const expiresAt = Date.now() + tokenResponse.expires_in * 1000;
+
+            // Add expires_at for easier expiration checking
+            tokenResponse.expires_at = expiresAt;
+
+            // Save tokens to file
+            fs.writeFileSync(
+              AUTH_CONFIG.tokenStorePath,
+              JSON.stringify(tokenResponse, null, 2),
+              { encoding: 'utf8', mode: 0o600 }
+            );
+            console.log(`Tokens saved to ${AUTH_CONFIG.tokenStorePath}`);
+
+            resolve(tokenResponse);
+          } catch (error) {
+            reject(new Error(`Error parsing token response: ${error.message}`));
+          }
+        } else {
+          reject(
+            new Error(
+              `Token exchange failed with status ${res.statusCode}: ${data}`
+            )
+          );
+        }
+      });
+    });
+
+    req.on('error', (error) => {
+      reject(error);
+    });
+
+    req.write(postData);
+    req.end();
+  });
+}
+
+// Start server
+const PORT = 3333;
+server.listen(PORT, '127.0.0.1', () => {
+  console.log(`Authentication server running at http://localhost:${PORT}`);
+  console.log(
+    `Waiting for authentication callback at ${AUTH_CONFIG.redirectUri}`
+  );
+  console.log(`Token will be stored at: ${AUTH_CONFIG.tokenStorePath}`);
+
+  if (!AUTH_CONFIG.clientId || !AUTH_CONFIG.clientSecret) {
+    console.log('\n⚠️  WARNING: Microsoft Graph API credentials are not set.');
+    console.log(
+      '   Please set the OUTLOOK_CLIENT_ID and OUTLOOK_CLIENT_SECRET environment variables.'
+    );
+  }
+});
+
+// Handle termination
+process.on('SIGINT', () => {
+  console.log('Authentication server shutting down');
+  process.exit(0);
+});
+
+process.on('SIGTERM', () => {
+  console.log('Authentication server shutting down');
+  process.exit(0);
+});

package/package.json

@@ -0,0 +1,97 @@
+{
+  "name": "@littlebearapps/outlook-assistant",
+  "version": "3.3.0",
+  "mcpName": "io.github.littlebearapps/outlook-assistant",
+  "description": "Outlook Assistant — MCP server with 20 tools for email, calendar, contacts, and settings via Microsoft Graph API",
+  "main": "index.js",
+  "bin": {
+    "outlook-assistant": "./index.js"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "auth-server": "node outlook-auth-server.js",
+    "test-mode": "USE_TEST_MODE=true node index.js",
+    "inspect": "npx @modelcontextprotocol/inspector node index.js",
+    "test": "jest",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "prepare": "husky"
+  },
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{md,json,yml,yaml}": [
+      "prettier --write"
+    ]
+  },
+  "keywords": [
+    "claude",
+    "outlook",
+    "mcp",
+    "microsoft-graph",
+    "email",
+    "calendar",
+    "contacts",
+    "model-context-protocol",
+    "anthropic"
+  ],
+  "author": "Little Bear Apps <hello@littlebearapps.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/littlebearapps/outlook-assistant.git"
+  },
+  "homepage": "https://littlebearapps.com/builds/outlook-assistant",
+  "bugs": {
+    "url": "https://github.com/littlebearapps/outlook-assistant/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "index.js",
+    "config.js",
+    "outlook-auth-server.js",
+    "auth/",
+    "calendar/",
+    "categories/",
+    "contacts/",
+    "email/",
+    "folder/",
+    "rules/",
+    "settings/",
+    "advanced/",
+    "utils/",
+    ".env.example",
+    "README.md",
+    "LICENSE",
+    "llms.txt"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "dotenv": "^17.3.1"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^20.4.3",
+    "@commitlint/config-conventional": "^20.4.3",
+    "@eslint/js": "^10.0.1",
+    "@modelcontextprotocol/inspector": "^0.21.1",
+    "eslint": "^10.0.2",
+    "globals": "^17.4.0",
+    "husky": "^9.1.7",
+    "jest": "^30.2.0",
+    "lint-staged": "^16.3.2",
+    "prettier": "^3.8.1",
+    "supertest": "^7.2.2"
+  },
+  "engines": {
+    "node": ">=18.18.0"
+  },
+  "overrides": {
+    "minimatch": ">=3.1.3"
+  }
+}