feat(P23IM2-1,P23IM2-2,P23IM2-3): 密钥加密持久化/遮罩读模型/企微可重试语义/迁移脚本

2026-03-13 21:50:04 +08:00
@@ -4,6 +4,10 @@ const { AppError } = require('../utils/AppError');
 const { sendData } = require('../utils/reply');
 const { buildAuditLogData } = require('../utils/audit');
 const { sendInstantMessageByChannel } = require('../services/notifications/channels');
+const {
+  buildStoredSecretFields,
+  getChannelSecretReadModel,
+} = require('../services/notifications/channelConfig');
 const { ROLE_PERMISSIONS } = require('../constants/permissions');
 const {
  IM_SUPPORTED_NOTIFICATION_TYPES,
@@ -36,7 +40,7 @@ const ROUTING_SCHEMA = z
  })
  .strict();

-const CONFIG_SCHEMA = z
+const CONFIG_CREATE_SCHEMA = z
  .object({
    mode: z.enum(CHANNEL_MODE_VALUES),
    webhookUrl: z.string().trim().max(2000).nullish(),
@@ -55,6 +59,26 @@ const CONFIG_SCHEMA = z
    }
  });

+const CONFIG_PATCH_SCHEMA = z
+  .object({
+    mode: z.enum(CHANNEL_MODE_VALUES),
+    webhookUrl: z.string().trim().max(2000).nullish(),
+    secret: z.string().trim().max(500).nullish(),
+    clearSecret: z.boolean().optional(),
+    timeoutMs: z.coerce.number().int().min(100).max(60000).optional(),
+    routing: ROUTING_SCHEMA.optional(),
+  })
+  .strict()
+  .superRefine((value, ctx) => {
+    if (value.mode === 'wecom_webhook' && !String(value.webhookUrl ?? '').trim()) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        path: ['webhookUrl'],
+        message: 'wecom_webhook_requires_webhook_url',
+      });
+    }
+  });
+
 const TEMPLATE_SCHEMA = z
  .object({
    title: z.string().trim().min(1).max(200).optional(),
@@ -69,7 +93,7 @@ const CHANNEL_CREATE_SCHEMA = z
    channelType: z.enum(CHANNEL_TYPE_VALUES),
    name: z.string().trim().min(1).max(100),
    enabled: z.boolean().optional(),
-    configJson: CONFIG_SCHEMA.optional(),
+    configJson: CONFIG_CREATE_SCHEMA.optional(),
    templateJson: TEMPLATE_SCHEMA.optional(),
  })
  .strict();
@@ -78,7 +102,7 @@ const CHANNEL_PATCH_SCHEMA = z
  .object({
    name: z.string().trim().min(1).max(100).optional(),
    enabled: z.boolean().optional(),
-    configJson: CONFIG_SCHEMA.optional(),
+    configJson: CONFIG_PATCH_SCHEMA.optional(),
    templateJson: TEMPLATE_SCHEMA.optional(),
  })
  .strict()
@@ -141,11 +165,16 @@ function normalizeRouting(routing) {
  };
 }

-function normalizeConfigJson(input = {}) {
+function normalizeConfigJson(input = {}, options = {}) {
  return {
    mode: input.mode ?? 'mock',
    webhookUrl: String(input.webhookUrl ?? '').trim() || null,
-    secret: String(input.secret ?? '').trim() || null,
+    ...buildStoredSecretFields({
+      config: options.config,
+      existingConfig: options.existingConfig,
+      inputSecret: input.secret,
+      clearSecret: Boolean(input.clearSecret),
+    }),
    timeoutMs: Math.max(100, Number(input.timeoutMs ?? 5000)),
    routing: normalizeRouting(input.routing),
  };
@@ -161,6 +190,36 @@ function normalizeTemplateJson(input = {}) {
  };
 }

+function mapChannelConfigForRead(configJson, options = {}) {
+  const rawConfig = configJson && typeof configJson === 'object' ? configJson : {};
+  const secretModel = getChannelSecretReadModel({
+    config: options.config,
+    configJson: rawConfig,
+    logger: options.logger,
+  });
+
+  return {
+    mode: rawConfig.mode ?? 'mock',
+    webhookUrl: String(rawConfig.webhookUrl ?? '').trim() || null,
+    timeoutMs: Math.max(100, Number(rawConfig.timeoutMs ?? 5000)),
+    routing: normalizeRouting(rawConfig.routing),
+    secretConfigured: secretModel.secretConfigured,
+    secretMasked: secretModel.secretMasked,
+  };
+}
+
+function mapTestResult(result) {
+  return {
+    ok: result.ok,
+    code: result.code,
+    message: result.message ?? null,
+    retryable: typeof result.retryable === 'boolean' ? result.retryable : null,
+    previewMessage: result.previewMessage ?? null,
+    response: result.response ?? null,
+    skipped: result.skipped ?? false,
+  };
+}
+
 function mapNotificationItem(record) {
  return {
    id: record.id,
@@ -174,8 +233,8 @@ function mapNotificationItem(record) {
  };
 }

-function mapNotificationChannel(record) {
-  const configJson = normalizeConfigJson(record.config_json);
+function mapNotificationChannel(record, options = {}) {
+  const configJson = mapChannelConfigForRead(record.config_json, options);
  const templateJson = normalizeTemplateJson(record.template_json ?? undefined);

  return {
@@ -191,9 +250,19 @@ function mapNotificationChannel(record) {
 }

 function handleNotificationChannelWriteError(error) {
+  if (error instanceof AppError) {
+    throw error;
+  }
+
  if (error?.code === 'P2002') {
    throw buildValidationError({ name: 'duplicate_channel_name' }, 409);
  }
+
+  const message = String(error?.message ?? error ?? '');
+  if (message.includes('FIELD_ENCRYPTION_KEY') || message.includes('Invalid encryption key')) {
+    throw buildValidationError({ secret: 'field_encryption_key_missing' });
+  }
+
  throw error;
 }

@@ -358,7 +427,7 @@ async function notificationsRoutes(fastify) {
      });

      return sendData(reply, request, {
-        items: items.map(mapNotificationChannel),
+        items: items.map((item) => mapNotificationChannel(item, { config: fastify.config, logger: fastify.log })),
      });
    },
  );
@@ -381,7 +450,7 @@ async function notificationsRoutes(fastify) {
            channel_type: input.channelType,
            name: input.name,
            enabled: input.enabled ?? true,
-            config_json: normalizeConfigJson(input.configJson),
+            config_json: normalizeConfigJson(input.configJson, { config: fastify.config }),
            template_json: normalizeTemplateJson(input.templateJson),
            created_by: request.employee.id,
            updated_by: request.employee.id,
@@ -402,7 +471,7 @@ async function notificationsRoutes(fastify) {
        });

        return sendData(reply, request, {
-          channel: mapNotificationChannel(channel),
+          channel: mapNotificationChannel(channel, { config: fastify.config, logger: fastify.log }),
        });
      } catch (error) {
        handleNotificationChannelWriteError(error);
@@ -422,7 +491,7 @@ async function notificationsRoutes(fastify) {
    async (request, reply) => {
      const channelId = parseNotificationId(request.params?.id);
      const input = parseBody(CHANNEL_PATCH_SCHEMA, request.body);
-      await loadNotificationChannelOrThrow(fastify.prisma, channelId);
+      const existingChannel = await loadNotificationChannelOrThrow(fastify.prisma, channelId);

      try {
        const channel = await fastify.prisma.notificationChannel.update({
@@ -430,7 +499,7 @@ async function notificationsRoutes(fastify) {
          data: {
            ...(input.name ? { name: input.name } : {}),
            ...(typeof input.enabled === 'boolean' ? { enabled: input.enabled } : {}),
-            ...(input.configJson ? { config_json: normalizeConfigJson(input.configJson) } : {}),
+            ...(input.configJson ? { config_json: normalizeConfigJson(input.configJson, { config: fastify.config, existingConfig: existingChannel.config_json }) } : {}),
            ...(input.templateJson ? { template_json: normalizeTemplateJson(input.templateJson) } : {}),
            updated_by: request.employee.id,
          },
@@ -450,7 +519,7 @@ async function notificationsRoutes(fastify) {
        });

        return sendData(reply, request, {
-          channel: mapNotificationChannel(channel),
+          channel: mapNotificationChannel(channel, { config: fastify.config, logger: fastify.log }),
        });
      } catch (error) {
        handleNotificationChannelWriteError(error);
@@ -497,14 +566,8 @@ async function notificationsRoutes(fastify) {
      });

      return sendData(reply, request, {
-        channel: mapNotificationChannel(channel),
-        testResult: {
-          ok: result.ok,
-          code: result.code,
-          previewMessage: result.previewMessage ?? null,
-          response: result.response ?? null,
-          skipped: result.skipped ?? false,
-        },
+        channel: mapNotificationChannel(channel, { config: fastify.config, logger: fastify.log }),
+        testResult: mapTestResult(result),
      });
    },
  );
@@ -539,7 +602,7 @@ async function notificationsRoutes(fastify) {
          },
          update: {
            enabled: true,
-            config_json: normalizeConfigJson({ mode: 'mock' }),
+            config_json: normalizeConfigJson({ mode: 'mock' }, { config: fastify.config }),
            template_json: normalizeTemplateJson(),
            updated_by: request.employee.id,
          },
@@ -547,7 +610,7 @@ async function notificationsRoutes(fastify) {
            channel_type: input.channelType,
            name: input.name,
            enabled: true,
-            config_json: normalizeConfigJson({ mode: 'mock' }),
+            config_json: normalizeConfigJson({ mode: 'mock' }, { config: fastify.config }),
            template_json: normalizeTemplateJson(),
            created_by: request.employee.id,
            updated_by: request.employee.id,
@@ -583,17 +646,18 @@ async function notificationsRoutes(fastify) {
      });

      return sendData(reply, request, {
-        channel: mapNotificationChannel(channel),
-        testResult: {
-          ok: result.ok,
-          code: result.code,
-          previewMessage: result.previewMessage ?? null,
-          response: result.response ?? null,
-          skipped: result.skipped ?? false,
-        },
+        channel: mapNotificationChannel(channel, { config: fastify.config, logger: fastify.log }),
+        testResult: mapTestResult(result),
      });
    },
  );
 }

+notificationsRoutes.__testables = {
+  mapChannelConfigForRead,
+  mapTestResult,
+  normalizeConfigJson,
+  normalizeRouting,
+};
+
 module.exports = notificationsRoutes;
@@ -0,0 +1,107 @@
+require('dotenv/config');
+
+const { getConfig } = require('../config');
+const { createPrismaClient } = require('../prismaClient');
+const {
+  decryptStringOrThrow,
+  encryptStringOrThrow,
+} = require('../services/crypto');
+const { readStoredSecret } = require('../services/notifications/channelConfig');
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function parseMode(argv) {
+  if (argv.includes('--encrypt')) {
+    return 'encrypt';
+  }
+
+  if (argv.includes('--decrypt')) {
+    return 'decrypt';
+  }
+
+  throw new Error('Usage: node src/scripts/migrate-notification-channel-secrets.js --encrypt|--decrypt');
+}
+
+(async () => {
+  const mode = parseMode(process.argv.slice(2));
+  const config = getConfig();
+  const { prisma, pool } = createPrismaClient();
+  await prisma.$connect();
+
+  try {
+    const rows = await prisma.notificationChannel.findMany({
+      select: {
+        id: true,
+        name: true,
+        config_json: true,
+      },
+      orderBy: [{ created_at: 'asc' }],
+    });
+
+    let updated = 0;
+    let skipped = 0;
+
+    for (const row of rows) {
+      const current = asObject(row.config_json);
+      const { secretEncrypted, legacySecret } = readStoredSecret(current);
+
+      if (mode === 'encrypt') {
+        if (!legacySecret) {
+          skipped += 1;
+          continue;
+        }
+
+        const next = {
+          ...current,
+          secretEncrypted: encryptStringOrThrow(config, legacySecret),
+        };
+        delete next.secret;
+
+        await prisma.notificationChannel.update({
+          where: { id: row.id },
+          data: {
+            config_json: next,
+            updated_by: null,
+          },
+        });
+        updated += 1;
+        continue;
+      }
+
+      if (!secretEncrypted) {
+        skipped += 1;
+        continue;
+      }
+
+      const decryptedSecret = decryptStringOrThrow(config, secretEncrypted);
+      if (!decryptedSecret) {
+        throw new Error(`notification_channel_secret_empty_after_decrypt:${row.id}`);
+      }
+
+      const next = {
+        ...current,
+        secret: decryptedSecret,
+      };
+      delete next.secretEncrypted;
+
+      await prisma.notificationChannel.update({
+        where: { id: row.id },
+        data: {
+          config_json: next,
+          updated_by: null,
+        },
+      });
+      updated += 1;
+    }
+
+    process.stdout.write(`mode=${mode} updated=${updated} skipped=${skipped}\n`);
+  } finally {
+    await prisma.$disconnect();
+    await pool.end();
+  }
+})().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
@@ -1,5 +1,7 @@
 const crypto = require('node:crypto');

+const { resolveChannelSecret } = require('../../notifications/channelConfig');
+
 function toSafeString(value, maxLength = 2000) {
  if (value == null) {
    return '';
@@ -47,7 +49,31 @@ function buildSignedWebhookUrl(webhookUrl, secret) {
  return `${rawUrl}${separator}timestamp=${timestamp}&sign=${sign}`;
 }

-async function sendWecomMessage({ channel, message }) {
+function mapSecretError(result, previewMessage) {
+  if (result?.errorCode === 'secret_missing_field_encryption_key') {
+    return {
+      ok: false,
+      skipped: false,
+      retryable: false,
+      code: 'wecom_secret_missing_field_encryption_key',
+      message: result.errorMessage ?? 'Missing FIELD_ENCRYPTION_KEY for encrypted WeCom secret',
+      response: null,
+      previewMessage,
+    };
+  }
+
+  return {
+    ok: false,
+    skipped: false,
+    retryable: false,
+    code: 'wecom_secret_decrypt_failed',
+    message: result?.errorMessage ?? 'Failed to decrypt WeCom secret',
+    response: null,
+    previewMessage,
+  };
+}
+
+async function sendWecomMessage({ config, channel, message }) {
  const configJson = channel?.config_json && typeof channel.config_json === 'object' ? channel.config_json : {};
  const mode = String(configJson.mode ?? 'mock').trim() || 'mock';
  const previewMessage = buildWecomMarkdownMessage(message);
@@ -56,7 +82,9 @@ async function sendWecomMessage({ channel, message }) {
    return {
      ok: true,
      skipped: false,
+      retryable: false,
      code: 'mock_sent',
+      message: null,
      response: {
        channelType: 'wecom',
        mode,
@@ -90,12 +118,20 @@ async function sendWecomMessage({ channel, message }) {
    };
  }

+  const secretResult = resolveChannelSecret({
+    config,
+    configJson,
+  });
+  if (secretResult.configured && !secretResult.secret) {
+    return mapSecretError(secretResult, previewMessage);
+  }
+
  const timeoutMs = Math.max(100, Number(configJson.timeoutMs ?? 5000));
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), timeoutMs);

  try {
-    const response = await fetch(buildSignedWebhookUrl(webhookUrl, configJson.secret ?? null), {
+    const response = await fetch(buildSignedWebhookUrl(webhookUrl, secretResult.secret), {
      method: 'POST',
      headers: {
        'content-type': 'application/json',
@@ -146,7 +182,9 @@ async function sendWecomMessage({ channel, message }) {
    return {
      ok: true,
      skipped: false,
+      retryable: false,
      code: 'wecom_sent',
+      message: null,
      response: responseBody,
      previewMessage,
    };
@@ -178,6 +216,7 @@ async function sendWecomMessage({ channel, message }) {
 }

 module.exports = {
+  buildSignedWebhookUrl,
  buildWecomMarkdownMessage,
  sendWecomMessage,
 };
@@ -0,0 +1,164 @@
+const {
+  decryptStringOrThrow,
+  encryptStringOrThrow,
+  resolveFieldEncryptionKey,
+} = require('../crypto');
+
+function asObject(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+function trimToNull(value, maxLength = 2000) {
+  const normalized = String(value ?? '').trim();
+  if (!normalized) {
+    return null;
+  }
+  return normalized.slice(0, maxLength);
+}
+
+function maskSecret(secret) {
+  const value = trimToNull(secret, 500);
+  if (!value) {
+    return null;
+  }
+
+  if (value.length <= 2) {
+    return '*'.repeat(value.length);
+  }
+
+  if (value.length <= 6) {
+    return `${value.slice(0, 1)}${'*'.repeat(value.length - 2)}${value.slice(-1)}`;
+  }
+
+  return `${value.slice(0, 2)}${'*'.repeat(Math.max(4, value.length - 4))}${value.slice(-2)}`;
+}
+
+function readStoredSecret(configJson) {
+  const normalized = asObject(configJson);
+  return {
+    secretEncrypted: trimToNull(normalized.secretEncrypted, 4000),
+    legacySecret: trimToNull(normalized.secret, 500),
+  };
+}
+
+function hasFieldEncryptionKey(config) {
+  return Boolean(resolveFieldEncryptionKey(config));
+}
+
+function resolveChannelSecret({ config, configJson, logger } = {}) {
+  const { secretEncrypted, legacySecret } = readStoredSecret(configJson);
+
+  if (secretEncrypted) {
+    if (!hasFieldEncryptionKey(config)) {
+      return {
+        configured: true,
+        secret: null,
+        source: 'encrypted',
+        errorCode: 'secret_missing_field_encryption_key',
+        errorMessage: 'Missing FIELD_ENCRYPTION_KEY for encrypted notification channel secret',
+      };
+    }
+
+    try {
+      const secret = decryptStringOrThrow(config, secretEncrypted);
+      if (!secret) {
+        return {
+          configured: true,
+          secret: null,
+          source: 'encrypted',
+          errorCode: 'secret_decrypt_failed',
+          errorMessage: 'Failed to decrypt notification channel secret',
+        };
+      }
+
+      return {
+        configured: true,
+        secret,
+        source: 'encrypted',
+        errorCode: null,
+        errorMessage: null,
+      };
+    } catch (error) {
+      logger?.warn?.({ err: error }, 'Notification channel secret decrypt failed');
+      const message = String(error?.message ?? 'Failed to decrypt notification channel secret');
+      return {
+        configured: true,
+        secret: null,
+        source: 'encrypted',
+        errorCode: message.includes('FIELD_ENCRYPTION_KEY')
+          ? 'secret_missing_field_encryption_key'
+          : 'secret_decrypt_failed',
+        errorMessage: message,
+      };
+    }
+  }
+
+  if (legacySecret) {
+    return {
+      configured: true,
+      secret: legacySecret,
+      source: 'legacy',
+      errorCode: null,
+      errorMessage: null,
+    };
+  }
+
+  return {
+    configured: false,
+    secret: null,
+    source: null,
+    errorCode: null,
+    errorMessage: null,
+  };
+}
+
+function getChannelSecretReadModel({ config, configJson, logger } = {}) {
+  const resolved = resolveChannelSecret({ config, configJson, logger });
+  return {
+    secretConfigured: resolved.configured,
+    secretMasked: resolved.secret ? maskSecret(resolved.secret) : resolved.configured ? '******' : null,
+  };
+}
+
+function buildStoredSecretFields({ config, existingConfig, inputSecret, clearSecret = false } = {}) {
+  if (clearSecret) {
+    return {};
+  }
+
+  const nextSecret = trimToNull(inputSecret, 500);
+  if (nextSecret) {
+    return {
+      secretEncrypted: encryptStringOrThrow(config, nextSecret),
+    };
+  }
+
+  const { secretEncrypted, legacySecret } = readStoredSecret(existingConfig);
+  if (secretEncrypted) {
+    return {
+      secretEncrypted,
+    };
+  }
+
+  if (legacySecret) {
+    if (hasFieldEncryptionKey(config)) {
+      return {
+        secretEncrypted: encryptStringOrThrow(config, legacySecret),
+      };
+    }
+
+    return {
+      secret: legacySecret,
+    };
+  }
+
+  return {};
+}
+
+module.exports = {
+  buildStoredSecretFields,
+  getChannelSecretReadModel,
+  hasFieldEncryptionKey,
+  maskSecret,
+  readStoredSecret,
+  resolveChannelSecret,
+};
@@ -46,7 +46,9 @@ async function sendInstantMessageByChannel({ config, channel, payload }) {
    return {
      ok: true,
      skipped: true,
+      retryable: false,
      code: 'im_notifier_disabled',
+      message: 'IM notifier disabled',
      response: { channelType: normalizedChannelType || null },
      previewMessage: null,
    };
@@ -56,7 +58,9 @@ async function sendInstantMessageByChannel({ config, channel, payload }) {
    return {
      ok: true,
      skipped: true,
+      retryable: false,
      code: 'channel_not_found',
+      message: 'Notification channel not found',
      response: { channelType: normalizedChannelType || null },
      previewMessage: null,
    };
@@ -66,7 +70,9 @@ async function sendInstantMessageByChannel({ config, channel, payload }) {
    return {
      ok: true,
      skipped: true,
+      retryable: false,
      code: 'channel_disabled',
+      message: 'Notification channel disabled',
      response: { channelType: normalizedChannelType || null },
      previewMessage: null,
    };
@@ -76,14 +82,16 @@ async function sendInstantMessageByChannel({ config, channel, payload }) {
    return {
      ok: true,
      skipped: true,
+      retryable: false,
      code: 'unsupported_channel_type',
+      message: 'Unsupported notification channel type',
      response: { channelType: normalizedChannelType || null },
      previewMessage: null,
    };
  }

  const message = buildNotificationMessage(channel, payload);
-  return sendWecomMessage({ channel, message });
+  return sendWecomMessage({ config, channel, message });
 }

 module.exports = {