@mastra/core/dist/agent-builder/ee/allowlist.d.ts

Mastra is a framework for building AI-powered applications and agents with a modern TypeScript stack.

import type { ModelCandidate, ModelCandidateInput } from './normalize-candidate.js';
import type { ProviderModelEntry } from './types.js';
/**
 * Candidate model to check against the allowlist.
 * Caller is responsible for normalizing the source shape via {@link toModelCandidates}
 * (in `./normalize-candidate.ts`) before reaching this matcher.
 */
export interface ModelMatchCandidate {
    provider: string;
    modelId: string;
}
/**
 * Single-entry match: provider equality (case-sensitive). When the entry omits
 * `modelId` it matches every model under that provider (provider wildcard).
 *
 * Custom (`kind: 'custom'`) entries match by exact provider string. Known-provider
 * entries match by exact provider string too — the typed surface is purely a
 * compile-time guard.
 */
export declare function matchesProvider(entry: ProviderModelEntry, candidate: ModelMatchCandidate): boolean;
/**
 * Returns `true` if the candidate is allowed under the given allowlist.
 *
 * Rules:
 * - `undefined` allowlist ⇒ unrestricted (always `true`).
 * - `[]` empty allowlist ⇒ unrestricted (always `true`).
 * - Non-empty allowlist where **every** entry's provider is unknown to the
 *   runtime registry AND not tagged `kind: 'custom'` ⇒ deny everything. This
 *   prevents typos (e.g. `openaii`) from acting as an unintended deny-all that
 *   silently allows anything else; it is the documented "deny vs ignore" rule.
 */
export declare function isModelAllowed(allowed: ProviderModelEntry[] | undefined, candidate: ModelMatchCandidate): boolean;
/**
 * Result of an allowlist enforcement check.
 *
 * `attempted` is the candidate (or list of candidates) that triggered the
 * decision; `offendingLabel` (when set) names the specific failing entry so
 * callers can surface it in error messages — particularly useful for
 * conditional model variants.
 */
export type EnforceModelAllowlistResult = {
    ok: true;
} | {
    ok: false;
    attempted: ModelCandidate;
    offendingLabel: string;
};
/**
 * Apply an allowlist to any supported model expression. Normalizes via
 * `toModelCandidates`, then runs `isModelAllowed` per candidate. Returns the
 * **first** failing candidate so error messages can pinpoint which variant of
 * a conditional / fallback list violated the policy.
 *
 * If `toModelCandidates` returns no candidates (dynamic function, unparsable
 * shape) this passes — runtime defense (Phase 7) handles those cases.
 */
export declare function enforceModelAllowlist(allowed: ProviderModelEntry[] | undefined, input: ModelCandidateInput): EnforceModelAllowlistResult;
/**
 * Convenience wrapper around `enforceModelAllowlist` that throws
 * `ModelNotAllowedError` on rejection. Use at write call sites so the server
 * adapter can translate into HTTP 422 + structured body.
 */
export declare function assertModelAllowed(allowed: ProviderModelEntry[] | undefined, input: ModelCandidateInput): void;
//# sourceMappingURL=allowlist.d.ts.map