Phase 4 — Apply policies

Policies are rules attached at the workspace, project, or environment level. They are evaluated during every resolve call. Resolve uses enabled-step order with policy filtering: it tries each enabled step in order and returns the first step that passes all policies. There is no implicit provider health probing. If a policy blocks a step, Restormel skips to the next step; if all steps are blocked, resolve returns a policy_blocked error (403) with violation details.

Policies stack. If you have both a model_allowlist and a budget_cap, both must pass for a model to be resolved.

Start with the most common policy: restricting which models your app can use.

1. Type: model_allowlist
2. Scope: Project (applies to all environments and routes in this project)
3. Models: Pick each ID from your live model catalog (Dashboard → Models or GET /api/models). Do not assume walkthrough example IDs exist in your deployment.
4. Save the policy.

You'll see

The policy listed on the project's Policies page with the type, scope, and allowed models.

How to test

Call resolve; the response data.modelId comes from the first enabled step that passes policies. If your route steps include a blocked model, resolve skips that step and returns the next allowed step.

Call resolve with an allowed model in your route; expected: a modelId from your allowlist. The resolve API returns data.providerType as vertex when the step uses Google internally (policies still use google).

This policy prevents your app from resolving to models that the Restormel model catalog has marked as approaching end-of-life. Even if a route step specifies a deprecated model, this policy blocks it and forces a fallback.

You'll see

The policy listed on the Policies page. Its effect depends on whether any models in your routes are actually deprecated in the catalog.

How to test

If you have a route step that specifies a model currently marked as deprecated in your catalog, resolve skips that step. If none are deprecated, test via evaluate using any deprecated ID that exists in your catalog, or skip until one exists.

Evaluate response shape (200):

{
  "data": {
    "allowed": true,
    "violations": []
  }
}

Each violation object has policyId, policyName, type, message.

curl -s -X POST \
  "https://restormel.dev/keys/dashboard/api/policies/evaluate" \
  -H "Authorization: Bearer ${RESTORMEL_GATEWAY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'${RESTORMEL_PROJECT_ID}'",
    "environmentId": "YOUR_ENV_ID",
    "modelId": "PICK_A_MODEL_ID_FROM_YOUR_CATALOG",
    "providerType": "openai"
  }' | jq '.data'

Minimal backend helper (server-only; key from process.env.RESTORMEL_GATEWAY_KEY):

// Server-only. Load RESTORMEL_GATEWAY_KEY from env; never send to the browser.
const base = process.env.RESTORMEL_KEYS_BASE ?? 'https://restormel.dev';

export async function evaluatePoliciesRemote(input: {
  projectId: string;
  environmentId?: string;
  routeId?: string;
  modelId?: string;
  providerType?: string;
}) {
  const key = process.env.RESTORMEL_GATEWAY_KEY;
  if (!key) throw new Error('RESTORMEL_GATEWAY_KEY is not set');
  const res = await fetch(
    `${base}/keys/dashboard/api/policies/evaluate`,
    {
      method: 'POST',
      headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
      body: JSON.stringify(input),
    }
  );
  const json = (await res.json()) as {
    data?: { allowed: boolean; violations: { policyId: string; policyName: string; type: string; message: string }[] };
    error?: string;
  };
  if (!res.ok) throw new Error(json.error ?? `evaluate HTTP ${res.status}`);
  return json.data!; // { allowed, violations }
}

// Assertions in tests: expect(allowed).toBe(false); expect(violations[0].type).toBe('model_allowlist');

Expected: data.allowed is false when blocked; inspect violations[].type.

budget_cap / token_cap compare usage in request_logs for the bound scope over the current calendar month. Resolve and evaluate both enforce them when policies are bound.

Success criteria (pick what matches your setup)

1. Config only: Policy + binding created via dashboard or API — you’ve proven the object exists; no runtime assertion yet.
2. Evaluate shape: With usage under cap, evaluate returns allowed; after synthetic over-cap usage in logs (or very low limit), evaluate returns budget_cap / token_cap violations.
3. End-to-end: Resolve rejects when caps are exceeded the same way as other policy failures (step skip or policy_blocked if all steps hit the cap). estimated_cost on logs only increases if you report usage; until then, token_cap may be easier to test than budget_cap.

Policies stack: all active policies must pass for a model to be resolved. Verify by having both a model_allowlist and a deprecated_model_block active, then evaluating a model that is on the allowlist but deprecated (if one exists).

curl -s -X POST \
  "https://restormel.dev/keys/dashboard/api/policies/evaluate" \
  -H "Authorization: Bearer ${RESTORMEL_GATEWAY_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'${RESTORMEL_PROJECT_ID}'",
    "environmentId": "YOUR_ENV_ID",
    "modelId": "MODEL_ON_ALLOWLIST",
    "providerType": "openai"
  }' | jq '.data'

Expected: Allowed model + provider → allowed: true. Same flow with a model on the allowlist but deprecated in your catalog → allowed: false, violations[].type includes deprecated_model_block. Use IDs that exist in your catalog.

When all route steps are blocked by policies, resolve returns HTTP 403 with a JSON body (not necessarily thrown as Error with that text). Primary contract:

• error — e.g. "policy_blocked"
• message — short human-readable summary
• violations — array of objects with policyId, policyName, type, message

Example body:

{
  "error": "policy_blocked",
  "message": "All route steps were blocked by policy",
  "violations": [
    {
      "policyId": "…",
      "policyName": "…",
      "type": "model_allowlist",
      "message": "…"
    }
  ]
}

Parse response.json(), branch on error and violations[].type. Use violation detail only in server logs; map to safe user-facing copy in your app. Same pattern for 402 usage_limit_reached and 404 no_route (different shapes — see Phase 2).

// After fetch to /resolve — always parse JSON on non-2xx; do not classify from err.message alone.
const res = await fetch(resolveUrl, { method: 'POST', headers, body: JSON.stringify({ environmentId, routeId }) });
const body = await res.json().catch(() => ({} as Record<string, unknown>));
if (!res.ok) {
  const code = typeof body.error === 'string' ? body.error : 'unknown';
  const violations = Array.isArray(body.violations) ? body.violations : [];
  if (res.status === 403 && code === 'policy_blocked') {
    // Classify by violations[].type: model_allowlist, budget_cap, token_cap, deprecated_model_block, …
    console.error('[restormel] policy_blocked', violations); // detail for logs; user-facing message separate
  }
  if (code === 'usage_limit_reached') { /* 402 + body.data.limit/used */ }
  if (code === 'no_route') { /* 404 */ }
  // App legacy fallback (non-Restormel routing) — not the same as Restormel route-step fallback
  return legacyResolve();
}

App legacy fallback (Phase 2) remains appropriate when resolve fails; that is separate from Restormel trying the next route step inside one resolve call.