@kya-os/contracts 1.3.4 → 1.4.0

package/dist/agentshield-api/schemas.js

@@ -0,0 +1,165 @@
+"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
+// ============================================================================
+/**
+ * Proof submission request schema
+ */
+exports.proofSubmissionRequestSchema = zod_1.z.object({
+    delegation_id: zod_1.z.string().uuid().nullable(),
+    session_id: zod_1.z.string().uuid(),
+    proofs: zod_1.z.array(proof_js_1.DetachedProofSchema).min(1),
+});
+/**
+ * Proof submission response schema
+ */
+exports.proofSubmissionResponseSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    received: zod_1.z.number().int().min(0),
+    processed: zod_1.z.number().int().min(0),
+    errors: zod_1.z.array(zod_1.z.object({
+        proofId: zod_1.z.string(),
+        error: zod_1.z.string(),
+    })).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(),
+    scopes: zod_1.z.array(zod_1.z.string()).min(1),
+    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(),
+});
+/**
+ * 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(),
+});
+/**
+ * Wrapped config response schema
+ */
+exports.toolProtectionConfigAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.toolProtectionConfigResponseSchema);
+// ============================================================================
+// Delegation Management Schemas
+// ============================================================================
+/**
+ * Create delegation request schema
+ */
+exports.createDelegationRequestSchema = zod_1.z.object({
+    delegation: index_js_1.DelegationRecordSchema,
+});
+/**
+ * Create delegation response schema
+ */
+exports.createDelegationResponseSchema = zod_1.z.object({
+    delegation_id: zod_1.z.string().uuid(),
+    delegation: index_js_1.DelegationRecordSchema,
+});
+/**
+ * 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);
+//# sourceMappingURL=schemas.js.map

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

@@ -0,0 +1,168 @@
+/**
+ * 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>;
+}
+/**
+ * Request body for proof submission endpoint
+ * POST /api/v1/bouncer/proofs
+ */
+export interface ProofSubmissionRequest {
+    /** Delegation ID (null if no delegation context) */
+    delegation_id: string | null;
+    /** Session ID for grouping proofs */
+    session_id: string;
+    /** Array of proofs to submit */
+    proofs: DetachedProof[];
+}
+/**
+ * Response from proof submission endpoint
+ */
+export interface ProofSubmissionResponse {
+    success: boolean;
+    received: number;
+    processed: number;
+    errors?: Array<{
+        proofId: string;
+        error: string;
+    }>;
+}
+/**
+ * Request body for delegation verification endpoint
+ * POST /api/v1/bouncer/delegations/verify
+ */
+export interface VerifyDelegationRequest {
+    /** Agent DID to verify */
+    agent_did: string;
+    /** Required scopes */
+    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/config/{projectId}
+ */
+export interface ToolProtectionConfigResponse {
+    agent_did: string;
+    tools: Record<string, AgentShieldToolProtection>;
+    reputation_threshold?: number;
+    denied_agents?: string[];
+}
+/**
+ * Wrapped config response
+ */
+export type ToolProtectionConfigAPIResponse = AgentShieldAPIResponse<ToolProtectionConfigResponse>;
+/**
+ * Request body for creating a delegation
+ * POST /api/v1/bouncer/delegations
+ */
+export interface CreateDelegationRequest {
+    delegation: DelegationRecord;
+}
+/**
+ * Response from delegation creation endpoint
+ */
+export interface CreateDelegationResponse {
+    delegation_id: string;
+    delegation: DelegationRecord;
+}
+/**
+ * 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,27 @@
+"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;
+//# sourceMappingURL=types.js.map