@open-mercato/search 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (37) hide show
  1. package/.turbo/turbo-build.log +1 -1
  2. package/dist/lib/merger.js +5 -2
  3. package/dist/lib/merger.js.map +2 -2
  4. package/dist/modules/search/__integration__/TC-SEARCH-003.spec.js +64 -0
  5. package/dist/modules/search/__integration__/TC-SEARCH-003.spec.js.map +7 -0
  6. package/dist/modules/search/__integration__/TC-SEARCH-004.spec.js +97 -0
  7. package/dist/modules/search/__integration__/TC-SEARCH-004.spec.js.map +7 -0
  8. package/dist/modules/search/__integration__/TC-SEARCH-005.spec.js +28 -0
  9. package/dist/modules/search/__integration__/TC-SEARCH-005.spec.js.map +7 -0
  10. package/dist/modules/search/__integration__/TC-SEARCH-006.spec.js +48 -0
  11. package/dist/modules/search/__integration__/TC-SEARCH-006.spec.js.map +7 -0
  12. package/dist/modules/search/__integration__/TC-SEARCH-007.spec.js +38 -0
  13. package/dist/modules/search/__integration__/TC-SEARCH-007.spec.js.map +7 -0
  14. package/dist/modules/search/__integration__/TC-SEARCH-008.spec.js +77 -0
  15. package/dist/modules/search/__integration__/TC-SEARCH-008.spec.js.map +7 -0
  16. package/dist/modules/search/__integration__/TC-SEARCH-009.spec.js +54 -0
  17. package/dist/modules/search/__integration__/TC-SEARCH-009.spec.js.map +7 -0
  18. package/dist/modules/search/ai-tools.js +61 -2
  19. package/dist/modules/search/ai-tools.js.map +2 -2
  20. package/dist/vector/services/vector-index.service.js +45 -25
  21. package/dist/vector/services/vector-index.service.js.map +2 -2
  22. package/package.json +9 -10
  23. package/src/__tests__/merger.test.ts +50 -0
  24. package/src/__tests__/vector-index-security.test.ts +230 -0
  25. package/src/lib/merger.ts +16 -2
  26. package/src/modules/search/README.md +1 -1
  27. package/src/modules/search/__integration__/TC-SEARCH-003.spec.ts +102 -0
  28. package/src/modules/search/__integration__/TC-SEARCH-004.spec.ts +135 -0
  29. package/src/modules/search/__integration__/TC-SEARCH-005.spec.ts +45 -0
  30. package/src/modules/search/__integration__/TC-SEARCH-006.spec.ts +74 -0
  31. package/src/modules/search/__integration__/TC-SEARCH-007.spec.ts +72 -0
  32. package/src/modules/search/__integration__/TC-SEARCH-008.spec.ts +124 -0
  33. package/src/modules/search/__integration__/TC-SEARCH-009.spec.ts +85 -0
  34. package/src/modules/search/__tests__/ai-tools.aggregate.test.ts +89 -4
  35. package/src/modules/search/__tests__/ai-tools.get.test.ts +118 -0
  36. package/src/modules/search/ai-tools.ts +111 -3
  37. package/src/vector/services/vector-index.service.ts +57 -25
@@ -0,0 +1,72 @@
1
+ import { expect, test } from '@playwright/test'
2
+ import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
3
+ import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
4
+
5
+ type ReindexLock = {
6
+ type?: string
7
+ action?: string
8
+ startedAt?: string
9
+ elapsedMinutes?: number
10
+ processedCount?: number | null
11
+ totalCount?: number | null
12
+ }
13
+ type ConflictBody = { error?: string; lock?: ReindexLock }
14
+ type SearchSettingsResponse = { settings?: { fulltextReindexLock?: ReindexLock | null } }
15
+
16
+ const DEFAULT_STRATEGIES = ['fulltext', 'vector', 'tokens']
17
+
18
+ /**
19
+ * TC-SEARCH-007: concurrent fulltext reindex returns 409 with lock info.
20
+ * Source: issue #2483.
21
+ *
22
+ * Route: POST /api/search/reindex (requireFeatures ['search.reindex']). The route
23
+ * acquires a per-tenant DB lock BEFORE any indexing work and, in queue mode
24
+ * (useQueue:true — the default), does NOT release it in `finally` (workers and
25
+ * the heartbeat own it). So a first call holds the lock and a second call returns
26
+ * 409 with the lock descriptor — independent of whether a fulltext backend is
27
+ * configured, because the lock is taken before the strategy-availability check.
28
+ * Integration specs run serially (workers:1), so no other test contends for the
29
+ * shared lock; it is released in `finally` via the cancel endpoint.
30
+ */
31
+ test.describe('TC-SEARCH-007: concurrent fulltext reindex returns 409 with lock info', () => {
32
+ test('a second reindex while one is active is rejected with 409', async ({ request }) => {
33
+ test.slow()
34
+ test.setTimeout(120_000)
35
+
36
+ let token: string | null = null
37
+
38
+ try {
39
+ token = await getAuthToken(request, 'admin')
40
+
41
+ // Start from a clean lock state.
42
+ await apiRequest(request, 'POST', '/api/search/reindex/cancel', { token }).catch(() => undefined)
43
+ await apiRequest(request, 'POST', '/api/search/settings/global-search', {
44
+ token,
45
+ data: { enabledStrategies: DEFAULT_STRATEGIES },
46
+ }).catch(() => undefined)
47
+
48
+ // First reindex acquires (and, in queue mode, holds) the fulltext lock.
49
+ const first = await apiRequest(request, 'POST', '/api/search/reindex', { token, data: { useQueue: true } })
50
+ expect(first.status(), 'first reindex must not hit a pre-existing lock').not.toBe(409)
51
+ expect([200, 503], 'first reindex starts (200) or reports backend unavailable (503)').toContain(first.status())
52
+
53
+ const settings = await apiRequest(request, 'GET', '/api/search/settings', { token })
54
+ expect(settings.ok(), 'search settings should be readable after starting reindex').toBeTruthy()
55
+ const settingsBody = (await readJsonSafe<SearchSettingsResponse>(settings)) ?? {}
56
+ expect(settingsBody.settings?.fulltextReindexLock?.type, 'first reindex should leave an observable fulltext lock').toBe('fulltext')
57
+
58
+ // Second reindex is rejected while the first holds the lock.
59
+ const second = await apiRequest(request, 'POST', '/api/search/reindex', { token, data: { useQueue: true } })
60
+ expect(second.status(), 'a concurrent reindex must be rejected with 409').toBe(409)
61
+ const body = (await readJsonSafe<ConflictBody>(second)) ?? {}
62
+ expect(body.lock?.type, 'the 409 lock descriptor identifies the fulltext lock').toBe('fulltext')
63
+ expect(typeof body.lock?.action, 'the lock reports its action').toBe('string')
64
+ expect(typeof body.lock?.startedAt, 'the lock reports when it started').toBe('string')
65
+ expect(typeof body.lock?.elapsedMinutes, 'the lock reports elapsed minutes').toBe('number')
66
+ } finally {
67
+ if (token) {
68
+ await apiRequest(request, 'POST', '/api/search/reindex/cancel', { token }).catch(() => undefined)
69
+ }
70
+ }
71
+ })
72
+ })
@@ -0,0 +1,124 @@
1
+ import { expect, test, type APIRequestContext } from '@playwright/test'
2
+ import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
3
+ import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
4
+ import { createCompanyFixture, deleteEntityIfExists } from '@open-mercato/core/helpers/integration/crmFixtures'
5
+
6
+ type IndexEntry = { entityId?: string; recordId?: string }
7
+ type IndexResponse = { entries?: IndexEntry[]; limit?: number; offset?: number }
8
+
9
+ const COMPANY_ENTITY = 'customers:customer_company_profile'
10
+
11
+ async function getIndex(
12
+ request: APIRequestContext,
13
+ token: string,
14
+ params: Record<string, string>,
15
+ ): Promise<{ status: number; body: IndexResponse }> {
16
+ const qs = new URLSearchParams(params).toString()
17
+ const res = await apiRequest(request, 'GET', `/api/search/index${qs ? `?${qs}` : ''}`, { token })
18
+ const body = res.ok() ? ((await readJsonSafe<IndexResponse>(res)) ?? {}) : {}
19
+ return { status: res.status(), body }
20
+ }
21
+
22
+ /**
23
+ * TC-SEARCH-008: vector index list pagination & entityId filter.
24
+ * Source: issue #2483.
25
+ *
26
+ * Route: GET /api/search/index (requireFeatures ['search.view']) returns the
27
+ * vector-store entries (VectorIndexEntry: entityId, recordId, … — there is no
28
+ * surrogate `id`) with limit/offset paging and an optional entityId filter.
29
+ * Exercising it requires a working embedding pipeline (a provider key AND an
30
+ * applied embedding config that produces indexed rows). When the index is not
31
+ * listable — the endpoint returns 503 (vector strategy unavailable) or 500 (no
32
+ * embedding config / vector table) — this test skips, mirroring how the
33
+ * fulltext-dependent specs skip when Meilisearch is absent. The full pagination
34
+ * contract runs only when the vector index is queryable and rows materialize.
35
+ */
36
+ test.describe('TC-SEARCH-008: vector index list pagination & entityId filter', () => {
37
+ test('paginates entries and filters by entityId', async ({ request }) => {
38
+ test.slow()
39
+
40
+ let token: string | null = null
41
+ const companyIds: string[] = []
42
+ const stamp = Date.now()
43
+
44
+ try {
45
+ token = await getAuthToken(request, 'admin')
46
+
47
+ // The endpoint must be queryable (200). A 503 (vector strategy unavailable)
48
+ // or 500 (no embedding config / vector table) means the index cannot be
49
+ // paginated in this environment — skip rather than fail.
50
+ const probe = await getIndex(request, token, {})
51
+ if (probe.status !== 200) {
52
+ test.skip(true, `vector index is not listable in this environment (status ${probe.status})`)
53
+ return
54
+ }
55
+
56
+ for (let i = 0; i < 3; i += 1) {
57
+ companyIds.push(await createCompanyFixture(request, token, `QASRCH008-${stamp}-${i}`))
58
+ }
59
+
60
+ // Trigger a (queued) vector reindex and wait for rows to materialize.
61
+ await apiRequest(request, 'POST', '/api/search/embeddings/reindex', {
62
+ token,
63
+ data: { entityId: COMPANY_ENTITY },
64
+ }).catch(() => undefined)
65
+
66
+ let entries: IndexEntry[] = []
67
+ for (let attempt = 0; attempt < 20; attempt += 1) {
68
+ entries = (await getIndex(request, token, {})).body.entries ?? []
69
+ if (entries.length >= 2) break
70
+ await new Promise((resolve) => setTimeout(resolve, 1_000))
71
+ }
72
+ if (entries.length < 2) {
73
+ test.skip(true, 'vector index did not reach 2 entries; the embedding pipeline does not produce rows here')
74
+ return
75
+ }
76
+
77
+ // Default paging metadata, with enough rows to page over.
78
+ const base = await getIndex(request, token, {})
79
+ expect(base.body.limit, 'default limit is 50').toBe(50)
80
+ expect(base.body.offset, 'default offset is 0').toBe(0)
81
+ expect((base.body.entries ?? []).length, 'index has at least two entries to page over').toBeGreaterThanOrEqual(2)
82
+
83
+ // limit caps the page size and is echoed back.
84
+ const limited = await getIndex(request, token, { limit: '1', offset: '0' })
85
+ expect(limited.body.limit, 'response echoes the requested limit').toBe(1)
86
+ expect(limited.body.entries?.length ?? 0, 'limit=1 returns at most one entry').toBeLessThanOrEqual(1)
87
+
88
+ // A two-row page returns two DISTINCT records — proves paging yields
89
+ // distinct rows (keyed on recordId, the stable per-record identifier).
90
+ const pageOfTwo = await getIndex(request, token, { limit: '2', offset: '0' })
91
+ const twoIds = (pageOfTwo.body.entries ?? []).map((entry) => entry.recordId)
92
+ expect(twoIds.length, 'a limit=2 page returns two rows').toBe(2)
93
+ expect(twoIds[0], 'each paged entry exposes a recordId').toBeTruthy()
94
+ expect(twoIds[1], 'the two paged entries are distinct records').not.toBe(twoIds[0])
95
+
96
+ // offset advances the window to a different record and is echoed back.
97
+ const page2 = await getIndex(request, token, { limit: '1', offset: '1' })
98
+ expect(page2.body.offset, 'response echoes the requested offset').toBe(1)
99
+ const offset0Id = limited.body.entries?.[0]?.recordId
100
+ const offset1Id = page2.body.entries?.[0]?.recordId
101
+ expect(offset1Id, 'offset=1 returns a record').toBeTruthy()
102
+ expect(offset1Id, 'offset=1 returns a different record than offset=0').not.toBe(offset0Id)
103
+
104
+ // entityId filter narrows to the requested entity type (and is non-empty,
105
+ // so the uniformity assertion is not vacuous).
106
+ const filtered = await getIndex(request, token, { entityId: COMPANY_ENTITY, limit: '50' })
107
+ expect((filtered.body.entries ?? []).length, 'company entityId filter returns at least our fixtures').toBeGreaterThan(
108
+ 0,
109
+ )
110
+ for (const entry of filtered.body.entries ?? []) {
111
+ expect(entry.entityId, 'entityId filter returns only that entity type').toBe(COMPANY_ENTITY)
112
+ }
113
+ } finally {
114
+ // Vector reindex acquires a lock that its route does NOT release (workers
115
+ // own it), so explicitly cancel to avoid leaving a lock behind.
116
+ if (token) {
117
+ await apiRequest(request, 'POST', '/api/search/embeddings/reindex/cancel', { token }).catch(() => undefined)
118
+ }
119
+ for (const id of companyIds) {
120
+ await deleteEntityIfExists(request, token, '/api/customers/companies', id)
121
+ }
122
+ }
123
+ })
124
+ })
@@ -0,0 +1,85 @@
1
+ import { expect, test, type APIRequestContext } from '@playwright/test'
2
+ import { apiRequest, getAuthToken } from '@open-mercato/core/helpers/integration/api'
3
+ import { readJsonSafe } from '@open-mercato/core/helpers/integration/generalFixtures'
4
+ import {
5
+ createCompanyFixture,
6
+ createPersonFixture,
7
+ deleteEntityIfExists,
8
+ } from '@open-mercato/core/helpers/integration/crmFixtures'
9
+
10
+ type SearchResultItem = { entityId?: string; presenter?: { title?: string } | null }
11
+ type SearchResponse = { results?: SearchResultItem[] }
12
+
13
+ const COMPANY_ENTITY = 'customers:customer_company_profile'
14
+ const PERSON_ENTITY = 'customers:customer_person_profile'
15
+
16
+ async function searchResults(
17
+ request: APIRequestContext,
18
+ token: string,
19
+ query: string,
20
+ entityTypes: string,
21
+ ): Promise<SearchResultItem[]> {
22
+ const params = new URLSearchParams({ q: query, limit: '20', entityTypes })
23
+ const res = await apiRequest(request, 'GET', `/api/search/search?${params.toString()}`, { token })
24
+ if (!res.ok()) return []
25
+ const body = (await readJsonSafe<SearchResponse>(res)) ?? {}
26
+ return Array.isArray(body.results) ? body.results : []
27
+ }
28
+
29
+ /**
30
+ * TC-SEARCH-009: search entityTypes filter isolates entity types
31
+ * Source: issue #2483.
32
+ *
33
+ * Creates a company and a person that share a unique token in their searchable
34
+ * text, then asserts that filtering by entity type returns only that type. Token
35
+ * search (PostgreSQL) is always available; indexing is asynchronous, so results
36
+ * are polled. The unique query token only matches these two fixtures, so a
37
+ * type-filtered response that is non-empty AND uniform proves the filter holds.
38
+ */
39
+ test.describe('TC-SEARCH-009: search entityTypes filter isolates entity types', () => {
40
+ test('filtering by company / person type returns only that type', async ({ request }) => {
41
+ test.slow()
42
+
43
+ const stamp = Date.now()
44
+ const unique = `QASRCH009${stamp}`
45
+ let token: string | null = null
46
+ let companyId: string | null = null
47
+ let personId: string | null = null
48
+
49
+ try {
50
+ token = await getAuthToken(request, 'admin')
51
+
52
+ companyId = await createCompanyFixture(request, token, `${unique} Co`)
53
+ personId = await createPersonFixture(request, token, {
54
+ firstName: 'QA',
55
+ lastName: `S9 ${stamp}`,
56
+ displayName: `${unique} Person`,
57
+ })
58
+
59
+ // Company-type filter: results appear and every hit is a company.
60
+ await expect
61
+ .poll(
62
+ async () => {
63
+ const results = await searchResults(request, token!, unique, COMPANY_ENTITY)
64
+ return results.length > 0 && results.every((r) => r.entityId === COMPANY_ENTITY)
65
+ },
66
+ { timeout: 15_000 },
67
+ )
68
+ .toBe(true)
69
+
70
+ // Person-type filter: results appear and every hit is a person (no company leaks in).
71
+ await expect
72
+ .poll(
73
+ async () => {
74
+ const results = await searchResults(request, token!, unique, PERSON_ENTITY)
75
+ return results.length > 0 && results.every((r) => r.entityId === PERSON_ENTITY)
76
+ },
77
+ { timeout: 15_000 },
78
+ )
79
+ .toBe(true)
80
+ } finally {
81
+ await deleteEntityIfExists(request, token, '/api/customers/people', personId)
82
+ await deleteEntityIfExists(request, token, '/api/customers/companies', companyId)
83
+ }
84
+ })
85
+ })
@@ -3,16 +3,35 @@ import { aiTools } from '../ai-tools'
3
3
  const aggregateTool = aiTools.find((t) => t.name === 'search_aggregate')
4
4
  if (!aggregateTool) throw new Error('search_aggregate tool not found in aiTools — was it renamed?')
5
5
 
6
- function makeCtx(queryResult: { items: unknown[]; total: number }) {
6
+ const ENTITY_CONFIGS: Record<string, { aclFeatures: string[]; fieldPolicy: { searchable: string[]; hashOnly?: string[]; excluded?: string[] } }> = {
7
+ 'customers:customer_deal': {
8
+ aclFeatures: ['customers.deals.view'],
9
+ fieldPolicy: { searchable: ['title', 'status', 'pipeline_stage', 'source'], hashOnly: [], excluded: ['value_amount'] },
10
+ },
11
+ 'catalog:product': {
12
+ aclFeatures: ['catalog.products.view'],
13
+ fieldPolicy: { searchable: ['category', 'status'], hashOnly: [], excluded: [] },
14
+ },
15
+ }
16
+
17
+ const DEFAULT_FEATURES = ['search.view', 'customers.deals.view', 'catalog.products.view']
18
+
19
+ function makeCtx(
20
+ queryResult: { items: unknown[]; total: number },
21
+ overrides: { userFeatures?: string[]; isSuperAdmin?: boolean } = {},
22
+ ) {
7
23
  const mockQuery = jest.fn().mockResolvedValue(queryResult)
24
+ const searchIndexer = {
25
+ getEntityConfig: (entityId: string) => ENTITY_CONFIGS[entityId],
26
+ }
8
27
  const ctx = {
9
28
  tenantId: 'tenant-1',
10
29
  organizationId: 'org-1',
11
30
  userId: null,
12
- userFeatures: ['search.view'],
13
- isSuperAdmin: false,
31
+ userFeatures: overrides.userFeatures ?? DEFAULT_FEATURES,
32
+ isSuperAdmin: overrides.isSuperAdmin ?? false,
14
33
  container: {
15
- resolve: (_name: string) => ({ query: mockQuery }),
34
+ resolve: (name: string) => (name === 'searchIndexer' ? searchIndexer : { query: mockQuery }),
16
35
  },
17
36
  }
18
37
  return { ctx, mockQuery }
@@ -110,4 +129,70 @@ describe('search_aggregate tool', () => {
110
129
  aggregateTool.handler({ entityType: 'customers:customer_deal', groupBy: 'status', limit: 20 }, noTenantCtx),
111
130
  ).rejects.toThrow('Tenant context is required')
112
131
  })
132
+
133
+ it('denies callers holding only search.view without the per-entity view feature', async () => {
134
+ const { ctx, mockQuery } = makeCtx({ items: [{ status: 'open' }], total: 1 }, { userFeatures: ['search.view'] })
135
+
136
+ await expect(
137
+ aggregateTool.handler({ entityType: 'customers:customer_deal', groupBy: 'status', limit: 20 }, ctx),
138
+ ).rejects.toThrow(/Insufficient permissions/)
139
+ expect(mockQuery).not.toHaveBeenCalled()
140
+ })
141
+
142
+ it('allows callers holding the per-entity view feature', async () => {
143
+ const { ctx, mockQuery } = makeCtx({ items: [{ status: 'open' }], total: 1 }, { userFeatures: ['customers.deals.view'] })
144
+
145
+ const result = await aggregateTool.handler(
146
+ { entityType: 'customers:customer_deal', groupBy: 'status', limit: 20 },
147
+ ctx,
148
+ ) as { total: number }
149
+ expect(result.total).toBe(1)
150
+ expect(mockQuery).toHaveBeenCalled()
151
+ })
152
+
153
+ it('honors wildcard module grants for the per-entity view feature', async () => {
154
+ const { ctx } = makeCtx({ items: [{ status: 'open' }], total: 1 }, { userFeatures: ['customers.*'] })
155
+
156
+ const result = await aggregateTool.handler(
157
+ { entityType: 'customers:customer_deal', groupBy: 'status', limit: 20 },
158
+ ctx,
159
+ ) as { total: number }
160
+ expect(result.total).toBe(1)
161
+ })
162
+
163
+ it('allows super admins regardless of features', async () => {
164
+ const { ctx } = makeCtx({ items: [{ status: 'open' }], total: 1 }, { userFeatures: [], isSuperAdmin: true })
165
+
166
+ const result = await aggregateTool.handler(
167
+ { entityType: 'customers:customer_deal', groupBy: 'status', limit: 20 },
168
+ ctx,
169
+ ) as { total: number }
170
+ expect(result.total).toBe(1)
171
+ })
172
+
173
+ it('rejects groupBy on an excluded (sensitive) field', async () => {
174
+ const { ctx, mockQuery } = makeCtx({ items: [{ value_amount: 100 }], total: 1 })
175
+
176
+ await expect(
177
+ aggregateTool.handler({ entityType: 'customers:customer_deal', groupBy: 'value_amount', limit: 20 }, ctx),
178
+ ).rejects.toThrow(/not an allowed grouping key/)
179
+ expect(mockQuery).not.toHaveBeenCalled()
180
+ })
181
+
182
+ it('rejects groupBy on a field not in the searchable allowlist (e.g. PII enumeration)', async () => {
183
+ const { ctx, mockQuery } = makeCtx({ items: [{ email: 'a@b.c' }], total: 1 })
184
+
185
+ await expect(
186
+ aggregateTool.handler({ entityType: 'customers:customer_deal', groupBy: 'email', limit: 20 }, ctx),
187
+ ).rejects.toThrow(/not an allowed grouping key/)
188
+ expect(mockQuery).not.toHaveBeenCalled()
189
+ })
190
+
191
+ it('fails closed for entity types not configured for search', async () => {
192
+ const { ctx } = makeCtx({ items: [], total: 0 })
193
+
194
+ await expect(
195
+ aggregateTool.handler({ entityType: 'secret:unconfigured', groupBy: 'status', limit: 20 }, ctx),
196
+ ).rejects.toThrow(/not configured for search/)
197
+ })
113
198
  })
@@ -0,0 +1,118 @@
1
+ import { aiTools } from '../ai-tools'
2
+
3
+ const getTool = aiTools.find((t) => t.name === 'search_get')
4
+ if (!getTool) throw new Error('search_get tool not found in aiTools — was it renamed?')
5
+
6
+ const PERSON_CONFIG = {
7
+ aclFeatures: ['customers.people.view'],
8
+ fieldPolicy: {
9
+ searchable: ['first_name', 'last_name'],
10
+ hashOnly: ['primary_email', 'primary_phone'],
11
+ excluded: ['ssn', 'date_of_birth'],
12
+ },
13
+ }
14
+
15
+ function makeCtx(
16
+ record: Record<string, unknown> | undefined,
17
+ overrides: { userFeatures?: string[]; isSuperAdmin?: boolean } = {},
18
+ ) {
19
+ const items = record ? [record] : []
20
+ const mockQuery = jest.fn().mockResolvedValue({ items, total: items.length })
21
+ const searchIndexer = {
22
+ getEntityConfig: (entityId: string) =>
23
+ entityId === 'customers:customer_person_profile' ? PERSON_CONFIG : undefined,
24
+ }
25
+ const ctx = {
26
+ tenantId: 'tenant-1',
27
+ organizationId: 'org-1',
28
+ userId: null,
29
+ userFeatures: overrides.userFeatures ?? ['customers.people.view'],
30
+ isSuperAdmin: overrides.isSuperAdmin ?? false,
31
+ container: {
32
+ resolve: (name: string) => (name === 'searchIndexer' ? searchIndexer : { query: mockQuery }),
33
+ },
34
+ }
35
+ return { ctx, mockQuery }
36
+ }
37
+
38
+ describe('search_get tool', () => {
39
+ it('denies callers holding only search.view without the per-entity view feature', async () => {
40
+ const { ctx, mockQuery } = makeCtx(
41
+ { id: 'rec-1', first_name: 'Jane', ssn: '123-45-6789' },
42
+ { userFeatures: ['search.view'] },
43
+ )
44
+
45
+ await expect(
46
+ getTool.handler({ entityType: 'customers:customer_person_profile', recordId: 'rec-1' }, ctx),
47
+ ).rejects.toThrow(/Insufficient permissions/)
48
+ expect(mockQuery).not.toHaveBeenCalled()
49
+ })
50
+
51
+ it('returns the record for callers holding the per-entity view feature', async () => {
52
+ const { ctx, mockQuery } = makeCtx({ id: 'rec-1', first_name: 'Jane', last_name: 'Doe' })
53
+
54
+ const result = await getTool.handler(
55
+ { entityType: 'customers:customer_person_profile', recordId: 'rec-1' },
56
+ ctx,
57
+ ) as { found: boolean; record: Record<string, unknown> }
58
+ expect(result.found).toBe(true)
59
+ expect(result.record.first_name).toBe('Jane')
60
+ expect(mockQuery).toHaveBeenCalled()
61
+ })
62
+
63
+ it('strips hashOnly and excluded (PII) fields from the returned record', async () => {
64
+ const { ctx } = makeCtx({
65
+ id: 'rec-1',
66
+ first_name: 'Jane',
67
+ primary_email: 'jane@example.com',
68
+ primary_phone: '+1555',
69
+ ssn: '123-45-6789',
70
+ date_of_birth: '1990-01-01',
71
+ })
72
+
73
+ const result = await getTool.handler(
74
+ { entityType: 'customers:customer_person_profile', recordId: 'rec-1' },
75
+ ctx,
76
+ ) as { record: Record<string, unknown> }
77
+ expect(result.record.first_name).toBe('Jane')
78
+ expect(result.record.id).toBe('rec-1')
79
+ expect(result.record.primary_email).toBeUndefined()
80
+ expect(result.record.primary_phone).toBeUndefined()
81
+ expect(result.record.ssn).toBeUndefined()
82
+ expect(result.record.date_of_birth).toBeUndefined()
83
+ })
84
+
85
+ it('honors wildcard grants and super admins', async () => {
86
+ const wildcard = makeCtx({ id: 'rec-1', first_name: 'Jane' }, { userFeatures: ['*'] })
87
+ const wildcardResult = await getTool.handler(
88
+ { entityType: 'customers:customer_person_profile', recordId: 'rec-1' },
89
+ wildcard.ctx,
90
+ ) as { found: boolean }
91
+ expect(wildcardResult.found).toBe(true)
92
+
93
+ const superAdmin = makeCtx({ id: 'rec-1', first_name: 'Jane' }, { userFeatures: [], isSuperAdmin: true })
94
+ const superResult = await getTool.handler(
95
+ { entityType: 'customers:customer_person_profile', recordId: 'rec-1' },
96
+ superAdmin.ctx,
97
+ ) as { found: boolean }
98
+ expect(superResult.found).toBe(true)
99
+ })
100
+
101
+ it('fails closed for entity types not configured for search', async () => {
102
+ const { ctx, mockQuery } = makeCtx({ id: 'rec-1' })
103
+
104
+ await expect(
105
+ getTool.handler({ entityType: 'secret:unconfigured', recordId: 'rec-1' }, ctx),
106
+ ).rejects.toThrow(/not configured for search/)
107
+ expect(mockQuery).not.toHaveBeenCalled()
108
+ })
109
+
110
+ it('throws when tenantId is missing', async () => {
111
+ const { ctx } = makeCtx({ id: 'rec-1' })
112
+ const noTenantCtx = { ...ctx, tenantId: null }
113
+
114
+ await expect(
115
+ getTool.handler({ entityType: 'customers:customer_person_profile', recordId: 'rec-1' }, noTenantCtx),
116
+ ).rejects.toThrow('Tenant context is required')
117
+ })
118
+ })
@@ -1,5 +1,10 @@
1
1
  import { z } from 'zod'
2
- import type { SearchResult, SearchStrategyId } from '@open-mercato/shared/modules/search'
2
+ import type {
3
+ SearchEntityConfig,
4
+ SearchResult,
5
+ SearchStrategyId,
6
+ } from '@open-mercato/shared/modules/search'
7
+ import { hasAllFeatures } from '@open-mercato/shared/security/features'
3
8
 
4
9
  /**
5
10
  * AI Tools definitions for the Search module.
@@ -47,6 +52,97 @@ type AiToolDefinition = {
47
52
  handler: (input: any, ctx: ToolContext) => Promise<unknown>
48
53
  }
49
54
 
55
+ /**
56
+ * Minimal shape of the `searchIndexer` DI service consumed by the per-entity
57
+ * ACL / field-policy resolution below. Kept local to avoid importing the full
58
+ * `SearchIndexer` class into the tool module.
59
+ */
60
+ type SearchIndexerLike = {
61
+ getEntityConfig: (entityId: string) => SearchEntityConfig | undefined
62
+ }
63
+
64
+ class SearchToolAuthorizationError extends Error {
65
+ constructor(message: string) {
66
+ super(message)
67
+ this.name = 'SearchToolAuthorizationError'
68
+ }
69
+ }
70
+
71
+ /**
72
+ * Resolve the search config for an entity type and enforce the per-entity view
73
+ * feature(s). Data-returning tools (`search_get` / `search_aggregate`) MUST NOT
74
+ * rely on the search-administration `search.view` feature to gate record reads.
75
+ *
76
+ * Fails closed: when the entity is not configured for search, or has no
77
+ * `aclFeatures` declared, access is denied so records are never exposed without
78
+ * an explicit owning-module grant.
79
+ */
80
+ function authorizeEntityAccess(entityType: string, ctx: ToolContext): SearchEntityConfig {
81
+ const searchIndexer = ctx.container.resolve<SearchIndexerLike>('searchIndexer')
82
+ const config = searchIndexer.getEntityConfig(entityType)
83
+
84
+ if (!config) {
85
+ throw new SearchToolAuthorizationError(
86
+ `[internal] Entity type "${entityType}" is not configured for search`
87
+ )
88
+ }
89
+
90
+ if (ctx.isSuperAdmin) return config
91
+
92
+ const required = config.aclFeatures
93
+ if (!required || required.length === 0) {
94
+ throw new SearchToolAuthorizationError(
95
+ `[internal] Entity type "${entityType}" does not declare aclFeatures; access denied`
96
+ )
97
+ }
98
+
99
+ if (!hasAllFeatures(ctx.userFeatures, required)) {
100
+ throw new SearchToolAuthorizationError(
101
+ `[internal] Insufficient permissions for entity "${entityType}". Required: ${required.join(', ')}`
102
+ )
103
+ }
104
+
105
+ return config
106
+ }
107
+
108
+ /**
109
+ * Strip fields that the entity's field policy marks as sensitive
110
+ * (`hashOnly` exact-match PII or fully `excluded`) from a query-engine record.
111
+ * Defense-in-depth so even an authorized caller never receives decrypted PII or
112
+ * fields a `fieldPolicy` keeps out of search.
113
+ */
114
+ function stripSensitiveFields(
115
+ record: Record<string, unknown>,
116
+ config: SearchEntityConfig
117
+ ): Record<string, unknown> {
118
+ const sensitive = new Set<string>([
119
+ ...(config.fieldPolicy?.hashOnly ?? []),
120
+ ...(config.fieldPolicy?.excluded ?? []),
121
+ ])
122
+ if (sensitive.size === 0) return record
123
+ const safe: Record<string, unknown> = {}
124
+ for (const [key, value] of Object.entries(record)) {
125
+ if (sensitive.has(key)) continue
126
+ safe[key] = value
127
+ }
128
+ return safe
129
+ }
130
+
131
+ /**
132
+ * Determine whether a field is a safe aggregation grouping key for an entity.
133
+ * Only fields explicitly declared `searchable` are allowed; `hashOnly` and
134
+ * `excluded` (PII / sensitive) fields can never be enumerated via group-by.
135
+ */
136
+ function isGroupByAllowed(field: string, config: SearchEntityConfig): boolean {
137
+ const sensitive = new Set<string>([
138
+ ...(config.fieldPolicy?.hashOnly ?? []),
139
+ ...(config.fieldPolicy?.excluded ?? []),
140
+ ])
141
+ if (sensitive.has(field)) return false
142
+ const searchable = config.fieldPolicy?.searchable ?? []
143
+ return searchable.includes(field)
144
+ }
145
+
50
146
  // =============================================================================
51
147
  // Tool Definitions
52
148
  // =============================================================================
@@ -169,6 +265,8 @@ const searchGetTool: AiToolDefinition = {
169
265
  throw new Error('Tenant context is required')
170
266
  }
171
267
 
268
+ const entityConfig = authorizeEntityAccess(input.entityType, ctx)
269
+
172
270
  const queryEngine = ctx.container.resolve<{
173
271
  query: (entityId: string, options: any) => Promise<{ items: unknown[]; total: number }>
174
272
  }>('queryEngine')
@@ -181,8 +279,8 @@ const searchGetTool: AiToolDefinition = {
181
279
  page: { page: 1, pageSize: 1 },
182
280
  })
183
281
 
184
- const record = result.items[0] as Record<string, unknown> | undefined
185
- if (!record) {
282
+ const rawRecord = result.items[0] as Record<string, unknown> | undefined
283
+ if (!rawRecord) {
186
284
  return {
187
285
  found: false,
188
286
  entityType: input.entityType,
@@ -191,6 +289,8 @@ const searchGetTool: AiToolDefinition = {
191
289
  }
192
290
  }
193
291
 
292
+ const record = stripSensitiveFields(rawRecord, entityConfig)
293
+
194
294
  // Extract custom fields
195
295
  const customFields: Record<string, unknown> = {}
196
296
  const standardFields: Record<string, unknown> = {}
@@ -329,6 +429,14 @@ const searchAggregateTool: AiToolDefinition = {
329
429
  throw new Error('Tenant context is required')
330
430
  }
331
431
 
432
+ const entityConfig = authorizeEntityAccess(input.entityType, ctx)
433
+
434
+ if (!isGroupByAllowed(input.groupBy, entityConfig)) {
435
+ throw new SearchToolAuthorizationError(
436
+ `[internal] Field "${input.groupBy}" is not an allowed grouping key for "${input.entityType}"`
437
+ )
438
+ }
439
+
332
440
  const queryEngine = ctx.container.resolve<{
333
441
  query: (entityId: string, options: any) => Promise<{ items: unknown[]; total: number }>
334
442
  }>('queryEngine')