Configuration

function defineConfig(config: TrustConfig): TrustConfig

import { defineConfig, loadConfig } from "usertrust";

// A partial literal does not compile: TrustConfig is the resolved type,
// so every defaulted field is required. Validate a partial object at
// runtime with loadConfig() instead — overrides merge on top of the file.
const config = await loadConfig({
  budget: 100_000,
  tier: "pro",
  pii: "block",
  circuitBreaker: { failureThreshold: 3, resetTimeout: 30_000 },
});

// defineConfig() type-checks a fully resolved object; IDE shows errors for
// invalid values (tier: "gold") and for missing fields.
const checked = defineConfig({ ...config, tier: "ultra" });

async function loadConfig(
  overrides?: Partial<TrustConfig>,
  vaultBase?: string
): Promise<TrustConfig>

const RateSchema = z.object({
  inputPer1k: z.number().finite().nonnegative(),
  outputPer1k: z.number().finite().nonnegative(),
  cacheReadPer1k: z.number().finite().nonnegative().optional(),
  cacheWritePer1k: z.number().finite().nonnegative().optional(),
  cacheWrite1hPer1k: z.number().finite().nonnegative().optional(),
});

const TrustConfigSchema = z.object({
  budget: z.number().int().positive(),
  tier: z.enum(["free", "mini", "pro", "mega", "ultra"]).default("mini"),
  proxy: z.string().url().optional(),
  key: z.string().optional(),
  parentUserId: z.string().superRefine((value, ctx) => {
    const refusal = parentUserIdRefusal(value);
    if (refusal !== null) ctx.addIssue(`parentUserId ${refusal}`);
  }).optional(),
  scope: z.array(z.string().regex(/^[a-zA-Z0-9._@:+/-]{1,128}$/)).max(32).optional(),
  policies: z.string().default("./policies/default.yml"),
  pii: z.enum(["redact", "warn", "block", "off"]).default("warn"),
  injection: z.enum(["block", "warn", "off"]).default("warn"),
  board: z.object({
    enabled: z.boolean().default(false),
    vetoThreshold: z.enum(["low", "medium", "high", "critical"]).default("high"),
  }).prefault({}),
  circuitBreaker: z.object({
    failureThreshold: z.number().int().default(5),
    resetTimeout: z.number().int().default(60_000),
  }).prefault({}),
  patterns: z.object({
    enabled: z.boolean().default(true),
    feedProxy: z.boolean().default(false),
  }).prefault({}),
  audit: z.object({
    rotation: z.enum(["daily", "weekly", "none"]).default("daily"),
    indexLimit: z.number().int().default(10_000),
    failClosed: z.boolean().default(false),
  }).prefault({}),
  tigerbeetle: z.object({
    addresses: z.array(z.string()).default(["127.0.0.1:3001"]),
    clusterId: z.number().int().nonnegative().default(0),
    connectTimeoutMs: z.number().int().positive().default(5_000),
  }).prefault({}),
  providers: z.array(z.object({
    name: z.string(),
    models: z.array(z.string()).default([]),
  })).default([]),
  pricing: z.enum(["recommended", "custom"]).default("recommended"),
  customRates: z.record(z.string(), RateSchema).optional(),
  endpoints: z.array(z.object({
    match: z.string().min(1),
    class: z.enum(["local", "cloud"]).default("local"),
    runtime: z.enum(["ollama", "vllm", "lmstudio", "openai-compat", "unknown"]).default("unknown"),
  })).default([]),
  local: z.object({
    autoDetectLoopback: z.boolean().default(true),
    defaultRate: RateSchema.default({ inputPer1k: 0, outputPer1k: 0 }),
    rateClass: z.enum(["nominal", "amortized-usd"]).default("nominal"),
    models: z.record(z.string(), RateSchema).default({}),
    injectUsageOptions: z.boolean().default(true),
  }).prefault({}),
  cloud: z.object({
    injectUsageOptions: z.boolean().default(true),
  }).prefault({}),
  unknownModelPolicy: z.enum(["fallback", "warn", "deny"]).default("warn"),
  supplyChain: z.object({
    enabled: z.boolean().default(true),
    trustedPublishers: z.array(z.string()).default([]),
    publisherKeys: z.record(z.string(), z.array(z.string().regex(/^[a-f0-9]{64}$/))).default({}),
    allowedPermissions: z.array(z.enum([
      "llm_call", "tool_use", "file_read", "file_write",
      "shell_command", "network_access", "credential_access",
    ])).default(["llm_call", "tool_use", "file_read"]),
    requireSignature: z.boolean().default(true),
  }).prefault({}),
  vault: z.object({
    enabled: z.boolean().default(false),
    masterKeyEnv: z.string().default("USERTRUST_VAULT_KEY"),
    auditAccess: z.boolean().default(true),
    defaultScope: z.object({
      agents: z.array(z.string()).default([]),
      actions: z.array(z.enum([
        "llm_call", "tool_use", "file_access", "shell_command", "api_request",
      ])).default([]),
      expiresAt: z.string().datetime().nullable().default(null),
    }).prefault({}),
  }).prefault({}),
  anomaly: z.object({
    enabled: z.boolean().default(false),
    tokenRate: z.object({
      thresholdTokPerSec: z.number().positive().default(500),
      localThresholdTokPerSec: z.number().positive().default(5000),
      perModel: z.record(z.string(), z.number().positive()).default({}),
      windowMs: z.number().int().positive().default(2_000),
      consecutiveWindows: z.number().int().positive().default(3),
    }).prefault({}),
    spendVelocity: z.object({
      thresholdDollarsPerMin: z.number().positive().default(1.0),
      localThresholdUsertokensPerMin: z.number().positive().default(10_000),
      windowMs: z.number().int().positive().default(10_000),
    }).prefault({}),
    injectionCascade: z.object({
      eventCount: z.number().int().positive().default(3),
      windowMs: z.number().int().positive().default(60_000),
    }).prefault({}),
    cooldownMs: z.number().int().nonnegative().default(30_000),
  }).prefault({}),
});

{
  "budget": 100000,
  "tier": "pro",
  "pii": "block",
  "policies": "./policies/default.yml",
  "circuitBreaker": {
    "failureThreshold": 3,
    "resetTimeout": 30000
  },
  "patterns": {
    "enabled": true,
    "feedProxy": false
  },
  "audit": {
    "rotation": "daily",
    "indexLimit": 10000
  },
  "tigerbeetle": {
    "addresses": ["127.0.0.1:3001"],
    "clusterId": 0,
    "connectTimeoutMs": 5000
  }
}

{
  "remote": { "kit": true }
}