@open-mercato/ai-assistant 0.6.5-develop.5382.1.f542de69af → 0.6.5

package/src/modules/ai_assistant/__tests__/cli-mcp-serve-key.test.ts

@@ -0,0 +1,63 @@
+import type { ModuleCli } from '@open-mercato/shared/modules/registry'
+import cliCommands from '../cli'
+
+const mockRunMcpServer = jest.fn(async () => undefined)
+
+jest.mock('@open-mercato/shared/lib/di/container', () => ({
+  createRequestContainer: jest.fn(async () => ({})),
+  getDiRegistrars: jest.fn(() => []),
+}))
+
+jest.mock('../lib/mcp-server', () => ({
+  runMcpServer: (...args: unknown[]) => mockRunMcpServer(...args),
+}))
+
+function getMcpServe(): ModuleCli {
+  const cmd = (cliCommands as ModuleCli[]).find((c) => c.command === 'mcp:serve')
+  if (!cmd) throw new Error('mcp:serve command not found')
+  return cmd
+}
+
+describe('mcp:serve API key resolution (issue #2669)', () => {
+  const originalEnv = process.env.OPEN_MERCATO_API_KEY
+
+  beforeEach(() => {
+    jest.clearAllMocks()
+    delete process.env.OPEN_MERCATO_API_KEY
+  })
+
+  afterEach(() => {
+    if (originalEnv === undefined) delete process.env.OPEN_MERCATO_API_KEY
+    else process.env.OPEN_MERCATO_API_KEY = originalEnv
+  })
+
+  it('reads the key from OPEN_MERCATO_API_KEY when --api-key is absent', async () => {
+    process.env.OPEN_MERCATO_API_KEY = 'omk_env.secret'
+
+    await getMcpServe().run([])
+
+    expect(mockRunMcpServer).toHaveBeenCalledTimes(1)
+    expect(mockRunMcpServer).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKeySecret: 'omk_env.secret' }),
+    )
+  })
+
+  it('still accepts the --api-key flag and prefers it over the env var', async () => {
+    process.env.OPEN_MERCATO_API_KEY = 'omk_env.secret'
+
+    await getMcpServe().run(['--api-key', 'omk_flag.secret'])
+
+    expect(mockRunMcpServer).toHaveBeenCalledWith(
+      expect.objectContaining({ apiKeySecret: 'omk_flag.secret' }),
+    )
+  })
+
+  it('prints usage and does not start the server when neither key nor tenant is provided', async () => {
+    const errorSpy = jest.spyOn(console, 'error').mockImplementation(() => {})
+
+    await getMcpServe().run([])
+
+    expect(mockRunMcpServer).not.toHaveBeenCalled()
+    errorSpy.mockRestore()
+  })
+})

package/src/modules/ai_assistant/__tests__/setup-schedules.test.ts

@@ -0,0 +1,33 @@
+import { setup } from '../setup'
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+function makeContainer() {
+  const register = jest.fn().mockResolvedValue(undefined)
+  return {
+    register,
+    container: {
+      resolve(name: string) {
+        if (name !== 'schedulerService') throw new Error(`unexpected registration: ${name}`)
+        return { register }
+      },
+    },
+  }
+}
+
+describe('ai_assistant setup schedules', () => {
+  it('registers module schedules with uuid ids accepted by the scheduler table', async () => {
+    const { container, register } = makeContainer()
+
+    await setup.seedDefaults?.({ container } as never)
+
+    expect(register).toHaveBeenCalledTimes(2)
+    const ids = register.mock.calls.map(([registration]) => registration.id)
+
+    expect(ids).toHaveLength(2)
+    expect(new Set(ids).size).toBe(2)
+    expect(ids).not.toContain('ai_assistant:pending-action-cleanup')
+    expect(ids).not.toContain('ai_assistant:token-usage-prune')
+    expect(ids.every((id) => UUID_RE.test(id))).toBe(true)
+  })
+})

package/src/modules/ai_assistant/cli.ts

@@ -47,30 +47,42 @@ const mcpServe: ModuleCli = {
   command: 'mcp:serve',
   async run(rest) {
     const args = parseArgs(rest)
-    const apiKey = String(args['api-key'] ?? args.apiKey ?? '') || null
+    // Prefer the OPEN_MERCATO_API_KEY env var so the secret never has to be
+    // placed on the command line (argv is world-readable via ps / /proc).
+    // The --api-key flag stays supported for backward compatibility.
+    const apiKey = String(args['api-key'] ?? args.apiKey ?? '') || process.env.OPEN_MERCATO_API_KEY || null
     const tenantId = String(args.tenant ?? args.tenantId ?? '') || null
     const organizationId = String(args.org ?? args.organizationId ?? '') || null
     const userId = String(args.user ?? args.userId ?? '') || null
     const debug = args.debug === true || args.debug === 'true'
+    const allowUnauthenticatedSuperadmin =
+      args['allow-unauthenticated-superadmin'] === true ||
+      args['allow-unauthenticated-superadmin'] === 'true'
 
     // Either API key or tenant is required
     if (!apiKey && !tenantId) {
       console.error('Usage: mercato ai_assistant mcp:serve [options]')
       console.error('')
       console.error('Authentication (choose one):')
-      console.error('  --api-key <secret>   API key secret for authentication (recommended)')
-      console.error('  --tenant <id>        Tenant ID (for manual context)')
+      console.error('  OPEN_MERCATO_API_KEY env   API key secret (recommended — keeps the secret off argv)')
+      console.error('  --api-key <secret>         API key secret for authentication (visible in process listings)')
+      console.error('  --tenant <id>              Tenant ID (for manual context)')
       console.error('')
       console.error('Options (with --tenant):')
       console.error('  --org <id>           Organization ID (optional)')
-      console.error('  --user <id>          User ID for ACL (optional, uses superadmin if not set)')
+      console.error('  --user <id>          User ID for ACL (required unless --allow-unauthenticated-superadmin is set)')
       console.error('')
       console.error('Common options:')
       console.error('  --debug              Enable debug logging')
+      console.error('  --allow-unauthenticated-superadmin')
+      console.error('                       DEV/TEST ONLY: run as superadmin with no per-user ACL when')
+      console.error('                       no --user (and no --api-key) is supplied. Never use in production.')
       console.error('')
       console.error('Examples:')
+      console.error('  OPEN_MERCATO_API_KEY=omk_xxxx.yyyy... mercato ai_assistant mcp:serve')
       console.error('  mercato ai_assistant mcp:serve --api-key omk_xxxx.yyyy...')
-      console.error('  mercato ai_assistant mcp:serve --tenant 123e4567-e89b-12d3-a456-426614174000')
+      console.error('  mercato ai_assistant mcp:serve --tenant 123e4567-e89b-12d3-a456-426614174000 --user <user-id>')
+      console.error('  mercato ai_assistant mcp:serve --tenant 123e4567-e89b-12d3-a456-426614174000 --allow-unauthenticated-superadmin')
       return
     }
 
@@ -102,6 +114,7 @@ const mcpServe: ModuleCli = {
           organizationId,
           userId,
         },
+        allowUnauthenticatedSuperadmin,
       })
     }
   },

package/src/modules/ai_assistant/data/__tests__/schema-unique-indexes.test.ts

@@ -38,6 +38,45 @@ describe('AI assistant nullable organization unique indexes', () => {
     },
   )
 
+  it('declares every snapshot expression index on the participants entity (no snapshot/entity drift)', () => {
+    const snapshot = JSON.parse(
+      readFileSync(
+        new URL('../../migrations/.snapshot-open-mercato.json', import.meta.url),
+        'utf8',
+      ),
+    ) as {
+      tables: Array<{ name: string; indexes?: Array<{ keyName: string; expression?: string }> }>
+    }
+
+    const participants = snapshot.tables.find(
+      (table) => table.name === 'ai_chat_conversation_participants',
+    )
+    expect(participants).toBeDefined()
+
+    const entitySource = readFileSync(
+      new URL('../entities.ts', import.meta.url),
+      'utf8',
+    )
+
+    const expressionIndexes = (participants?.indexes ?? []).filter((index) => index.expression)
+    expect(expressionIndexes.length).toBeGreaterThan(0)
+
+    for (const index of expressionIndexes) {
+      expect(entitySource).toContain(index.keyName)
+    }
+  })
+
+  it('keeps the active-participants partial index declared on the entity', () => {
+    const entitySource = readFileSync(
+      new URL('../entities.ts', import.meta.url),
+      'utf8',
+    )
+
+    expect(entitySource).toContain(
+      'create index "ai_chat_conv_participants_active_conv_user_idx" on "ai_chat_conversation_participants" ("tenant_id", "organization_id", "conversation_id", "user_id") where "deleted_at" is null',
+    )
+  })
+
   it('keeps the module snapshot aligned with partial unique indexes', () => {
     const snapshot = JSON.parse(
       readFileSync(

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

@@ -789,6 +789,11 @@ export class AiChatConversation {
   expression:
     'create unique index "ai_chat_conv_participants_tenant_conv_user_null_org_uq" on "ai_chat_conversation_participants" ("tenant_id", "conversation_id", "user_id") where "organization_id" is null',
 })
+@Index({
+  name: 'ai_chat_conv_participants_active_conv_user_idx',
+  expression:
+    'create index "ai_chat_conv_participants_active_conv_user_idx" on "ai_chat_conversation_participants" ("tenant_id", "organization_id", "conversation_id", "user_id") where "deleted_at" is null',
+})
 @Index({
   name: 'ai_chat_conv_participants_tenant_org_user_conv_idx',
   properties: ['tenantId', 'organizationId', 'userId', 'conversationId'],

package/src/modules/ai_assistant/lib/__tests__/attachment-parts.test.ts

@@ -349,6 +349,118 @@ describe('resolveAttachmentParts — tenant / org scope enforcement', () => {
     expect(parts).toEqual([])
     expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('not found'))
   })
+
+  // Regression for #2663 — null-scoped rows used to bypass the tenant check via
+  // a truthiness short-circuit and leak into the caller's LLM context.
+  it('drops a null-tenant (global) record for a non super-admin caller', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(
+      makeRow({
+        id: 'null-tenant-1',
+        tenantId: null,
+        organizationId: null,
+        mimeType: 'image/png',
+        fileSize: 64,
+        content: 'secret OCR text',
+      }),
+    )
+
+    const parts = await resolveAttachmentParts({
+      attachmentIds: ['null-tenant-1'],
+      authContext: makeAuth({ tenantId: 'tenant-1', organizationId: 'org-1' }),
+      container: makeContainer(),
+    })
+
+    expect(parts).toEqual([])
+    expect(fsReadFileMock).not.toHaveBeenCalled()
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('out of scope'))
+  })
+
+  // Regression for #2663 — `tenantId='X', organizationId=null` used to be
+  // readable by every org within tenant X.
+  it('drops a null-org record in the caller tenant for an org-scoped caller', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(
+      makeRow({
+        id: 'null-org-1',
+        tenantId: 'tenant-1',
+        organizationId: null,
+        mimeType: 'image/png',
+        fileSize: 64,
+      }),
+    )
+
+    const parts = await resolveAttachmentParts({
+      attachmentIds: ['null-org-1'],
+      authContext: makeAuth({ tenantId: 'tenant-1', organizationId: 'org-1' }),
+      container: makeContainer(),
+    })
+
+    expect(parts).toEqual([])
+    expect(console.warn).toHaveBeenCalledWith(expect.stringContaining('out of scope'))
+  })
+
+  it('lets a tenant-wide caller (null org) read any org within its tenant', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(
+      makeRow({
+        id: 'same-tenant-other-org',
+        tenantId: 'tenant-1',
+        organizationId: 'org-OTHER',
+        mimeType: 'application/zip',
+        fileSize: 64,
+        content: null,
+      }),
+    )
+
+    const parts = await resolveAttachmentParts({
+      attachmentIds: ['same-tenant-other-org'],
+      authContext: makeAuth({ tenantId: 'tenant-1', organizationId: null }),
+      container: makeContainer(),
+    })
+
+    expect(parts).toHaveLength(1)
+    expect(parts[0].attachmentId).toBe('same-tenant-other-org')
+  })
+
+  it('scopes the ORM query by tenant + org for a non super-admin caller', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(makeRow({ id: 'att-scope-1', fileSize: 0 }))
+
+    await resolveAttachmentParts({
+      attachmentIds: ['att-scope-1'],
+      authContext: makeAuth({ tenantId: 'tenant-1', organizationId: 'org-1' }),
+      container: makeContainer(),
+    })
+
+    const whereArg = findOneWithDecryptionMock.mock.calls[0][2]
+    expect(whereArg).toEqual({ id: 'att-scope-1', tenantId: 'tenant-1', organizationId: 'org-1' })
+  })
+
+  it('omits org from the ORM query for a tenant-wide caller (null org)', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(makeRow({ id: 'att-scope-2', fileSize: 0 }))
+
+    await resolveAttachmentParts({
+      attachmentIds: ['att-scope-2'],
+      authContext: makeAuth({ tenantId: 'tenant-1', organizationId: null }),
+      container: makeContainer(),
+    })
+
+    const whereArg = findOneWithDecryptionMock.mock.calls[0][2]
+    expect(whereArg).toEqual({ id: 'att-scope-2', tenantId: 'tenant-1' })
+    expect(whereArg).not.toHaveProperty('organizationId')
+  })
+
+  it('does not scope the ORM query for super-admin callers', async () => {
+    findOneWithDecryptionMock.mockResolvedValueOnce(
+      makeRow({ id: 'att-scope-3', tenantId: 'tenant-OTHER', organizationId: 'org-OTHER', fileSize: 0 }),
+    )
+
+    await resolveAttachmentParts({
+      attachmentIds: ['att-scope-3'],
+      authContext: makeAuth({ isSuperAdmin: true }),
+      container: makeContainer(),
+    })
+
+    const whereArg = findOneWithDecryptionMock.mock.calls[0][2]
+    expect(whereArg).toEqual({ id: 'att-scope-3' })
+  })
 })
 
 describe('resolveAttachmentParts — unavailable service graceful skip', () => {

package/src/modules/ai_assistant/lib/__tests__/client-factory.test.ts

@@ -0,0 +1,42 @@
+import { createMcpClient } from '../client-factory'
+
+const mockConnect = jest.fn(async () => ({ listTools: jest.fn(), callTool: jest.fn(), close: jest.fn() }))
+
+jest.mock('../mcp-client', () => ({
+  McpClient: {
+    connect: (...args: unknown[]) => mockConnect(...args),
+  },
+}))
+
+describe('createMcpClient stdio mode (issue #2669)', () => {
+  beforeEach(() => {
+    jest.clearAllMocks()
+  })
+
+  it('never places the API key on the default argv', async () => {
+    await createMcpClient({ mode: 'stdio', apiKeySecret: 'omk_secret.value' })
+
+    expect(mockConnect).toHaveBeenCalledTimes(1)
+    const options = mockConnect.mock.calls[0][0] as { apiKeySecret: string; args?: string[] }
+
+    // The secret is forwarded to McpClient.connect, which delivers it via env.
+    expect(options.apiKeySecret).toBe('omk_secret.value')
+
+    // The factory must not build default args that embed the secret. Leaving
+    // args undefined lets connectStdio use its secret-free default.
+    expect(options.args).toBeUndefined()
+    expect(JSON.stringify(options.args ?? [])).not.toContain('--api-key')
+    expect(JSON.stringify(options.args ?? [])).not.toContain('omk_secret.value')
+  })
+
+  it('honors explicitly provided stdio args without injecting the secret', async () => {
+    await createMcpClient({
+      mode: 'stdio',
+      apiKeySecret: 'omk_secret.value',
+      stdioArgs: ['node', 'custom-server.js'],
+    })
+
+    const options = mockConnect.mock.calls[0][0] as { args?: string[] }
+    expect(options.args).toEqual(['node', 'custom-server.js'])
+  })
+})

package/src/modules/ai_assistant/lib/__tests__/codemode-tools.test.ts

@@ -7,6 +7,7 @@ import {
   CODE_MODE_MAX_MUTATION_CALLS,
   CODE_MODE_REQUIRED_FEATURES,
   createApiRequestFn,
+  isUnsafeApiRequestPath,
   isUnsafeHttpMethod,
   matchApiEndpointPath,
 } from '../codemode-tools'
@@ -287,6 +288,112 @@ describe('authorizeCodeModeApiRequest', () => {
   })
 })
 
+describe('path traversal hardening (issue #2667)', () => {
+  describe('isUnsafeApiRequestPath', () => {
+    it.each([
+      '/api/foo/../admin',
+      '/api/foo/..',
+      '/api/foo/./admin',
+      '/api/.',
+      '/api/foo/%2e%2e/admin',
+      '/api/foo/%2E%2E/admin',
+      '/api/foo/%2e./admin',
+      '/api/foo/.%2e/admin',
+      '/api/foo/%2e/admin',
+      '/api/foo\\admin',
+      '/api/foo%2fadmin',
+      '/api/foo%2Fadmin',
+      '/api/foo%5cadmin',
+      'foo/../admin',
+      '/api/foo/../admin?expand=1',
+      // Raw ASCII tab/newline/CR are stripped by the WHATWG URL parser before
+      // the fetch, so `.<ctrl>.` collapses to `..` on the wire.
+      '/api/foo/.\t./admin',
+      '/api/foo/.\n./admin',
+      '/api/foo/.\r./admin',
+      '/api/foo/\t../admin',
+    ])('flags %s as unsafe', (path) => {
+      expect(isUnsafeApiRequestPath(path)).toBe(true)
+    })
+
+    it.each([
+      '/api/customers/companies',
+      '/api/customers/companies/company-1',
+      'customers/companies/company-1?expand=1',
+      '/api/catalog/products/1.2.3',
+      '/api/customers/companies/00000000-0000-0000-0000-000000000000',
+    ])('treats %s as safe', (path) => {
+      expect(isUnsafeApiRequestPath(path)).toBe(false)
+    })
+  })
+
+  it('denies a traversal path even when a parameterized endpoint would match', async () => {
+    mockedGetApiEndpoints.mockReset()
+    // A documented read the user is authorized for. The un-normalized segment
+    // matcher would have accepted '/api/foo/..' against '/api/foo/{id}', then
+    // the wire fetch would collapse it to '/api/admin'. The guard blocks it.
+    mockedGetApiEndpoints.mockResolvedValue([
+      {
+        id: 'get_foo',
+        operationId: 'get_foo',
+        method: 'GET',
+        path: '/api/foo/{id}',
+        summary: '',
+        description: '',
+        tags: [],
+        requiredFeatures: [],
+        parameters: [],
+        requestBodySchema: null,
+        deprecated: false,
+      },
+    ])
+
+    const result = await authorizeCodeModeApiRequest(createContext(), 'GET', '/api/foo/..')
+
+    expect(result).toEqual({
+      allowed: false,
+      statusCode: 403,
+      error: 'Code Mode rejected unsafe API path: GET /api/foo/..',
+    })
+  })
+
+  it('never issues the wire request for a traversal path', async () => {
+    mockedGetApiEndpoints.mockReset()
+    mockedFetchWithTimeout.mockReset()
+    mockedFetchWithTimeout.mockResolvedValue(okResponse())
+    mockedGetApiEndpoints.mockResolvedValue([
+      {
+        id: 'create_company',
+        operationId: 'create_company',
+        method: 'POST',
+        path: '/api/customers/companies',
+        summary: '',
+        description: '',
+        tags: [],
+        requiredFeatures: ['customers.companies.create'],
+        parameters: [],
+        requestBodySchema: null,
+        deprecated: false,
+      },
+    ])
+
+    const apiRequest = createApiRequestFn(
+      createContext({ userFeatures: ['ai_assistant.view', 'customers.companies.create'] }),
+      () => {}
+    )
+
+    const result = (await apiRequest({
+      method: 'POST',
+      path: '/api/customers/companies/../admin',
+      body: {},
+    })) as { success: boolean; statusCode: number }
+
+    expect(result.success).toBe(false)
+    expect(result.statusCode).toBe(403)
+    expect(mockedFetchWithTimeout).not.toHaveBeenCalled()
+  })
+})
+
 describe('mutation call cap (issue #2724)', () => {
   beforeEach(() => {
     mockedGetApiEndpoints.mockReset()

package/src/modules/ai_assistant/lib/__tests__/generated-registry-loader.test.ts

@@ -5,6 +5,7 @@ import { pathToFileURL } from 'node:url'
 import * as registry from '@open-mercato/shared/modules/registry'
 import {
   rewriteGeneratedAliasImports,
+  escapeUnsafeJsStringChars,
   findGeneratedFile,
   ensureApiRouteManifestsRegistered,
 } from '../generated-registry-loader'
@@ -13,6 +14,14 @@ function makeTempDir(): string {
   return fs.mkdtempSync(path.join(os.tmpdir(), 'om-gen-loader-'))
 }
 
+// Mirror the production sanitizer so expectations match how the rewriter
+// embeds a resolved path into the generated source. For ordinary file URLs the
+// escape is a no-op, but routing the expected literal through the same helper
+// keeps the test honest if the rewriter's escaping ever changes.
+function safeJsLiteral(value: string): string {
+  return escapeUnsafeJsStringChars(JSON.stringify(value))
+}
+
 describe('rewriteGeneratedAliasImports', () => {
   // Regression for the MCP dev-server crash:
   //   "Cannot find package '@/.mercato' imported from .../tool-loader.js"
@@ -28,7 +37,7 @@ describe('rewriteGeneratedAliasImports', () => {
     const expectedUrl = pathToFileURL(
       path.join(appRoot, '.mercato/generated/entities'),
     ).href
-    expect(out).toBe(`import { x } from ${JSON.stringify(expectedUrl)}`)
+    expect(out).toBe(`import { x } from ${safeJsLiteral(expectedUrl)}`)
     expect(out).not.toContain('@/')
   })
 
@@ -40,7 +49,7 @@ describe('rewriteGeneratedAliasImports', () => {
     const expectedUrl = pathToFileURL(
       path.join(appRoot, '.mercato/generated/ai-tools.generated'),
     ).href
-    const expected = source.replace(aliasSpecifier, JSON.stringify(expectedUrl))
+    const expected = source.replace(aliasSpecifier, safeJsLiteral(expectedUrl))
     expect(out).toBe(expected)
     expect(out).not.toContain('@/')
   })
@@ -53,7 +62,7 @@ describe('rewriteGeneratedAliasImports', () => {
     const out = rewriteGeneratedAliasImports(`import x from '@/src/thing'`, appRoot)
 
     const expectedUrl = pathToFileURL(path.join(appRoot, 'src', 'thing.ts')).href
-    expect(out).toBe(`import x from ${JSON.stringify(expectedUrl)}`)
+    expect(out).toBe(`import x from ${safeJsLiteral(expectedUrl)}`)
   })
 
   it('leaves non-alias imports untouched', () => {
@@ -66,6 +75,24 @@ describe('rewriteGeneratedAliasImports', () => {
   })
 })
 
+describe('escapeUnsafeJsStringChars', () => {
+  it('escapes characters JSON.stringify leaves intact in a JS string literal', () => {
+    const lineSep = String.fromCharCode(0x2028)
+    const paraSep = String.fromCharCode(0x2029)
+    const out = escapeUnsafeJsStringChars(`a<b>c${lineSep}d${paraSep}e`)
+    expect(out).toBe('a\\u003Cb\\u003Ec\\u2028d\\u2029e')
+    expect(out).not.toContain('<')
+    expect(out).not.toContain('>')
+    expect(out).not.toContain(lineSep)
+    expect(out).not.toContain(paraSep)
+  })
+
+  it('leaves ordinary file URLs unchanged', () => {
+    const url = pathToFileURL(path.join('/tmp', 'app', '.mercato', 'x.generated')).href
+    expect(escapeUnsafeJsStringChars(JSON.stringify(url))).toBe(JSON.stringify(url))
+  })
+})
+
 describe('findGeneratedFile', () => {
   let cwdSpy: jest.SpyInstance
 

package/src/modules/ai_assistant/lib/__tests__/mcp-client.test.ts

@@ -58,7 +58,7 @@ describe('McpClient stdio transport', () => {
       command: 'node',
       args: ['server.js'],
       cwd: '/tmp/open-mercato',
-      env: process.env,
+      env: { ...process.env, OPEN_MERCATO_API_KEY: 'test-secret' },
       stderr: 'pipe',
     })
     expect(mockClientConnect).toHaveBeenCalledTimes(1)
@@ -71,4 +71,23 @@ describe('McpClient stdio transport', () => {
     expect(mockTransportClose).toHaveBeenCalledTimes(1)
     expect(mockManualChildKill).not.toHaveBeenCalled()
   })
+
+  it('passes the API key via OPEN_MERCATO_API_KEY env, never on argv (issue #2669)', async () => {
+    await McpClient.connect({
+      transport: 'stdio',
+      apiKeySecret: 'omk_secret.value',
+    })
+
+    expect(StdioClientTransport).toHaveBeenCalledTimes(1)
+    const transportArgs = (StdioClientTransport as jest.Mock).mock.calls[0][0]
+
+    // The secret must reach the child process exclusively through the env var.
+    expect(transportArgs.env.OPEN_MERCATO_API_KEY).toBe('omk_secret.value')
+
+    // It must NOT appear on argv (world-readable via ps / /proc/<pid>/cmdline).
+    expect(transportArgs.args).toEqual(['mercato', 'ai_assistant', 'mcp:serve'])
+    expect(transportArgs.args).not.toContain('--api-key')
+    expect(transportArgs.args).not.toContain('omk_secret.value')
+    expect(JSON.stringify(transportArgs.args)).not.toContain('omk_secret.value')
+  })
 })