@nuxt-customer-portal/core 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @nuxt-customer-portal/core
 
+## 0.11.0
+
+### Patch Changes
+
+- b604141: Return actionable encryption configuration errors when saving a portal email API key, display the explanation in email settings, and log server failures through Nitro with secret-safe structured diagnostics, including database migration and connectivity hints.
+
+## 0.10.3
+
 ## 0.10.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxt-customer-portal/core",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "license": "MIT",
   "homepage": "https://nuxt-customer-portal.com",
   "repository": {

package/portal.manifest.mjs

@@ -1,6 +1,6 @@
 export default {
   id: 'core',
-  version: '0.10.2',
+  version: '0.11.0',
   source: '@nuxt-customer-portal/core',
   dependsOn: [],
   schema: './server/db/schema/index.ts',

package/server/plugins/error-logging.ts

@@ -0,0 +1,7 @@
+import { logPortalServerError } from '../utils/server-error-logging'
+
+export default defineNitroPlugin((nitroApp) => {
+  nitroApp.hooks.hook('error', (error, { event }) => {
+    logPortalServerError(error, event)
+  })
+})

package/server/utils/portal-email.ts

@@ -16,7 +16,8 @@ import {
   decryptLegacyDotSecret,
   decryptPortalSecret,
   encryptPortalSecret,
-  isPortalSecretCiphertext
+  isPortalSecretCiphertext,
+  PortalEncryptionConfigurationError
 } from './portal-encryption'
 
 export type PortalEmailTextOverrides = Record<string, Partial<PortalEmailText>>
@@ -159,7 +160,21 @@ const emailEncryption = {
   overrides: [{ env: 'PORTAL_EMAIL_ENCRYPTION_KEY', format: 'sha256' as const }]
 }
 
-export const encryptPortalEmailSecret = (value: string) => encryptPortalSecret(value, emailEncryption)
+export const encryptPortalEmailSecret = (value: string) => {
+  try {
+    return encryptPortalSecret(value, emailEncryption)
+  } catch (error) {
+    if (error instanceof PortalEncryptionConfigurationError) {
+      throw createError({
+        statusCode: 503,
+        statusMessage: 'Email credential encryption is not configured correctly',
+        data: { code: 'EMAIL_ENCRYPTION_CONFIGURATION', message: error.message },
+        cause: error
+      })
+    }
+    throw error
+  }
+}
 
 export const decryptPortalEmailSecret = (value: string) => {
   try {

package/server/utils/portal-encryption.ts

@@ -13,14 +13,18 @@ export type PortalEncryptionOptions = {
 const VERSION = 'v2'
 const ROOT_KEY_ENV = 'PORTAL_ENCRYPTION_KEY'
 
+export class PortalEncryptionConfigurationError extends Error {
+  override name = 'PortalEncryptionConfigurationError'
+}
+
 const decodeBase64Key = (value: string, name: string) => {
   const normalized = value.trim()
   if (!/^[A-Za-z0-9+/_-]+={0,2}$/.test(normalized)) {
-    throw new Error(`${name} must be a base64-encoded 32-byte key`)
+    throw new PortalEncryptionConfigurationError(`${name} must be a base64-encoded 32-byte key`)
   }
   const key = Buffer.from(normalized, normalized.includes('-') || normalized.includes('_') ? 'base64url' : 'base64')
   if (key.length !== 32) {
-    throw new Error(`${name} must be a base64-encoded 32-byte key`)
+    throw new PortalEncryptionConfigurationError(`${name} must be a base64-encoded 32-byte key`)
   }
   return key
 }
@@ -58,7 +62,7 @@ const resolvePortalEncryptionMaterial = ({ purpose, overrides = [] }: PortalEncr
 
   const rootValue = process.env.PORTAL_ENCRYPTION_KEY
   if (!rootValue) {
-    throw new Error(missingKeyMessage(overrides))
+    throw new PortalEncryptionConfigurationError(missingKeyMessage(overrides))
   }
   const rootKey = decodeBase64Key(rootValue, ROOT_KEY_ENV)
   return {
@@ -74,7 +78,7 @@ const materialForSource = (source: string, options: PortalEncryptionOptions) =>
   if (source === ROOT_KEY_ENV) {
     const rootValue = process.env.PORTAL_ENCRYPTION_KEY
     if (!rootValue) {
-      throw new Error(`Configure ${ROOT_KEY_ENV} to decrypt this credential`)
+      throw new PortalEncryptionConfigurationError(`Configure ${ROOT_KEY_ENV} to decrypt this credential`)
     }
     const rootKey = decodeBase64Key(rootValue, ROOT_KEY_ENV)
     return Buffer.from(hkdfSync('sha256', rootKey, Buffer.alloc(0), `nuxt-customer-portal:${options.purpose}`, 32))
@@ -85,7 +89,7 @@ const materialForSource = (source: string, options: PortalEncryptionOptions) =>
   }
   const key = overrideKey(override)
   if (!key) {
-    throw new Error(`Configure ${source} to decrypt this credential`)
+    throw new PortalEncryptionConfigurationError(`Configure ${source} to decrypt this credential`)
   }
   return key
 }
@@ -137,7 +141,9 @@ const requireLegacyOverrideKey = (overrides: PortalEncryptionOverride[]) => {
   if (material) {
     return material.key
   }
-  throw new Error(`Retain ${overrides.map(({ env }) => env).join(' or ')} to decrypt legacy credentials`)
+  throw new PortalEncryptionConfigurationError(
+    `Retain ${overrides.map(({ env }) => env).join(' or ')} to decrypt legacy credentials`
+  )
 }
 
 export const decryptLegacyDotSecret = (value: string, overrides: PortalEncryptionOverride[]) => {

package/server/utils/server-error-logging.ts

@@ -0,0 +1,53 @@
+import type { H3Event } from 'h3'
+import { PortalEncryptionConfigurationError } from './portal-encryption'
+
+const diagnostics: Record<string, string> = {
+  '42P01': 'Database table is missing; check package migrations',
+  '42703': 'Database column is missing; check package migrations',
+  '23503': 'Database foreign-key constraint failed',
+  '23505': 'Database unique constraint failed',
+  '42501': 'Database permissions are insufficient',
+  '28P01': 'Database authentication failed',
+  ECONNREFUSED: 'A required service refused the connection',
+  ETIMEDOUT: 'A required service timed out',
+  ENOTFOUND: 'A required service hostname could not be resolved'
+}
+
+const record = (value: unknown): Record<string, unknown> =>
+  value && typeof value === 'object' ? (value as Record<string, unknown>) : {}
+
+const diagnostic = (error: unknown) => {
+  let current = error
+  for (let depth = 0; depth < 6; depth++) {
+    if (current instanceof PortalEncryptionConfigurationError) {
+      return { code: 'PORTAL_ENCRYPTION_CONFIGURATION', message: current.message }
+    }
+    const { code, cause } = record(current)
+    if (typeof code === 'string' && Object.hasOwn(diagnostics, code)) {
+      return { code, message: diagnostics[code] }
+    }
+    current = cause
+  }
+  return { code: 'SERVER_ERROR', message: 'Unexpected server error' }
+}
+
+export const logPortalServerError = (
+  error: unknown,
+  event?: H3Event,
+  write: (message: string) => void = console.error
+) => {
+  const value = record(error).statusCode
+  const statusCode = typeof value === 'number' && value >= 400 && value <= 599 ? value : 500
+  if (statusCode < 500) {
+    return
+  }
+  write(
+    JSON.stringify({
+      event: 'portal.server_error',
+      method: event?.method ?? null,
+      path: event?.path.split('?')[0] ?? null,
+      statusCode,
+      ...diagnostic(error)
+    })
+  )
+}