fluxmail 0.4.1 → 0.6.0

package/dist/http/rest.js

@@ -2,12 +2,15 @@ import { createHash } from 'node:crypto';
 import { createRoute, OpenAPIHono, z } from '@hono/zod-openapi';
 import { HTTPException } from 'hono/http-exception';
 import { EmailError, isEmailError } from '@fluxmail/core';
-import { authenticateApiKey } from '../storage/apiKeys.js';
+import { authenticateBearer, isBootstrapComplete } from '../auth.js';
 import { completeIdempotencyKey, reserveIdempotencyKey } from '../storage/restIdempotency.js';
-import { FULL_PERMISSION_POLICY, hasCapability } from '../permissions.js';
+import { allowsCapability } from '../authorization.js';
+import { captureOperation } from '../telemetry.js';
 import { VERSION } from '../version.js';
-import { administrationUsesHttps, registerAdminRoutes, requestBodyExceedsLimit } from './admin.js';
+import { administrationUsesHttps, adminOperationId, registerAdminRoutes, requestBodyExceedsLimit } from './admin.js';
 import { recordAdminAuditEvent } from '../storage/adminAudit.js';
+import { identityOperationId, registerIdentityRoutes } from './identity.js';
+import { logCodedFailure, logFailure } from '../logging.js';
 const id = z.string().trim().min(1);
 const accountId = id.openapi({ example: 'acct_123' });
 const messageId = id.openapi({ example: 'msg_123' });
@@ -72,6 +75,21 @@ const FolderSchema = z
 })
     .strict()
     .openapi('Folder');
+const LabelSchema = z
+    .object({
+    id: z.string(),
+    name: z.string(),
+    color: z
+        .object({
+        background: z.string().optional(),
+        text: z.string().optional(),
+        preset: z.string().optional(),
+    })
+        .strict()
+        .optional(),
+})
+    .strict()
+    .openapi('Label');
 const MessageSchema = z
     .object({
     id: z.string(),
@@ -114,10 +132,9 @@ const AccountSchema = z
         snippets: z.boolean(),
     })
         .strict(),
-    ownerId: z.string().optional(),
-    sharingMode: z.enum(['private', 'all', 'selected']),
-    sharedMemberIds: z.array(z.string()),
-    memberId: z.string().optional(),
+    ownerMemberId: z.string(),
+    sharedWithAll: z.boolean(),
+    grantedMemberIds: z.array(z.string()),
 })
     .strict()
     .openapi('Account');
@@ -173,6 +190,14 @@ const errorResponses = {
 const protectedRoute = {
     security: [{ bearerAuth: [] }],
 };
+export const REST_OPENAPI_DOCUMENT = {
+    openapi: '3.1.0',
+    info: {
+        title: 'Fluxmail REST API',
+        version: VERSION,
+        description: 'Read, draft, send, schedule, and organize email through connected Fluxmail accounts.',
+    },
+};
 const idempotencyHeaders = z.object({
     'Idempotency-Key': z
         .string()
@@ -241,7 +266,7 @@ const ModifyRequestSchema = z
         .array(z.string().min(1))
         .max(100)
         .optional()
-        .describe('Required when action is addLabels or removeLabels. Change system labels with dedicated actions.'),
+        .describe('Required when action is addLabels or removeLabels. Change Gmail system labels with dedicated actions.'),
 })
     .strict()
     .superRefine((value, ctx) => {
@@ -295,7 +320,6 @@ const MODIFY_CAPABILITIES = {
     removeLabels: 'mail.organize',
 };
 const PROTECTED_MOVE_DESTINATIONS = new Set(['archive', 'trash']);
-const SYSTEM_LABELS = new Set(['inbox', 'sent', 'draft', 'drafts', 'trash', 'spam', 'starred', 'unread', 'important']);
 class RestFailure extends Error {
     code;
     status;
@@ -309,6 +333,19 @@ class RestFailure extends Error {
         this.retryAfter = retryAfter;
     }
 }
+function logRestFailure(deps, operation, error, startedAt) {
+    const context = {
+        productSurface: 'rest',
+        operation,
+        durationMs: performance.now() - startedAt,
+    };
+    if (error instanceof RestFailure) {
+        logCodedFailure(deps.logger, 'rest.operation_failed', error.code, error.message, context);
+    }
+    else {
+        logFailure(deps.logger, 'rest.operation_failed', error, context);
+    }
+}
 function apiFailure(err) {
     if (err instanceof RestFailure) {
         return {
@@ -377,14 +414,6 @@ function safeAttachmentFilename(filename) {
     }
     return safe || 'attachment';
 }
-function captureRestTelemetry(telemetry, properties) {
-    try {
-        telemetry?.capture('rest api called', { product_surface: 'rest', ...properties });
-    }
-    catch {
-        // Telemetry must not affect API responses.
-    }
-}
 async function runJson(c, deps, options, fn) {
     const finishActivity = deps.telemetry?.beginActivity?.();
     const startedAt = performance.now();
@@ -394,7 +423,7 @@ async function runJson(c, deps, options, fn) {
     let reservation;
     try {
         const auth = c.get('restAuth');
-        const missing = options.capabilities.filter((capability) => !hasCapability(auth.permissions, capability));
+        const missing = options.capabilities.filter((capability) => !allowsCapability(auth, capability));
         if (missing.length) {
             throw new EmailError('permission_denied', `This API key does not allow: ${missing.join(', ')}.`);
         }
@@ -407,7 +436,7 @@ async function runJson(c, deps, options, fn) {
             if (options.accountId !== undefined)
                 service.assertAccountAccess(options.accountId);
             const hash = requestHash(options.operation, options.request);
-            const principalId = auth.keyId;
+            const principalId = auth.principalId;
             const result = reserveIdempotencyKey(deps.db, {
                 principalId,
                 idempotencyKey,
@@ -460,6 +489,7 @@ async function runJson(c, deps, options, fn) {
             });
         }
         catch (err) {
+            logRestFailure(deps, options.operation, err, startedAt);
             const failure = apiFailure(err);
             const body = JSON.stringify(failure.payload);
             if (reservation) {
@@ -481,18 +511,22 @@ async function runJson(c, deps, options, fn) {
         }
     }
     catch (err) {
+        logRestFailure(deps, options.operation, err, startedAt);
         const failure = apiFailure(err);
         errorCode = failure.payload.error.code;
         return jsonResponse(failure.payload, failure.status, failure.retryAfter ? { 'retry-after': failure.retryAfter } : {});
     }
     finally {
-        captureRestTelemetry(deps.telemetry, {
+        captureOperation(deps.telemetry, {
+            productSurface: 'rest',
             operation: options.operation,
             outcome,
-            duration_ms: Math.round(performance.now() - startedAt),
-            ...(errorCode ? { error_code: errorCode } : {}),
-            ...(idempotencyStatus ? { idempotency_status: idempotencyStatus } : {}),
-            ...options.telemetry,
+            durationMs: performance.now() - startedAt,
+            errorCode,
+            properties: {
+                ...(idempotencyStatus ? { idempotency_status: idempotencyStatus } : {}),
+                ...options.telemetry,
+            },
         });
         finishActivity?.();
     }
@@ -504,7 +538,7 @@ async function runAttachment(c, deps, accountId, messageId, attachmentId) {
     let errorCode;
     try {
         const auth = c.get('restAuth');
-        if (!hasCapability(auth.permissions, 'mail.read')) {
+        if (!allowsCapability(auth, 'mail.read')) {
             throw new EmailError('permission_denied', 'This API key does not allow: mail.read.');
         }
         const service = c.get('restService');
@@ -534,16 +568,18 @@ async function runAttachment(c, deps, accountId, messageId, attachmentId) {
         });
     }
     catch (err) {
+        logRestFailure(deps, 'downloadAttachment', err, startedAt);
         const failure = apiFailure(err);
         errorCode = failure.payload.error.code;
         return jsonResponse(failure.payload, failure.status);
     }
     finally {
-        captureRestTelemetry(deps.telemetry, {
+        captureOperation(deps.telemetry, {
+            productSurface: 'rest',
             operation: 'downloadAttachment',
             outcome,
-            duration_ms: Math.round(performance.now() - startedAt),
-            ...(errorCode ? { error_code: errorCode } : {}),
+            durationMs: performance.now() - startedAt,
+            errorCode,
         });
         finishActivity?.();
     }
@@ -592,6 +628,9 @@ function adminAuditPath(path) {
     if (/^\/api\/v1\/admin\/accounts\/[^/]+\/imap\/folders$/.test(path)) {
         return '/api/v1/admin/accounts/:id/imap/folders';
     }
+    if (/^\/api\/v1\/admin\/oauth-apps\/(google|outlook)$/.test(path)) {
+        return '/api/v1/admin/oauth-apps/:provider';
+    }
     return '/api/v1/admin/*';
 }
 function modifyAction(input) {
@@ -604,18 +643,21 @@ function modifyAction(input) {
     }
     if (input.action === 'addLabels' || input.action === 'removeLabels') {
         const labels = input.labels;
-        if (labels.some((label) => SYSTEM_LABELS.has(label.trim().toLowerCase()))) {
-            throw new EmailError('invalid_request', 'System labels must be changed with their dedicated message action.');
-        }
         return input.action === 'addLabels' ? { addLabels: labels } : { removeLabels: labels };
     }
     return input.action;
 }
 export function createRestApi(deps) {
     const app = new OpenAPIHono({
-        defaultHook(result, _c) {
+        defaultHook(result, c) {
             if (result.success)
                 return;
+            logCodedFailure(deps.logger, 'rest.operation_failed', 'invalid_request', 'Request validation failed', {
+                productSurface: 'rest',
+                operation: identityOperationId(c.req.method, c.req.path) ??
+                    adminOperationId(c.req.method, c.req.path) ??
+                    'request_validation',
+            });
             return jsonResponse({
                 error: {
                     code: 'invalid_request',
@@ -627,15 +669,47 @@ export function createRestApi(deps) {
             }, 400);
         },
     });
+    app.use('/api/v1/*', async (c, next) => {
+        const telemetryOperation = identityOperationId(c.req.method, c.req.path);
+        if (!telemetryOperation)
+            return next();
+        const finishActivity = deps.telemetry?.beginActivity?.();
+        const startedAt = performance.now();
+        let errorCode;
+        try {
+            await next();
+            if (c.res.status >= 400) {
+                try {
+                    const payload = (await c.res.clone().json());
+                    if (typeof payload.error?.code === 'string')
+                        errorCode = payload.error.code;
+                }
+                catch {
+                    errorCode = 'internal';
+                }
+            }
+        }
+        catch (error) {
+            errorCode = isEmailError(error) ? error.code : 'internal';
+            throw error;
+        }
+        finally {
+            captureOperation(deps.telemetry, {
+                productSurface: 'rest',
+                operation: telemetryOperation,
+                outcome: c.res.status < 400 && !errorCode ? 'success' : 'error',
+                durationMs: performance.now() - startedAt,
+                errorCode,
+            });
+            finishActivity?.();
+        }
+    });
     app.use('/api/v1/admin/*', async (c, next) => {
+        const telemetryOperation = adminOperationId(c.req.method, c.req.path);
+        const identityOperation = identityOperationId(c.req.method, c.req.path);
+        const finishActivity = telemetryOperation ? deps.telemetry?.beginActivity?.() : undefined;
+        const startedAt = performance.now();
         await next();
-        if (!['POST', 'PATCH', 'PUT', 'DELETE'].includes(c.req.method))
-            return;
-        const auth = c.get('restAuth');
-        if (!auth)
-            return;
-        const resource = c.req.path.match(/\/(api-keys|accounts)\/((?:key|acct)_[^/]+)/);
-        const operation = `${c.req.method.toLowerCase()} ${adminAuditPath(c.req.path)}`;
         let errorCode;
         if (c.res.status >= 400) {
             try {
@@ -647,11 +721,29 @@ export function createRestApi(deps) {
                 errorCode = 'internal';
             }
         }
+        if (telemetryOperation) {
+            captureOperation(deps.telemetry, {
+                productSurface: 'rest',
+                operation: telemetryOperation,
+                outcome: c.res.status < 400 ? 'success' : 'error',
+                durationMs: performance.now() - startedAt,
+                errorCode,
+            });
+            finishActivity?.();
+        }
+        if (!['POST', 'PATCH', 'PUT', 'DELETE'].includes(c.req.method) || (identityOperation && c.res.status < 400))
+            return;
+        const auth = c.get('restAuth');
+        if (!auth)
+            return;
+        const resource = c.req.path.match(/\/(api-keys|accounts)\/((?:key|acct)_[^/]+)/);
+        const operation = `${c.req.method.toLowerCase()} ${adminAuditPath(c.req.path)}`;
         try {
             recordAdminAuditEvent(deps.db, {
                 operation,
                 outcome: c.res.status < 400 ? 'success' : 'error',
-                actorKeyId: auth.keyId,
+                actorKeyId: auth.kind === 'api_key' ? auth.keyId : undefined,
+                actorSessionId: auth.kind === 'session' ? auth.sessionId : undefined,
                 actorMemberId: auth.memberId,
                 ...(resource
                     ? { resourceType: resource[1] === 'api-keys' ? 'api_key' : 'account', resourceId: resource[2] }
@@ -664,7 +756,31 @@ export function createRestApi(deps) {
         }
     });
     app.use('/api/v1/*', async (c, next) => {
-        if (c.req.path === '/api/v1' || c.req.path === '/api/v1/openapi.json')
+        c.set('restLogger', deps.logger);
+        if (c.req.path.startsWith('/api/v1/auth/') ||
+            c.req.path === '/api/v1/me' ||
+            c.req.path.startsWith('/api/v1/me/') ||
+            c.req.path === '/api/v1/accounts/connections') {
+            c.header('cache-control', 'no-store');
+            c.header('x-content-type-options', 'nosniff');
+            c.header('referrer-policy', 'no-referrer');
+        }
+        const publicPaths = new Set([
+            '/api/v1',
+            '/api/v1/openapi.json',
+            '/api/v1/auth/login',
+            '/api/v1/auth/enroll',
+            '/api/v1/auth/password-reset',
+        ]);
+        const publicAuthRequest = c.req.method === 'POST' &&
+            (c.req.path === '/api/v1/auth/login' ||
+                c.req.path === '/api/v1/auth/enroll' ||
+                c.req.path === '/api/v1/auth/password-reset');
+        if (publicAuthRequest && (await requestBodyExceedsLimit(c.req.raw))) {
+            logCodedFailure(deps.logger, 'rest.request_rejected', 'request_too_large', 'Authentication request body exceeded the size limit', { productSurface: 'rest', operation: identityOperationId(c.req.method, c.req.path) ?? 'request' });
+            return jsonResponse({ error: { code: 'request_too_large', message: 'Authentication request bodies are limited to 64 KiB.' } }, 413);
+        }
+        if (publicPaths.has(c.req.path))
             return next();
         const administrative = c.req.path.startsWith('/api/v1/admin/');
         if (administrative) {
@@ -674,46 +790,44 @@ export function createRestApi(deps) {
             if (!administrationUsesHttps(c.req.raw, {
                 remoteAddress: c.env?.incoming?.socket.remoteAddress,
                 encrypted: Boolean(c.env?.incoming?.socket?.encrypted),
-            })) {
+            }, deps.config.trustProxy)) {
+                logCodedFailure(deps.logger, 'rest.request_rejected', 'https_required', 'Administrative request did not use HTTPS', { productSurface: 'rest', operation: adminOperationId(c.req.method, c.req.path) ?? 'admin_request' });
                 return jsonResponse({ error: { code: 'https_required', message: 'Administrative routes require HTTPS outside loopback.' } }, 400);
             }
         }
-        let auth;
-        if (deps.config.authMode === 'none' && !administrative) {
-            auth = {
-                keyId: 'auth:none',
-                memberId: null,
-                role: null,
-                permissions: FULL_PERMISSION_POLICY,
-                accountIds: null,
-            };
-        }
-        else {
-            const authorization = c.req.header('authorization');
-            const bearer = authorization?.match(/^Bearer\s+([^\s]+)$/i)?.[1];
-            auth = bearer ? authenticateApiKey(deps.db, bearer) : null;
+        if (!isBootstrapComplete(deps.db)) {
+            logCodedFailure(deps.logger, 'rest.request_rejected', 'setup_required', 'Fluxmail setup is incomplete', {
+                productSurface: 'rest',
+                operation: identityOperationId(c.req.method, c.req.path) ?? adminOperationId(c.req.method, c.req.path) ?? 'request',
+            });
+            return jsonResponse({ error: { code: 'setup_required', message: 'Run "fluxmail setup" on the server before using Fluxmail.' } }, 503);
         }
+        const authorization = c.req.header('authorization');
+        const bearer = authorization?.match(/^Bearer\s+([^\s]+)$/i)?.[1];
+        const auth = bearer ? authenticateBearer(deps.db, bearer) : null;
         if (!auth) {
-            return jsonResponse({ error: { code: 'unauthorized', message: 'Pass an API key as a Bearer token.' } }, 401, {
-                'www-authenticate': 'Bearer',
+            logCodedFailure(deps.logger, 'rest.request_rejected', 'unauthorized', 'REST request was not authorized', {
+                productSurface: 'rest',
+                operation: identityOperationId(c.req.method, c.req.path) ?? adminOperationId(c.req.method, c.req.path) ?? 'request',
             });
+            return jsonResponse({ error: { code: 'unauthorized', message: 'Pass a member session or API key as a Bearer token.' } }, 401, { 'www-authenticate': 'Bearer' });
         }
         c.set('restAuth', auth);
         if (administrative && (c.req.method === 'POST' || c.req.method === 'PATCH' || c.req.method === 'PUT')) {
             const mediaType = c.req.header('content-type')?.split(';', 1)[0]?.trim().toLowerCase();
             if (mediaType !== 'application/json') {
+                logCodedFailure(deps.logger, 'rest.request_rejected', 'unsupported_media_type', 'Administrative request did not use application/json', { productSurface: 'rest', operation: adminOperationId(c.req.method, c.req.path) ?? 'admin_request' });
                 return jsonResponse({ error: { code: 'unsupported_media_type', message: 'Content-Type must be application/json.' } }, 415);
             }
             if (await requestBodyExceedsLimit(c.req.raw)) {
+                logCodedFailure(deps.logger, 'rest.request_rejected', 'request_too_large', 'Administrative request body exceeded the size limit', { productSurface: 'rest', operation: adminOperationId(c.req.method, c.req.path) ?? 'admin_request' });
                 return jsonResponse({ error: { code: 'request_too_large', message: 'Administrative request bodies are limited to 64 KiB.' } }, 413);
             }
         }
-        const scope = deps.config.authMode === 'none'
-            ? { memberId: null }
-            : { memberId: auth.memberId, role: auth.role, accountIds: auth.accountIds };
-        c.set('restService', deps.service.withScope(scope));
+        c.set('restService', deps.service.withPrincipal(auth));
         return next();
     });
+    registerIdentityRoutes(app, deps);
     registerAdminRoutes(app, deps);
     const discoveryRoute = createRoute({
         method: 'get',
@@ -732,7 +846,17 @@ export function createRestApi(deps) {
             },
         },
     });
-    app.openapi(discoveryRoute, (c) => c.json({ data: { name: 'fluxmail', version: VERSION, openapi: '/api/v1/openapi.json' } }));
+    app.openapi(discoveryRoute, (c) => {
+        const startedAt = performance.now();
+        const response = c.json({ data: { name: 'fluxmail', version: VERSION, openapi: '/api/v1/openapi.json' } }, 200);
+        captureOperation(deps.telemetry, {
+            productSurface: 'rest',
+            operation: 'getApiInfo',
+            outcome: 'success',
+            durationMs: performance.now() - startedAt,
+        });
+        return response;
+    });
     const statusRoute = createRoute({
         method: 'get',
         path: '/api/v1/status',
@@ -785,6 +909,25 @@ export function createRestApi(deps) {
             data: await c.get('restService').listFolders(accountId),
         }));
     });
+    const labelsRoute = createRoute({
+        method: 'get',
+        path: '/api/v1/accounts/{accountId}/labels',
+        operationId: 'listLabels',
+        summary: 'List labels',
+        description: 'List Gmail user labels or Outlook categories in an email account.',
+        request: { params: accountParams },
+        ...protectedRoute,
+        responses: {
+            200: { content: { 'application/json': { schema: dataEnvelope(z.array(LabelSchema)) } }, description: 'Labels' },
+            ...errorResponses,
+        },
+    });
+    app.openapi(labelsRoute, (c) => {
+        const { accountId } = c.req.valid('param');
+        return runJson(c, deps, { operation: 'listLabels', capabilities: ['mail.read'] }, async () => ({
+            data: await c.get('restService').listLabels(accountId),
+        }));
+    });
     const listMessagesRoute = createRoute({
         method: 'get',
         path: '/api/v1/accounts/{accountId}/messages',
@@ -1107,21 +1250,20 @@ export function createRestApi(deps) {
     app.openAPIRegistry.registerComponent('securitySchemes', 'bearerAuth', {
         type: 'http',
         scheme: 'bearer',
-        bearerFormat: 'Fluxmail API key',
+        bearerFormat: 'Fluxmail member session or API key',
     });
-    app.doc31('/api/v1/openapi.json', {
-        openapi: '3.1.0',
-        info: {
-            title: 'Fluxmail REST API',
-            version: VERSION,
-            description: 'Read, draft, send, schedule, and organize email through connected Fluxmail accounts.',
-        },
+    app.openAPIRegistry.registerComponent('securitySchemes', 'memberSessionAuth', {
+        type: 'http',
+        scheme: 'bearer',
+        bearerFormat: 'Fluxmail member session',
     });
+    app.doc31('/api/v1/openapi.json', REST_OPENAPI_DOCUMENT);
     app.all('/api/v1/*', () => jsonResponse({ error: { code: 'not_found', message: 'No REST route matches this request.' } }, 404));
     app.onError((err) => {
         const malformedJson = err instanceof SyntaxError || (err instanceof HTTPException && err.status === 400)
             ? new EmailError('invalid_request', 'Malformed JSON body.')
             : err;
+        logFailure(deps.logger, 'rest.unhandled_error', malformedJson, { productSurface: 'rest' });
         const failure = apiFailure(malformedJson);
         return jsonResponse(failure.payload, failure.status);
     });