feat: add allowedModels/disallowedModels policy enforcement to api-proxy

Implements issue #4389: allowed and disallowed model glob pattern lists
enforced at two points:
1. Alias resolution: policy-violating candidates filtered in _resolveAliasPatterns
2. Inference guard: model-policy-guard.js checked in enforceGuards pipeline

Config flows from awf.yml → TypeScript config → env vars AWF_ALLOWED_MODELS /
AWF_DISALLOWED_MODELS (JSON arrays) → api-proxy container.

Disallowed takes priority over allowed when a model matches both lists.

Author: Copilot

containers/api-proxy/guards/common-guard-checks.js

@@ -32,6 +32,8 @@
  * @param {Function} deps.getRetiredModelBlockState
  * @param {Function} deps.buildRetiredModelError
  * @param {Function} deps.checkUnknownModelRejection
+ * @param {Function} deps.getModelPolicyBlockState
+ * @param {Function} deps.buildModelPolicyError
  * @param {string|null} model - Model name extracted from the request, or null
  *   to skip model-specific guards.
  * @returns {Array<object>} Array of guard descriptor objects.
@@ -51,6 +53,8 @@ function buildCommonGuardChecks(deps, model) {
     getRetiredModelBlockState,
     buildRetiredModelError,
     checkUnknownModelRejection,
+    getModelPolicyBlockState,
+    buildModelPolicyError,
   } = deps;
 
   return [
@@ -134,6 +138,17 @@ function buildCommonGuardChecks(deps, model) {
           model: block.model,
         }),
       },
+      {
+        block: getModelPolicyBlockState(model),
+        isBlocked: block => !!block,
+        statusCode: 400,
+        eventName: 'model_policy_violation',
+        buildError: buildModelPolicyError,
+        buildLogFields: block => ({
+          model: block.model,
+          reason: block.reason,
+        }),
+      },
     ] : []),
   ];
 }

containers/api-proxy/guards/model-policy-guard.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const { globMatch } = require('../model-utils');
+
+/**
+ * Model policy enforcement for AWF API proxy.
+ *
+ * Enforces allowed and disallowed model lists using glob patterns.
+ *
+ * Config (JSON arrays of glob patterns):
+ *   AWF_ALLOWED_MODELS  — allowlist: only models matching at least one pattern are permitted
+ *   AWF_DISALLOWED_MODELS — denylist: models matching any pattern are rejected
+ *
+ * Rules:
+ *   1. If a model matches any disallowed pattern → rejected.
+ *   2. If an allowlist is configured and the model matches no allowed pattern → rejected.
+ *   3. Otherwise → permitted.
+ *
+ * Glob syntax: * wildcard, case-insensitive. Examples: "*opus*", "claude-*", "gpt-5*".
+ */
+
+/**
+ * Parse a JSON array of glob pattern strings from a raw env var value.
+ *
+ * @param {string|null|undefined} raw
+ * @returns {string[]|null} Parsed array of pattern strings, or null if absent/invalid/empty.
+ */
+function parseModelPatterns(raw) {
+  if (!raw || !raw.trim()) return null;
+  try {
+    const parsed = JSON.parse(raw.trim());
+    if (!Array.isArray(parsed)) return null;
+    const strings = parsed.filter(p => typeof p === 'string' && p.trim());
+    return strings.length > 0 ? strings : null;
+  } catch {
+    return null;
+  }
+}
+
+const ALLOWED_MODELS = parseModelPatterns(process.env.AWF_ALLOWED_MODELS);
+const DISALLOWED_MODELS = parseModelPatterns(process.env.AWF_DISALLOWED_MODELS);
+
+if (ALLOWED_MODELS) {
+  const { logRequest } = require('../logging');
+  logRequest('info', 'startup', {
+    message: 'Model policy: allowed models configured',
+    allowed_models: ALLOWED_MODELS,
+  });
+}
+
+if (DISALLOWED_MODELS) {
+  const { logRequest } = require('../logging');
+  logRequest('info', 'startup', {
+    message: 'Model policy: disallowed models configured',
+    disallowed_models: DISALLOWED_MODELS,
+  });
+}
+
+/**
+ * Check whether a model name is permitted by the current policy.
+ *
+ * @param {string} model - The model name to check (case-insensitive)
+ * @param {string[]|null} [allowedModels] - Override for allowed patterns (defaults to module-level config)
+ * @param {string[]|null} [disallowedModels] - Override for disallowed patterns (defaults to module-level config)
+ * @returns {boolean} true when the model is permitted.
+ */
+function isModelPermittedByPolicy(model, allowedModels = ALLOWED_MODELS, disallowedModels = DISALLOWED_MODELS) {
+  if (!allowedModels && !disallowedModels) return true;
+  if (!model) return true;
+
+  // Disallowed check first (denylist takes priority over allowlist)
+  if (disallowedModels && disallowedModels.some(pattern => globMatch(pattern, model))) {
+    return false;
+  }
+
+  // Allowlist check
+  if (allowedModels && !allowedModels.some(pattern => globMatch(pattern, model))) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Returns a block-state object when the model is rejected by the model policy,
+ * or null when the model is permitted.
+ *
+ * @param {string|null} model - The model name extracted from the request body.
+ * @returns {{ model: string, reason: 'disallowed'|'not_allowed' } | null}
+ */
+function getModelPolicyBlockState(model) {
+  if (!model) return null;
+  if (!ALLOWED_MODELS && !DISALLOWED_MODELS) return null;
+
+  if (DISALLOWED_MODELS && DISALLOWED_MODELS.some(pattern => globMatch(pattern, model))) {
+    return { model, reason: 'disallowed' };
+  }
+
+  if (ALLOWED_MODELS && !ALLOWED_MODELS.some(pattern => globMatch(pattern, model))) {
+    return { model, reason: 'not_allowed' };
+  }
+
+  return null;
+}
+
+/**
+ * Builds the structured 400 error response body for a model-policy rejection.
+ *
+ * @param {{ model: string, reason: string }} state
+ * @returns {{ error: object }}
+ */
+function buildModelPolicyError(state) {
+  const message = state.reason === 'disallowed'
+    ? `Model '${state.model}' is not permitted: it is explicitly disallowed by the model policy.`
+    : `Model '${state.model}' is not permitted: it does not match the allowed models policy.`;
+  return {
+    error: {
+      type: 'model_policy_violation',
+      message,
+      model: state.model,
+      reason: state.reason,
+    },
+  };
+}
+
+module.exports = {
+  parseModelPatterns,
+  isModelPermittedByPolicy,
+  getModelPolicyBlockState,
+  buildModelPolicyError,
+  ALLOWED_MODELS,
+  DISALLOWED_MODELS,
+};

containers/api-proxy/guards/model-policy-guard.test.js

@@ -0,0 +1,206 @@
+'use strict';
+
+// Reset module registry between tests so env-var-based constants are re-evaluated.
+beforeEach(() => {
+  jest.resetModules();
+  delete process.env.AWF_ALLOWED_MODELS;
+  delete process.env.AWF_DISALLOWED_MODELS;
+});
+
+afterEach(() => {
+  delete process.env.AWF_ALLOWED_MODELS;
+  delete process.env.AWF_DISALLOWED_MODELS;
+});
+
+// Helper: load a fresh instance of the guard with the current env vars.
+function loadGuard() {
+  return require('./model-policy-guard');
+}
+
+describe('parseModelPatterns', () => {
+  it('should return null for an empty string', () => {
+    const { parseModelPatterns } = loadGuard();
+    expect(parseModelPatterns('')).toBeNull();
+    expect(parseModelPatterns('  ')).toBeNull();
+    expect(parseModelPatterns(null)).toBeNull();
+    expect(parseModelPatterns(undefined)).toBeNull();
+  });
+
+  it('should return null for invalid JSON', () => {
+    const { parseModelPatterns } = loadGuard();
+    expect(parseModelPatterns('not-json')).toBeNull();
+    expect(parseModelPatterns('{}')).toBeNull();
+    expect(parseModelPatterns('"string"')).toBeNull();
+  });
+
+  it('should return null for an empty array', () => {
+    const { parseModelPatterns } = loadGuard();
+    expect(parseModelPatterns('[]')).toBeNull();
+  });
+
+  it('should return null for arrays with non-string items', () => {
+    const { parseModelPatterns } = loadGuard();
+    expect(parseModelPatterns('[1, 2]')).toBeNull();
+  });
+
+  it('should return the parsed array for a valid JSON array of strings', () => {
+    const { parseModelPatterns } = loadGuard();
+    expect(parseModelPatterns('["*opus*", "gpt-5*"]')).toEqual(['*opus*', 'gpt-5*']);
+  });
+
+  it('should filter out empty strings', () => {
+    const { parseModelPatterns } = loadGuard();
+    expect(parseModelPatterns('["*opus*", "", "  "]')).toEqual(['*opus*']);
+  });
+});
+
+describe('isModelPermittedByPolicy', () => {
+  it('should permit all models when no policy is configured', () => {
+    const { isModelPermittedByPolicy } = loadGuard();
+    expect(isModelPermittedByPolicy('claude-opus-4.5', null, null)).toBe(true);
+    expect(isModelPermittedByPolicy('gpt-5-codex', null, null)).toBe(true);
+  });
+
+  it('should reject models matching a disallowed pattern', () => {
+    const { isModelPermittedByPolicy } = loadGuard();
+    const disallowed = ['*opus*'];
+    expect(isModelPermittedByPolicy('claude-opus-4.5', null, disallowed)).toBe(false);
+    expect(isModelPermittedByPolicy('claude-sonnet-4.6', null, disallowed)).toBe(true);
+  });
+
+  it('should reject models not matching an allowed pattern', () => {
+    const { isModelPermittedByPolicy } = loadGuard();
+    const allowed = ['*sonnet*', '*haiku*'];
+    expect(isModelPermittedByPolicy('claude-sonnet-4.6', allowed, null)).toBe(true);
+    expect(isModelPermittedByPolicy('claude-haiku-3-5', allowed, null)).toBe(true);
+    expect(isModelPermittedByPolicy('claude-opus-4.5', allowed, null)).toBe(false);
+    expect(isModelPermittedByPolicy('gpt-5-codex', allowed, null)).toBe(false);
+  });
+
+  it('should reject models in disallowed list even if also in allowed list', () => {
+    const { isModelPermittedByPolicy } = loadGuard();
+    const allowed = ['*sonnet*'];
+    const disallowed = ['*sonnet*'];
+    expect(isModelPermittedByPolicy('claude-sonnet-4.6', allowed, disallowed)).toBe(false);
+  });
+
+  it('should be case-insensitive', () => {
+    const { isModelPermittedByPolicy } = loadGuard();
+    expect(isModelPermittedByPolicy('Claude-Sonnet-4.6', ['*sonnet*'], null)).toBe(true);
+    expect(isModelPermittedByPolicy('CLAUDE-OPUS-4.5', null, ['*opus*'])).toBe(false);
+  });
+
+  it('should permit models when allowed list is empty/null', () => {
+    const { isModelPermittedByPolicy } = loadGuard();
+    expect(isModelPermittedByPolicy('any-model', null, null)).toBe(true);
+  });
+});
+
+describe('getModelPolicyBlockState', () => {
+  describe('no policy configured', () => {
+    it('should return null for any model', () => {
+      const guard = loadGuard();
+      expect(guard.getModelPolicyBlockState('claude-opus-4.5')).toBeNull();
+      expect(guard.getModelPolicyBlockState('gpt-5-codex')).toBeNull();
+      expect(guard.getModelPolicyBlockState(null)).toBeNull();
+    });
+  });
+
+  describe('disallowedModels only', () => {
+    beforeEach(() => {
+      process.env.AWF_DISALLOWED_MODELS = JSON.stringify(['*opus*']);
+    });
+
+    it('should return block state for a disallowed model', () => {
+      const guard = loadGuard();
+      const result = guard.getModelPolicyBlockState('claude-opus-4.5');
+      expect(result).not.toBeNull();
+      expect(result.model).toBe('claude-opus-4.5');
+      expect(result.reason).toBe('disallowed');
+    });
+
+    it('should return null for a non-disallowed model', () => {
+      const guard = loadGuard();
+      expect(guard.getModelPolicyBlockState('claude-sonnet-4.6')).toBeNull();
+    });
+
+    it('should handle multiple disallowed patterns', () => {
+      process.env.AWF_DISALLOWED_MODELS = JSON.stringify(['*opus*', 'gpt-5*']);
+      const guard = loadGuard();
+      expect(guard.getModelPolicyBlockState('claude-opus-4.5')).not.toBeNull();
+      expect(guard.getModelPolicyBlockState('gpt-5-codex')).not.toBeNull();
+      expect(guard.getModelPolicyBlockState('claude-sonnet-4.6')).toBeNull();
+    });
+  });
+
+  describe('allowedModels only', () => {
+    beforeEach(() => {
+      process.env.AWF_ALLOWED_MODELS = JSON.stringify(['*sonnet*', '*haiku*']);
+    });
+
+    it('should return null for an allowed model', () => {
+      const guard = loadGuard();
+      expect(guard.getModelPolicyBlockState('claude-sonnet-4.6')).toBeNull();
+      expect(guard.getModelPolicyBlockState('claude-haiku-3-5')).toBeNull();
+    });
+
+    it('should return block state for a model not in the allowed list', () => {
+      const guard = loadGuard();
+      const result = guard.getModelPolicyBlockState('claude-opus-4.5');
+      expect(result).not.toBeNull();
+      expect(result.model).toBe('claude-opus-4.5');
+      expect(result.reason).toBe('not_allowed');
+    });
+
+    it('should return null for null model', () => {
+      const guard = loadGuard();
+      expect(guard.getModelPolicyBlockState(null)).toBeNull();
+    });
+  });
+
+  describe('both allowedModels and disallowedModels', () => {
+    beforeEach(() => {
+      process.env.AWF_ALLOWED_MODELS = JSON.stringify(['*claude*']);
+      process.env.AWF_DISALLOWED_MODELS = JSON.stringify(['*opus*']);
+    });
+
+    it('should block a model in the disallowed list even if it matches allowed', () => {
+      const guard = loadGuard();
+      const result = guard.getModelPolicyBlockState('claude-opus-4.5');
+      expect(result).not.toBeNull();
+      expect(result.reason).toBe('disallowed');
+    });
+
+    it('should block a model not in the allowed list', () => {
+      const guard = loadGuard();
+      const result = guard.getModelPolicyBlockState('gpt-5-codex');
+      expect(result).not.toBeNull();
+      expect(result.reason).toBe('not_allowed');
+    });
+
+    it('should allow a model that matches allowed and does not match disallowed', () => {
+      const guard = loadGuard();
+      expect(guard.getModelPolicyBlockState('claude-sonnet-4.6')).toBeNull();
+    });
+  });
+});
+
+describe('buildModelPolicyError', () => {
+  it('should build a disallowed error message', () => {
+    const { buildModelPolicyError } = loadGuard();
+    const result = buildModelPolicyError({ model: 'claude-opus-4.5', reason: 'disallowed' });
+    expect(result.error.type).toBe('model_policy_violation');
+    expect(result.error.model).toBe('claude-opus-4.5');
+    expect(result.error.reason).toBe('disallowed');
+    expect(result.error.message).toContain('explicitly disallowed');
+  });
+
+  it('should build a not_allowed error message', () => {
+    const { buildModelPolicyError } = loadGuard();
+    const result = buildModelPolicyError({ model: 'gpt-5-codex', reason: 'not_allowed' });
+    expect(result.error.type).toBe('model_policy_violation');
+    expect(result.error.model).toBe('gpt-5-codex');
+    expect(result.error.reason).toBe('not_allowed');
+    expect(result.error.message).toContain('allowed models policy');
+  });
+});

containers/api-proxy/model-body-rewriter.js

@@ -22,9 +22,10 @@ const { resolveModel } = require('./model-resolver');
  * @param {Record<string, string[]|{patterns: string[], fallback?: boolean}>} aliases - Parsed alias map
  * @param {Record<string, string[]|null>} availableModels - Cached models per provider
  * @param {{ enabled?: boolean, strategy?: string }} [modelFallbackConfig]
+ * @param {{ allowedModels?: string[]|null, disallowedModels?: string[]|null }|null} [modelPolicyConfig]
  * @returns {{ body: Buffer, originalModel: string, resolvedModel: string, log: string[], fallback?: object } | null}
  */
-function rewriteModelInBody(body, provider, aliases, availableModels, modelFallbackConfig) {
+function rewriteModelInBody(body, provider, aliases, availableModels, modelFallbackConfig, modelPolicyConfig) {
   // Only attempt rewrite for non-empty bodies
   if (!body || body.length === 0) return null;
 
@@ -34,7 +35,7 @@ function rewriteModelInBody(body, provider, aliases, availableModels, modelFallb
   // Determine the requested model. If absent, try the default alias ("").
   const originalModel = typeof parsed.model === 'string' ? parsed.model : '';
 
-  const resolution = resolveModel(originalModel, aliases, availableModels, provider, [], modelFallbackConfig);
+  const resolution = resolveModel(originalModel, aliases, availableModels, provider, [], modelFallbackConfig, modelPolicyConfig);
   if (!resolution) return null;
 
   const { resolvedModel, log } = resolution;