@open-mercato/core 0.6.7-develop.6706.1.b3a4c759bb → 0.6.7-develop.6726.1.983ae8a07e

package/src/modules/dashboards/lib/aggregations.ts

@@ -97,54 +97,56 @@ export type BuildAggregationQueryOptions = {
   registry: AnalyticsRegistry
 }
 
-export function buildAggregationQuery(options: BuildAggregationQueryOptions): AggregationQuery | null {
-  const { registry } = options
-  const config = registry.getEntityTypeConfig(options.entityType)
-  if (!config) return null
-
-  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
-  if (!metricMapping) return null
-
-  const params: unknown[] = []
+export type ResolvedGroupExpression = {
+  expression: string
+  /** Column the group expression reads from — the encryption map is keyed by this. */
+  dbColumn: string
+  /** JSONB path below `dbColumn`, when the groupBy field used path notation. */
+  jsonPath: string | null
+}
 
-  const tableName = config.schema ? `"${config.schema}"."${config.tableName}"` : `"${config.tableName}"`
-  const aggregateExpr = buildAggregateExpression(options.metric.aggregate, metricMapping.dbColumn)
+/**
+ * Resolves the SQL expression a groupBy field maps to, together with the underlying column so
+ * callers can decide whether the source is encrypted at rest before grouping over it (#4622).
+ */
+export function resolveGroupExpression(
+  registry: AnalyticsRegistry,
+  entityType: string,
+  groupBy: { field: string; granularity?: DateGranularity },
+): ResolvedGroupExpression | null {
+  const groupMapping = registry.getFieldMapping(entityType, groupBy.field)
 
-  let selectClause = `SELECT ${aggregateExpr} AS value`
-  let groupByClause = ''
-  let orderByClause = ''
-  let limitClause = ''
-
-  if (options.groupBy) {
-    let groupMapping = registry.getFieldMapping(options.entityType, options.groupBy.field)
-    let groupExpr: string | null = null
-
-    // Handle JSONB path notation (e.g., shippingAddressSnapshot.region)
-    if (!groupMapping && options.groupBy.field.includes('.')) {
-      const [baseField, ...pathParts] = options.groupBy.field.split('.')
-      const baseMapping = registry.getFieldMapping(options.entityType, baseField)
-      if (baseMapping?.type === 'jsonb') {
-        groupExpr = buildJsonbFieldExpression(baseMapping.dbColumn, pathParts.join('.'))
-      }
-    } else if (groupMapping) {
-      if (groupMapping.type === 'timestamp' && options.groupBy.granularity) {
-        groupExpr = buildDateTruncExpression(groupMapping.dbColumn, options.groupBy.granularity)
-      } else {
-        groupExpr = groupMapping.dbColumn
-      }
+  // Handle JSONB path notation (e.g., shippingAddressSnapshot.region)
+  if (!groupMapping && groupBy.field.includes('.')) {
+    const [baseField, ...pathParts] = groupBy.field.split('.')
+    const baseMapping = registry.getFieldMapping(entityType, baseField)
+    if (baseMapping?.type !== 'jsonb') return null
+    const jsonPath = pathParts.join('.')
+    return {
+      expression: buildJsonbFieldExpression(baseMapping.dbColumn, jsonPath),
+      dbColumn: baseMapping.dbColumn,
+      jsonPath,
     }
+  }
 
-    if (groupExpr) {
-      selectClause = `SELECT ${groupExpr} AS group_key, ${aggregateExpr} AS value`
-      groupByClause = `GROUP BY ${groupExpr}`
-      orderByClause = `ORDER BY value DESC`
+  if (!groupMapping) return null
 
-      if (options.groupBy.limit && options.groupBy.limit > 0) {
-        limitClause = `LIMIT ${Math.min(options.groupBy.limit, 100)}`
-      }
+  if (groupMapping.type === 'timestamp' && groupBy.granularity) {
+    return {
+      expression: buildDateTruncExpression(groupMapping.dbColumn, groupBy.granularity),
+      dbColumn: groupMapping.dbColumn,
+      jsonPath: null,
     }
   }
 
+  return { expression: groupMapping.dbColumn, dbColumn: groupMapping.dbColumn, jsonPath: null }
+}
+
+function buildWhereClause(
+  options: Pick<BuildAggregationQueryOptions, 'entityType' | 'dateRange' | 'filters' | 'scope' | 'registry'>,
+): { clause: string; params: unknown[] } {
+  const { registry } = options
+  const params: unknown[] = []
   const whereClauses: string[] = []
 
   whereClauses.push(`tenant_id = ?`)
@@ -215,11 +217,88 @@ export function buildAggregationQuery(options: BuildAggregationQueryOptions): Ag
     }
   }
 
-  const whereClause = whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : ''
+  return { clause: whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : '', params }
+}
+
+function resolveTableName(config: EntityTypeConfig): string {
+  return config.schema ? `"${config.schema}"."${config.tableName}"` : `"${config.tableName}"`
+}
+
+export function buildAggregationQuery(options: BuildAggregationQueryOptions): AggregationQuery | null {
+  const { registry } = options
+  const config = registry.getEntityTypeConfig(options.entityType)
+  if (!config) return null
+
+  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
+  if (!metricMapping) return null
+
+  const tableName = resolveTableName(config)
+  const aggregateExpr = buildAggregateExpression(options.metric.aggregate, metricMapping.dbColumn)
+
+  let selectClause = `SELECT ${aggregateExpr} AS value`
+  let groupByClause = ''
+  let orderByClause = ''
+  let limitClause = ''
+
+  if (options.groupBy) {
+    const resolved = resolveGroupExpression(registry, options.entityType, options.groupBy)
+
+    if (resolved) {
+      selectClause = `SELECT ${resolved.expression} AS group_key, ${aggregateExpr} AS value`
+      groupByClause = `GROUP BY ${resolved.expression}`
+      // NULLS LAST is stated explicitly (PostgreSQL defaults DESC to NULLS FIRST) so a group limit
+      // keeps the highest-value buckets instead of the empty ones, and so the application-side
+      // encrypted path can mirror the same ordering (#4622).
+      orderByClause = `ORDER BY value DESC NULLS LAST`
+
+      if (options.groupBy.limit && options.groupBy.limit > 0) {
+        limitClause = `LIMIT ${Math.min(options.groupBy.limit, 100)}`
+      }
+    }
+  }
+
+  const where = buildWhereClause(options)
+
+  const sql = [selectClause, `FROM ${tableName}`, where.clause, groupByClause, orderByClause, limitClause]
+    .filter(Boolean)
+    .join(' ')
+
+  return { sql, params: where.params }
+}
+
+export type BuildGroupSourceRowsQueryOptions = Omit<BuildAggregationQueryOptions, 'groupBy'> & {
+  /** Column holding the (encrypted) group source, resolved via `resolveGroupExpression`. */
+  groupColumn: string
+  /** Hard cap on scanned rows; callers fetch `rowLimit + 1` to detect overflow. */
+  rowLimit: number
+}
+
+/**
+ * Builds a per-row query for group sources that cannot be grouped in SQL because the column is
+ * encrypted at rest. Returns the raw group source alongside the metric value so the caller can
+ * decrypt, then aggregate in application code (#4622).
+ */
+export function buildGroupSourceRowsQuery(options: BuildGroupSourceRowsQueryOptions): AggregationQuery | null {
+  const { registry } = options
+  const config = registry.getEntityTypeConfig(options.entityType)
+  if (!config) return null
+
+  const metricMapping = registry.getFieldMapping(options.entityType, options.metric.field)
+  if (!metricMapping) return null
+
+  if (!isSafeIdentifier(options.groupColumn)) {
+    throw new Error(`Invalid group column: ${options.groupColumn}`)
+  }
 
-  const sql = [selectClause, `FROM ${tableName}`, whereClause, groupByClause, orderByClause, limitClause]
+  const where = buildWhereClause(options)
+  const sql = [
+    `SELECT ${options.groupColumn} AS group_source, ${metricMapping.dbColumn} AS metric_value`,
+    `FROM ${resolveTableName(config)}`,
+    where.clause,
+    `LIMIT ${Math.max(1, Math.floor(options.rowLimit)) + 1}`,
+  ]
     .filter(Boolean)
     .join(' ')
 
-  return { sql, params }
+  return { sql, params: where.params }
 }

package/src/modules/dashboards/lib/exactDecimal.ts

@@ -0,0 +1,96 @@
+/**
+ * Minimal exact decimal arithmetic for application-side aggregation of PostgreSQL `numeric`
+ * columns. The SQL path sums money in `numeric` and converts once, so the application path must
+ * not accumulate in binary floating point — `0.1 + 0.2` would drift the totals of encrypted group
+ * sources away from the plaintext ones (#4622).
+ *
+ * A value is stored as scaled integer `units` plus a decimal `scale`, so `12.34` is
+ * `{ units: 1234n, scale: 2 }`. Conversion to `number` happens only at the response boundary.
+ */
+
+export type ExactDecimal = {
+  units: bigint
+  scale: number
+}
+
+const DECIMAL_PATTERN = /^([+-]?)(\d*)(?:\.(\d*))?(?:[eE]([+-]?\d+))?$/
+
+export const EXACT_DECIMAL_ZERO: ExactDecimal = { units: 0n, scale: 0 }
+
+function pow10(exponent: number): bigint {
+  return 10n ** BigInt(exponent)
+}
+
+/**
+ * Parses a `numeric` column value. The PostgreSQL driver hands these over as strings to preserve
+ * precision, so the string form is authoritative; numbers and bigints are accepted for callers that
+ * already hold a JavaScript value. Returns `null` for anything that is not a finite decimal.
+ */
+export function parseExactDecimal(raw: unknown): ExactDecimal | null {
+  if (raw === null || raw === undefined) return null
+  if (typeof raw === 'bigint') return { units: raw, scale: 0 }
+
+  let text: string
+  if (typeof raw === 'number') {
+    if (!Number.isFinite(raw)) return null
+    text = String(raw)
+  } else if (typeof raw === 'string') {
+    text = raw.trim()
+  } else {
+    return null
+  }
+
+  if (!text) return null
+
+  const match = DECIMAL_PATTERN.exec(text)
+  if (!match) return null
+
+  const [, sign, intPart = '', fracPart = '', exponentPart] = match
+  if (!intPart && !fracPart) return null
+
+  const digits = `${intPart}${fracPart}`
+  let units = BigInt(digits)
+  let scale = fracPart.length
+
+  if (exponentPart) {
+    scale -= Number(exponentPart)
+    if (scale < 0) {
+      units *= pow10(-scale)
+      scale = 0
+    }
+  }
+
+  if (sign === '-') units = -units
+  return { units, scale }
+}
+
+function rescale(value: ExactDecimal, scale: number): bigint {
+  return scale === value.scale ? value.units : value.units * pow10(scale - value.scale)
+}
+
+export function addExactDecimal(left: ExactDecimal, right: ExactDecimal): ExactDecimal {
+  const scale = Math.max(left.scale, right.scale)
+  return { units: rescale(left, scale) + rescale(right, scale), scale }
+}
+
+export function compareExactDecimal(left: ExactDecimal, right: ExactDecimal): number {
+  const scale = Math.max(left.scale, right.scale)
+  const leftUnits = rescale(left, scale)
+  const rightUnits = rescale(right, scale)
+  if (leftUnits === rightUnits) return 0
+  return leftUnits < rightUnits ? -1 : 1
+}
+
+export function exactDecimalToString(value: ExactDecimal): string {
+  const negative = value.units < 0n
+  const digits = (negative ? -value.units : value.units).toString().padStart(value.scale + 1, '0')
+  const boundary = digits.length - value.scale
+  const integerPart = digits.slice(0, boundary)
+  const fractionPart = value.scale > 0 ? digits.slice(boundary) : ''
+  return `${negative ? '-' : ''}${integerPart}${fractionPart ? `.${fractionPart}` : ''}`
+}
+
+/** Response-boundary conversion: the only place where the exact value becomes a binary float. */
+export function exactDecimalToNumber(value: ExactDecimal): number {
+  return Number(exactDecimalToString(value))
+}

package/src/modules/dashboards/services/widgetDataService.ts

@@ -13,19 +13,42 @@ import {
   determineChangeDirection,
   isValidDateRangePreset,
 } from '@open-mercato/ui/backend/date-range'
+import { parseDecryptedFieldValue } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { TenantDek } from '@open-mercato/shared/lib/encryption/kms'
+import { isTenantDataEncryptionEnabled } from '@open-mercato/shared/lib/encryption/toggles'
 import {
   type AggregateFunction,
   type DateGranularity,
   buildAggregationQuery,
+  buildGroupSourceRowsQuery,
+  resolveGroupExpression,
 } from '../lib/aggregations'
+import {
+  type ExactDecimal,
+  EXACT_DECIMAL_ZERO,
+  addExactDecimal,
+  compareExactDecimal,
+  exactDecimalToNumber,
+  parseExactDecimal,
+} from '../lib/exactDecimal'
 import type { AnalyticsRegistry } from './analyticsRegistry'
 
 const WIDGET_DATA_CACHE_TTL = 120_000
 const WIDGET_DATA_SEGMENT_TTL = 86_400_000
 const WIDGET_DATA_SEGMENT_KEY = 'widget-data:__segment__'
 
+/**
+ * Encrypted group sources cannot be grouped by the database, so the rows are scanned and
+ * aggregated in application code. The cap keeps that scan bounded; overflowing it fails loudly
+ * instead of charting a silently truncated result (#4622).
+ */
+const ENCRYPTED_GROUP_SCAN_LIMIT = 20_000
+
 const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
 
+const logger = createLogger('dashboards').child({ component: 'widget-data' })
+
 export class WidgetDataValidationError extends Error {
   constructor(message: string) {
     super(message)
@@ -33,12 +56,120 @@ export class WidgetDataValidationError extends Error {
   }
 }
 
+export class WidgetDataScanLimitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WidgetDataScanLimitError'
+  }
+}
+
+/**
+ * Raised when encryption is configured but the group source cannot currently be resolved — an
+ * unhealthy KMS, an unreadable encryption map, or a missing tenant DEK. Grouping would either read
+ * ciphertext in SQL or silently collapse every encrypted row into "Unknown", so the request fails
+ * closed instead (#4622).
+ */
+export class WidgetDataEncryptionUnavailableError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WidgetDataEncryptionUnavailableError'
+  }
+}
+
+type EncryptedGroupSource = {
+  entityId: string
+  dbColumn: string
+  jsonPath: string | null
+}
+
 function assertSafeIdentifier(value: string, name: string): void {
   if (!SAFE_IDENTIFIER_PATTERN.test(value)) {
     throw new Error(`Invalid ${name}: ${value}`)
   }
 }
 
+/**
+ * Encryption maps may register a field in either casing (`findKey` in the encryption service
+ * accepts both), so match the analytics column tolerantly rather than by exact snake_case.
+ */
+function matchesColumn(fieldName: string, dbColumn: string): boolean {
+  const normalize = (value: string) => value.replace(/_/g, '').toLowerCase()
+  return normalize(fieldName) === normalize(dbColumn)
+}
+
+function readJsonPath(value: unknown, path: string): unknown {
+  let current = value
+  for (const part of path.split('.')) {
+    if (current === null || typeof current !== 'object') return null
+    current = (current as Record<string, unknown>)[part]
+  }
+  return current
+}
+
+/**
+ * Running aggregate state for one group. Values are folded in as they are scanned — the bucket
+ * never holds the row set — so the scan cost stays linear and independent of the row cap.
+ */
+type GroupBucket = {
+  /** Rows with a non-null metric column, mirroring SQL `COUNT(column)`. */
+  count: number
+  /** Rows whose metric parsed as a decimal, mirroring the row set SQL aggregates operate on. */
+  numericCount: number
+  /** Exact running sum, so money never accumulates in binary floating point. */
+  sum: ExactDecimal
+  min: ExactDecimal | null
+  max: ExactDecimal | null
+}
+
+function createGroupBucket(): GroupBucket {
+  return { count: 0, numericCount: 0, sum: EXACT_DECIMAL_ZERO, min: null, max: null }
+}
+
+function foldMetricValue(bucket: GroupBucket, value: ExactDecimal): void {
+  bucket.numericCount += 1
+  bucket.sum = addExactDecimal(bucket.sum, value)
+  if (bucket.min === null || compareExactDecimal(value, bucket.min) < 0) bucket.min = value
+  if (bucket.max === null || compareExactDecimal(value, bucket.max) > 0) bucket.max = value
+}
+
+/**
+ * Mirrors the SQL semantics of `buildAggregateExpression` for application-side aggregation. That
+ * expression wraps `SUM`/`AVG` in `COALESCE(..., 0)`, so an empty value set aggregates to `0` on
+ * both paths, while the uncoalesced `MIN`/`MAX` keep PostgreSQL's `NULL`. An encrypted group source
+ * must not report a different value than the same data would report in plaintext (#4622).
+ */
+function aggregateBucket(aggregate: AggregateFunction, bucket: GroupBucket): number | null {
+  switch (aggregate) {
+    case 'count':
+      return bucket.count
+    case 'sum':
+      return bucket.numericCount === 0 ? 0 : exactDecimalToNumber(bucket.sum)
+    case 'avg':
+      return bucket.numericCount === 0 ? 0 : exactDecimalToNumber(bucket.sum) / bucket.numericCount
+    case 'min':
+      return bucket.min === null ? null : exactDecimalToNumber(bucket.min)
+    case 'max':
+      return bucket.max === null ? null : exactDecimalToNumber(bucket.max)
+    default:
+      return bucket.count
+  }
+}
+
+/**
+ * Mirrors the SQL path's `ORDER BY value DESC NULLS LAST`. PostgreSQL defaults DESC to NULLS FIRST,
+ * which would let empty buckets displace real ones under a group limit, so both paths state the
+ * policy explicitly: highest value first, buckets without a value last.
+ */
+function compareWidgetDataItemsByValueDesc(
+  left: { value: number | null },
+  right: { value: number | null },
+): number {
+  if (left.value === null && right.value === null) return 0
+  if (left.value === null) return 1
+  if (right.value === null) return -1
+  return right.value - left.value
+}
+
 export type WidgetDataRequest = {
   entityType: string
   metric: {
@@ -229,6 +360,13 @@ export class WidgetDataService {
     request: WidgetDataRequest,
     dateRange?: { start: Date; end: Date },
   ): Promise<{ value: number | null; data: WidgetDataItem[] }> {
+    if (request.groupBy) {
+      const encryptedSource = await this.resolveEncryptedGroupSource(request.entityType, request.groupBy)
+      if (encryptedSource) {
+        return this.executeEncryptedGroupQuery(request, encryptedSource, dateRange)
+      }
+    }
+
     const query = buildAggregationQuery({
       entityType: request.entityType,
       metric: request.metric,
@@ -264,6 +402,193 @@ export class WidgetDataService {
     return { value: singleValue, data: [] }
   }
 
+  /**
+   * Reports the encrypted column a groupBy field reads from, or null when the source is stored in
+   * plaintext and can be grouped by the database. Grouping over an encrypted column in SQL buckets
+   * ciphertext and renders it to the user (#4622).
+   */
+  private async resolveEncryptedGroupSource(
+    entityType: string,
+    groupBy: NonNullable<WidgetDataRequest['groupBy']>,
+  ): Promise<EncryptedGroupSource | null> {
+    // Encryption is not configured for this deployment, so no column can hold ciphertext and the
+    // database may group the source directly.
+    if (!isTenantDataEncryptionEnabled()) return null
+
+    const resolved = resolveGroupExpression(this.registry, entityType, groupBy)
+    if (!resolved) return null
+
+    const tableName = this.registry.getEntityTypeConfig(entityType)?.tableName
+    if (!tableName) return null
+
+    // Without an encryption entity id the table is outside the encryption map entirely, which is
+    // the same state the encrypting subscriber sees when it skips the row.
+    const entityId = this.resolveEncryptionEntityId(tableName)
+    if (!entityId) return null
+
+    const encryptionService = resolveTenantEncryptionService(this.em)
+    if (!encryptionService) {
+      throw new WidgetDataEncryptionUnavailableError(
+        `Cannot determine whether ${groupBy.field} is encrypted: encryption service unavailable`,
+      )
+    }
+
+    const organizationId = this.resolveOrganizationId()
+    let encryptedFields: string[]
+    try {
+      // Deliberately independent of KMS health: the map describes how the rows were written, and
+      // an unhealthy KMS must not be read as "this column is plaintext" (#4622).
+      encryptedFields = await encryptionService.getEncryptedFieldNames(
+        entityId,
+        this.scope.tenantId,
+        organizationId,
+        { ignoreRuntimeHealth: true },
+      )
+    } catch (err) {
+      logger.error('Failed to resolve encrypted fields for widget grouping', { err, entityId, entityType })
+      throw new WidgetDataEncryptionUnavailableError(
+        `Cannot determine whether ${groupBy.field} is encrypted: encryption map lookup failed`,
+      )
+    }
+
+    if (!encryptedFields.some((field) => matchesColumn(field, resolved.dbColumn))) return null
+
+    if (resolved.jsonPath === null && groupBy.granularity) {
+      throw new WidgetDataValidationError(
+        `Cannot group encrypted field by granularity: ${groupBy.field}`,
+      )
+    }
+
+    return { entityId, dbColumn: resolved.dbColumn, jsonPath: resolved.jsonPath }
+  }
+
+  /**
+   * Aggregates an encrypted group source in application code: rows are scanned, the group column is
+   * decrypted, and only the resulting plaintext keys are grouped. Values that cannot be decrypted
+   * collapse into the null ("Unknown") bucket so ciphertext never reaches the response.
+   */
+  private async executeEncryptedGroupQuery(
+    request: WidgetDataRequest,
+    source: EncryptedGroupSource,
+    dateRange?: { start: Date; end: Date },
+  ): Promise<{ value: number | null; data: WidgetDataItem[] }> {
+    const query = buildGroupSourceRowsQuery({
+      entityType: request.entityType,
+      metric: request.metric,
+      dateRange: dateRange && request.dateRange ? { field: request.dateRange.field, ...dateRange } : undefined,
+      filters: request.filters,
+      scope: this.scope,
+      registry: this.registry,
+      groupColumn: source.dbColumn,
+      rowLimit: ENCRYPTED_GROUP_SCAN_LIMIT,
+    })
+
+    if (!query) {
+      throw new Error('Failed to build aggregation query')
+    }
+
+    const rows = await this.em.getConnection().execute(query.sql, query.params)
+    const results = Array.isArray(rows) ? rows : []
+
+    if (results.length > ENCRYPTED_GROUP_SCAN_LIMIT) {
+      throw new WidgetDataScanLimitError(
+        `Too many rows to group encrypted field ${request.groupBy?.field} (limit ${ENCRYPTED_GROUP_SCAN_LIMIT})`,
+      )
+    }
+
+    const encryptionService = resolveTenantEncryptionService(this.em)
+    let dek: TenantDek | null = null
+    try {
+      dek = encryptionService ? await encryptionService.getDek(this.scope.tenantId) : null
+    } catch (err) {
+      logger.error('Failed to resolve the tenant DEK for widget grouping', { err, entityId: source.entityId })
+      dek = null
+    }
+
+    const buckets = new Map<string | null, GroupBucket>()
+    let undecryptableRows = 0
+
+    for (const row of results as Array<Record<string, unknown>>) {
+      const resolvedKey = this.resolveDecryptedGroupKey(row.group_source, source, dek?.key ?? null)
+      // An undecryptable source joins the null ("Unknown") bucket rather than being dropped, so the
+      // widget total still matches the underlying rows.
+      if (resolvedKey === undefined) undecryptableRows += 1
+      const groupKey = resolvedKey === undefined ? null : resolvedKey
+
+      let bucket = buckets.get(groupKey)
+      if (!bucket) {
+        bucket = createGroupBucket()
+        buckets.set(groupKey, bucket)
+      }
+
+      const metricValue = row.metric_value
+      if (metricValue === null || metricValue === undefined) continue
+      bucket.count += 1
+      const numeric = parseExactDecimal(metricValue)
+      if (numeric) foldMetricValue(bucket, numeric)
+    }
+
+    if (undecryptableRows > 0) {
+      // No DEK at all means every ciphertext row would collapse into "Unknown" and the widget would
+      // report a confidently wrong distribution, so fail closed rather than chart it (#4622).
+      if (!dek) {
+        throw new WidgetDataEncryptionUnavailableError(
+          `Cannot group encrypted field ${request.groupBy?.field}: tenant encryption key is unavailable`,
+        )
+      }
+      logger.warn('Grouped rows with an undecryptable group source as unknown', {
+        entityId: source.entityId,
+        column: source.dbColumn,
+        rows: undecryptableRows,
+      })
+    }
+
+    let data: WidgetDataItem[] = Array.from(buckets.entries())
+      .map(([groupKey, bucket]) => ({ groupKey, value: aggregateBucket(request.metric.aggregate, bucket) }))
+      .sort(compareWidgetDataItemsByValueDesc)
+
+    if (request.groupBy?.limit && request.groupBy.limit > 0) {
+      data = data.slice(0, Math.min(request.groupBy.limit, 100))
+    }
+
+    if (request.groupBy?.resolveLabels) {
+      data = await this.resolveGroupLabels(data, request.entityType, request.groupBy.field)
+    }
+
+    const totalValue = data.reduce((sum: number, item: WidgetDataItem) => sum + (item.value ?? 0), 0)
+    return { value: totalValue, data }
+  }
+
+  /**
+   * Returns the plaintext group key for a scanned row, `null` for an empty/absent value, or
+   * `undefined` when the source is ciphertext that could not be decrypted.
+   */
+  private resolveDecryptedGroupKey(
+    rawValue: unknown,
+    source: EncryptedGroupSource,
+    dek: string | null,
+  ): string | null | undefined {
+    if (rawValue === null || rawValue === undefined) return null
+
+    let value: unknown = rawValue
+    if (typeof value === 'string' && this.isEncryptedPayload(value)) {
+      if (!dek) return undefined
+      const decrypted = this.decryptWithDek(value, dek)
+      if (decrypted === null) return undefined
+      value = parseDecryptedFieldValue(decrypted)
+    }
+
+    if (source.jsonPath !== null) {
+      value = readJsonPath(value, source.jsonPath)
+    }
+
+    if (value === null || value === undefined || value === '') return null
+    if (typeof value === 'object') return null
+    const key = String(value)
+    // Defense in depth: a nested value that is itself ciphertext must never reach the response.
+    return this.isEncryptedPayload(key) ? undefined : key
+  }
+
   private async resolveGroupLabels(
     data: WidgetDataItem[],
     entityType: string,
@@ -272,10 +597,13 @@ export class WidgetDataService {
     const config = this.registry.getLabelResolverConfig(entityType, groupByField)
 
     if (!config) {
-      return data.map((item) => ({
-        ...item,
-        groupLabel: item.groupKey != null && item.groupKey !== '' ? String(item.groupKey) : undefined,
-      }))
+      return data.map((item) => {
+        if (item.groupKey == null || item.groupKey === '') return { ...item, groupLabel: undefined }
+        const label = String(item.groupKey)
+        // A ciphertext group key has no meaningful label; echoing it would render encrypted data
+        // into the chart legend (#4622).
+        return { ...item, groupLabel: this.isEncryptedPayload(label) ? undefined : label }
+      })
     }
 
     const ids = data
@@ -468,6 +796,16 @@ export class WidgetDataService {
     }
   }
 
+  /**
+   * Resolves the encryption entity id for an analytics table. A request-scoped `EntityManager` fork
+   * frequently reports an empty metadata registry, which used to make every group source look
+   * unencrypted and send the request back to the ciphertext-grouping SQL path (#4622). The table
+   * name alone is enough for the entity-id lookup, so it is the fallback.
+   */
+  private resolveEncryptionEntityId(tableName: string): string | null {
+    return this.resolveEntityId(this.resolveEntityMetadata(tableName)) ?? this.resolveEntityId({ tableName })
+  }
+
   private isEncryptedPayload(value: string): boolean {
     const parts = value.split(':')
     return parts.length === 4 && parts[3] === 'v1'