mcp-twake-mail 0.1.0 → 1.0.0

package/build/signature/converter.test.js

@@ -0,0 +1,84 @@
+import { describe, it, expect } from 'vitest';
+import { markdownToHtml, markdownToPlainText } from './converter.js';
+describe('markdownToHtml', () => {
+    it('converts simple paragraph to HTML', () => {
+        const result = markdownToHtml('Hello world');
+        expect(result).toContain('<p>Hello world</p>');
+    });
+    it('converts bold **text** to <strong>', () => {
+        const result = markdownToHtml('This is **bold** text');
+        expect(result).toContain('<strong>bold</strong>');
+    });
+    it('converts italic *text* to <em>', () => {
+        const result = markdownToHtml('This is *italic* text');
+        expect(result).toContain('<em>italic</em>');
+    });
+    it('converts links [text](url) to <a> tags', () => {
+        const result = markdownToHtml('[Click here](https://example.com)');
+        expect(result).toContain('<a href="https://example.com">Click here</a>');
+    });
+    it('preserves paragraphs on double newlines', () => {
+        const result = markdownToHtml('Line one\n\nLine two');
+        expect(result).toContain('<p>Line one</p>');
+        expect(result).toContain('<p>Line two</p>');
+    });
+    it('converts mixed formatting correctly', () => {
+        const markdown = 'Hello **world**!\n\nThis is [a link](https://example.com)';
+        const result = markdownToHtml(markdown);
+        expect(result).toContain('<strong>world</strong>');
+        expect(result).toContain('<a href="https://example.com">a link</a>');
+    });
+});
+describe('markdownToPlainText', () => {
+    it('strips heading markers', () => {
+        expect(markdownToPlainText('# Heading 1')).toBe('Heading 1');
+        expect(markdownToPlainText('## Heading 2')).toBe('Heading 2');
+        expect(markdownToPlainText('### Heading 3')).toBe('Heading 3');
+    });
+    it('strips bold markers **text**', () => {
+        const result = markdownToPlainText('This is **bold** text');
+        expect(result).toBe('This is bold text');
+    });
+    it('strips bold markers __text__', () => {
+        const result = markdownToPlainText('This is __bold__ text');
+        expect(result).toBe('This is bold text');
+    });
+    it('strips italic markers *text*', () => {
+        const result = markdownToPlainText('This is *italic* text');
+        expect(result).toBe('This is italic text');
+    });
+    it('strips italic markers _text_', () => {
+        const result = markdownToPlainText('This is _italic_ text');
+        expect(result).toBe('This is italic text');
+    });
+    it('converts links to "text (url)" format', () => {
+        const result = markdownToPlainText('[Click here](https://example.com)');
+        expect(result).toBe('Click here (https://example.com)');
+    });
+    it('strips inline code backticks', () => {
+        const result = markdownToPlainText('Use `const` instead of `var`');
+        expect(result).toBe('Use const instead of var');
+    });
+    it('converts list markers to bullets', () => {
+        const markdown = '* Item 1\n- Item 2\n+ Item 3';
+        const result = markdownToPlainText(markdown);
+        expect(result).toContain('• Item 1');
+        expect(result).toContain('• Item 2');
+        expect(result).toContain('• Item 3');
+    });
+    it('handles mixed formatting', () => {
+        const markdown = '## Welcome\n\nThis is **bold** and *italic*.\n\n[Link](https://example.com)';
+        const result = markdownToPlainText(markdown);
+        expect(result).toContain('Welcome');
+        expect(result).toContain('This is bold and italic.');
+        expect(result).toContain('Link (https://example.com)');
+        expect(result).not.toContain('##');
+        expect(result).not.toContain('**');
+        expect(result).not.toContain('*');
+    });
+    it('trims whitespace', () => {
+        const result = markdownToPlainText('  \n\nHello  \n\n  ');
+        expect(result).toBe('Hello');
+    });
+});
+//# sourceMappingURL=converter.test.js.map

package/build/signature/converter.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"converter.test.js","sourceRoot":"","sources":["../../src/signature/converter.test.ts"],"names":[],"mappings":"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"}

package/build/signature/index.d.ts

@@ -0,0 +1,2 @@
+export { loadSignature, type SignatureContent } from './loader.js';
+export { markdownToHtml, markdownToPlainText } from './converter.js';

package/build/signature/index.js

@@ -0,0 +1,3 @@
+export { loadSignature } from './loader.js';
+export { markdownToHtml, markdownToPlainText } from './converter.js';
+//# sourceMappingURL=index.js.map

package/build/signature/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/signature/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAyB,MAAM,aAAa,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC"}

package/build/signature/loader.d.ts

@@ -0,0 +1,6 @@
+import type { Logger } from '../config/logger.js';
+export interface SignatureContent {
+    text: string;
+    html: string;
+}
+export declare function loadSignature(signaturePath: string | undefined, logger: Logger): Promise<SignatureContent | undefined>;

package/build/signature/loader.js

@@ -0,0 +1,31 @@
+import { readFile, access } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { homedir } from 'node:os';
+import { markdownToHtml, markdownToPlainText } from './converter.js';
+export async function loadSignature(signaturePath, logger) {
+    if (!signaturePath) {
+        logger.debug('No signature path configured');
+        return undefined;
+    }
+    // Expand ~ to home directory
+    const expandedPath = signaturePath.replace(/^~/, homedir());
+    try {
+        // Check file exists and is readable
+        await access(expandedPath, constants.R_OK);
+        // Read file content
+        const markdown = await readFile(expandedPath, 'utf-8');
+        // Convert to both formats
+        const result = {
+            text: markdownToPlainText(markdown),
+            html: markdownToHtml(markdown),
+        };
+        logger.info({ path: expandedPath }, 'Signature loaded successfully');
+        return result;
+    }
+    catch (error) {
+        // Don't crash if file missing - just log warning
+        logger.warn({ error, path: expandedPath }, 'Failed to load signature file - emails will be sent without signature');
+        return undefined;
+    }
+}
+//# sourceMappingURL=loader.js.map

package/build/signature/loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.js","sourceRoot":"","sources":["../../src/signature/loader.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAOrE,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,aAAiC,EACjC,MAAc;IAEd,IAAI,CAAC,aAAa,EAAE,CAAC;QACnB,MAAM,CAAC,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC7C,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,6BAA6B;IAC7B,MAAM,YAAY,GAAG,aAAa,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;IAE5D,IAAI,CAAC;QACH,oCAAoC;QACpC,MAAM,MAAM,CAAC,YAAY,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;QAE3C,oBAAoB;QACpB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QAEvD,0BAA0B;QAC1B,MAAM,MAAM,GAAqB;YAC/B,IAAI,EAAE,mBAAmB,CAAC,QAAQ,CAAC;YACnC,IAAI,EAAE,cAAc,CAAC,QAAQ,CAAC;SAC/B,CAAC;QAEF,MAAM,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,EAAE,+BAA+B,CAAC,CAAC;QACrE,OAAO,MAAM,CAAC;IAChB,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,iDAAiD;QACjD,MAAM,CAAC,IAAI,CACT,EAAE,KAAK,EAAE,IAAI,EAAE,YAAY,EAAE,EAC7B,uEAAuE,CACxE,CAAC;QACF,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/build/signature/loader.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/signature/loader.test.js

@@ -0,0 +1,85 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { homedir } from 'node:os';
+import { loadSignature } from './loader.js';
+// Mock fs/promises
+vi.mock('node:fs/promises', () => ({
+    readFile: vi.fn(),
+    access: vi.fn(),
+}));
+// Import after mocking
+const { readFile, access } = await import('node:fs/promises');
+describe('loadSignature', () => {
+    let mockLogger;
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockLogger = {
+            debug: vi.fn(),
+            info: vi.fn(),
+            warn: vi.fn(),
+            error: vi.fn(),
+            fatal: vi.fn(),
+            trace: vi.fn(),
+            child: vi.fn(),
+        };
+    });
+    it('returns undefined when signaturePath is undefined', async () => {
+        const result = await loadSignature(undefined, mockLogger);
+        expect(result).toBeUndefined();
+        expect(mockLogger.debug).toHaveBeenCalledWith('No signature path configured');
+        expect(access).not.toHaveBeenCalled();
+    });
+    it('returns undefined when signaturePath is empty string', async () => {
+        const result = await loadSignature('', mockLogger);
+        expect(result).toBeUndefined();
+        expect(mockLogger.debug).toHaveBeenCalledWith('No signature path configured');
+        expect(access).not.toHaveBeenCalled();
+    });
+    it('loads and converts file successfully', async () => {
+        const markdown = '**John Doe**\nSoftware Engineer\n[email@example.com](mailto:email@example.com)';
+        vi.mocked(access).mockResolvedValue(undefined);
+        vi.mocked(readFile).mockResolvedValue(markdown);
+        const result = await loadSignature('/path/to/signature.md', mockLogger);
+        expect(result).toBeDefined();
+        expect(result?.text).toContain('John Doe');
+        expect(result?.text).toContain('Software Engineer');
+        expect(result?.text).toContain('email@example.com (mailto:email@example.com)');
+        expect(result?.html).toContain('<strong>John Doe</strong>');
+        expect(result?.html).toContain('<a href="mailto:email@example.com">email@example.com</a>');
+        expect(mockLogger.info).toHaveBeenCalledWith({ path: '/path/to/signature.md' }, 'Signature loaded successfully');
+    });
+    it('expands ~ to home directory', async () => {
+        const markdown = 'Test signature';
+        const expectedPath = `${homedir()}/signature.md`;
+        vi.mocked(access).mockResolvedValue(undefined);
+        vi.mocked(readFile).mockResolvedValue(markdown);
+        await loadSignature('~/signature.md', mockLogger);
+        expect(access).toHaveBeenCalledWith(expectedPath, expect.any(Number));
+        expect(readFile).toHaveBeenCalledWith(expectedPath, 'utf-8');
+        expect(mockLogger.info).toHaveBeenCalledWith({ path: expectedPath }, 'Signature loaded successfully');
+    });
+    it('returns undefined and logs warning when file does not exist', async () => {
+        const error = new Error('ENOENT: no such file or directory');
+        vi.mocked(access).mockRejectedValue(error);
+        const result = await loadSignature('/nonexistent/signature.md', mockLogger);
+        expect(result).toBeUndefined();
+        expect(mockLogger.warn).toHaveBeenCalledWith({ error, path: '/nonexistent/signature.md' }, 'Failed to load signature file - emails will be sent without signature');
+        expect(readFile).not.toHaveBeenCalled();
+    });
+    it('returns undefined and logs warning when file is not readable', async () => {
+        const error = new Error('EACCES: permission denied');
+        vi.mocked(access).mockRejectedValue(error);
+        const result = await loadSignature('/restricted/signature.md', mockLogger);
+        expect(result).toBeUndefined();
+        expect(mockLogger.warn).toHaveBeenCalledWith({ error, path: '/restricted/signature.md' }, 'Failed to load signature file - emails will be sent without signature');
+        expect(readFile).not.toHaveBeenCalled();
+    });
+    it('returns undefined and logs warning when readFile fails', async () => {
+        const error = new Error('Read error');
+        vi.mocked(access).mockResolvedValue(undefined);
+        vi.mocked(readFile).mockRejectedValue(error);
+        const result = await loadSignature('/path/to/signature.md', mockLogger);
+        expect(result).toBeUndefined();
+        expect(mockLogger.warn).toHaveBeenCalledWith({ error, path: '/path/to/signature.md' }, 'Failed to load signature file - emails will be sent without signature');
+    });
+});
+//# sourceMappingURL=loader.test.js.map

package/build/signature/loader.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loader.test.js","sourceRoot":"","sources":["../../src/signature/loader.test.ts"],"names":[],"mappings":"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"}

package/docs/auto-discovery.md

@@ -0,0 +1,210 @@
+# Auto-Discovery
+
+mcp-twake-mail supports automatic discovery of JMAP server and OIDC configuration from just an email address. This simplifies setup by eliminating the need to manually find server URLs.
+
+## How It Works
+
+When you provide an email address (e.g., `user@example.com`), the auto-discovery system performs the following steps:
+
+### 1. DNS SRV Lookup
+
+First, the system queries DNS for a SRV record:
+
+```
+_jmap._tcp.example.com
+```
+
+If found, this returns the JMAP server hostname and port. For example:
+```
+_jmap._tcp.example.com. 3600 IN SRV 0 1 443 jmap.example.com.
+```
+
+This indicates the JMAP server is at `jmap.example.com` on port 443.
+
+### 2. Well-Known JMAP Endpoint
+
+If DNS SRV fails or as a verification step, the system tries the `.well-known/jmap` endpoint:
+
+```
+https://example.com/.well-known/jmap
+```
+
+This endpoint should redirect (302/307) or return the JMAP session URL directly. Per RFC 8620, the response provides the full session URL like:
+```
+https://jmap.example.com/jmap/session
+```
+
+### 3. OAuth/OIDC Discovery
+
+Once the JMAP server is found, the system attempts to discover OAuth/OIDC configuration:
+
+#### Protected Resource Metadata (RFC 9728)
+
+The system checks for OAuth metadata at the JMAP URL:
+```
+https://jmap.example.com/.well-known/oauth-protected-resource
+```
+
+This may return the authorization server (OIDC issuer) URL.
+
+#### WWW-Authenticate Header
+
+If the above fails, the system makes an unauthenticated request to the JMAP session URL and parses the `WWW-Authenticate` header:
+
+```http
+WWW-Authenticate: Bearer realm="example.com", authorization_uri="https://sso.example.com"
+```
+
+#### Common SSO Patterns
+
+As a fallback, the system tries common SSO subdomain patterns:
+- `https://sso.example.com`
+- `https://auth.example.com`
+- `https://login.example.com`
+- `https://id.example.com`
+- `https://accounts.example.com`
+
+For each, it checks if `/.well-known/openid-configuration` exists.
+
+## Using Auto-Discovery
+
+### Setup Wizard
+
+Run the setup wizard and choose auto-discovery mode:
+
+```bash
+npx mcp-twake-mail setup
+```
+
+```
+=== MCP Twake Mail Setup Wizard ===
+
+Setup mode:
+  1. Auto-discover from email address (Recommended)
+  2. Manual configuration
+Choose [1-2]: 1
+
+Email address: user@example.com
+
+Discovering JMAP server...
+✓ Found JMAP server: https://jmap.example.com/jmap/session
+✓ Found OIDC issuer: https://sso.example.com
+
+Use discovered settings? [Y/n]: y
+```
+
+### Programmatic Usage
+
+The discovery module can be used programmatically:
+
+```typescript
+import { discoverFromEmail } from 'mcp-twake-mail/discovery';
+
+const result = await discoverFromEmail('user@example.com');
+
+console.log(result.jmapUrl);    // https://jmap.example.com/jmap/session
+console.log(result.jmapMethod); // 'dns-srv' | 'well-known'
+
+if (result.oidc) {
+  console.log(result.oidc.issuer);   // https://sso.example.com
+  console.log(result.oidc.method);   // 'protected-resource' | 'www-authenticate' | 'sso-pattern'
+}
+```
+
+## Discovery Methods
+
+### JMAP Discovery
+
+| Method | Priority | Description |
+|--------|----------|-------------|
+| DNS SRV | 1 (first) | `_jmap._tcp.{domain}` lookup |
+| .well-known/jmap | 2 (fallback) | HTTPS endpoint at domain root |
+
+### OIDC Discovery
+
+| Method | Priority | Description |
+|--------|----------|-------------|
+| Protected Resource Metadata | 1 | RFC 9728 OAuth metadata |
+| WWW-Authenticate | 2 | Parse Bearer challenge header |
+| SSO Patterns | 3 | Try common subdomain patterns |
+
+## Configuration After Discovery
+
+After discovery, you'll have:
+
+- **JMAP Session URL** — Required for all operations
+- **OIDC Issuer** — Optional, for OAuth authentication
+
+You can then choose your authentication method:
+
+1. **Basic** — Username/password (no OIDC needed)
+2. **Bearer** — Pre-existing JWT token (no OIDC needed)
+3. **OIDC** — Full OAuth flow using discovered issuer
+
+## Timeout Handling
+
+All discovery operations have built-in timeouts:
+
+| Operation | Timeout |
+|-----------|---------|
+| DNS SRV lookup | 3 seconds |
+| HTTP requests | 10 seconds |
+
+If discovery fails or times out, the setup wizard automatically falls back to manual configuration.
+
+## Troubleshooting
+
+### DNS SRV Not Found
+
+This is normal for many domains. The system will automatically try `.well-known/jmap`.
+
+### .well-known/jmap Returns 404
+
+The domain doesn't support JMAP auto-discovery. You'll need to manually enter the JMAP session URL.
+
+### OIDC Discovery Fails
+
+OIDC discovery is optional. If it fails:
+- You can still use Basic or Bearer authentication
+- You can manually enter the OIDC issuer URL
+
+### Firewall Blocking DNS
+
+Corporate firewalls may block DNS SRV queries. The system will fall back to HTTPS-based discovery.
+
+## Server Requirements
+
+For auto-discovery to work, your JMAP server should implement:
+
+### RFC 8620 Service Discovery
+
+1. **DNS SRV record** (recommended):
+   ```
+   _jmap._tcp.example.com. 3600 IN SRV 0 1 443 jmap.example.com.
+   ```
+
+2. **.well-known/jmap endpoint**:
+   ```
+   https://example.com/.well-known/jmap
+   ```
+   Should redirect to or return the JMAP session URL.
+
+### OAuth Discovery (Optional)
+
+For OIDC auto-discovery:
+
+1. **Protected Resource Metadata** (RFC 9728):
+   ```
+   https://jmap.example.com/.well-known/oauth-protected-resource
+   ```
+
+2. **WWW-Authenticate header** on 401 responses:
+   ```
+   WWW-Authenticate: Bearer realm="example.com", authorization_uri="https://sso.example.com"
+   ```
+
+## References
+
+- [RFC 8620](https://datatracker.ietf.org/doc/html/rfc8620) — JMAP Core (Section 2.2: Service Autodiscovery)
+- [RFC 9728](https://datatracker.ietf.org/doc/html/rfc9728) — OAuth 2.0 Protected Resource Metadata
+- [OpenID Connect Discovery](https://openid.net/specs/openid-connect-discovery-1_0.html) — OIDC Discovery specification