fluxmail 0.13.0 → 0.15.0

package/dist/cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
 import { emitKeypressEvents } from 'node:readline';
 import { createInterface } from 'node:readline/promises';
 import { hostname } from 'node:os';
@@ -17,6 +18,7 @@ import { createApp } from './http/app.js';
 import { buildMcpServer } from './mcp/buildServer.js';
 import { runLoopbackFlow } from './accounts/googleAuth.js';
 import { runMicrosoftLoopbackFlow } from './accounts/microsoftAuth.js';
+import { IMAP_CONNECTION_TEST_TIMEOUT_MS } from './accounts/registry.js';
 import { assertHostedConnectionReady, prepareHostedGmailConnection, prepareHostedOutlookConnection, selectGmailConnectionMode, validateAccountConnectionFlags, } from './accounts/gmailConnection.js';
 import { listApiKeys } from './storage/apiKeys.js';
 import { findMember } from './storage/members.js';
@@ -24,9 +26,9 @@ import { LICENSE_KEY_PATTERN } from './licensing/client.js';
 import { checkLicenseState, getEntitlements } from './licensing/entitlements.js';
 import { VERSION } from './version.js';
 import { inspectStoreCompatibility, MIN_SUPPORTED_STORE_FORMAT, openDb, openReadonlyDb, } from './storage/db.js';
-import { customPermissionPolicy, ADMIN_CAPABILITIES, FULL_PERMISSION_POLICY, isNamedPermissionProfile, MCP_CAPABILITIES, NAMED_PERMISSION_PROFILES, permissionPolicyForProfile, } from './permissions.js';
+import { customPermissionPolicy, ADMIN_CAPABILITIES, DEFAULT_PERMISSION_POLICY, DEFAULT_PERMISSION_PROFILE, isNamedPermissionProfile, MCP_CAPABILITIES, NAMED_PERMISSION_PROFILES, permissionPolicyForProfile, } from './permissions.js';
 import { captureOperation, getTelemetry, installTelemetryStreamEndHandler, isTelemetryEnabled, setTelemetryEnabled, shutdownTelemetry, telemetryDisabledInAnyEnvironment, } from './telemetry.js';
-import { apiErrorCode, apiRequestId, clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, resolveStdioInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, setRequestDeadlineMs, useInstance, } from './cliInstances.js';
+import { apiErrorCode, CliCanceledError, apiRequestId, clearSessionToken, instanceClient, loadInstanceConfig, removeInstance, resolveInstance, resolveStdioInstance, saveLocalInstance, saveRemoteInstance, saveSessionToken, setRequestDeadlineMs, useInstance, } from './cliInstances.js';
 import { cliExitCode, parseOutputFormat, printOutput } from './cliOutput.js';
 import { CliStartupError, cliStartupDiagnostics } from './cliStartupDiagnostics.js';
 import { authenticateBearer, isBootstrapComplete, normalizeAndValidatePassword, recoverAdminPassword, setupInitialAdmin, } from './auth.js';
@@ -34,7 +36,7 @@ import { recordAdminAuditEvent } from './storage/adminAudit.js';
 import { canManageOwnedAccount } from './authorization.js';
 import { createCliUpdateNotifier } from './updateNotifier.js';
 import { registerMailCommands } from './cliMail.js';
-import { accountInventoryProperties, configuredOAuthAppKind, connectionProperties, instanceUsageProperties, } from './accounts/telemetry.js';
+import { accountInventoryProperties, connectionFailureKind, configuredOAuthAppKind, connectionProperties, instanceUsageProperties, } from './accounts/telemetry.js';
 import { flushLogging, escapeLogTextForConsole, getLogger, logCodedFailure, logFailure, readLocalLogs, shutdownLogging, } from './logging.js';
 function collectOption(value, previous) {
     return [...previous, value];
@@ -45,25 +47,24 @@ function accountIdsFromRefs(ctx, refs) {
 export function permissionPolicyFromOptions(opts, requireSelection = false) {
     try {
         const supplemental = opts.admin ?? [];
-        if (opts.profile && opts.allow.length) {
-            throw new Error('--profile cannot be combined with --allow.');
-        }
-        if (opts.allow.length && supplemental.length) {
+        if (!opts.profile && opts.allow.length && supplemental.length) {
             throw new Error('--admin can only be combined with a named --profile. Put admin capabilities in --allow for a custom policy.');
         }
         if (opts.profile) {
             if (!isNamedPermissionProfile(opts.profile)) {
                 throw new Error(`Unknown profile "${opts.profile}". Expected one of: ${NAMED_PERMISSION_PROFILES.join(', ')}.`);
             }
-            return permissionPolicyForProfile(opts.profile, supplemental);
+            const named = permissionPolicyForProfile(opts.profile, supplemental);
+            // --allow adds capabilities to the profile, which makes the result a custom policy.
+            return opts.allow.length ? customPermissionPolicy([...named.capabilities, ...opts.allow]) : named;
         }
         if (opts.allow.length)
             return customPermissionPolicy(opts.allow);
         if (supplemental.length)
-            return permissionPolicyForProfile('full', supplemental);
+            return permissionPolicyForProfile(DEFAULT_PERMISSION_PROFILE, supplemental);
         if (requireSelection)
             throw new Error('Choose --profile or at least one --allow capability.');
-        return FULL_PERMISSION_POLICY;
+        return DEFAULT_PERMISSION_POLICY;
     }
     catch (error) {
         throw new EmailError('invalid_request', error instanceof Error ? error.message : String(error));
@@ -87,7 +88,12 @@ function connectionPort(value, option) {
     }
     return port;
 }
-function connectionSecurity(value, option) {
+// Without an explicit mode, follow the port's standard: implicit TLS on 993 and
+// 465, STARTTLS elsewhere. A mismatched mode fails the TLS handshake or waits
+// for a greeting the server never sends.
+function connectionSecurity(value, port, option) {
+    if (value === undefined)
+        return port === 993 || port === 465 ? 'tls' : 'starttls';
     if (value !== 'tls' && value !== 'starttls') {
         throw new EmailError('invalid_request', `${option} must be "tls" or "starttls".`);
     }
@@ -117,8 +123,8 @@ async function hiddenPrompt(label) {
                 resolve(value);
         };
         const onKeypress = (input, key) => {
-            if (key.ctrl && key.name === 'c')
-                return finish(new Error('Canceled'));
+            if (key.ctrl && (key.name === 'c' || key.name === 'd'))
+                return finish(new CliCanceledError());
             if (key.name === 'return' || key.name === 'enter')
                 return finish();
             if (key.name === 'backspace') {
@@ -143,6 +149,12 @@ async function textPrompt(label) {
     try {
         return (await prompt.question(`${label}: `)).trim();
     }
+    catch (error) {
+        // readline rejects a pending question with AbortError on Ctrl+C or Ctrl+D.
+        if (error instanceof Error && error.name === 'AbortError')
+            throw new CliCanceledError();
+        throw error;
+    }
     finally {
         prompt.close();
     }
@@ -260,11 +272,23 @@ async function inspectLocalRegistry(inspect) {
         }
     }
 }
-function finishCliOperation(program, outcome, errorCode, error) {
+function finishCliOperation(program, outcome, errorCode, error, 
+/** Provider failure detail for a partial failure, which has no error. */
+failure) {
     const active = activeCliOperations.get(program);
     if (!active)
         return;
     activeCliOperations.delete(program);
+    if (active.operation === 'accounts add' && outcome === 'error') {
+        const status = apiHttpStatus(error);
+        const connectionStage = apiConnectionStage(error);
+        active.properties = {
+            ...active.properties,
+            failure_kind: connectionFailureKind(errorCode ?? 'internal', status, error instanceof TypeError),
+            ...(status === undefined ? {} : { http_status: status }),
+            ...(connectionStage ? { connection_stage: connectionStage } : {}),
+        };
+    }
     const startupProperties = active.operation === 'stdio' && outcome === 'error'
         ? {
             startup_phase: active.properties?.startup_phase,
@@ -274,11 +298,23 @@ function finishCliOperation(program, outcome, errorCode, error) {
         }
         : {};
     if (outcome === 'error') {
+        const connectionDetails = active.operation === 'accounts add'
+            ? {
+                request_id: apiRequestId(error),
+                connection_stage: active.properties?.connection_stage,
+                failure_kind: active.properties?.failure_kind,
+                http_status: active.properties?.http_status,
+            }
+            : undefined;
+        const details = {
+            ...(active.operation === 'stdio' ? startupProperties : {}),
+            ...connectionDetails,
+        };
         const context = {
             productSurface: 'cli',
             operation: active.operation,
             skipConsole: true,
-            ...(active.operation === 'stdio' ? { details: startupProperties } : {}),
+            ...(Object.values(details).some((value) => value !== undefined) ? { details } : {}),
         };
         if (error !== undefined)
             logFailure(active.logger, 'cli.operation_failed', error, context);
@@ -291,9 +327,25 @@ function finishCliOperation(program, outcome, errorCode, error) {
         outcome,
         durationMs: performance.now() - active.startedAt,
         errorCode,
+        error: error ?? (failure ? { failure } : undefined),
         properties: { ...active.properties, ...startupProperties },
     });
 }
+function apiHttpStatus(error) {
+    if (!error || typeof error !== 'object' || !('status' in error))
+        return undefined;
+    const status = error.status;
+    return typeof status === 'number' && Number.isInteger(status) && status >= 0 && status <= 599 ? status : undefined;
+}
+function apiConnectionStage(error) {
+    if (!error || typeof error !== 'object' || !('connectionStage' in error))
+        return undefined;
+    const stage = error.connectionStage;
+    return typeof stage === 'string' &&
+        ['server_validation', 'provider_check', 'account_persist', 'oauth_prepare', 'complete'].includes(stage)
+        ? stage
+        : undefined;
+}
 /** End a failed command with the error's own telemetry code instead of a generic one. */
 function failCliOperation(program, error, prefix = 'Error: ') {
     const code = apiErrorCode(error);
@@ -791,7 +843,7 @@ export function createCliProgram(options = {}) {
         .description('Run as a stdio MCP server (for Claude Desktop / Claude Code local config)')
         .option('--account <account>', 'Limit access to one mailbox; repeat as needed', collectOption, [])
         .option('--profile <profile>', `Tool profile: ${NAMED_PERMISSION_PROFILES.join(', ')}`)
-        .option('--allow <capability>', 'Allow one MCP capability; repeat as needed', collectOption, [])
+        .option('--allow <capability>', 'Allow one MCP capability, or add it to --profile; repeat as needed', collectOption, [])
         .action(async (opts) => {
         const startupPhase = (phase) => recordCliOperationProperties(program, { startup_phase: phase });
         let ctx;
@@ -841,6 +893,10 @@ export function createCliProgram(options = {}) {
             // stdout belongs to the MCP protocol; log to stderr only.
             ctx.licenseController.start();
             console.error('Fluxmail MCP server running on stdio');
+            if (!opts.profile && !opts.allow.length) {
+                console.error('No permission profile selected, so this connection is read-only. ' +
+                    'Add --profile or --allow to enable drafts, organizing, or sending: https://fluxmail.ai/docs/permissions');
+            }
             warnLicense(ctx.db);
             const pending = permissions.capabilities.includes('mail.read')
                 ? scopedService.listScheduled().filter((send) => send.status === 'pending').length
@@ -943,12 +999,12 @@ export function createCliProgram(options = {}) {
         .option('--display-name <name>', 'Sender name for IMAP messages')
         .option('--imap-host <host>', 'IMAP server hostname')
         .option('--imap-port <port>', 'IMAP server port', '993')
-        .option('--imap-security <mode>', 'IMAP security: tls or starttls', 'tls')
+        .option('--imap-security <mode>', 'IMAP security: tls or starttls; defaults to tls on port 993, otherwise starttls')
         .option('--imap-user <user>', 'IMAP username; defaults to the mailbox address')
         .option('--imap-password-env <name>', 'Read the IMAP password from this environment variable')
         .option('--smtp-host <host>', 'SMTP server hostname')
         .option('--smtp-port <port>', 'SMTP server port', '587')
-        .option('--smtp-security <mode>', 'SMTP security: tls or starttls', 'starttls')
+        .option('--smtp-security <mode>', 'SMTP security: tls or starttls; defaults to tls on port 465, otherwise starttls')
         .option('--smtp-user <user>', 'SMTP username; defaults to the IMAP username')
         .option('--smtp-password-env <name>', 'Read a separate SMTP password from this environment variable')
         .option('--sent-folder <path>', 'Sent mailbox path')
@@ -974,7 +1030,12 @@ export function createCliProgram(options = {}) {
             : selected.profile.kind === 'remote' && provider === 'imap'
                 ? undefined
                 : false;
-        recordCliOperationProperties(program, connectionProperties({ provider, reauthorize }));
+        recordCliOperationProperties(program, connectionProperties({
+            provider,
+            reauthorize,
+            stage: 'cli_validation',
+            ...(provider === 'imap' ? { flow: 'imap_credentials' } : {}),
+        }));
         if (!selected.token) {
             failCliOperation(program, new EmailError('permission_denied', `Log in to instance "${selected.name}" before connecting a mailbox.`));
             return;
@@ -1040,21 +1101,23 @@ export function createCliProgram(options = {}) {
                         ? await accountSecret(opts.smtpPasswordEnv, 'SMTP password')
                         : imapPassword;
                     const imapUser = opts.imapUser ?? email;
+                    const imapPort = connectionPort(opts.imapPort, '--imap-port');
+                    const smtpPort = connectionPort(opts.smtpPort, '--smtp-port');
                     request = {
                         ...request,
                         email,
                         ...(opts.displayName ? { displayName: opts.displayName } : {}),
                         imap: {
                             host: opts.imapHost,
-                            port: connectionPort(opts.imapPort, '--imap-port'),
-                            security: connectionSecurity(opts.imapSecurity, '--imap-security'),
+                            port: imapPort,
+                            security: connectionSecurity(opts.imapSecurity, imapPort, '--imap-security'),
                             user: imapUser,
                             password: imapPassword,
                         },
                         smtp: {
                             host: opts.smtpHost,
-                            port: connectionPort(opts.smtpPort, '--smtp-port'),
-                            security: connectionSecurity(opts.smtpSecurity, '--smtp-security'),
+                            port: smtpPort,
+                            security: connectionSecurity(opts.smtpSecurity, smtpPort, '--smtp-security'),
                             user: opts.smtpUser ?? imapUser,
                             password: smtpPassword,
                         },
@@ -1068,10 +1131,45 @@ export function createCliProgram(options = {}) {
                         },
                     };
                 }
-                const result = await instanceClient(selected.name).json('/api/v1/accounts/connections', {
-                    method: 'POST',
-                    headers: { 'content-type': 'application/json' },
-                    body: JSON.stringify(request),
+                // The server's IMAP connection check has its own 30-second limit. Give
+                // its response a small margin so the CLI reports the server's result.
+                const requestTimeoutMs = provider === 'imap' && program.getOptionValueSource('timeout') === 'default'
+                    ? IMAP_CONNECTION_TEST_TIMEOUT_MS + 5_000
+                    : undefined;
+                const requestTimeoutClass = program.getOptionValueSource('timeout') !== 'default'
+                    ? 'custom'
+                    : requestTimeoutMs
+                        ? 'imap_margin'
+                        : 'default';
+                const requestId = randomUUID();
+                recordCliOperationProperties(program, {
+                    connection_stage: 'connection_request',
+                    request_timeout_class: requestTimeoutClass,
+                });
+                const requestStartedAt = performance.now();
+                let result;
+                try {
+                    result = await instanceClient(selected.name, true, requestTimeoutMs).json('/api/v1/accounts/connections', {
+                        method: 'POST',
+                        headers: { 'content-type': 'application/json', 'x-request-id': requestId },
+                        body: JSON.stringify(request),
+                    });
+                }
+                catch (error) {
+                    const status = apiHttpStatus(error);
+                    recordCliOperationProperties(program, {
+                        connection_request_duration_ms: performance.now() - requestStartedAt,
+                        ...(status === undefined ? { http_status: 0 } : { http_status: status }),
+                    });
+                    throw error;
+                }
+                recordCliOperationProperties(program, {
+                    connection_request_duration_ms: performance.now() - requestStartedAt,
+                    ...(result.connectionUrl
+                        ? { connection_stage: 'oauth_prepare' }
+                        : result.account
+                            ? { connection_stage: 'complete' }
+                            : {}),
                 });
                 if (result.connectionUrl)
                     console.log(`Open this URL in your browser:\n\n  ${result.connectionUrl}\n`);
@@ -1129,6 +1227,7 @@ export function createCliProgram(options = {}) {
             if (provider === 'outlook') {
                 const connectionMode = selectGmailConnectionMode(ctx.config, opts);
                 if (connectionMode === 'hosted') {
+                    recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
                     const { connectionUrl } = prepareHostedOutlookConnection(ctx.db, ctx.config, {
                         ownerMemberId: owner.id,
                         ...(existing ? { reauthorizeAccountId: existing.id } : {}),
@@ -1140,6 +1239,7 @@ export function createCliProgram(options = {}) {
                     console.log('This link expires in 10 minutes and can only be used once.');
                     return;
                 }
+                recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
                 const account = await runMicrosoftLoopbackFlow(ctx.config, (url, context) => printLoopbackInstructions('outlook', url, context, ctx.config.oauthPort), (result) => {
                     const duplicate = ctx.registry
                         .listAccounts()
@@ -1151,10 +1251,12 @@ export function createCliProgram(options = {}) {
                         throw new EmailError('invalid_request', `Microsoft authorized ${result.email}, but account ${existing.id} belongs to ${existing.email}. ` +
                             'Try again and choose the matching Microsoft account.');
                     }
+                    recordCliOperationProperties(program, { connection_stage: 'account_persist' });
                     return ctx.registry.addOutlookAccount(result.email, result.credentials, result.displayName, owner.id, existing?.id, access);
                 }, loopbackFlowOptions(program, 'outlook'));
                 auditConnection('account.connection.complete', account.id);
                 recordCliOperationProperties(program, {
+                    connection_stage: 'complete',
                     reauthorize: accountIdsBeforeConnection.has(account.id),
                     ...accountInventoryProperties(ctx.registry),
                 });
@@ -1164,6 +1266,7 @@ export function createCliProgram(options = {}) {
             }
             const gmailConnectionMode = selectGmailConnectionMode(ctx.config, opts);
             if (gmailConnectionMode === 'hosted') {
+                recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
                 const { connectionUrl } = prepareHostedGmailConnection(ctx.db, ctx.config, {
                     ownerMemberId: owner.id,
                     ...(existing ? { reauthorizeAccountId: existing.id } : {}),
@@ -1175,6 +1278,7 @@ export function createCliProgram(options = {}) {
                 console.log('This link expires in 10 minutes and can only be used once.');
                 return;
             }
+            recordCliOperationProperties(program, { connection_stage: 'oauth_prepare' });
             const account = await runLoopbackFlow(ctx.config, (url, context) => printLoopbackInstructions('gmail', url, context, ctx.config.oauthPort), (result) => {
                 const duplicate = ctx.registry
                     .listAccounts()
@@ -1186,10 +1290,12 @@ export function createCliProgram(options = {}) {
                     throw new EmailError('invalid_request', `Google authorized ${result.email}, but account ${existing.id} belongs to ${existing.email}. ` +
                         'Try again and choose the matching Google account.');
                 }
+                recordCliOperationProperties(program, { connection_stage: 'account_persist' });
                 return ctx.registry.addGmailAccount(result.email, result.tokens, result.displayName, owner.id, access, result.oauthClient);
             }, loopbackFlowOptions(program, 'gmail'));
             auditConnection('account.connection.complete', account.id);
             recordCliOperationProperties(program, {
+                connection_stage: 'complete',
                 reauthorize: accountIdsBeforeConnection.has(account.id),
                 ...accountInventoryProperties(ctx.registry),
             });
@@ -1486,7 +1592,7 @@ export function createCliProgram(options = {}) {
         .option('--member <member>', 'Admin only: issue the key to another member')
         .option('--account <account>', 'Limit the key to one mailbox; repeat as needed', collectOption, [])
         .option('--profile <profile>', `Tool profile: ${NAMED_PERMISSION_PROFILES.join(', ')}`)
-        .option('--allow <capability>', 'Allow one capability in a custom policy; repeat as needed', collectOption, [])
+        .option('--allow <capability>', 'Allow one capability in a custom policy, or add it to --profile; repeat as needed', collectOption, [])
         .option('--admin <capability>', 'Add one admin capability to a named profile; repeat as needed', collectOption, [])
         .description('Create an API key (shown once)')
         .action(async (opts) => {
@@ -1581,7 +1687,7 @@ export function createCliProgram(options = {}) {
         .command('permissions')
         .argument('<keyId>')
         .option('--profile <profile>', `Tool profile: ${NAMED_PERMISSION_PROFILES.join(', ')}`)
-        .option('--allow <capability>', 'Allow one capability in a custom policy; repeat as needed', collectOption, [])
+        .option('--allow <capability>', 'Allow one capability in a custom policy, or add it to --profile; repeat as needed', collectOption, [])
         .option('--admin <capability>', 'Add one admin capability to a named profile; repeat as needed', collectOption, [])
         .description('Change the permissions for an API key')
         .action(async (keyId, opts) => {
@@ -1905,8 +2011,8 @@ export function createCliProgram(options = {}) {
                 }));
             process.exitCode = cliExitCode(code);
         },
-        reportPartialFailure: (code) => {
-            finishCliOperation(program, 'error', code);
+        reportPartialFailure: (code, failure) => {
+            finishCliOperation(program, 'error', code, undefined, failure);
             process.exitCode = cliExitCode(code);
         },
     });