@open-mercato/core 0.6.5-develop.5337.1.534b781eac → 0.6.5

package/src/modules/auth/migrations/Migration20260610120000.ts

@@ -0,0 +1,53 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// #2934: User email uniqueness must be per-tenant, not global. The original
+// `users_email_unique` constraint (unique on `email` across all tenants) contradicts the
+// multi-tenant login flow — which resolves the same email across tenants via
+// `findUsersByEmail` — and leaks cross-tenant account existence / enables registration
+// squatting. Replace it with a partial unique index scoped per-tenant over live rows.
+//
+// The index is keyed on `email_hash`, NOT `email`: `email` is encrypted at rest with a
+// per-row IV (auth/encryption.ts -> shared aes.ts), so its ciphertext is non-deterministic
+// and a unique index on it would never detect duplicates under the default (encryption-on)
+// configuration. `email_hash` is the deterministic lookup hash the application already
+// de-dupes on, so the constraint is effective in both encryption-on and encryption-off
+// modes. This mirrors `customer_users_tenant_email_hash_uniq` in customer_accounts.
+//
+// `WHERE deleted_at IS NULL` lets a soft-deleted user's email be reused (the old non-partial
+// constraint blocked this); `AND email_hash IS NOT NULL` skips the rare legacy/bootstrap rows
+// that predate hash population (encryption-off `setup-app` users) — those remain protected by
+// the tenant-scoped application duplicate check.
+//
+// Before creating the index, soft-delete any pre-existing duplicate live rows per
+// (tenant_id, email_hash), keeping the most-recently-updated one. Under encryption the old
+// `email` constraint never fired, so same-tenant duplicates were only blocked by the
+// application check and a historical race could have slipped one through; the dedupe makes
+// the index creation safe on such data (no-op when there are none).
+export class Migration20260610120000 extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`
+      with ranked as (
+        select id,
+               row_number() over (
+                 partition by tenant_id, email_hash
+                 order by coalesce(updated_at, created_at) desc, created_at desc, id desc
+               ) as rn
+        from users
+        where deleted_at is null and email_hash is not null
+      )
+      update users
+      set deleted_at = now()
+      from ranked
+      where users.id = ranked.id and ranked.rn > 1;
+    `);
+    this.addSql(`alter table "users" drop constraint if exists "users_email_unique";`);
+    this.addSql(`create unique index if not exists "users_tenant_email_hash_uniq" on "users" ("tenant_id", "email_hash") where "deleted_at" is null and "email_hash" is not null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index if exists "users_tenant_email_hash_uniq";`);
+    this.addSql(`alter table "users" add constraint "users_email_unique" unique ("email");`);
+  }
+
+}

package/src/modules/auth/migrations/Migration20260611103000.ts

@@ -0,0 +1,21 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// #2966: user_roles carries only its FK constraints and Postgres does not
+// auto-index FK columns, so RBAC scans it sequentially by user_id on every
+// ACL cache miss (rbacService super-admin check + ACL aggregation) and by
+// role_id on user-list filtering and role rename/delete guards. Index both
+// FK columns so these hot paths become index scans. The table is small
+// relative to search_tokens, so a plain (transactional) build is safe.
+export class Migration20260611103000 extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create index if not exists "user_roles_user_id_idx" on "user_roles" ("user_id");`);
+    this.addSql(`create index if not exists "user_roles_role_id_idx" on "user_roles" ("role_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index if exists "user_roles_user_id_idx";`);
+    this.addSql(`drop index if exists "user_roles_role_id_idx";`);
+  }
+
+}

package/src/modules/auth/services/authService.ts

@@ -5,6 +5,13 @@ import { emailHashLookupValues } from '@open-mercato/core/modules/auth/lib/email
 import { generateAuthToken, hashAuthToken } from '@open-mercato/core/modules/auth/lib/tokenHash'
 import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 
+// A fixed, valid bcrypt hash (cost 10) of a throwaway value no real password
+// can match. verifyPassword compares against it whenever the user is missing or
+// has no password hash, so a failed login spends the same bcrypt CPU time
+// regardless of whether the account exists — closing the timing side channel
+// for account enumeration (issue #2242).
+const TIMING_EQUALIZER_PASSWORD_HASH = '$2b$10$OcZrhmZpIzJOjkfwUrk7d.Nl0eHNzOvalBcBlt5Ran.4lj8R3HZg6'
+
 export class AuthService {
   constructor(private em: EntityManager) {}
 
@@ -48,9 +55,13 @@ export class AuthService {
     )
   }
 
-  async verifyPassword(user: User, password: string) {
-    if (!user.passwordHash) return false
-    return compare(password, user.passwordHash)
+  async verifyPassword(user: User | null, password: string) {
+    const storedHash = user?.passwordHash ?? null
+    // Always run a bcrypt comparison — against a fixed dummy hash when the user
+    // is absent or has no password — so login latency does not reveal whether
+    // the account exists (timing-based enumeration, issue #2242).
+    const matched = await compare(password, storedHash ?? TIMING_EQUALIZER_PASSWORD_HASH)
+    return storedHash !== null && matched
   }
 
   async updateLastLoginAt(user: User) {
@@ -70,7 +81,16 @@ export class AuthService {
       { populate: ['role'] },
       { tenantId: resolvedTenantId, organizationId: user.organizationId ?? null },
     )
-    return links.map((l) => l.role.name)
+    // A populated `role` can still be null when the link points at a soft-deleted
+    // role (the Role soft-delete filter suppresses hydration), e.g. an admin link
+    // orphaned by a re-seed during interrupted-provisioning recovery. Dropping such
+    // links keeps role resolution from throwing on the login / session-refresh hot
+    // path, mirroring resolveCanonicalStaffAuthContext in lib/sessionIntegrity.ts.
+    return links
+      .map((l) => l.role)
+      .filter((role): role is Role => !!role)
+      .map((role) => role.name)
+      .filter((name): name is string => typeof name === 'string' && name.trim().length > 0)
   }
 
 

package/src/modules/auth/services/rbacService.ts

@@ -4,6 +4,7 @@ import { getCurrentCacheTenant, runWithCacheTenant } from '@open-mercato/cache'
 import { UserAcl, RoleAcl, User, UserRole } from '@open-mercato/core/modules/auth/data/entities'
 import { ApiKey } from '@open-mercato/core/modules/api_keys/data/entities'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { buildOrgScopeUserCacheTag, buildOrgScopeTenantCacheTag } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { matchFeature as sharedMatchFeature, hasAllFeatures as sharedHasAllFeatures } from '@open-mercato/shared/lib/auth/featureMatch'
 import { filterGrantsByEnabledModules, getOwningModuleId, getEnabledModuleIds } from '@open-mercato/shared/security/enabledModulesRegistry'
 
@@ -130,7 +131,12 @@ export class RbacService {
    */
   async invalidateUserCache(userId: string): Promise<void> {
     this.globalSuperAdminCache.delete(userId)
-    await this.deleteCacheByTags([this.getUserTag(userId)])
+    // Also drop the directory OrganizationScope cache for this user. That scope's
+    // accessible-org set is derived from this user's ACL/role grants, so any
+    // permission change that invalidates the RBAC cache must invalidate the
+    // resolved scope too. This is the missing `org-scope:user:*` caller required
+    // before the cross-request scope TTL can be safely enabled (issue #2259).
+    await this.deleteCacheByTags([this.getUserTag(userId), buildOrgScopeUserCacheTag(userId)])
   }
 
   /**
@@ -142,7 +148,10 @@ export class RbacService {
    */
   async invalidateTenantCache(tenantId: string): Promise<void> {
     this.globalSuperAdminCache.clear()
-    await this.deleteCacheByTags([this.getTenantTag(tenantId)], [tenantId])
+    // Role ACL changes invalidate every user in the tenant; the resolved
+    // OrganizationScope for those users derives from the same grants, so drop
+    // the tenant-tagged scope entries alongside the RBAC ones (issue #2259).
+    await this.deleteCacheByTags([this.getTenantTag(tenantId), buildOrgScopeTenantCacheTag(tenantId)], [tenantId])
   }
 
   /**

package/src/modules/catalog/ai-tools/configuration-pack.ts

@@ -5,7 +5,7 @@
  * Product-configuration surface: option schemas (variant axes) and unit
  * conversions (UoM factors).
  *
- * Phase 3c of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3c of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * both tools are now API-backed wrappers over the documented CRUD list
  * routes (`GET /api/catalog/option-schemas` and
  * `GET /api/catalog/product-unit-conversions`). Tool names, schemas,

package/src/modules/catalog/ai-tools/prices-offers-pack.ts

@@ -11,7 +11,7 @@
  * names available so the D18 tool can layer merchandising-specific shape
  * over the base enumerator.
  *
- * Phase 3b of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3b of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * `catalog.list_prices` and `catalog.list_offers` are now API-backed wrappers
  * over `GET /api/catalog/prices` and `GET /api/catalog/offers`. Tool names,
  * schemas, requiredFeatures, and output shapes are unchanged. The offers

package/src/modules/catalog/ai-tools/products-pack.ts

@@ -4,7 +4,7 @@
  * Read-only tools scoped to `ctx.tenantId` + `ctx.organizationId`. Mutation
  * tools are deferred to Step 5.14 under the pending-action contract.
  *
- * Phase 3b of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3b of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * `catalog.list_products` is now an API-backed wrapper over
  * `GET /api/catalog/products`. Tool name, schema, requiredFeatures, and
  * output shape are unchanged.

package/src/modules/catalog/ai-tools/variants-pack.ts

@@ -3,7 +3,7 @@
  *
  * Enumerate variants for a single product with option values + media refs.
  *
- * Phase 3b of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3b of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * `catalog.list_variants` is now an API-backed wrapper over
  * `GET /api/catalog/variants`. Tool name, schema, requiredFeatures, and
  * output shape are unchanged.

package/src/modules/communication_channels/data/entities.ts

@@ -440,7 +440,7 @@ export class MessageReaction {
  * forged inbound messages: tokens that don't HMAC-verify never reach the DB
  * lookup.
  *
- * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`.
+ * See `.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md`.
  */
 @Entity({ tableName: 'channel_thread_tokens' })
 // One token row per (tenant, thread): the matcher resolves every reply to the
@@ -495,7 +495,7 @@ export class ChannelThreadToken {
  * `raw_body` is encrypted at rest via the module's `encryption.ts`
  * `defaultEncryptionMaps` entry (MIME bodies may contain PII).
  *
- * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`
+ * See `.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md`
  * (§ 3 Data Model).
  */
 @Entity({ tableName: 'channel_ingest_dead_letters' })

package/src/modules/communication_channels/encryption.ts

@@ -31,7 +31,7 @@ import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryptio
  *     contact resolution looks addresses up by value (see the address blind-index
  *     follow-up in customers/lib/findPeopleByAddresses.ts).
  *
- * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`
+ * See `.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md`
  * (§ 3 Encryption posture).
  */
 export const defaultEncryptionMaps: ModuleEncryptionMap[] = [

package/src/modules/communication_channels/lib/adapter.ts

@@ -445,7 +445,7 @@ export interface ExchangeOAuthCodeResult {
  * `RefreshCredentialsInput`. Adapters without OAuth refresh (IMAP, WhatsApp
  * Business API) ignore it.
  *
- * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`.
+ * See `.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md`.
  */
 export interface OAuthClientConfig {
   clientId: string

package/src/modules/communication_channels/lib/thread-matcher.ts

@@ -19,7 +19,7 @@ import { extractTokenFromBody, extractTokenFromHeaders } from './thread-token'
  * `UPDATE` that bumps a matched token's `last_seen_at` (a future-GC hint),
  * which does not touch the caller's pending entities.
  *
- * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`
+ * See `.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md`
  * § 4 Threading Algorithm.
  */
 

package/src/modules/communication_channels/lib/thread-token.ts

@@ -17,7 +17,7 @@ import { isUniqueViolation } from './pg-errors'
  * `(tenantId, token)` so that even if the HMAC key leaked, tenant
  * isolation still holds at the DB layer.
  *
- * See `.ai/specs/2026-05-27-email-integration-inbound-reliability-and-threading.md`.
+ * See `.ai/specs/implemented/2026-05-27-email-integration-inbound-reliability-and-threading.md`.
  */
 
 const TOKEN_PREFIX = 'om_'

package/src/modules/currencies/api/currencies/route.ts

@@ -6,6 +6,7 @@ import type { EntityManager } from '@mikro-orm/postgresql'
 import type { FilterQuery } from '@mikro-orm/core'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
 import { currencyCreateSchema, currencyUpdateSchema } from '../../data/validators'
 import {
   createCurrenciesCrudOpenApi,
@@ -148,9 +149,9 @@ export async function GET(req: Request) {
   if (code) filter.code = code
   if (search) {
     filter.$or = [
-      { code: { $ilike: `%${search}%` } },
-      { name: { $ilike: `%${search}%` } },
-      { symbol: { $ilike: `%${search}%` } },
+      { code: { $ilike: `%${escapeLikePattern(search)}%` } },
+      { name: { $ilike: `%${escapeLikePattern(search)}%` } },
+      { symbol: { $ilike: `%${escapeLikePattern(search)}%` } },
     ]
   }
   if (isBase === 'true') filter.isBase = true

package/src/modules/customer_accounts/api/admin/roles.ts

@@ -3,6 +3,7 @@ import { z } from 'zod'
 import type { OpenApiRouteDoc, OpenApiMethodDoc } from '@open-mercato/shared/lib/openapi'
 import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
 import { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
 import { CustomerRole, CustomerRoleAcl } from '@open-mercato/core/modules/customer_accounts/data/entities'
 import { createRoleSchema } from '@open-mercato/core/modules/customer_accounts/data/validators'
@@ -37,7 +38,7 @@ export async function GET(req: Request) {
   }
 
   if (search) {
-    const escapedSearch = search.replace(/[%_\\]/g, '\\$&')
+    const escapedSearch = escapeLikePattern(search)
     where.$or = [
       { name: { $ilike: `%${escapedSearch}%` } },
       { slug: { $ilike: `%${escapedSearch}%` } },

package/src/modules/customer_accounts/backend/customer_accounts/settings/domain/components/Diagnostics.tsx

@@ -1,7 +1,6 @@
 "use client"
 
 import * as React from 'react'
-import { AlertTriangle } from 'lucide-react'
 import { Alert, AlertTitle, AlertDescription } from '@open-mercato/ui/primitives/alert'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import type { DomainMappingRow } from './types'
@@ -15,7 +14,6 @@ export function DnsDiagnostics({ mapping }: DiagnosticsProps) {
   if (mapping.status !== 'dns_failed') return null
   return (
     <Alert variant="destructive">
-      <AlertTriangle className="h-4 w-4" aria-hidden />
       <AlertTitle>
         {t('customer_accounts.domainMapping.dns.diagnostics.title', 'DNS configuration issue')}
       </AlertTitle>
@@ -41,7 +39,6 @@ export function TlsDiagnostics({ mapping }: DiagnosticsProps) {
   if (mapping.status !== 'tls_failed') return null
   return (
     <Alert variant="warning">
-      <AlertTriangle className="h-4 w-4" aria-hidden />
       <AlertTitle>
         {t('customer_accounts.domainMapping.tls.diagnostics.title', 'SSL certificate issue')}
       </AlertTitle>

package/src/modules/customer_accounts/events.ts

@@ -18,7 +18,7 @@ const events = [
   { id: 'customer_accounts.role.deleted', label: 'Customer Role Deleted', entity: 'role', category: 'crud' },
   { id: 'customer_accounts.invitation.accepted', label: 'Customer Invitation Accepted', category: 'lifecycle', clientBroadcast: true },
   { id: 'customer_accounts.password_reset.requested', label: 'Customer Password Reset Requested', category: 'lifecycle' },
-  // Custom domain mapping lifecycle (see .ai/specs/2026-04-08-portal-custom-domain-routing.md)
+  // Custom domain mapping lifecycle (see .ai/specs/implemented/2026-04-08-portal-custom-domain-routing.md)
   { id: 'customer_accounts.domain_mapping.created', label: 'Custom Domain Registered', entity: 'domain_mapping', category: 'crud', clientBroadcast: true },
   { id: 'customer_accounts.domain_mapping.verified', label: 'Custom Domain DNS Verified', entity: 'domain_mapping', category: 'lifecycle', clientBroadcast: true },
   { id: 'customer_accounts.domain_mapping.activated', label: 'Custom Domain Active', entity: 'domain_mapping', category: 'lifecycle', clientBroadcast: true },

package/src/modules/customer_accounts/lib/resolveTenantContext.ts

@@ -12,8 +12,8 @@
  * signup, magic-link, password-reset) so they all behave consistently when
  * the request arrives on a tenant's branded URL.
  *
- * See `.ai/specs/2026-04-08-portal-custom-domain-routing.md` Phase 1.5 and
- * `.ai/specs/2026-06-05-tenant-ownership-and-module-acl-authorization.md` § C.
+ * See `.ai/specs/implemented/2026-04-08-portal-custom-domain-routing.md` Phase 1.5 and
+ * `.ai/specs/implemented/2026-06-05-tenant-ownership-and-module-acl-authorization.md` § C.
  */
 
 import { tryNormalizeHostname } from '@open-mercato/core/modules/customer_accounts/lib/hostname'

package/src/modules/customers/acl.ts

@@ -89,7 +89,7 @@ export const features = [
   // privacy model is strict owner-only with NO admin bypass, so this feature is
   // declared but INERT — granting it does not unlock other users' private emails
   // (the visibility filter and the visibility-change gate ignore it). See
-  // .ai/specs/2026-05-27-crm-email-integration.md (v1 strict owner-only).
+  // .ai/specs/implemented/2026-05-27-crm-email-integration.md (v1 strict owner-only).
   {
     id: 'customers.email.view_private',
     title: 'View other users\' private emails (reserved — inert in v1)',

package/src/modules/customers/ai-tools/companies-pack.ts

@@ -1,7 +1,7 @@
 /**
  * `customers.list_companies` + `customers.get_company` (Phase 1 WS-C, Step 3.9).
  *
- * Phase 3a of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3a of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * `customers.list_companies` is now an API-backed wrapper over
  * `GET /api/customers/companies`. Tool name, schema, requiredFeatures, and
  * output shape are unchanged.

package/src/modules/customers/ai-tools/deals-pack.ts

@@ -2,7 +2,7 @@
  * `customers.list_deals` + `customers.get_deal` (Phase 1 WS-C, Step 3.9).
  * `customers.update_deal_stage` mutation tool (Phase 3 WS-C, Step 5.13).
  *
- * Phase 3a of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3a of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * `customers.list_deals` is now an API-backed wrapper over
  * `GET /api/customers/deals`. Tool name, schema, requiredFeatures, and output
  * shape are unchanged.

package/src/modules/customers/ai-tools/people-pack.ts

@@ -5,7 +5,7 @@
  * the existing customers query engine + encryption helpers. Mutation tools
  * are deferred to Step 5.13+ under the pending-action contract.
  *
- * Phase 3a of `.ai/specs/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
+ * Phase 3a of `.ai/specs/implemented/2026-04-27-ai-tools-api-backed-dry-refactor.md`:
  * `customers.list_people` is now an API-backed wrapper over
  * `GET /api/customers/people`. The `companyId` AI input has no inclusion
  * equivalent on the route (the route exposes `excludeLinkedCompanyId` only)

package/src/modules/customers/api/companies/route.ts

@@ -23,7 +23,7 @@ import {
   extractAllCustomFieldEntries,
   splitCustomFieldPayload,
 } from '@open-mercato/shared/lib/crud/custom-fields'
-import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { buildIlikeTerm } from '@open-mercato/shared/lib/db/buildIlikeTerm'
 import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { consumeAdvancedFilterState, mergeAdvancedFilterTree } from '@open-mercato/shared/lib/crud/advanced-filter-integration'
@@ -178,7 +178,7 @@ const crud = makeCrudRoute({
         if (matchingIds !== null && matchingIds.length > 0) {
           applyEntityIdRestriction(filters, matchingIds)
         } else {
-          const searchPattern = `%${escapeLikePattern(query.search)}%`
+          const searchPattern = buildIlikeTerm(query.search)
           filters.$or = [
             { display_name: { $ilike: searchPattern } },
             { primary_email: { $ilike: searchPattern } },
@@ -276,9 +276,9 @@ const crud = makeCrudRoute({
       if (email) {
         filters.primary_email = { $eq: email }
       } else if (emailStartsWith) {
-        filters.primary_email = { $ilike: `${escapeLikePattern(emailStartsWith)}%` }
+        filters.primary_email = { $ilike: buildIlikeTerm(emailStartsWith, 'startsWith') }
       } else if (emailContains) {
-        filters.primary_email = { $ilike: `%${escapeLikePattern(emailContains)}%` }
+        filters.primary_email = { $ilike: buildIlikeTerm(emailContains) }
       }
       const hasEmail = parseBooleanToken(query.hasEmail)
       if (!email && !emailStartsWith && !emailContains && hasEmail !== null) {

package/src/modules/customers/api/deals/route.ts

@@ -27,6 +27,7 @@ import { fetchStuckDealIds } from '../../lib/stuckDeals'
 const rawBodySchema = z.object({}).passthrough()
 
 const stringOrStringArray = z.union([z.string(), z.array(z.string())])
+const OPEN_DEAL_STATUSES = ['open', 'in_progress'] as const
 const booleanQueryParam = z.preprocess((value) => {
   const parsed = parseBooleanFromUnknown(value)
   return parsed === null ? value : parsed
@@ -47,6 +48,7 @@ export const dealListQuerySchema = z
     expectedCloseAtTo: z.string().optional(),
     isStuck: booleanQueryParam,
     isOverdue: booleanQueryParam,
+    needsAttention: booleanQueryParam,
     valueCurrency: stringOrStringArray.optional(),
     sortField: z.string().optional(),
     sortDir: z.enum(['asc', 'desc']).optional(),
@@ -156,6 +158,43 @@ async function fetchDealIdsMatchingAssociations(
   return rows.map((row) => row.id)
 }
 
+async function fetchNeedAttentionDealIds(
+  em: EntityManager,
+  organizationId: string,
+  tenantId: string,
+): Promise<string[]> {
+  const connection = em.getConnection()
+  const overdueRows = await connection.execute<Array<{ id: string }>>(
+    `SELECT id FROM customer_deals
+      WHERE organization_id = ?
+        AND tenant_id = ?
+        AND deleted_at IS NULL
+        AND status = 'open'
+        AND expected_close_at IS NOT NULL
+        AND expected_close_at < CURRENT_DATE`,
+    [organizationId, tenantId],
+  )
+
+  const attentionIds = new Set(overdueRows.map((row) => row.id))
+  const stuckIds = await fetchStuckDealIds(em, organizationId, tenantId)
+  if (stuckIds.length > 0) {
+    const idPlaceholders = stuckIds.map(() => '?').join(',')
+    const statusPlaceholders = OPEN_DEAL_STATUSES.map(() => '?').join(',')
+    const openStuckRows = await connection.execute<Array<{ id: string }>>(
+      `SELECT id FROM customer_deals
+        WHERE organization_id = ?
+          AND tenant_id = ?
+          AND deleted_at IS NULL
+          AND status IN (${statusPlaceholders})
+          AND id IN (${idPlaceholders})`,
+      [organizationId, tenantId, ...OPEN_DEAL_STATUSES, ...stuckIds],
+    )
+    for (const row of openStuckRows) attentionIds.add(row.id)
+  }
+
+  return Array.from(attentionIds)
+}
+
 function normalizeCurrencyList(value: unknown): string[] {
   const set = new Set<string>()
   const visit = (entry: unknown) => {
@@ -302,7 +341,7 @@ export async function buildDealListFilters(query: DealListQuery, ctx?: import('@
     filters.expected_close_at = range
   }
 
-  if (query.isOverdue) {
+  if (query.isOverdue && !query.needsAttention) {
     const today = new Date()
     today.setHours(0, 0, 0, 0)
     if (statusList.length === 0) {
@@ -316,7 +355,7 @@ export async function buildDealListFilters(query: DealListQuery, ctx?: import('@
     filters.expected_close_at = existingRange
   }
 
-  if (query.isStuck && ctx) {
+  if (query.isStuck && !query.needsAttention && ctx) {
     const tenantId = ctx.auth?.tenantId
     // CrudCtx.auth carries `orgId` (not `organizationId`). The previous code referenced
     // `organizationId` which is always `undefined`, so the typeof check below silently
@@ -329,6 +368,16 @@ export async function buildDealListFilters(query: DealListQuery, ctx?: import('@
     }
   }
 
+  if (query.needsAttention && ctx) {
+    const tenantId = ctx.auth?.tenantId
+    const organizationId = ctx.auth?.orgId
+    if (typeof tenantId === 'string' && typeof organizationId === 'string') {
+      const em = ctx.container.resolve<EntityManager>('em')
+      const attentionIds = await fetchNeedAttentionDealIds(em, organizationId, tenantId)
+      intersectIds(attentionIds)
+    }
+  }
+
   // Pre-pagination association filter. Must run on the FULL dataset (before pagination),
   // otherwise matching deals on later pages disappear and `total` would be wrong. Read the
   // raw URL too so legacy `?personEntityId=` / `?companyEntityId=` keep working alongside the