@kya-os/contracts 1.5.3-canary.2 → 1.5.3-canary.20

package/src/agentshield-api/schemas.ts

@@ -0,0 +1,304 @@
+/**
+ * AgentShield/Bouncer API Zod Validation Schemas
+ *
+ * Runtime validation schemas matching the API contract types.
+ * These schemas ensure request/response validation before sending/receiving.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+import { z } from "zod";
+import { DetachedProofSchema } from "../proof.js";
+import { DelegationRecordSchema } from "../delegation/index.js";
+
+/**
+ * Standard error schema
+ */
+export const agentShieldAPIErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.record(z.unknown()).optional(),
+});
+
+/**
+ * Standard API response wrapper schema
+ */
+export const agentShieldAPIResponseSchema = <T extends z.ZodTypeAny>(
+  dataSchema: T
+) =>
+  z.object({
+    success: z.boolean(),
+    data: dataSchema,
+    metadata: z
+      .object({
+        requestId: z.string(),
+        timestamp: z.string(),
+      })
+      .optional(),
+  });
+
+// ============================================================================
+// Proof Submission Schemas
+// ============================================================================
+
+/**
+ * Tool Call Context Schema (AgentShield Extension)
+ * Optional plaintext context for dashboard enrichment
+ */
+const toolCallContextSchema = z.object({
+  tool: z.string().min(1, "Tool name is required"),
+  args: z.record(z.unknown()),
+  result: z.unknown().optional(),
+  scopeId: z.string().min(1, "scopeId is required to link context to proof"),
+  userIdentifier: z.string().optional(),
+});
+
+/**
+ * Consent Event Context Schema
+ * Represents consent-related events for audit tracking
+ */
+const consentEventContextSchema = z.object({
+  eventType: z.enum([
+    "consent:page_viewed",
+    "consent:approved",
+    "consent:delegation_created",
+    "consent:credential_required"
+  ]),
+  timestamp: z.number().int().positive(),
+  sessionId: z.string().min(1),
+  userDid: z.string().optional(),
+  agentDid: z.string().min(1),
+  targetTools: z.array(z.string()).min(1), // ALWAYS array
+  scopes: z.array(z.string()).min(0),
+  delegationId: z.string().uuid().optional(),
+  projectId: z.string().uuid(),
+  termsAccepted: z.boolean().optional(),
+  credentialStatus: z.enum(["present", "required", "obtained"]).optional(),
+  oauthIdentity: z.object({
+    provider: z.string(),
+    identifier: z.string(),
+  }).optional(),
+});
+
+/**
+ * Proof submission request schema
+ */
+export const proofSubmissionRequestSchema = z.object({
+  session_id: z.string().max(100), // AgentShield session ID (may differ from MCP-I sessionId)
+  delegation_id: z.string().uuid().nullish(),
+  proofs: z.array(DetachedProofSchema).min(1),
+  // AgentShield extension: Optional context for dashboard enrichment
+  context: z
+    .object({
+      toolCalls: z.array(toolCallContextSchema).optional(),
+      consentEvents: z.array(consentEventContextSchema).optional(), // NEW: Consent events for audit tracking
+      mcpServerUrl: z.string().url().optional(), // MCP server URL for tool discovery
+    })
+    .optional(),
+});
+
+/**
+ * Proof submission response schema
+ */
+export const proofSubmissionResponseSchema = z.object({
+  success: z.boolean(),
+  accepted: z.number().int().min(0),
+  rejected: z.number().int().min(0),
+  outcomes: z.record(z.string(), z.number().int().min(0)).optional(), // Record<BouncerOutcome, number> - Optional because API may return empty object or omit it
+  errors: z
+    .array(
+      z.object({
+        proof_index: z.number().int().min(0),
+        error: z.object({
+          code: z.string(),
+          message: z.string(),
+          details: z.record(z.unknown()).optional(),
+        }),
+      })
+    )
+    .optional(),
+});
+
+// ============================================================================
+// Delegation Verification Schemas
+// ============================================================================
+
+/**
+ * Delegation credential schema
+ */
+export const delegationCredentialSchema = z.object({
+  agent_did: z.string(),
+  user_id: z.string().optional(),
+  user_identifier: z.string().optional(),
+  scopes: z.array(z.string()),
+  constraints: z.record(z.unknown()).optional(),
+  issued_at: z.number().int().positive(),
+  created_at: z.number().int().positive(),
+});
+
+/**
+ * Delegation verification request schema
+ */
+export const verifyDelegationRequestSchema = z.object({
+  agent_did: z.string(),
+  credential_jwt: z.string().optional(), // Optional, omit (don't set to empty string) when not available for OAuth flow
+  delegation_token: z.string().optional(), // Optional, for stateless MCP servers
+  scopes: z.array(z.string()).optional(), // Optional, can be empty array
+  timestamp: z.number().int().positive().optional(),
+  client_info: z
+    .object({
+      ip_address: z.string().ip().optional(),
+      origin: z.string().url().optional(),
+      user_agent: z.string().optional(),
+    })
+    .optional(),
+}).partial({ scopes: true }); // Make scopes truly optional by using partial
+
+/**
+ * Delegation verification response schema
+ */
+export const verifyDelegationResponseSchema = z.object({
+  valid: z.boolean(),
+  delegation: DelegationRecordSchema.optional(),
+  delegation_id: z.string().uuid().optional(),
+  credential: delegationCredentialSchema.optional(),
+  error: agentShieldAPIErrorSchema.optional(),
+  reason: z.string().optional(),
+});
+
+/**
+ * Wrapped verification response schema
+ */
+export const verifyDelegationAPIResponseSchema = agentShieldAPIResponseSchema(
+  verifyDelegationResponseSchema
+);
+
+// ============================================================================
+// Tool Protection Configuration Schemas
+// ============================================================================
+
+/**
+ * AgentShield tool protection schema (supports both snake_case and camelCase)
+ * This is the API-specific format, not the MCP-I spec schema
+ */
+export const agentShieldToolProtectionSchema = z
+  .object({
+    scopes: z.array(z.string()),
+    requires_delegation: z.boolean().optional(),
+    requiresDelegation: z.boolean().optional(),
+    required_scopes: z.array(z.string()).optional(),
+  })
+  .passthrough(); // Allow additional properties
+
+/**
+ * Tool protection config response schema
+ */
+export const toolProtectionConfigResponseSchema = z.object({
+  agent_did: z.string(),
+  tools: z.record(z.string(), agentShieldToolProtectionSchema),
+  reputation_threshold: z.number().min(0).max(1).optional(),
+  denied_agents: z.array(z.string()).optional(),
+  crisp_budget: z
+    .object({
+      max_tokens: z.number(),
+      max_cost: z.number(),
+      currency: z.string(),
+      time_window: z.string(),
+    })
+    .optional(),
+});
+
+/**
+ * Wrapped config response schema
+ */
+export const toolProtectionConfigAPIResponseSchema =
+  agentShieldAPIResponseSchema(toolProtectionConfigResponseSchema);
+
+// ============================================================================
+// Delegation Management Schemas
+// ============================================================================
+
+/**
+ * Create delegation request schema
+ *
+ * Note: AgentShield API accepts a simplified format, not the full DelegationRecord.
+ * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, user_identifier, custom_fields
+ *
+ * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
+ */
+export const createDelegationRequestSchema = z
+  .object({
+    agent_did: z.string().min(1),
+    scopes: z.array(z.string()).min(1),
+    expires_in_days: z.number().int().positive().optional(),
+    expires_at: z.string().datetime().optional(),
+    session_id: z.string().optional(),
+    project_id: z.string().uuid().optional(),
+    user_identifier: z.string().max(200).optional(), // Matches AgentShield's max(200)
+    custom_fields: z.record(z.unknown()).optional(),
+  })
+  .passthrough()
+  .refine(
+    (data) => {
+      // expires_in_days and expires_at are mutually exclusive
+      const hasExpiresInDays = data.expires_in_days !== undefined;
+      const hasExpiresAt = data.expires_at !== undefined;
+      return !(hasExpiresInDays && hasExpiresAt);
+    },
+    {
+      message:
+        "expires_in_days and expires_at are mutually exclusive - use one or the other, not both",
+      path: ["expires_in_days", "expires_at"],
+    }
+  );
+
+/**
+ * Create delegation response schema
+ *
+ * Canonical format returned by POST /api/v1/bouncer/delegations
+ *
+ * IMPORTANT: delegation_token is NOT returned by this endpoint.
+ * delegation_token is only available via OAuth callback flow (/api/v1/bouncer/oauth/callback)
+ * and is passed as a URL parameter, not in the API response body.
+ */
+export const createDelegationResponseSchema = z.object({
+  delegation_id: z.string().uuid(),
+  agent_did: z.string().min(1),
+  user_id: z.string().optional(),
+  user_identifier: z.string().optional(),
+  scopes: z.array(z.string()),
+  status: z.enum(['active', 'expired', 'revoked']), // Matches AgentShield's actual API behavior
+  issued_at: z.string().datetime(),
+  expires_at: z.string().datetime().nullable().optional(), // AgentShield allows null values
+  created_at: z.string().datetime(),
+});
+
+/**
+ * Wrapped creation response schema
+ */
+export const createDelegationAPIResponseSchema = agentShieldAPIResponseSchema(
+  createDelegationResponseSchema
+);
+
+/**
+ * Revoke delegation request schema
+ */
+export const revokeDelegationRequestSchema = z.object({
+  reason: z.string().optional(),
+});
+
+/**
+ * Revoke delegation response schema
+ */
+export const revokeDelegationResponseSchema = z.object({
+  delegation_id: z.string().uuid(),
+  revoked: z.boolean(),
+  revoked_at: z.number().int().positive(),
+});
+
+/**
+ * Wrapped revocation response schema
+ */
+export const revokeDelegationAPIResponseSchema = agentShieldAPIResponseSchema(
+  revokeDelegationResponseSchema
+);

package/src/agentshield-api/types.ts

@@ -0,0 +1,317 @@
+/**
+ * AgentShield/Bouncer API Type Definitions
+ *
+ * TypeScript interfaces matching the AgentShield dashboard API contract.
+ * These types ensure parity between xmcp-i clients and the AgentShield service.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+
+import type { DetachedProof } from "../proof.js";
+import type { DelegationRecord } from "../delegation/index.js";
+
+/**
+ * Standard AgentShield API response wrapper
+ */
+export interface AgentShieldAPIResponse<T> {
+  success: boolean;
+  data: T;
+  metadata?: {
+    requestId: string;
+    timestamp: string;
+  };
+}
+
+/**
+ * Standard AgentShield API error response structure
+ * (Use AgentShieldAPIError class for runtime errors)
+ */
+export interface AgentShieldAPIErrorResponse {
+  code: string;
+  message: string;
+  details?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Proof Submission API
+// ============================================================================
+
+/**
+ * Tool Call Context (AgentShield Extension to MCP-I)
+ *
+ * Optional plaintext context for dashboard enrichment.
+ * Links to MCP-I proof via scopeId.
+ */
+export interface ToolCallContext {
+  tool: string; // Tool name (e.g., "greet", "searchProducts")
+  args: Record<string, unknown>; // Tool arguments from canonical request
+  result?: unknown; // Tool result from canonical response (optional)
+  scopeId: string; // Links to proof.meta.scopeId
+  userIdentifier?: string; // User context (optional)
+}
+
+/**
+ * Consent Event Context
+ *
+ * Represents consent-related events that occur during the consent flow.
+ * These events are logged separately from tool executions and allow
+ * multiple events per session (unlike regular audit logs).
+ */
+export interface ConsentEventContext {
+  eventType: "consent:page_viewed" | "consent:approved" | "consent:delegation_created" | "consent:credential_required";
+  timestamp: number;
+  sessionId: string;
+  userDid?: string;
+  agentDid: string;
+  targetTools: string[]; // ALWAYS array, even for single tool
+  scopes: string[];
+  delegationId?: string;
+  projectId: string;
+  termsAccepted?: boolean;
+  credentialStatus?: "present" | "required" | "obtained";
+  oauthIdentity?: {
+    provider: string;
+    identifier: string;
+  };
+}
+
+/**
+ * Request body for proof submission endpoint
+ * POST /api/v1/bouncer/proofs
+ */
+export interface ProofSubmissionRequest {
+  /** Delegation ID (nullable, optional - null if no delegation context) */
+  delegation_id?: string | null;
+
+  /** Session ID for grouping proofs (AgentShield session ID, may differ from MCP-I sessionId) */
+  session_id: string;
+
+  /** Array of proofs to submit */
+  proofs: DetachedProof[];
+
+  /** AgentShield extension: Optional context for dashboard enrichment */
+  context?: {
+    toolCalls?: ToolCallContext[];
+    consentEvents?: ConsentEventContext[]; // NEW: Consent events for audit tracking
+    mcpServerUrl?: string; // MCP server URL for tool discovery
+  };
+}
+
+/**
+ * Bouncer outcome types
+ */
+export type BouncerOutcome = "success" | "failed" | "blocked" | "error";
+
+/**
+ * Response from proof submission endpoint
+ */
+export interface ProofSubmissionResponse {
+  success: boolean;
+  accepted: number;
+  rejected: number;
+  outcomes?: Record<BouncerOutcome, number>; // Optional - API may omit or return empty object
+  errors?: Array<{
+    proof_index: number;
+    error: {
+      code: string;
+      message: string;
+      details?: Record<string, unknown>;
+    };
+  }>;
+}
+
+// ============================================================================
+// Delegation Verification API
+// ============================================================================
+
+/**
+ * Request body for delegation verification endpoint
+ * POST /api/v1/bouncer/delegations/verify
+ */
+export interface VerifyDelegationRequest {
+  /** Agent DID to verify */
+  agent_did: string;
+
+  /** Credential JWT (optional, defaults to empty string for OAuth flow) */
+  credential_jwt?: string;
+
+  /** Delegation token from OAuth flow (optional, for stateless MCP servers) */
+  delegation_token?: string;
+
+  /** Required scopes (optional, can be empty array) */
+  scopes?: string[];
+
+  /** Optional timestamp for verification */
+  timestamp?: number;
+
+  /** Optional client info for IP/origin checking */
+  client_info?: {
+    ip_address?: string;
+    origin?: string;
+    user_agent?: string;
+  };
+}
+
+/**
+ * Credential information returned in verification response
+ */
+export interface DelegationCredential {
+  agent_did: string;
+  user_id?: string;
+  user_identifier?: string;
+  scopes: string[];
+  constraints?: Record<string, unknown>;
+  issued_at: number;
+  created_at: number;
+}
+
+/**
+ * Response from delegation verification endpoint
+ */
+export interface VerifyDelegationResponse {
+  valid: boolean;
+  delegation?: DelegationRecord;
+  delegation_id?: string;
+  credential?: DelegationCredential;
+  error?: AgentShieldAPIErrorResponse;
+  reason?: string;
+}
+
+/**
+ * Wrapped verification response (AgentShield wraps in success/data)
+ */
+export type VerifyDelegationAPIResponse =
+  AgentShieldAPIResponse<VerifyDelegationResponse>;
+
+// ============================================================================
+// Tool Protection Configuration API
+// ============================================================================
+
+/**
+ * AgentShield API tool protection format for a single tool
+ * This is the API-specific format, not the MCP-I spec type
+ */
+export interface AgentShieldToolProtection {
+  scopes: string[];
+  requires_delegation?: boolean;
+  requiresDelegation?: boolean; // Support both snake_case and camelCase
+  required_scopes?: string[]; // Alternative naming
+}
+
+/**
+ * Response from tool protection config endpoint
+ * GET /api/v1/bouncer/projects/{projectId}/config
+ */
+export interface ToolProtectionConfigResponse {
+  agent_did: string;
+  tools: Record<string, AgentShieldToolProtection>;
+  reputation_threshold?: number;
+  denied_agents?: string[];
+  crisp_budget?: {
+    max_tokens: number;
+    max_cost: number;
+    currency: string;
+    time_window: string;
+  };
+}
+
+/**
+ * Wrapped config response
+ */
+export type ToolProtectionConfigAPIResponse =
+  AgentShieldAPIResponse<ToolProtectionConfigResponse>;
+
+// ============================================================================
+// Delegation Management API
+// ============================================================================
+
+/**
+ * Request body for creating a delegation
+ * POST /api/v1/bouncer/delegations
+ *
+ * Note: AgentShield API accepts a simplified format, not the full DelegationRecord.
+ * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, user_identifier, custom_fields
+ *
+ * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
+ */
+export interface CreateDelegationRequest {
+  agent_did: string;
+  scopes: string[];
+  /** Number of days until expiration (1-365). Mutually exclusive with expires_at. */
+  expires_in_days?: number;
+  /** ISO 8601 datetime when delegation expires. Mutually exclusive with expires_in_days. */
+  expires_at?: string;
+  session_id?: string;
+  project_id?: string; // Usually extracted from API key, but can be provided
+  /** User identifier string, max 200 chars, optional */
+  user_identifier?: string;
+  custom_fields?: Record<string, unknown>;
+}
+
+/**
+ * Response from delegation creation endpoint
+ *
+ * Canonical format returned by POST /api/v1/bouncer/delegations
+ *
+ * IMPORTANT: delegation_token is NOT returned by this endpoint.
+ * delegation_token is only available via OAuth callback flow (/api/v1/bouncer/oauth/callback)
+ * and is passed as a URL parameter, not in the API response body.
+ */
+export interface CreateDelegationResponse {
+  delegation_id: string;
+  agent_did: string;
+  user_id?: string;
+  user_identifier?: string;
+  scopes: string[];
+  status: "active" | "expired" | "revoked"; // Matches AgentShield's actual API behavior
+  issued_at: string; // ISO 8601 datetime
+  expires_at?: string | null; // ISO 8601 datetime, nullable
+  created_at: string; // ISO 8601 datetime
+}
+
+/**
+ * Wrapped creation response
+ */
+export type CreateDelegationAPIResponse =
+  AgentShieldAPIResponse<CreateDelegationResponse>;
+
+/**
+ * Request body for revoking a delegation
+ * POST /api/v1/bouncer/delegations/{id}/revoke
+ */
+export interface RevokeDelegationRequest {
+  reason?: string;
+}
+
+/**
+ * Response from delegation revocation endpoint
+ */
+export interface RevokeDelegationResponse {
+  delegation_id: string;
+  revoked: boolean;
+  revoked_at: number;
+}
+
+/**
+ * Wrapped revocation response
+ */
+export type RevokeDelegationAPIResponse =
+  AgentShieldAPIResponse<RevokeDelegationResponse>;
+
+// ============================================================================
+// Error Types
+// ============================================================================
+
+/**
+ * AgentShield API error class
+ */
+export class AgentShieldAPIError extends Error {
+  constructor(
+    public readonly code: string,
+    message: string,
+    public readonly details?: Record<string, unknown>
+  ) {
+    super(message);
+    this.name = "AgentShieldAPIError";
+  }
+}