@open-mercato/shared 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/scripts/versionSource.cjs

@@ -0,0 +1,65 @@
+// Pure source emitter for the build-time replacement of src/lib/version.ts.
+// Kept side-effect free, and CommonJS so both build.mjs and the Jest suite can load it.
+
+const { Project, QuoteKind, ScriptKind, StructureKind, VariableDeclarationKind } = require('ts-morph')
+
+const VIRTUAL_FILE_NAME = 'version.ts'
+const BANNER = '// Build-time generated version\n'
+
+let sharedProject = null
+
+function getProject() {
+  if (!sharedProject) {
+    sharedProject = new Project({
+      useInMemoryFileSystem: true,
+      manipulationSettings: { quoteKind: QuoteKind.Single },
+    })
+  }
+
+  return sharedProject
+}
+
+function assertNoSyntacticDiagnostics(project, sourceFile) {
+  const diagnostics = project.getProgram().getSyntacticDiagnostics(sourceFile)
+  if (diagnostics.length === 0) return
+
+  const details = diagnostics
+    .map((diagnostic) => `  line ${diagnostic.getLineNumber() ?? 0}: ${diagnostic.getMessageText()}`)
+    .join('\n')
+  throw new Error(`[internal] Generated ${VIRTUAL_FILE_NAME} is not syntactically valid:\n${details}`)
+}
+
+function normalizeSourceText(text) {
+  const normalized = text.replace(/\r\n/g, '\n')
+  return normalized.endsWith('\n') ? normalized : `${normalized}\n`
+}
+
+function buildVersionSource(version) {
+  const project = getProject()
+  const sourceFile = project.createSourceFile(VIRTUAL_FILE_NAME, '', {
+    overwrite: true,
+    scriptKind: ScriptKind.TS,
+  })
+
+  sourceFile.addVariableStatement({
+    kind: StructureKind.VariableStatement,
+    isExported: true,
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [{ name: 'APP_VERSION', initializer: (writer) => writer.quote(String(version)) }],
+  })
+
+  sourceFile.addVariableStatement({
+    kind: StructureKind.VariableStatement,
+    isExported: true,
+    declarationKind: VariableDeclarationKind.Const,
+    declarations: [{ name: 'appVersion', initializer: 'APP_VERSION' }],
+  })
+
+  sourceFile.formatText({ indentSize: 2, convertTabsToSpaces: true })
+  sourceFile.insertText(0, BANNER)
+  assertNoSyntacticDiagnostics(project, sourceFile)
+
+  return normalizeSourceText(sourceFile.getFullText())
+}
+
+module.exports = { buildVersionSource }

package/src/lib/__tests__/versionSource.test.ts

@@ -0,0 +1,46 @@
+import { Project, SyntaxKind } from 'ts-morph'
+import { buildVersionSource } from '../../../scripts/versionSource.cjs'
+
+function parse(source: string) {
+  const project = new Project({ useInMemoryFileSystem: true })
+  const sourceFile = project.createSourceFile('version.ts', source, { overwrite: true })
+  return { project, sourceFile }
+}
+
+function exportedLiteral(source: string, name: string): string {
+  const { sourceFile } = parse(source)
+  return sourceFile.getVariableDeclarationOrThrow(name).getInitializerOrThrow().getText()
+}
+
+describe('buildVersionSource', () => {
+  it('exports both APP_VERSION and appVersion', () => {
+    const { sourceFile } = parse(buildVersionSource('1.2.3'))
+    expect([...sourceFile.getExportedDeclarations().keys()].sort()).toEqual(['APP_VERSION', 'appVersion'])
+  })
+
+  it('writes the supplied version as the APP_VERSION literal', () => {
+    expect(exportedLiteral(buildVersionSource('1.2.3'), 'APP_VERSION')).toBe("'1.2.3'")
+  })
+
+  it('aliases appVersion to APP_VERSION rather than repeating the literal', () => {
+    expect(exportedLiteral(buildVersionSource('1.2.3'), 'appVersion')).toBe('APP_VERSION')
+  })
+
+  it('escapes a version string that would otherwise break the literal', () => {
+    const source = buildVersionSource("0.0.0-dev'; drop")
+    const { sourceFile } = parse(source)
+    const literal = sourceFile
+      .getVariableDeclarationOrThrow('APP_VERSION')
+      .getInitializerIfKindOrThrow(SyntaxKind.StringLiteral)
+    expect(literal.getLiteralValue()).toBe("0.0.0-dev'; drop")
+  })
+
+  it('emits zero syntactic diagnostics', () => {
+    const { project, sourceFile } = parse(buildVersionSource('1.2.3'))
+    expect(project.getProgram().getSyntacticDiagnostics(sourceFile)).toEqual([])
+  })
+
+  it('keeps the build-time banner comment', () => {
+    expect(buildVersionSource('1.2.3').startsWith('// Build-time generated version\n')).toBe(true)
+  })
+})

package/src/lib/ai/__tests__/llm-provider-contract.test.ts

@@ -0,0 +1,59 @@
+import type { EnvLookup, LlmProvider, LlmCreateModelOptions } from '../llm-provider'
+
+function makeBaseProvider(overrides: Partial<LlmProvider> = {}): LlmProvider {
+  const id = overrides.id ?? 'contract-provider'
+  const envKeys = overrides.envKeys ?? [`${id.toUpperCase()}_API_KEY`]
+  const base: LlmProvider = {
+    id,
+    name: `Contract Provider ${id}`,
+    envKeys,
+    defaultModel: 'contract-model',
+    defaultModels: [{ id: 'contract-model', name: 'Contract Model', contextWindow: 8192 }],
+    isConfigured(env?: EnvLookup): boolean {
+      const lookup = env ?? process.env
+      return envKeys.some((key) => {
+        const value = lookup[key]
+        return typeof value === 'string' && value.trim().length > 0
+      })
+    },
+    resolveApiKey(): string | null {
+      return null
+    },
+    getConfiguredEnvKey(): string {
+      return envKeys[0]
+    },
+    createModel(options: LlmCreateModelOptions) {
+      return { __kind: 'contract-model', modelId: options.modelId }
+    },
+  }
+  return { ...base, ...overrides }
+}
+
+describe('LlmProvider contract — moderation/safety-identifier additive members', () => {
+  it('treats mapEndUserIdentifier and supportsInputModeration as optional (legacy adapters)', () => {
+    const provider = makeBaseProvider()
+    expect(provider.mapEndUserIdentifier).toBeUndefined()
+    expect(provider.supportsInputModeration).toBeUndefined()
+  })
+
+  it('accepts an optional endUserIdentifier on createModel options without changing behavior', () => {
+    const provider = makeBaseProvider()
+    const withIdentifier: LlmCreateModelOptions = {
+      modelId: 'contract-model',
+      apiKey: 'sk-test',
+      endUserIdentifier: 'hashed-identifier',
+    }
+    expect(provider.createModel(withIdentifier)).toEqual({ __kind: 'contract-model', modelId: 'contract-model' })
+  })
+
+  it('exposes a providerOptions fragment when mapEndUserIdentifier is implemented', () => {
+    const provider = makeBaseProvider({
+      mapEndUserIdentifier(identifier: string) {
+        return { contract: { user_id: identifier } }
+      },
+      supportsInputModeration: true,
+    })
+    expect(provider.supportsInputModeration).toBe(true)
+    expect(provider.mapEndUserIdentifier?.('abc123')).toEqual({ contract: { user_id: 'abc123' } })
+  })
+})

package/src/lib/ai/__tests__/safety-identifier.test.ts

@@ -0,0 +1,71 @@
+import { computeEndUserIdentifier, deriveAiSafetyIdentifierSecret } from '../safety-identifier'
+
+const BASE_SECRET = 'unit-test-base-secret'
+const HEX_64 = /^[0-9a-f]{64}$/
+
+describe('safety-identifier', () => {
+  describe('deriveAiSafetyIdentifierSecret', () => {
+    it('is deterministic and memoized for a given base secret', () => {
+      const first = deriveAiSafetyIdentifierSecret(BASE_SECRET)
+      const second = deriveAiSafetyIdentifierSecret(BASE_SECRET)
+      expect(first).toBe(second)
+      expect(first).toMatch(HEX_64)
+    })
+
+    it('produces a different key for a different base secret', () => {
+      expect(deriveAiSafetyIdentifierSecret(BASE_SECRET)).not.toBe(
+        deriveAiSafetyIdentifierSecret('other-base-secret'),
+      )
+    })
+
+    it('throws when no base secret is available', () => {
+      const previous = process.env.JWT_SECRET
+      delete process.env.JWT_SECRET
+      try {
+        expect(() => deriveAiSafetyIdentifierSecret()).toThrow(/JWT_SECRET/)
+      } finally {
+        if (previous !== undefined) process.env.JWT_SECRET = previous
+      }
+    })
+  })
+
+  describe('computeEndUserIdentifier', () => {
+    it('is stable for the same (tenant, user) pair', () => {
+      const a = computeEndUserIdentifier('tenant-1', 'user-1', { baseSecret: BASE_SECRET })
+      const b = computeEndUserIdentifier('tenant-1', 'user-1', { baseSecret: BASE_SECRET })
+      expect(a).toBe(b)
+      expect(a).toMatch(HEX_64)
+    })
+
+    it('separates the same user across tenants (tenant-salted)', () => {
+      const t1 = computeEndUserIdentifier('tenant-1', 'user-1', { baseSecret: BASE_SECRET })
+      const t2 = computeEndUserIdentifier('tenant-2', 'user-1', { baseSecret: BASE_SECRET })
+      expect(t1).not.toBe(t2)
+    })
+
+    it('separates different users within the same tenant', () => {
+      const u1 = computeEndUserIdentifier('tenant-1', 'user-1', { baseSecret: BASE_SECRET })
+      const u2 = computeEndUserIdentifier('tenant-1', 'user-2', { baseSecret: BASE_SECRET })
+      expect(u1).not.toBe(u2)
+    })
+
+    it('never leaks the raw tenant or user id', () => {
+      const id = computeEndUserIdentifier('tenant-1', 'user-1', { baseSecret: BASE_SECRET })
+      expect(id).not.toContain('tenant-1')
+      expect(id).not.toContain('user-1')
+    })
+
+    it('treats a null tenant as an empty salt without throwing', () => {
+      const withNull = computeEndUserIdentifier(null, 'user-1', { baseSecret: BASE_SECRET })
+      const withEmpty = computeEndUserIdentifier('', 'user-1', { baseSecret: BASE_SECRET })
+      expect(withNull).toMatch(HEX_64)
+      expect(withNull).toBe(withEmpty)
+    })
+
+    it('throws when userId is empty', () => {
+      expect(() => computeEndUserIdentifier('tenant-1', '   ', { baseSecret: BASE_SECRET })).toThrow(
+        /userId/,
+      )
+    })
+  })
+})

package/src/lib/ai/llm-provider.ts

@@ -62,6 +62,16 @@ export interface LlmCreateModelOptions {
    * proxy); Google honors it when the SDK supports it (@ai-sdk/google ≥3.0).
    */
   baseURL?: string
+  /**
+   * Optional opaque, non-reversible end-user identifier attached to the model
+   * call so provider-side abuse enforcement can target a single end user
+   * instead of the whole API-key organization. The runtime computes this as a
+   * tenant-salted HMAC (no PII leaves the platform); the adapter decides how to
+   * map it into per-call `providerOptions` via
+   * {@link LlmProvider.mapEndUserIdentifier}. Adapters without a mapping ignore
+   * it. Always optional — absent identifiers reproduce today's behavior.
+   */
+  endUserIdentifier?: string
 }
 
 /**
@@ -146,4 +156,27 @@ export interface LlmProvider {
    * behavior at `packages/ai-assistant/src/modules/ai_assistant/api/route/route.ts`.
    */
   createModel(options: LlmCreateModelOptions): unknown
+
+  /**
+   * Optional. Maps a runtime-computed end-user identifier (see
+   * {@link LlmCreateModelOptions.endUserIdentifier}) into the AI SDK
+   * `providerOptions` fragment this provider understands — e.g. OpenAI returns
+   * `{ openai: { safetyIdentifier } }`, Anthropic returns
+   * `{ anthropic: { metadata: { userId } } }`. Keys MUST be the AI SDK
+   * provider-option names (camelCase); the SDK translates them to the
+   * provider's request-body fields and strips unknown keys. The runtime merges
+   * the returned fragment into the per-call `providerOptions`. Adapters that
+   * omit this method send no identifier (today's behavior). Implementations
+   * MUST be pure and stateless.
+   */
+  mapEndUserIdentifier?(identifier: string): Record<string, unknown>
+
+  /**
+   * Optional. When `true`, the runtime may run input pre-moderation through
+   * this provider's moderation endpoint before the model call. Only providers
+   * that actually expose a moderation API (initially the OpenAI adapter) set
+   * this. Absent/`false` means the moderation gate is skipped for this provider
+   * and the surface relies on the provider's own server-side filtering.
+   */
+  readonly supportsInputModeration?: boolean
 }

package/src/lib/ai/safety-identifier.ts

@@ -0,0 +1,73 @@
+/**
+ * End-user safety identifiers for AI provider calls.
+ *
+ * Providers such as OpenAI let developers attach an opaque per-end-user
+ * identifier to each request so abuse enforcement can target one user instead
+ * of suspending the whole API-key organization. We never send a reversible id:
+ * the value is a tenant-salted HMAC computed from the platform's existing auth
+ * secret, so no PII or internal id leaves the platform and the same end user in
+ * two tenants produces two unrelated hashes.
+ *
+ * The per-process secret derivation mirrors `deriveJwtAudienceSecret`
+ * (`@open-mercato/shared/lib/auth/jwt`): one HMAC from the base `JWT_SECRET`
+ * under a versioned purpose label, memoized for the process lifetime. No new
+ * secret to provision.
+ *
+ * @see .ai/specs/2026-06-04-ai-input-moderation-and-safety-identifiers.md
+ */
+
+import crypto from 'node:crypto'
+
+const SAFETY_IDENTIFIER_SECRET_LABEL = 'open-mercato:ai-safety-identifier:v1'
+
+const derivedSecretCache = new Map<string, string>()
+
+function readBaseSecret(explicit?: string): string {
+  const secret = explicit ?? process.env.JWT_SECRET
+  if (!secret) {
+    throw new Error('[internal] JWT_SECRET is not set; cannot derive AI safety-identifier secret')
+  }
+  return secret
+}
+
+/**
+ * Derive the per-process safety-identifier HMAC key from the base auth secret.
+ *
+ * Deterministic HMAC-SHA256 of a versioned purpose label keyed by the base
+ * secret, memoized per base secret. Rotating the base secret rotates every
+ * derived identifier — documented as accepted (identifiers are advisory
+ * provider-side metadata, not an in-platform security control).
+ */
+export function deriveAiSafetyIdentifierSecret(baseSecret?: string): string {
+  const base = readBaseSecret(baseSecret)
+  const cached = derivedSecretCache.get(base)
+  if (cached !== undefined) return cached
+  const derived = crypto
+    .createHmac('sha256', base)
+    .update(SAFETY_IDENTIFIER_SECRET_LABEL)
+    .digest('hex')
+  derivedSecretCache.set(base, derived)
+  return derived
+}
+
+/**
+ * Compute the opaque end-user safety identifier for a (tenant, user) pair.
+ *
+ * Returns a 64-char lowercase hex HMAC-SHA256 of `${tenantId}:${userId}` keyed
+ * by the derived secret. Throws (with an `[internal]` message) when the base
+ * secret is missing or `userId` is empty — callers in the runtime wrap this in
+ * a best-effort try/catch so identifier-derivation failures never break chat.
+ */
+export function computeEndUserIdentifier(
+  tenantId: string | null | undefined,
+  userId: string,
+  options?: { baseSecret?: string },
+): string {
+  const normalizedUser = (userId ?? '').trim()
+  if (!normalizedUser) {
+    throw new Error('[internal] computeEndUserIdentifier requires a non-empty userId')
+  }
+  const key = deriveAiSafetyIdentifierSecret(options?.baseSecret)
+  const salt = (tenantId ?? '').trim()
+  return crypto.createHmac('sha256', key).update(`${salt}:${normalizedUser}`).digest('hex')
+}

package/src/lib/auth/__tests__/organizationScope.test.ts

@@ -0,0 +1,107 @@
+/** @jest-environment node */
+
+import {
+  ORGANIZATION_SCOPE_REQUIRED_ERROR_CODE,
+  organizationScopeRequiredResponse,
+  resolveActiveOrganizationId,
+} from '../organizationScope'
+
+const accountOrgId = '22222222-2222-4222-8222-222222222222'
+const selectedOrgId = '33333333-3333-4333-8333-333333333333'
+const actorTenantId = '44444444-4444-4444-8444-444444444444'
+const foreignTenantId = '55555555-5555-4555-8555-555555555555'
+
+describe('resolveActiveOrganizationId', () => {
+  it('uses the selected organization when one is set', () => {
+    expect(
+      resolveActiveOrganizationId({ orgId: selectedOrgId, actorOrgId: accountOrgId }),
+    ).toBe(selectedOrgId)
+  })
+
+  // `orgId: null` + `actorOrgId` set is exactly the shape `applySuperAdminScope` produces for an
+  // all-organizations selection. Answering 401 for it sent `apiFetch` into a refresh loop.
+  it('falls back to the actor organization for an all-organizations selection', () => {
+    expect(
+      resolveActiveOrganizationId({ orgId: null, actorOrgId: accountOrgId }),
+    ).toBe(accountOrgId)
+  })
+
+  // `actorTenantId` is only present when the super-admin cookie override switched tenants.
+  // Selecting the actor's own tenant explicitly keeps the fallback valid.
+  it('keeps the fallback when the tenant override selects the actor tenant', () => {
+    expect(
+      resolveActiveOrganizationId({
+        orgId: null,
+        actorOrgId: accountOrgId,
+        tenantId: actorTenantId,
+        actorTenantId,
+      }),
+    ).toBe(accountOrgId)
+  })
+
+  // The reviewed blocker: tenant B + "all organizations" must not pair the actor's
+  // tenant-A organization with tenant B. No fallback — the route answers 400 instead.
+  it('refuses the fallback when the effective tenant is not the actor tenant', () => {
+    expect(
+      resolveActiveOrganizationId({
+        orgId: null,
+        actorOrgId: accountOrgId,
+        tenantId: foreignTenantId,
+        actorTenantId,
+      }),
+    ).toBeNull()
+  })
+
+  it('refuses the fallback when the tenant override cleared the tenant entirely', () => {
+    expect(
+      resolveActiveOrganizationId({
+        orgId: null,
+        actorOrgId: accountOrgId,
+        tenantId: null,
+        actorTenantId,
+      }),
+    ).toBeNull()
+    expect(
+      resolveActiveOrganizationId({
+        orgId: null,
+        actorOrgId: accountOrgId,
+        tenantId: foreignTenantId,
+        actorTenantId: null,
+      }),
+    ).toBeNull()
+  })
+
+  it('returns null when the caller has no organization at all', () => {
+    expect(resolveActiveOrganizationId({ orgId: null })).toBeNull()
+    expect(resolveActiveOrganizationId({ orgId: null, actorOrgId: null })).toBeNull()
+    expect(resolveActiveOrganizationId(null)).toBeNull()
+  })
+
+  it('ignores blank and non-string values rather than scoping to them', () => {
+    expect(resolveActiveOrganizationId({ orgId: '   ', actorOrgId: accountOrgId })).toBe(accountOrgId)
+    expect(resolveActiveOrganizationId({ orgId: null, actorOrgId: '  ' })).toBeNull()
+    expect(resolveActiveOrganizationId({ orgId: null, actorOrgId: 42 })).toBeNull()
+  })
+
+  it('still honours an explicit organization selection across tenants', () => {
+    expect(
+      resolveActiveOrganizationId({
+        orgId: selectedOrgId,
+        actorOrgId: accountOrgId,
+        tenantId: foreignTenantId,
+        actorTenantId,
+      }),
+    ).toBe(selectedOrgId)
+  })
+})
+
+describe('organizationScopeRequiredResponse', () => {
+  // 401 would send `apiFetch` back into the session-refresh loop; the scope error must not.
+  it('answers 400 with a machine-readable code', async () => {
+    const response = organizationScopeRequiredResponse()
+    expect(response.status).toBe(400)
+    const body = await response.json()
+    expect(body.code).toBe(ORGANIZATION_SCOPE_REQUIRED_ERROR_CODE)
+    expect(typeof body.error).toBe('string')
+  })
+})

package/src/lib/auth/__tests__/server.test.ts

@@ -161,4 +161,27 @@ describe('auth server integrity checks', () => {
 
     await expect(getAuthFromRequest(request)).resolves.toBeNull()
   })
+
+  it('reports a transient DB failure on the api-key path as "error" (retryable 503)', async () => {
+    const { resolveAuthFromRequestDetailed } = await import('@open-mercato/shared/lib/auth/server')
+    // Distinct secret so the shared api-key auth cache does not serve a prior miss.
+    findApiKeyBySecret.mockRejectedValue(Object.assign(new Error('sorry, too many clients already'), { code: '53300' }))
+
+    const request = new Request('https://example.test/api/test', {
+      headers: { 'x-api-key': 'transient-key' },
+    })
+
+    await expect(resolveAuthFromRequestDetailed(request)).resolves.toEqual({ auth: null, status: 'error' })
+  })
+
+  it('keeps a non-transient api-key failure as "missing" (unchanged 401 behavior)', async () => {
+    const { resolveAuthFromRequestDetailed } = await import('@open-mercato/shared/lib/auth/server')
+    findApiKeyBySecret.mockRejectedValue(new Error('unexpected non-db failure'))
+
+    const request = new Request('https://example.test/api/test', {
+      headers: { 'x-api-key': 'non-transient-key' },
+    })
+
+    await expect(resolveAuthFromRequestDetailed(request)).resolves.toEqual({ auth: null, status: 'missing' })
+  })
 })

package/src/lib/auth/organizationScope.ts

@@ -0,0 +1,65 @@
+type OrganizationScopedAuth = {
+  orgId?: string | null
+  actorOrgId?: unknown
+  tenantId?: string | null
+  actorTenantId?: unknown
+} | null | undefined
+
+function normalizeId(value: unknown): string | null {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length > 0 ? trimmed : null
+}
+
+/**
+ * Resolves the organization a request is scoped to when the caller may be viewing
+ * "all organizations".
+ *
+ * Organization-scoped configuration modules (integrations credentials/state, data sync
+ * mappings/schedules/runs) all require a non-null `organization_id`, so there is no
+ * meaningful "all organizations" view of them. When an operator selects that option the
+ * super-admin cookie override clears `auth.orgId` and preserves the actor's own
+ * organization in `actorOrgId`; fall back to it so those modules keep showing the
+ * operator's own configuration instead of failing.
+ *
+ * The fallback is only valid while the effective tenant is still the actor's own tenant.
+ * When the super-admin cookie override also switched tenants (`actorTenantId` is present
+ * and differs from `auth.tenantId`), the actor's organization belongs to another tenant —
+ * scoping to it would persist a cross-tenant `{ organizationId, tenantId }` pair. Return
+ * `null` instead and let the route answer with `organizationScopeRequiredResponse()`.
+ *
+ * Answering 401 for an unresolvable scope is not merely wrong but self-perpetuating:
+ * `apiFetch` reads 401 as an expired session and redirects through
+ * `/api/auth/session/refresh`, which succeeds and returns to the same page, reloading
+ * forever. That is why the missing-scope answer is a 400, never a 401.
+ */
+export function resolveActiveOrganizationId(auth: OrganizationScopedAuth): string | null {
+  if (!auth) return null
+  const selected = normalizeId(auth.orgId)
+  if (selected) return selected
+  const actorOrgId = normalizeId(auth.actorOrgId)
+  if (!actorOrgId) return null
+  if ('actorTenantId' in auth) {
+    const actorTenantId = normalizeId(auth.actorTenantId)
+    const effectiveTenantId = normalizeId(auth.tenantId)
+    if (!actorTenantId || actorTenantId !== effectiveTenantId) return null
+  }
+  return actorOrgId
+}
+
+export const ORGANIZATION_SCOPE_REQUIRED_ERROR_CODE = 'organization_scope_required'
+
+/**
+ * 400 response for an authenticated caller whose organization scope cannot be resolved
+ * (e.g. a super-admin viewing a foreign tenant with "all organizations" selected).
+ * Deliberately not a 401: the session is valid, so refreshing it would loop.
+ */
+export function organizationScopeRequiredResponse(): Response {
+  return Response.json(
+    {
+      error: 'Select an organization to access this resource',
+      code: ORGANIZATION_SCOPE_REQUIRED_ERROR_CODE,
+    },
+    { status: 400 },
+  )
+}

package/src/lib/auth/server.ts

@@ -2,6 +2,7 @@ import { cookies } from 'next/headers.js'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import { verifyJwt } from './jwt'
 import { getSharedApiKeyAuthCache } from './apiKeyAuthCache'
+import { isTransientDbError } from '@open-mercato/shared/lib/db/pg-errors'
 
 const TENANT_COOKIE_NAME = 'om_selected_tenant'
 const ORGANIZATION_COOKIE_NAME = 'om_selected_org'
@@ -253,7 +254,14 @@ async function resolveApiKeyAuth(secret: string): Promise<AuthContext> {
     }
     cache.setSuccess(secret, auth, record.expiresAt ? record.expiresAt.getTime() : null)
     return auth
-  } catch {
+  } catch (err) {
+    // A transient DB failure (pool exhausted, `max_connections` reached, DB
+    // restarting) means we could not confirm the key — NOT that it is invalid.
+    // Surface it so callers return a retryable 503 instead of masking it as an
+    // auth miss (401). Genuine misses already returned `null` above.
+    if (isTransientDbError(err)) {
+      throw new AuthResolutionUnavailableError(err)
+    }
     return null
   }
 }
@@ -365,7 +373,20 @@ export async function resolveAuthFromRequestDetailed(req: Request): Promise<Auth
   if (!apiKey) {
     return { auth: null, status: resolveUnauthenticatedStatus() }
   }
-  const apiAuth = await resolveApiKeyAuth(apiKey)
+  let apiAuth: AuthContext
+  try {
+    apiAuth = await resolveApiKeyAuth(apiKey)
+  } catch (err) {
+    // Only a transient canonical-resolution failure maps to 'error' (retryable
+    // 503), mirroring the interactive-token path above. Anything else is an
+    // unexpected bug — rethrow so it surfaces as a 500 rather than being masked
+    // as an auth failure.
+    if (!(err instanceof AuthResolutionUnavailableError)) {
+      throw err
+    }
+    hadUnavailableResolution = true
+    return { auth: null, status: resolveUnauthenticatedStatus() }
+  }
   if (!apiAuth) {
     return { auth: null, status: resolveUnauthenticatedStatus() }
   }