@kya-os/contracts 1.5.2-canary.4 → 1.5.2-canary.5

package/dist/agentshield-api/schemas.js

@@ -0,0 +1,240 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.revokeDelegationAPIResponseSchema = exports.revokeDelegationResponseSchema = exports.revokeDelegationRequestSchema = exports.createDelegationAPIResponseSchema = exports.createDelegationResponseSchema = exports.createDelegationRequestSchema = exports.toolProtectionConfigAPIResponseSchema = exports.toolProtectionConfigResponseSchema = exports.agentShieldToolProtectionSchema = exports.verifyDelegationAPIResponseSchema = exports.verifyDelegationResponseSchema = exports.verifyDelegationRequestSchema = exports.delegationCredentialSchema = exports.proofSubmissionResponseSchema = exports.proofSubmissionRequestSchema = exports.agentShieldAPIResponseSchema = exports.agentShieldAPIErrorSchema = void 0;
+const zod_1 = require("zod");
+const proof_js_1 = require("../proof.js");
+const index_js_1 = require("../delegation/index.js");
+/**
+ * Standard error schema
+ */
+exports.agentShieldAPIErrorSchema = zod_1.z.object({
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    details: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+/**
+ * Standard API response wrapper schema
+ */
+const agentShieldAPIResponseSchema = (dataSchema) => zod_1.z.object({
+    success: zod_1.z.boolean(),
+    data: dataSchema,
+    metadata: zod_1.z
+        .object({
+        requestId: zod_1.z.string(),
+        timestamp: zod_1.z.string(),
+    })
+        .optional(),
+});
+exports.agentShieldAPIResponseSchema = agentShieldAPIResponseSchema;
+// ============================================================================
+// Proof Submission Schemas
+// ============================================================================
+/**
+ * Tool Call Context Schema (AgentShield Extension)
+ * Optional plaintext context for dashboard enrichment
+ */
+const toolCallContextSchema = zod_1.z.object({
+    tool: zod_1.z.string().min(1, "Tool name is required"),
+    args: zod_1.z.record(zod_1.z.unknown()),
+    result: zod_1.z.unknown().optional(),
+    scopeId: zod_1.z.string().min(1, "scopeId is required to link context to proof"),
+    userIdentifier: zod_1.z.string().optional(),
+});
+/**
+ * Proof submission request schema
+ */
+exports.proofSubmissionRequestSchema = zod_1.z.object({
+    session_id: zod_1.z.string().max(100), // AgentShield session ID (may differ from MCP-I sessionId)
+    delegation_id: zod_1.z.string().uuid().nullish(),
+    proofs: zod_1.z.array(proof_js_1.DetachedProofSchema).min(1),
+    // AgentShield extension: Optional context for dashboard enrichment
+    context: zod_1.z
+        .object({
+        toolCalls: zod_1.z.array(toolCallContextSchema).optional(),
+        mcpServerUrl: zod_1.z.string().url().optional(), // MCP server URL for tool discovery
+    })
+        .optional(),
+});
+/**
+ * Proof submission response schema
+ */
+exports.proofSubmissionResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    accepted: zod_1.z.number().int().min(0),
+    rejected: zod_1.z.number().int().min(0),
+    outcomes: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().min(0)), // Record<BouncerOutcome, number>
+    errors: zod_1.z
+        .array(zod_1.z.object({
+        proof_index: zod_1.z.number().int().min(0),
+        error: zod_1.z.object({
+            code: zod_1.z.string(),
+            message: zod_1.z.string(),
+            details: zod_1.z.record(zod_1.z.unknown()).optional(),
+        }),
+    }))
+        .optional(),
+});
+// ============================================================================
+// Delegation Verification Schemas
+// ============================================================================
+/**
+ * Delegation credential schema
+ */
+exports.delegationCredentialSchema = zod_1.z.object({
+    agent_did: zod_1.z.string(),
+    user_id: zod_1.z.string().optional(),
+    user_identifier: zod_1.z.string().optional(),
+    scopes: zod_1.z.array(zod_1.z.string()),
+    constraints: zod_1.z.record(zod_1.z.unknown()).optional(),
+    issued_at: zod_1.z.number().int().positive(),
+    created_at: zod_1.z.number().int().positive(),
+});
+/**
+ * Delegation verification request schema
+ */
+exports.verifyDelegationRequestSchema = zod_1.z.object({
+    agent_did: zod_1.z.string(),
+    credential_jwt: zod_1.z.string().optional(), // Optional, omit (don't set to empty string) when not available for OAuth flow
+    delegation_token: zod_1.z.string().optional(), // Optional, for stateless MCP servers
+    scopes: zod_1.z.array(zod_1.z.string()).optional(), // Optional, can be empty array
+    timestamp: zod_1.z.number().int().positive().optional(),
+    client_info: zod_1.z
+        .object({
+        ip_address: zod_1.z.string().ip().optional(),
+        origin: zod_1.z.string().url().optional(),
+        user_agent: zod_1.z.string().optional(),
+    })
+        .optional(),
+}).partial({ scopes: true }); // Make scopes truly optional by using partial
+/**
+ * Delegation verification response schema
+ */
+exports.verifyDelegationResponseSchema = zod_1.z.object({
+    valid: zod_1.z.boolean(),
+    delegation: index_js_1.DelegationRecordSchema.optional(),
+    delegation_id: zod_1.z.string().uuid().optional(),
+    credential: exports.delegationCredentialSchema.optional(),
+    error: exports.agentShieldAPIErrorSchema.optional(),
+    reason: zod_1.z.string().optional(),
+});
+/**
+ * Wrapped verification response schema
+ */
+exports.verifyDelegationAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.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
+ */
+exports.agentShieldToolProtectionSchema = zod_1.z
+    .object({
+    scopes: zod_1.z.array(zod_1.z.string()),
+    requires_delegation: zod_1.z.boolean().optional(),
+    requiresDelegation: zod_1.z.boolean().optional(),
+    required_scopes: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough(); // Allow additional properties
+/**
+ * Tool protection config response schema
+ */
+exports.toolProtectionConfigResponseSchema = zod_1.z.object({
+    agent_did: zod_1.z.string(),
+    tools: zod_1.z.record(zod_1.z.string(), exports.agentShieldToolProtectionSchema),
+    reputation_threshold: zod_1.z.number().min(0).max(1).optional(),
+    denied_agents: zod_1.z.array(zod_1.z.string()).optional(),
+    crisp_budget: zod_1.z
+        .object({
+        max_tokens: zod_1.z.number(),
+        max_cost: zod_1.z.number(),
+        currency: zod_1.z.string(),
+        time_window: zod_1.z.string(),
+    })
+        .optional(),
+});
+/**
+ * Wrapped config response schema
+ */
+exports.toolProtectionConfigAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.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, custom_fields
+ *
+ * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
+ */
+exports.createDelegationRequestSchema = zod_1.z
+    .object({
+    agent_did: zod_1.z.string().min(1),
+    scopes: zod_1.z.array(zod_1.z.string()).min(1),
+    expires_in_days: zod_1.z.number().int().positive().optional(),
+    expires_at: zod_1.z.string().datetime().optional(),
+    session_id: zod_1.z.string().optional(),
+    project_id: zod_1.z.string().uuid().optional(),
+    custom_fields: zod_1.z.record(zod_1.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.
+ */
+exports.createDelegationResponseSchema = zod_1.z.object({
+    delegation_id: zod_1.z.string().uuid(),
+    agent_did: zod_1.z.string().min(1),
+    user_id: zod_1.z.string().optional(),
+    user_identifier: zod_1.z.string().optional(),
+    scopes: zod_1.z.array(zod_1.z.string()),
+    status: zod_1.z.literal("active"),
+    issued_at: zod_1.z.string().datetime(),
+    expires_at: zod_1.z.string().datetime().optional(),
+    created_at: zod_1.z.string().datetime(),
+});
+/**
+ * Wrapped creation response schema
+ */
+exports.createDelegationAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.createDelegationResponseSchema);
+/**
+ * Revoke delegation request schema
+ */
+exports.revokeDelegationRequestSchema = zod_1.z.object({
+    reason: zod_1.z.string().optional(),
+});
+/**
+ * Revoke delegation response schema
+ */
+exports.revokeDelegationResponseSchema = zod_1.z.object({
+    delegation_id: zod_1.z.string().uuid(),
+    revoked: zod_1.z.boolean(),
+    revoked_at: zod_1.z.number().int().positive(),
+});
+/**
+ * Wrapped revocation response schema
+ */
+exports.revokeDelegationAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.revokeDelegationResponseSchema);

package/dist/agentshield-api/types.d.ts

@@ -0,0 +1,231 @@
+/**
+ * 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>;
+}
+/**
+ * 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;
+    args: Record<string, unknown>;
+    result?: unknown;
+    scopeId: string;
+    userIdentifier?: 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[];
+        mcpServerUrl?: string;
+    };
+}
+/**
+ * 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>;
+    errors?: Array<{
+        proof_index: number;
+        error: {
+            code: string;
+            message: string;
+            details?: Record<string, unknown>;
+        };
+    }>;
+}
+/**
+ * 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>;
+/**
+ * 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;
+    required_scopes?: string[];
+}
+/**
+ * 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>;
+/**
+ * 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, 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;
+    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";
+    issued_at: string;
+    expires_at?: string;
+    created_at: string;
+}
+/**
+ * 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>;
+/**
+ * AgentShield API error class
+ */
+export declare class AgentShieldAPIError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}

package/dist/agentshield-api/types.js

@@ -0,0 +1,26 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentShieldAPIError = void 0;
+// ============================================================================
+// Error Types
+// ============================================================================
+/**
+ * AgentShield API error class
+ */
+class AgentShieldAPIError extends Error {
+    constructor(code, message, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = "AgentShieldAPIError";
+    }
+}
+exports.AgentShieldAPIError = AgentShieldAPIError;