@agentguard-run/spend 0.5.0 → 0.6.1

package/src/middleware/provider-registry.ts

@@ -0,0 +1,293 @@
+import type {
+  ComplianceProvenance,
+  HostingProvenance,
+  JurisdictionCountry,
+  ModelIdentity,
+  ProvenanceProvider,
+  WeightsOriginCountry,
+} from '../receipts/schema';
+
+export interface ProviderRouteInfo {
+  provider: ProvenanceProvider;
+  weights_origin_country: WeightsOriginCountry;
+  available_jurisdictions: string[];
+  baa_path: string | null;
+  hipaa_eligible: boolean;
+  zdr_available: boolean;
+  default_retention_days: number | null;
+  foreign_origin?: boolean;
+}
+
+export interface ProviderRegistryRequest {
+  url?: string;
+  provider?: string;
+  providerRoute?: string;
+  model?: string;
+}
+
+export interface ProviderRegistryConfig {
+  providerRoute?: string;
+  jurisdictionCountry?: JurisdictionCountry;
+  jurisdictionRegion?: string;
+  baaInForce?: boolean;
+  baaVendor?: string | null;
+  dataRetentionDays?: number | null;
+  dataResidencyAttested?: boolean;
+  foreignOriginConsentReceiptId?: string | null;
+  inferenceBilling?: 'agentguard_managed' | 'customer_managed';
+  inferenceBillingDetail?: ComplianceProvenance['inference_billing_detail'];
+}
+
+export const PROVIDER_REGISTRY: Record<string, ProviderRouteInfo> = {
+  'anthropic-direct': {
+    provider: 'anthropic',
+    weights_origin_country: 'US',
+    available_jurisdictions: ['US'],
+    baa_path: 'Anthropic Enterprise Messages API with BAA eligible routing',
+    hipaa_eligible: true,
+    zdr_available: true,
+    default_retention_days: 0,
+  },
+  'aws-bedrock': {
+    provider: 'anthropic',
+    weights_origin_country: 'US',
+    available_jurisdictions: ['us-east-1', 'us-east-2', 'us-west-2', 'eu-west-1', 'eu-central-1', 'ap-northeast-1'],
+    baa_path: 'AWS BAA for Bedrock HIPAA eligible services',
+    hipaa_eligible: true,
+    zdr_available: true,
+    default_retention_days: 0,
+  },
+  'azure-openai': {
+    provider: 'openai',
+    weights_origin_country: 'US',
+    available_jurisdictions: ['eastus', 'westus', 'westeurope', 'francecentral', 'switzerlandnorth'],
+    baa_path: 'Microsoft Product Terms DPA',
+    hipaa_eligible: true,
+    zdr_available: true,
+    default_retention_days: 0,
+  },
+  'openai-direct': {
+    provider: 'openai',
+    weights_origin_country: 'US',
+    available_jurisdictions: ['US'],
+    baa_path: 'OpenAI Enterprise BAA with eligible API configuration',
+    hipaa_eligible: true,
+    zdr_available: true,
+    default_retention_days: 30,
+  },
+  'vertex-ai': {
+    provider: 'google',
+    weights_origin_country: 'US',
+    available_jurisdictions: ['us-central1', 'us-east4', 'europe-west4', 'europe-west1', 'asia-northeast1'],
+    baa_path: 'Google Cloud BAA',
+    hipaa_eligible: true,
+    zdr_available: true,
+    default_retention_days: 0,
+  },
+  fireworks: {
+    provider: 'fireworks',
+    weights_origin_country: 'unknown',
+    available_jurisdictions: ['US'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+  },
+  baseten: {
+    provider: 'baseten',
+    weights_origin_country: 'unknown',
+    available_jurisdictions: ['US'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+  },
+  together: {
+    provider: 'together',
+    weights_origin_country: 'unknown',
+    available_jurisdictions: ['US'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+  },
+  'moonshot-direct': {
+    provider: 'moonshot',
+    weights_origin_country: 'CN',
+    available_jurisdictions: ['CN'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+    foreign_origin: true,
+  },
+  'deepseek-direct': {
+    provider: 'deepseek',
+    weights_origin_country: 'CN',
+    available_jurisdictions: ['CN'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+    foreign_origin: true,
+  },
+  'alibaba-direct': {
+    provider: 'alibaba',
+    weights_origin_country: 'CN',
+    available_jurisdictions: ['CN'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+    foreign_origin: true,
+  },
+  'kimi-k2-on-baseten': {
+    provider: 'baseten',
+    weights_origin_country: 'CN',
+    available_jurisdictions: ['US'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+    foreign_origin: true,
+  },
+  'deepseek-on-together': {
+    provider: 'together',
+    weights_origin_country: 'CN',
+    available_jurisdictions: ['US'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+    foreign_origin: true,
+  },
+  'qwen-on-together': {
+    provider: 'together',
+    weights_origin_country: 'CN',
+    available_jurisdictions: ['US'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: false,
+    default_retention_days: 30,
+    foreign_origin: true,
+  },
+  'self-hosted': {
+    provider: 'self_hosted',
+    weights_origin_country: 'unknown',
+    available_jurisdictions: ['self-hosted'],
+    baa_path: null,
+    hipaa_eligible: false,
+    zdr_available: true,
+    default_retention_days: 0,
+  },
+};
+
+const FOREIGN_ORIGIN_PATTERNS = [/kimi/i, /deepseek/i, /qwen/i, /yi[-_ ]/i, /baichuan/i, /glm/i, /moonshot/i];
+
+export function isForeignOriginModel(model: string): boolean {
+  return FOREIGN_ORIGIN_PATTERNS.some((pattern) => pattern.test(model));
+}
+
+export function inferProviderRoute(req: ProviderRegistryRequest): string {
+  const model = String(req.model || '').toLowerCase();
+  const url = String(req.url || '').toLowerCase();
+  if ((req.providerRoute === 'baseten' || url.includes('baseten')) && /kimi/.test(model)) return 'kimi-k2-on-baseten';
+  if ((req.providerRoute === 'together' || url.includes('together')) && /deepseek/.test(model)) return 'deepseek-on-together';
+  if ((req.providerRoute === 'together' || url.includes('together')) && /qwen/.test(model)) return 'qwen-on-together';
+  if (req.providerRoute && PROVIDER_REGISTRY[req.providerRoute]) return req.providerRoute;
+  if (url.includes('bedrock') || req.provider === 'bedrock') return 'aws-bedrock';
+  if (url.includes('anthropic') || req.provider === 'anthropic') return 'anthropic-direct';
+  if (url.includes('azure') || url.includes('openai.azure')) return 'azure-openai';
+  if (url.includes('aiplatform.googleapis') || url.includes('vertex')) return 'vertex-ai';
+  if (url.includes('fireworks') || req.providerRoute === 'fireworks') return 'fireworks';
+  if (url.includes('baseten') || req.providerRoute === 'baseten') return 'baseten';
+  if (url.includes('together') || req.providerRoute === 'together') return 'together';
+  if (url.includes('moonshot') || /kimi/.test(model)) return 'moonshot-direct';
+  if (url.includes('deepseek') || /deepseek/.test(model)) return 'deepseek-direct';
+  if (url.includes('dashscope') || url.includes('alibaba') || /qwen/.test(model)) return 'alibaba-direct';
+  if (req.provider === 'openai') return 'openai-direct';
+  if (req.provider === 'gemini') return 'vertex-ai';
+  return 'self-hosted';
+}
+
+export function inferModelIdentity(model: string, route: string): ModelIdentity {
+  const info = PROVIDER_REGISTRY[route] ?? PROVIDER_REGISTRY['self-hosted'];
+  const modelId = model || 'unknown';
+  return {
+    provider: modelProvider(modelId, info.provider),
+    model_id: modelId,
+    model_version: modelVersion(modelId),
+    model_family: modelFamily(modelId),
+    weights_origin_country: isForeignOriginModel(modelId) || info.foreign_origin ? 'CN' : info.weights_origin_country,
+  };
+}
+
+export function inferHosting(route: string, config: ProviderRegistryConfig = {}): HostingProvenance {
+  const info = PROVIDER_REGISTRY[route] ?? PROVIDER_REGISTRY['self-hosted'];
+  const region = config.jurisdictionRegion || info.available_jurisdictions[0] || 'unknown';
+  return {
+    provider_route: route,
+    jurisdiction_country: config.jurisdictionCountry || countryFromRegion(region),
+    jurisdiction_region: region,
+  };
+}
+
+export function inferCompliance(route: string, model: ModelIdentity, config: ProviderRegistryConfig = {}): ComplianceProvenance {
+  const info = PROVIDER_REGISTRY[route] ?? PROVIDER_REGISTRY['self-hosted'];
+  const retention = config.dataRetentionDays !== undefined ? config.dataRetentionDays : info.default_retention_days;
+  return {
+    baa_in_force: config.baaInForce ?? false,
+    baa_vendor: config.baaVendor ?? info.baa_path,
+    hipaa_eligible: info.hipaa_eligible,
+    data_retention_days: retention,
+    data_residency_attested: config.dataResidencyAttested ?? false,
+    foreign_origin_weight_flag: model.weights_origin_country === 'CN' || info.foreign_origin === true,
+    foreign_origin_consent_receipt_id: config.foreignOriginConsentReceiptId ?? null,
+    inference_billing: config.inferenceBilling ?? 'customer_managed',
+    inference_billing_detail: config.inferenceBilling === 'agentguard_managed' ? config.inferenceBillingDetail ?? null : null,
+  };
+}
+
+function modelProvider(model: string, fallback: ProvenanceProvider): ProvenanceProvider {
+  const lower = model.toLowerCase();
+  if (lower.includes('claude')) return 'anthropic';
+  if (lower.includes('gpt') || lower.includes('openai')) return 'openai';
+  if (lower.includes('gemini')) return 'google';
+  if (lower.includes('mistral')) return 'mistral';
+  if (lower.includes('llama')) return 'meta';
+  if (lower.includes('command')) return 'cohere';
+  if (lower.includes('deepseek')) return 'deepseek';
+  if (lower.includes('kimi') || lower.includes('moonshot')) return 'moonshot';
+  if (lower.includes('qwen') || lower.includes('yi') || lower.includes('baichuan') || lower.includes('glm')) return 'alibaba';
+  return fallback;
+}
+
+function modelVersion(model: string): string {
+  const match = model.match(/(?:^|[-_])(20\d{6}|\d{8})(?:$|[-_])/);
+  return match?.[1] ?? 'unknown';
+}
+
+function modelFamily(model: string): string {
+  const lower = model.toLowerCase();
+  if (lower.includes('claude')) return 'claude';
+  if (lower.includes('gpt')) return 'gpt';
+  if (lower.includes('gemini')) return 'gemini';
+  if (lower.includes('llama-4') || lower.includes('llama4')) return 'llama-4';
+  if (lower.includes('mistral')) return 'mistral';
+  if (lower.includes('kimi')) return 'kimi';
+  if (lower.includes('deepseek')) return 'deepseek';
+  if (lower.includes('qwen')) return 'qwen';
+  return lower.split(/[/:_]/).pop()?.split('-').slice(0, 2).join('-') || 'unknown';
+}
+
+function countryFromRegion(region: string): JurisdictionCountry {
+  const lower = region.toLowerCase();
+  if (lower.startsWith('us') || lower.includes('eastus') || lower.includes('westus')) return 'US';
+  if (lower.startsWith('eu') || lower.includes('europe') || lower.includes('france') || lower.includes('switzerland')) return 'EU';
+  if (lower.startsWith('uk')) return 'UK';
+  if (lower.startsWith('ca')) return 'CA';
+  if (lower.startsWith('cn')) return 'CN';
+  if (lower.startsWith('ap-northeast') || lower.includes('tokyo') || lower.includes('japan')) return 'JP';
+  if (lower.startsWith('ap-southeast-2') || lower.includes('australia')) return 'AU';
+  return 'unknown';
+}

package/src/posture/enforce.ts

@@ -0,0 +1,87 @@
+import * as http from 'http';
+import * as https from 'https';
+import type { ProvenanceBlock } from '../receipts/schema';
+
+export type GovernancePosture = 'velocity' | 'standard' | 'compliance';
+
+export interface ComplianceEnforcementConfig {
+  posture?: GovernancePosture;
+  foreignOriginConsentReceiptId?: string | null;
+  consentEndpointBaseUrl?: string;
+  consentGetJson?: (url: string) => Promise<unknown>;
+}
+
+export class AgentGuardComplianceError extends Error {
+  code = 'AGENTGUARD_COMPLIANCE_BLOCK';
+  constructor(message: string) {
+    super(message);
+    this.name = 'AgentGuardComplianceError';
+  }
+}
+
+export class AgentGuardConsentRequiredError extends Error {
+  code = 'AGENTGUARD_CONSENT_REQUIRED';
+  constructor(message: string) {
+    super(message);
+    this.name = 'AgentGuardConsentRequiredError';
+  }
+}
+
+const DEFAULT_CONSENT_BASE_URL = 'https://agentguard.run';
+
+export async function enforceCompliance(
+  provenance: ProvenanceBlock,
+  config: ComplianceEnforcementConfig = {},
+): Promise<void> {
+  if (!provenance.compliance.foreign_origin_weight_flag) return;
+  const posture = config.posture ?? 'standard';
+  if (posture === 'compliance') {
+    throw new AgentGuardComplianceError(
+      'Foreign origin weights are blocked in compliance posture. Set posture to standard and provide foreign_origin_consent_receipt_id to use this model.',
+    );
+  }
+  if (posture !== 'standard') return;
+  const consentId = config.foreignOriginConsentReceiptId || provenance.compliance.foreign_origin_consent_receipt_id;
+  if (!consentId) {
+    throw new AgentGuardConsentRequiredError(
+      'This call uses foreign origin weights. Generate a consent receipt at https://agentguard.run/dashboard/consent/foreign-origin-weights before using this model.',
+    );
+  }
+  const verified = await verifyConsentReceipt(consentId, config);
+  if (!verified) {
+    throw new AgentGuardConsentRequiredError(`Foreign origin consent receipt ${consentId} is invalid or expired.`);
+  }
+}
+
+export async function verifyConsentReceipt(
+  consentId: string,
+  config: ComplianceEnforcementConfig = {},
+): Promise<boolean> {
+  if (!/^ag_consent_[A-Za-z0-9_-]+$/.test(consentId)) return false;
+  const base = (config.consentEndpointBaseUrl || DEFAULT_CONSENT_BASE_URL).replace(/\/$/, '');
+  const raw = await (config.consentGetJson ?? getJson)(`${base}/api/consent/verify/${encodeURIComponent(consentId)}`);
+  return Boolean(raw && typeof raw === 'object' && (raw as { valid?: unknown }).valid === true);
+}
+
+function getJson(url: string): Promise<unknown> {
+  if (url.startsWith('mock://')) return Promise.resolve({ valid: true });
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const client = parsed.protocol === 'http:' ? http : https;
+    const req = client.request(
+      { method: 'GET', hostname: parsed.hostname, port: parsed.port, path: parsed.pathname + parsed.search, timeout: 5000 },
+      (res) => {
+        const chunks: Buffer[] = [];
+        res.on('data', (chunk: Buffer) => chunks.push(chunk));
+        res.on('end', () => {
+          const text = Buffer.concat(chunks).toString('utf8');
+          if ((res.statusCode ?? 0) >= 400) return reject(new Error(`consent endpoint failed: ${res.statusCode}`));
+          try { resolve(text ? JSON.parse(text) : {}); } catch { resolve({}); }
+        });
+      },
+    );
+    req.on('error', reject);
+    req.on('timeout', () => req.destroy(new Error('consent endpoint timed out')));
+    req.end();
+  });
+}

package/src/receipts/schema.ts

@@ -0,0 +1,91 @@
+import type { ReceiptV2 } from '../workflow/types';
+
+export type ProvenanceProvider =
+  | 'anthropic'
+  | 'openai'
+  | 'google'
+  | 'mistral'
+  | 'meta'
+  | 'cohere'
+  | 'fireworks'
+  | 'baseten'
+  | 'together'
+  | 'deepseek'
+  | 'moonshot'
+  | 'alibaba'
+  | 'self_hosted'
+  | 'unknown';
+
+export type WeightsOriginCountry = 'US' | 'EU' | 'UK' | 'CA' | 'CN' | 'unknown';
+export type JurisdictionCountry = 'US' | 'EU' | 'UK' | 'CA' | 'CN' | 'AU' | 'JP' | 'unknown';
+
+export interface ModelIdentity {
+  provider: ProvenanceProvider;
+  model_id: string;
+  model_version: string;
+  model_family: string;
+  weights_origin_country: WeightsOriginCountry;
+}
+
+export interface HostingProvenance {
+  provider_route: string;
+  jurisdiction_country: JurisdictionCountry;
+  jurisdiction_region: string;
+}
+
+export interface ComplianceInferenceBillingDetail {
+  via: 'openrouter_key' | 'openrouter_workspace';
+  workspace_id?: string | null;
+  key_hash?: string | null;
+  tier: 'solo_pro' | 'startup_pro' | 'growth_pro';
+  guardrails_active: string[];
+}
+
+export interface ComplianceProvenance {
+  baa_in_force: boolean;
+  baa_vendor: string | null;
+  hipaa_eligible: boolean;
+  data_retention_days: number | null;
+  data_residency_attested: boolean;
+  foreign_origin_weight_flag: boolean;
+  foreign_origin_consent_receipt_id: string | null;
+  inference_billing: 'agentguard_managed' | 'customer_managed';
+  inference_billing_detail?: ComplianceInferenceBillingDetail | null;
+}
+
+export interface ProvenanceBlock {
+  model_identity: ModelIdentity;
+  hosting: HostingProvenance;
+  compliance: ComplianceProvenance;
+  captured_at: string;
+}
+
+export interface ReceiptV1 {
+  receipt_id: string;
+  schema_version?: 1;
+  signature?: string;
+  [key: string]: unknown;
+}
+
+export type ReceiptV3 = Omit<ReceiptV2, 'schema_version'> & {
+  schema_version: 3;
+  provenance: ProvenanceBlock;
+};
+
+export type AnyReceipt = ReceiptV1 | ReceiptV2 | ReceiptV3;
+
+export function receiptSchemaVersion(receipt: unknown): 1 | 2 | 3 {
+  if (!receipt || typeof receipt !== 'object') throw new Error('Receipt must be an object');
+  const raw = (receipt as { schema_version?: unknown }).schema_version;
+  if (raw === undefined || raw === 1) return 1;
+  if (raw === 2 || raw === 3) return raw;
+  throw new Error(`Unsupported receipt schema_version: ${String(raw)}`);
+}
+
+export function isReceiptV3(receipt: unknown): receipt is ReceiptV3 {
+  return receiptSchemaVersion(receipt) === 3 && Boolean((receipt as { provenance?: unknown }).provenance);
+}
+
+export function assertReceiptV3(receipt: unknown): asserts receipt is ReceiptV3 {
+  if (!isReceiptV3(receipt)) throw new Error('Receipt schema v3 requires a provenance block');
+}

package/src/workflow/receipt.ts

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from 'crypto';
 import { canonicalJson, sha256Hex } from '../decision-log';
-import type { ReceiptV2, ReviewerCascadeEvidence } from './types';
+import type { ProvenanceBlock } from '../receipts/schema';
+import type { ReceiptV2, ReceiptV3, ReviewerCascadeEvidence } from './types';
 
 export function canonicalJSONStringify(value: unknown): string {
   return canonicalJson(value);
@@ -14,7 +15,7 @@ export function workflowReceiptId(prefix = 'ag_r'): string {
   return `${prefix}_${randomUUID().replace(/-/g, '').slice(0, 16)}`;
 }
 
-export function signReceiptPayload(payload: Omit<ReceiptV2, 'signature'>): string {
+export function signReceiptPayload(payload: unknown): string {
   return sha256Hex(canonicalJson(payload));
 }
 
@@ -63,6 +64,39 @@ export function buildReceipt(args: {
   return { ...unsigned, signature: signReceiptPayload(unsigned) };
 }
 
+
+
+export function buildReceiptV3(args: {
+  workflow_id: string | null;
+  outcome_name: string;
+  user_id: string;
+  cost_usd: number;
+  parent_receipt_id: string | null;
+  chain_validation_hash: string | null;
+  workflow_checkpoint_idx: number | null;
+  workflow_total_spend_usd_to_date: number | null;
+  provenance: ProvenanceBlock;
+  is_checkpoint?: boolean;
+  checkpoint_label?: string | null;
+  reviewer_cascade?: ReviewerCascadeEvidence | null;
+  receipt_type?: ReceiptV2['receipt_type'];
+  cancelled_reason?: string | null;
+}): ReceiptV3 {
+  const v2 = buildReceipt(args);
+  const unsigned: Omit<ReceiptV3, 'signature'> = {
+    ...v2,
+    schema_version: 3,
+    provenance: args.provenance,
+  };
+  const { signature: _oldSignature, ...withoutSignature } = unsigned as Omit<ReceiptV3, 'signature'> & { signature?: string };
+  return { ...withoutSignature, signature: signReceiptPayload(withoutSignature) };
+}
+
+export function verifyAnyReceipt(receipt: ReceiptV2 | ReceiptV3): boolean {
+  const { signature: _signature, ...unsigned } = receipt;
+  return signReceiptPayload(unsigned) === receipt.signature;
+}
+
 export function verifyReceipt(receipt: ReceiptV2): boolean {
   const { signature: _signature, ...unsigned } = receipt;
   return signReceiptPayload(unsigned) === receipt.signature;

package/src/workflow/types.ts

@@ -1,3 +1,4 @@
+import type { ProvenanceBlock } from '../receipts/schema';
 export type WorkflowState =
   | 'active'
   | 'paused'
@@ -86,3 +87,9 @@ export interface ValidationFailure {
 }
 
 export type ChainValidationResult = ValidationResult | ValidationFailure;
+
+
+export interface ReceiptV3 extends Omit<ReceiptV2, 'schema_version'> {
+  schema_version: 3;
+  provenance: ProvenanceBlock;
+}