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

package/src/modules/ai_assistant/lib/moderation-policy.ts

@@ -0,0 +1,77 @@
+/**
+ * Input-moderation policy resolution.
+ *
+ * Resolves the effective moderation policy for an agent turn using a fixed
+ * precedence (first match wins):
+ *
+ *   1. `agentDef.untrustedInput === true` → `enforced` (tenant cannot disable).
+ *   2. Per-agent tenant override (`ai_agent_runtime_overrides` row with an
+ *      `agent_id`) `input_moderation` → `on` / `off`.
+ *   3. Tenant-wide override (row with `agent_id = NULL`) `input_moderation` →
+ *      `on` / `off`.
+ *   4. Env default `OM_AI_INPUT_MODERATION` (parsed via `parseBooleanWithDefault`)
+ *      → `on` / `off`.
+ *   5. Default `off`.
+ *
+ * Steps 4 and 5 collapse into `parseBooleanWithDefault(env, false)`.
+ *
+ * @see .ai/specs/2026-06-04-ai-input-moderation-and-safety-identifiers.md
+ */
+
+import type { EnvLookup } from '@open-mercato/shared/lib/ai/llm-provider'
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+
+/** Effective runtime moderation policy for a turn. */
+export type ModerationPolicy = 'enforced' | 'on' | 'off'
+
+/** The per-agent display state shown in settings (adds `inherit`). */
+export type ModerationPolicyDisplay = 'enforced' | 'on' | 'off' | 'inherit'
+
+export interface ResolveModerationPolicyInput {
+  /** Whether the agent definition marks this surface as untrusted. */
+  untrustedInput?: boolean
+  /**
+   * `input_moderation` from the agent-scoped tenant override row, or
+   * `null`/`undefined` when the row is absent or leaves it unset (inherit).
+   */
+  perAgentOverride?: boolean | null
+  /**
+   * `input_moderation` from the tenant-wide override row (`agent_id = NULL`),
+   * or `null`/`undefined` when absent/unset (inherit).
+   */
+  tenantWideOverride?: boolean | null
+  /** Env lookup; reads `OM_AI_INPUT_MODERATION`. Defaults to `process.env`. */
+  env?: EnvLookup
+}
+
+/**
+ * Resolves the effective moderation policy following the 5-step precedence.
+ * Pure and synchronous — the runtime hydrates the override values from the DB
+ * before calling this.
+ */
+export function resolveModerationPolicy(input: ResolveModerationPolicyInput): ModerationPolicy {
+  if (input.untrustedInput === true) return 'enforced'
+  if (input.perAgentOverride !== null && input.perAgentOverride !== undefined) {
+    return input.perAgentOverride ? 'on' : 'off'
+  }
+  if (input.tenantWideOverride !== null && input.tenantWideOverride !== undefined) {
+    return input.tenantWideOverride ? 'on' : 'off'
+  }
+  const env = input.env ?? process.env
+  return parseBooleanWithDefault(env.OM_AI_INPUT_MODERATION, false) ? 'on' : 'off'
+}
+
+/** Whether a resolved policy should run the moderation gate for the turn. */
+export function isModerationActive(policy: ModerationPolicy): boolean {
+  return policy === 'enforced' || policy === 'on'
+}
+
+/**
+ * Whether an *unavailable* moderation check (endpoint outage) should fail
+ * closed (reject the turn) rather than fail open (allow it through). Per spec:
+ * only `enforced` (untrusted) surfaces fail closed; opt-in `on` surfaces prefer
+ * availability and fail open. Both paths log. (`off` never reaches the gate.)
+ */
+export function shouldFailClosed(policy: ModerationPolicy): boolean {
+  return policy === 'enforced'
+}

package/src/modules/ai_assistant/lib/moderation.ts

@@ -0,0 +1,179 @@
+/**
+ * Input pre-moderation service.
+ *
+ * Wraps OpenAI's free `/v1/moderations` endpoint so the agent runtime can
+ * screen the current user turn BEFORE the model call on surfaces that opt in
+ * (or are forced on via `untrustedInput`). The service is intentionally pure:
+ * it performs the HTTP check and returns category flags + scores, or throws
+ * {@link AiModerationUnavailableError} when the endpoint is unreachable. It does
+ * NOT persist audit records, emit events, or throw the user-facing block — the
+ * runtime gate orchestrates those (see `agent-runtime.ts`).
+ *
+ * @see .ai/specs/2026-06-04-ai-input-moderation-and-safety-identifiers.md
+ */
+
+import { z } from 'zod'
+
+/** Default moderation model; override with `OM_AI_MODERATION_MODEL`. */
+export const DEFAULT_MODERATION_MODEL = 'omni-moderation-latest'
+
+const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1'
+const REQUEST_TIMEOUT_MS = 3000
+
+/** Per-category moderation outcome: whether it tripped and the model's score. */
+export interface ModerationCategoryResult {
+  flagged: boolean
+  score: number
+}
+
+/** Result of an input moderation check — flags + scores only, never content. */
+export interface ModerationResult {
+  flagged: boolean
+  categories: Record<string, ModerationCategoryResult>
+}
+
+/** Arguments for {@link ModerationService.checkInput}. */
+export interface ModerationCheckInput {
+  /** The current user turn text to screen. */
+  text: string
+  /** Resolved OpenAI(-compatible) API key for the moderations endpoint. */
+  apiKey: string
+  /** Optional base URL override (defaults to the OpenAI public endpoint). */
+  baseURL?: string
+  /** Optional model override (defaults to {@link DEFAULT_MODERATION_MODEL}). */
+  model?: string
+}
+
+/** Port resolved from the DI container by the agent runtime. */
+export interface ModerationService {
+  checkInput(input: ModerationCheckInput): Promise<ModerationResult>
+}
+
+/**
+ * Thrown by the runtime gate (NOT the service) when flagged input is rejected
+ * on an enabled/enforced surface. The SSE error path maps it to the
+ * `moderation_blocked` code; the raw categories are never sent to the client.
+ */
+export class AiModerationBlockedError extends Error {
+  readonly categories: Record<string, ModerationCategoryResult>
+
+  constructor(categories: Record<string, ModerationCategoryResult>) {
+    super('[internal] Input rejected by the content safety filter')
+    this.name = 'AiModerationBlockedError'
+    this.categories = categories
+  }
+}
+
+/**
+ * Thrown by {@link ModerationService.checkInput} when the moderation endpoint
+ * is unreachable (timeout, network error, or non-2xx after one retry). The gate
+ * decides fail-closed (enforced surfaces) vs fail-open (opt-in surfaces).
+ */
+export class AiModerationUnavailableError extends Error {
+  readonly cause?: unknown
+
+  constructor(message: string, cause?: unknown) {
+    super(`[internal] ${message}`)
+    this.name = 'AiModerationUnavailableError'
+    this.cause = cause
+  }
+}
+
+const moderationResponseSchema = z.object({
+  results: z
+    .array(
+      z.object({
+        flagged: z.boolean(),
+        categories: z.record(z.string(), z.boolean()),
+        category_scores: z.record(z.string(), z.number()),
+      }),
+    )
+    .min(1),
+})
+
+function mergeCategories(
+  categories: Record<string, boolean>,
+  scores: Record<string, number>,
+): Record<string, ModerationCategoryResult> {
+  const merged: Record<string, ModerationCategoryResult> = {}
+  for (const [name, flagged] of Object.entries(categories)) {
+    merged[name] = { flagged, score: scores[name] ?? 0 }
+  }
+  return merged
+}
+
+async function postModeration(input: ModerationCheckInput): Promise<Response> {
+  const baseURL = (input.baseURL ?? DEFAULT_OPENAI_BASE_URL).replace(/\/$/, '')
+  const controller = new AbortController()
+  const timer = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS)
+  try {
+    return await fetch(`${baseURL}/moderations`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${input.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: input.model ?? DEFAULT_MODERATION_MODEL,
+        input: input.text,
+      }),
+      signal: controller.signal,
+    })
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/**
+ * Builds the default {@link ModerationService}. Stateless and DI-friendly —
+ * registered in `di.ts` and overridable by downstream apps.
+ */
+export function createModerationService(): ModerationService {
+  return {
+    async checkInput(input: ModerationCheckInput): Promise<ModerationResult> {
+      let lastError: unknown
+      // One short-timeout attempt + one retry (R: outage mitigation).
+      for (let attempt = 0; attempt < 2; attempt += 1) {
+        let response: Response
+        try {
+          response = await postModeration(input)
+        } catch (error) {
+          lastError = error
+          continue
+        }
+        if (response.status >= 500) {
+          lastError = new Error(`moderation endpoint returned ${response.status}`)
+          continue
+        }
+        if (!response.ok) {
+          // 4xx is a configuration/credential error — not transient; do not retry.
+          throw new AiModerationUnavailableError(
+            `moderation endpoint returned ${response.status}`,
+          )
+        }
+        let json: unknown
+        try {
+          json = await response.json()
+        } catch (error) {
+          throw new AiModerationUnavailableError('moderation response was not valid JSON', error)
+        }
+        const parsed = moderationResponseSchema.safeParse(json)
+        if (!parsed.success) {
+          throw new AiModerationUnavailableError(
+            'moderation response did not match the expected schema',
+            parsed.error,
+          )
+        }
+        const result = parsed.data.results[0]
+        return {
+          flagged: result.flagged,
+          categories: mergeCategories(result.categories, result.category_scores),
+        }
+      }
+      throw new AiModerationUnavailableError(
+        'moderation endpoint unreachable after retry',
+        lastError,
+      )
+    },
+  }
+}

package/src/modules/ai_assistant/lib/openai-compatible-presets.ts

@@ -26,6 +26,8 @@ const OPENAI_PRESET: OpenAICompatiblePreset = {
   baseURL: undefined,
   baseURLEnvKeys: ['OPENAI_BASE_URL'],
   envKeys: ['OPENAI_API_KEY', 'OPENCODE_OPENAI_API_KEY'],
+  supportsInputModeration: true,
+  supportsEndUserSafetyIdentifier: true,
   defaultModel: 'gpt-5-mini',
   defaultModels: [
     {

package/src/modules/ai_assistant/lib/tool-search.ts

@@ -1,5 +1,6 @@
 import type { SearchService } from '@open-mercato/search/service'
 import type { SearchStrategyId, IndexableRecord } from '@open-mercato/search/types'
+import { authorizeFeatures } from '@open-mercato/shared/security/featurePolicy'
 import type { McpToolRegistry, McpToolDefinition } from './types'
 import {
   TOOL_ENTITY_ID,
@@ -294,23 +295,9 @@ export class ToolSearchService {
     userFeatures: string[],
     isSuperAdmin: boolean
   ): boolean {
-    if (isSuperAdmin) return true
-    if (!requiredFeatures?.length) return true
-
-    return requiredFeatures.every((required) => {
-      // Direct match
-      if (userFeatures.includes(required)) return true
-      // Wildcard match
-      if (userFeatures.includes('*')) return true
-
-      // Prefix wildcard match (e.g., 'customers.*' matches 'customers.people.view')
-      return userFeatures.some((feature) => {
-        if (feature.endsWith('.*')) {
-          const prefix = feature.slice(0, -2)
-          return required.startsWith(prefix + '.')
-        }
-        return false
-      })
+    return authorizeFeatures(requiredFeatures ?? [], {
+      grantedFeatures: userFeatures,
+      unrestricted: isSuperAdmin,
     })
   }
 }