@kya-os/contracts 1.7.20 → 1.7.22

package/dist/policy/schemas.js

@@ -0,0 +1,424 @@
+"use strict";
+/**
+ * Policy Configuration Schemas
+ *
+ * Zod schemas for agent detection policy configuration.
+ * These schemas define how MCP-I servers and AgentShield enforce
+ * access control based on detected agent characteristics.
+ *
+ * @module @kya-os/contracts/policy
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EXAMPLE_CHALLENGE_LOW_REP = exports.EXAMPLE_ALLOW_CHATGPT = exports.EXAMPLE_BLOCK_AI_AGENTS = exports.DEFAULT_POLICY_CONFIG = exports.UpdatePolicyResponseSchema = exports.UpdatePolicyRequestSchema = exports.GetPolicyResponseSchema = exports.GetPolicyRequestSchema = exports.PolicyConfigPartialSchema = exports.PolicyConfigSchema = exports.PolicyRuleSchema = exports.PolicyConditionSchema = exports.AllowListEntrySchema = exports.DenyListEntrySchema = exports.ThresholdConfigSchema = exports.EnforcementActionSchema = void 0;
+exports.validatePolicyConfig = validatePolicyConfig;
+exports.safeParsePolicyConfig = safeParsePolicyConfig;
+exports.validateDenyListEntry = validateDenyListEntry;
+exports.validatePolicyRule = validatePolicyRule;
+const zod_1 = require("zod");
+// ============================================================================
+// Enforcement Actions
+// ============================================================================
+/**
+ * Available enforcement actions
+ *
+ * - `allow` - Allow the request to proceed
+ * - `block` - Block the request (return 403)
+ * - `redirect` - Redirect to a configured URL
+ * - `challenge` - Present a challenge (CAPTCHA, proof-of-work, etc.)
+ * - `log` - Allow but log for monitoring
+ */
+exports.EnforcementActionSchema = zod_1.z.enum([
+    'allow',
+    'block',
+    'redirect',
+    'challenge',
+    'log',
+]);
+// ============================================================================
+// Threshold Configuration
+// ============================================================================
+/**
+ * Threshold-based enforcement settings
+ *
+ * These thresholds determine automatic enforcement based on
+ * detection confidence and reputation scores.
+ */
+exports.ThresholdConfigSchema = zod_1.z.object({
+    /**
+     * Detection confidence threshold (0-100)
+     * Agents detected with confidence >= this value trigger the configured action
+     * @default 80
+     */
+    confidenceThreshold: zod_1.z.number().min(0).max(100).default(80),
+    /**
+     * Action to take when confidence threshold is exceeded
+     * @default 'block'
+     */
+    confidenceAction: exports.EnforcementActionSchema.default('block'),
+    /**
+     * Minimum reputation score (0-100) required to allow access
+     * Agents with reputation < this value may be blocked/challenged
+     * Set to 0 to disable reputation-based enforcement
+     * @default 0
+     */
+    minReputationScore: zod_1.z.number().min(0).max(100).default(0),
+    /**
+     * Action to take when reputation is below threshold
+     * @default 'challenge'
+     */
+    lowReputationAction: exports.EnforcementActionSchema.default('challenge'),
+    /**
+     * High reputation score threshold (0-100)
+     * Agents with reputation >= this value are trusted and bypass other checks
+     * @default 90
+     */
+    trustedReputationThreshold: zod_1.z.number().min(0).max(100).default(90),
+    /**
+     * Whether cryptographically signed requests (MCP-I verified) bypass thresholds
+     * @default true
+     */
+    trustSignedRequests: zod_1.z.boolean().default(true),
+});
+// ============================================================================
+// Deny List Entry
+// ============================================================================
+/**
+ * Entry in the deny list for blocking specific agents
+ *
+ * At least one identifier must be provided: clientDid, agentDid, or clientName
+ */
+exports.DenyListEntrySchema = zod_1.z
+    .object({
+    /** MCP-I client DID (e.g., "did:key:z6Mk...") */
+    clientDid: zod_1.z.string().optional(),
+    /** Agent DID from MCP-I identity */
+    agentDid: zod_1.z.string().optional(),
+    /** Human-readable client name (e.g., "Perplexity", "ChatGPT") */
+    clientName: zod_1.z.string().optional(),
+    /** Agent type to block (e.g., "ai_agent", "bot", "scraper") */
+    agentType: zod_1.z.string().optional(),
+    /** Reason for denial (shown to user/logged) */
+    reason: zod_1.z.string().optional(),
+    /** ISO 8601 timestamp when entry was added */
+    blockedAt: zod_1.z.string().datetime().optional(),
+    /** Who added this entry (user ID or "system") */
+    addedBy: zod_1.z.string().optional(),
+    /** Whether this entry is currently active */
+    active: zod_1.z.boolean().default(true),
+    /** Optional expiration date for temporary blocks */
+    expiresAt: zod_1.z.string().datetime().optional(),
+})
+    .refine((data) => data.clientDid || data.agentDid || data.clientName || data.agentType, 'At least one identifier (clientDid, agentDid, clientName, or agentType) must be provided');
+// ============================================================================
+// Allow List Entry
+// ============================================================================
+/**
+ * Entry in the allow list for exempting specific agents from all checks
+ *
+ * At least one identifier must be provided: clientDid, agentDid, clientName, or agentType
+ */
+exports.AllowListEntrySchema = zod_1.z
+    .object({
+    /** MCP-I client DID (e.g., "did:key:z6Mk...") */
+    clientDid: zod_1.z.string().optional(),
+    /** Agent DID from MCP-I identity */
+    agentDid: zod_1.z.string().optional(),
+    /** Human-readable client name (e.g., "Perplexity", "ChatGPT") */
+    clientName: zod_1.z.string().optional(),
+    /** Agent type to allow (e.g., "ai_agent", "verified_bot") */
+    agentType: zod_1.z.string().optional(),
+    /** Reason for allowing (documentation) */
+    reason: zod_1.z.string().optional(),
+    /** ISO 8601 timestamp when entry was added */
+    addedAt: zod_1.z.string().datetime().optional(),
+    /** Who added this entry */
+    addedBy: zod_1.z.string().optional(),
+})
+    .refine((data) => data.clientDid || data.agentDid || data.clientName || data.agentType, 'At least one identifier (clientDid, agentDid, clientName, or agentType) must be provided');
+// ============================================================================
+// Policy Rule Condition
+// ============================================================================
+/**
+ * Condition for matching requests in a policy rule
+ */
+exports.PolicyConditionSchema = zod_1.z.object({
+    /** Field to match against */
+    field: zod_1.z.enum([
+        // Agent identification
+        'agentType', // 'ai_agent', 'bot', 'automation', 'scraper', etc.
+        'agentName', // Detected agent name (e.g., "ChatGPT", "Claude")
+        'agentVendor', // Agent vendor (e.g., "OpenAI", "Anthropic")
+        'clientDid', // MCP-I client DID
+        'agentDid', // MCP-I agent DID
+        // Detection metrics
+        'confidence', // Detection confidence (0-100)
+        'reputationScore', // Agent reputation score (0-100)
+        'riskLevel', // 'low', 'medium', 'high', 'critical'
+        // Request context
+        'path', // Request path
+        'method', // HTTP method
+        'origin', // Request origin header
+        'userAgent', // User-Agent string
+        // Verification status
+        'signatureVerified', // Whether MCP-I signature was verified (boolean)
+        'isAuthenticated', // Whether agent is authenticated via MCP-I (boolean)
+        'hasValidDelegation', // Whether agent has valid delegation chain (boolean)
+    ]),
+    /** Comparison operator */
+    operator: zod_1.z.enum([
+        'equals',
+        'notEquals',
+        'contains',
+        'notContains',
+        'startsWith',
+        'endsWith',
+        'greaterThan',
+        'lessThan',
+        'greaterThanOrEquals',
+        'lessThanOrEquals',
+        'matches', // Regex match
+        'in', // Value in list
+        'notIn', // Value not in list
+    ]),
+    /** Value to compare against */
+    value: zod_1.z.union([zod_1.z.string(), zod_1.z.number(), zod_1.z.boolean(), zod_1.z.array(zod_1.z.string())]),
+    /** Whether this condition is case-insensitive (for string comparisons) */
+    caseInsensitive: zod_1.z.boolean().optional(),
+});
+// ============================================================================
+// Policy Rule
+// ============================================================================
+/**
+ * A single policy rule that maps conditions to an action
+ */
+exports.PolicyRuleSchema = zod_1.z
+    .object({
+    /** Unique identifier for this rule */
+    id: zod_1.z.string(),
+    /** Human-readable name */
+    name: zod_1.z.string(),
+    /** Description of what this rule does */
+    description: zod_1.z.string().optional(),
+    /** Priority (lower = higher priority, evaluated first) */
+    priority: zod_1.z.number().int().min(0).max(1000).default(100),
+    /**
+     * Conditions that must ALL match for this rule to apply (AND logic)
+     * For OR logic, create multiple rules with same action
+     */
+    conditions: zod_1.z.array(exports.PolicyConditionSchema).min(1),
+    /** Action to take when conditions match */
+    action: exports.EnforcementActionSchema,
+    /** Redirect URL (required if action is 'redirect') */
+    redirectUrl: zod_1.z.string().url().optional(),
+    /** Custom message to show/log */
+    message: zod_1.z.string().optional(),
+    /** Whether this rule is currently active */
+    enabled: zod_1.z.boolean().default(true),
+    /** Metadata for auditing */
+    metadata: zod_1.z
+        .object({
+        createdAt: zod_1.z.string().datetime().optional(),
+        updatedAt: zod_1.z.string().datetime().optional(),
+        createdBy: zod_1.z.string().optional(),
+    })
+        .optional(),
+})
+    .refine((data) => data.action !== 'redirect' || data.redirectUrl, 'redirectUrl is required when action is "redirect"');
+// ============================================================================
+// Policy Configuration
+// ============================================================================
+/**
+ * Base policy configuration object (without refinements)
+ * Used for partial updates where full validation happens after merge
+ */
+const PolicyConfigBaseSchema = zod_1.z.object({
+    /** Schema version for migrations */
+    version: zod_1.z.string().default('1.0.0'),
+    /** Whether policy enforcement is enabled */
+    enabled: zod_1.z.boolean().default(true),
+    /** Default action when no rules match */
+    defaultAction: exports.EnforcementActionSchema.default('allow'),
+    /** Default redirect URL for redirect actions */
+    redirectUrl: zod_1.z.string().url().optional(),
+    /** Threshold-based enforcement settings */
+    thresholds: exports.ThresholdConfigSchema.default({
+        confidenceThreshold: 80,
+        confidenceAction: 'block',
+        minReputationScore: 0,
+        lowReputationAction: 'challenge',
+        trustedReputationThreshold: 90,
+        trustSignedRequests: true,
+    }),
+    /** Deny list entries (checked after allow list, before rules) */
+    denyList: zod_1.z.array(exports.DenyListEntrySchema).default([]),
+    /** Allow list entries (exempt from all checks) */
+    allowList: zod_1.z.array(exports.AllowListEntrySchema).default([]),
+    /** Custom policy rules (evaluated by priority after threshold checks) */
+    rules: zod_1.z.array(exports.PolicyRuleSchema).default([]),
+    /** Paths to exclude from policy enforcement (glob patterns supported) */
+    excludedPaths: zod_1.z.array(zod_1.z.string()).default([]),
+    /** Paths to include (if set, only these paths are enforced) */
+    includedPaths: zod_1.z.array(zod_1.z.string()).optional(),
+    /** Metadata for the policy configuration */
+    metadata: zod_1.z
+        .object({
+        lastUpdated: zod_1.z.string().datetime().optional(),
+        updatedBy: zod_1.z.string().optional(),
+        policyId: zod_1.z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Complete policy configuration for a project
+ *
+ * Policy evaluation order:
+ * 1. Allow list (exempt agents, always allowed)
+ * 2. Deny list (blocked agents, always blocked)
+ * 3. Threshold checks (confidence, reputation)
+ * 4. Custom rules (evaluated by priority, first match wins)
+ * 5. Default action (if no rules match)
+ */
+exports.PolicyConfigSchema = PolicyConfigBaseSchema.refine((data) => data.defaultAction !== 'redirect' || data.redirectUrl, 'redirectUrl is required when defaultAction is "redirect"');
+/** Partial policy config for updates (refinements applied after merge) */
+exports.PolicyConfigPartialSchema = PolicyConfigBaseSchema.partial();
+// ============================================================================
+// API Request/Response Schemas
+// ============================================================================
+/**
+ * Request to get policy configuration
+ */
+exports.GetPolicyRequestSchema = zod_1.z.object({
+    projectId: zod_1.z.string(),
+});
+/**
+ * Response with policy configuration
+ */
+exports.GetPolicyResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    data: zod_1.z.object({
+        policy: exports.PolicyConfigSchema,
+    }),
+    metadata: zod_1.z
+        .object({
+        requestId: zod_1.z.string().optional(),
+        timestamp: zod_1.z.string().datetime().optional(),
+        cachedUntil: zod_1.z.string().datetime().optional(),
+    })
+        .optional(),
+});
+/**
+ * Request to update policy configuration
+ */
+exports.UpdatePolicyRequestSchema = zod_1.z.object({
+    projectId: zod_1.z.string(),
+    policy: exports.PolicyConfigPartialSchema,
+});
+/**
+ * Response after updating policy
+ */
+exports.UpdatePolicyResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    data: zod_1.z.object({
+        policy: exports.PolicyConfigSchema,
+        changes: zod_1.z.array(zod_1.z.string()).optional(),
+    }),
+    metadata: zod_1.z
+        .object({
+        requestId: zod_1.z.string().optional(),
+        timestamp: zod_1.z.string().datetime().optional(),
+    })
+        .optional(),
+});
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate a policy configuration
+ */
+function validatePolicyConfig(data) {
+    return exports.PolicyConfigSchema.parse(data);
+}
+/**
+ * Safely validate a policy configuration (returns result object)
+ */
+function safeParsePolicyConfig(data) {
+    return exports.PolicyConfigSchema.safeParse(data);
+}
+/**
+ * Validate a deny list entry
+ */
+function validateDenyListEntry(data) {
+    return exports.DenyListEntrySchema.parse(data);
+}
+/**
+ * Validate a policy rule
+ */
+function validatePolicyRule(data) {
+    return exports.PolicyRuleSchema.parse(data);
+}
+// ============================================================================
+// Default Policy
+// ============================================================================
+/**
+ * Default policy configuration for new projects
+ */
+exports.DEFAULT_POLICY_CONFIG = {
+    version: '1.0.0',
+    enabled: true,
+    defaultAction: 'allow',
+    thresholds: {
+        confidenceThreshold: 80,
+        confidenceAction: 'block',
+        minReputationScore: 0,
+        lowReputationAction: 'challenge',
+        trustedReputationThreshold: 90,
+        trustSignedRequests: true,
+    },
+    denyList: [],
+    allowList: [],
+    rules: [],
+    excludedPaths: [],
+};
+// ============================================================================
+// Example Policies (for documentation)
+// ============================================================================
+/**
+ * Example: Block high-confidence AI agents
+ */
+exports.EXAMPLE_BLOCK_AI_AGENTS = {
+    id: 'block-ai-agents',
+    name: 'Block AI Agents',
+    description: 'Block requests from AI agents detected with high confidence',
+    priority: 10,
+    conditions: [
+        { field: 'agentType', operator: 'equals', value: 'ai_agent' },
+        { field: 'confidence', operator: 'greaterThanOrEquals', value: 85 },
+    ],
+    action: 'block',
+    message: 'AI agent access is not permitted',
+    enabled: true,
+};
+/**
+ * Example: Allow verified ChatGPT
+ */
+exports.EXAMPLE_ALLOW_CHATGPT = {
+    clientName: 'ChatGPT',
+    reason: 'Verified OpenAI integration',
+    addedAt: new Date().toISOString(),
+};
+/**
+ * Example: Challenge low-reputation agents
+ */
+exports.EXAMPLE_CHALLENGE_LOW_REP = {
+    id: 'challenge-low-rep',
+    name: 'Challenge Low Reputation',
+    description: 'Present challenge to agents with low reputation scores',
+    priority: 50,
+    conditions: [
+        { field: 'reputationScore', operator: 'lessThan', value: 30 },
+        { field: 'signatureVerified', operator: 'equals', value: false },
+    ],
+    action: 'challenge',
+    message: 'Please verify your identity',
+    enabled: true,
+};