Data Sovereignty

⚠️

Roadmap item — dataSovereigntyPack is not yet shipped in @veridex/agent-security. The tool-level piiTags field described below is live and already respected by custom packs, but the out-of-the-box jurisdictional pack is still in design. Use the pattern shown here to plan integrations; approximate enforcement today with secretDetectionPack plus a hand-rolled SecurityPack.

The Veridex agent framework is designed to detect PII in tool arguments and enforce jurisdictional transfer rules, helping teams align with GDPR, CCPA, PIPEDA, and other data protection regulations.

Overview

Data sovereignty enforcement works at two levels:

Tool-level PII tagging — Declare which PII categories each tool exposes via ppiTags on ToolContract
Security gateway evaluation — The dataSovereigntyPack in @veridex/agent-security detects PII in tool arguments and evaluates jurisdictional rules

⚠️

PII tagging on tools is advisory — it helps the security gateway focus its evaluation. The gateway also performs independent PII detection via regex patterns and heuristics.

Tagging Tools with PII Categories

import { tool } from '@veridex/agents';
import { z } from 'zod';
 
const userLookup = tool({
  name: 'lookup_user',
  description: 'Look up user profile by ID',
  input: z.object({ userId: z.string() }),
  safetyClass: 'read',
  ppiTags: ['name', 'email', 'address', 'phone'],
  async execute({ input }) {
    return { success: true, llmOutput: `User ${input.userId}: ...` };
  },
});

Supported PII Categories

Category	Examples
`email`	Email addresses
`phone`	Phone numbers
`ssn`	Social security numbers, national IDs
`name`	Full names, first/last names
`address`	Physical addresses
`dob`	Dates of birth
`financial`	Bank accounts, card numbers
`health`	Medical records, diagnoses
`biometric`	Fingerprints, face data

Configuring Jurisdictional Rules

import { dataSovereigntyPack } from '@veridex/agent-security';
 
const sovereignty = dataSovereigntyPack({
  defaultJurisdiction: 'US',
  piiCategories: ['email', 'phone', 'ssn', 'name', 'address', 'dob', 'financial'],
  jurisdictionRules: [
    {
      from: 'EU',
      to: 'US',
      verdict: 'block',
      reason: 'GDPR prohibits PII transfer to US without adequacy decision',
      regulations: ['GDPR Art. 44-49'],
    },
    {
      from: 'EU',
      to: 'UK',
      verdict: 'allow',
      reason: 'UK has GDPR adequacy decision',
      regulations: ['GDPR Art. 45'],
    },
    {
      from: 'CA',
      to: '*',
      verdict: 'flag',
      reason: 'PIPEDA requires consent for cross-border PII transfer',
      regulations: ['PIPEDA Principle 4.1.3'],
    },
  ],
  toolJurisdictions: {
    'store_in_eu_db': 'EU',
    'send_to_us_api': 'US',
    'log_to_ca_service': 'CA',
  },
});

Sovereignty Violation Flow

Tool Call

Agent invokes a tool that handles PII (detected via ppiTags or pattern matching).

Jurisdiction Check

The security gateway determines the source jurisdiction (tool tag or default) and destination jurisdiction (target tool or service).

Rule Evaluation

Jurisdictional rules are evaluated. If a cross-border transfer violates a rule, a violation is generated.

Verdict

Depending on the rule verdict (block, flag, or allow), the tool call is blocked, flagged for review, or allowed.

Audit

Violations are recorded as SovereigntyViolationSummary events in the trace and forwarded to the relayer for audit.

Sovereignty Violations in Runtime

The agent runtime automatically detects sovereignty violations and emits them as trace events:

interface SovereigntyViolationSummary {
  runId: string;
  agentId: string;
  turnIndex: number;
  toolName: string;
  piiCategories: string[];
  fromJurisdiction: string;
  toJurisdiction: string;
  regulation: string;
  timestamp: number;
}

Listen for violations:

agent.events.on('sovereignty_violation', (violation) => {
  console.log(`PII violation: ${violation.piiCategories.join(', ')}`);
  console.log(`${violation.fromJurisdiction} → ${violation.toJurisdiction}`);
  console.log(`Regulation: ${violation.regulation}`);
});

Integration with Security Gateway

For agents using the standalone security gateway:

import { SecurityGateway, dataSovereigntyPack } from '@veridex/agent-security';
 
const gateway = new SecurityGateway({
  packs: [
    dataSovereigntyPack({ /* config */ }),
    // ... other packs
  ],
});
 
const result = await gateway.evaluate({
  type: 'tool_call',
  toolName: 'send_to_us_api',
  arguments: { email: 'user@example.com', name: 'John Doe' },
  agentId: 'data-agent',
});
 
if (result.overall === 'block') {
  // PII transfer blocked by sovereignty rules
}

Agent Security — Security gateway
Governance: Sovereignty Compliance — Audit trail
Security: Data Sovereignty — Policy reference
API Reference — Configuration types

Agent Integrity & Response Seals Examples