@kya-os/contracts 1.5.3-canary.21 → 1.5.3-canary.23

package/src/agentshield-api/index.ts

@@ -1,70 +0,0 @@
-/**
- * AgentShield/Bouncer API Contracts
- *
- * Centralized type definitions, validation schemas, and endpoint constants
- * for the AgentShield dashboard API integration.
- *
- * @package @kya-os/contracts/agentshield-api
- */
-
-// Type exports
-export type {
-  AgentShieldAPIResponse,
-  AgentShieldAPIErrorResponse,
-  ProofSubmissionRequest,
-  ProofSubmissionResponse,
-  ToolCallContext,
-  ConsentEventContext,
-  BouncerOutcome,
-  VerifyDelegationRequest,
-  VerifyDelegationResponse,
-  VerifyDelegationAPIResponse,
-  DelegationCredential,
-  AgentShieldToolProtection,
-  ToolProtectionConfigResponse,
-  ToolProtectionConfigAPIResponse,
-  CreateDelegationRequest,
-  CreateDelegationResponse,
-  CreateDelegationAPIResponse,
-  RevokeDelegationRequest,
-  RevokeDelegationResponse,
-  RevokeDelegationAPIResponse,
-} from "./types.js";
-
-export { AgentShieldAPIError } from "./types.js";
-export type { AgentShieldAPIHeaders } from "./endpoints.js";
-
-export type { ClearCacheRequest, ClearCacheResponse } from "./admin-types.js";
-
-// Schema exports
-export {
-  agentShieldAPIErrorSchema,
-  agentShieldAPIResponseSchema,
-  proofSubmissionRequestSchema,
-  proofSubmissionResponseSchema,
-  delegationCredentialSchema,
-  verifyDelegationRequestSchema,
-  verifyDelegationResponseSchema,
-  verifyDelegationAPIResponseSchema,
-  agentShieldToolProtectionSchema,
-  toolProtectionConfigResponseSchema,
-  toolProtectionConfigAPIResponseSchema,
-  createDelegationRequestSchema,
-  createDelegationResponseSchema,
-  createDelegationAPIResponseSchema,
-  revokeDelegationRequestSchema,
-  revokeDelegationResponseSchema,
-  revokeDelegationAPIResponseSchema,
-} from "./schemas.js";
-
-export {
-  clearCacheRequestSchema,
-  clearCacheResponseSchema,
-} from "./admin-schemas.js";
-
-// Endpoint exports
-export {
-  AGENTSHIELD_API_BASE,
-  AGENTSHIELD_ENDPOINTS,
-  AGENTSHIELD_METHODS,
-} from "./endpoints.js";

package/src/agentshield-api/schemas.ts

@@ -1,304 +0,0 @@
-/**
- * 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

@@ -1,317 +0,0 @@
-/**
- * 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";
-  }
-}