@kya-os/contracts 1.3.5 → 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

package/dist/cli.d.ts

@@ -1,4 +1,13 @@
 import { z } from "zod";
+/**
+ * CLI command schemas and results
+ */
+/**
+ * CLI Identity File Format Schema
+ *
+ * Format for identity.json files stored on disk.
+ * Used by CLI tools for identity management.
+ */
 export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
     version: z.ZodLiteral<"1.0">;
     did: z.ZodString;
@@ -350,6 +359,10 @@ export type CacheInfo = z.infer<typeof CacheInfoSchema>;
 export type DoctorResult = z.infer<typeof DoctorResultSchema>;
 export type ScaffolderOptions = z.infer<typeof ScaffolderOptionsSchema>;
 export type ScaffolderResult = z.infer<typeof ScaffolderResultSchema>;
+/**
+ * @deprecated Use CLIIdentityFile instead
+ * This export is maintained for backward compatibility
+ */
 export type IdentityConfig = CLIIdentityFile;
 export declare const ERROR_CODES: {
     readonly XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF";

package/dist/cli.js

@@ -2,9 +2,19 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CLI_EXIT_CODES = exports.ERROR_CODES = exports.ScaffolderResultSchema = exports.ScaffolderOptionsSchema = exports.DoctorResultSchema = exports.CacheInfoSchema = exports.KTAInfoSchema = exports.EnvironmentInfoSchema = exports.XMCPUpstreamInfoSchema = exports.PackageInfoSchema = exports.StatusReportSchema = exports.KeyRotationResultSchema = exports.CLIIdentityFileSchema = void 0;
 const zod_1 = require("zod");
+/**
+ * CLI command schemas and results
+ */
+/**
+ * CLI Identity File Format Schema
+ *
+ * Format for identity.json files stored on disk.
+ * Used by CLI tools for identity management.
+ */
 exports.CLIIdentityFileSchema = zod_1.z.object({
     version: zod_1.z.literal("1.0"),
     did: zod_1.z.string().min(1),
+    // Accept both kid and keyId for backward compatibility with pre-1.3 identity files
     kid: zod_1.z.string().min(1).optional(),
     keyId: zod_1.z.string().min(1).optional(),
     privateKey: zod_1.z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 private key (44 characters)"),
@@ -34,7 +44,7 @@ exports.KeyRotationResultSchema = zod_1.z.object({
 });
 exports.StatusReportSchema = zod_1.z.object({
     did: zod_1.z.string().min(1),
-    kid: zod_1.z.string().min(1),
+    kid: zod_1.z.string().min(1), // Changed from keyId to kid for spec compliance
     ktaURL: zod_1.z.string().url(),
     mirrorStatus: zod_1.z.enum(["pending", "success", "error"]),
     lastHandshake: zod_1.z.number().int().positive().optional(),
@@ -86,6 +96,7 @@ exports.ScaffolderResultSchema = zod_1.z.object({
     identityEnabled: zod_1.z.boolean(),
     warnings: zod_1.z.array(zod_1.z.string()).optional(),
 });
+// Error codes as string literal union
 exports.ERROR_CODES = {
     XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF",
     XMCP_I_ENOIDENTITY: "XMCP_I_ENOIDENTITY",
@@ -96,6 +107,7 @@ exports.ERROR_CODES = {
     XMCP_I_ECONFIG: "XMCP_I_ECONFIG",
     XMCP_I_ERUNTIME: "XMCP_I_ERUNTIME",
 };
+// CLI exit codes
 exports.CLI_EXIT_CODES = {
     SUCCESS: 0,
     GENERAL_ERROR: 1,

package/dist/config/base.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Base Configuration Types
+ *
+ * Shared configuration interfaces that are platform-agnostic and used
+ * across all XMCP-I implementations. These form the foundation of the
+ * configuration hierarchy.
+ *
+ * @module @kya-os/contracts/config
+ */
+/**
+ * Base configuration shared across ALL platforms
+ *
+ * This interface defines the core configuration options that are
+ * universally applicable regardless of the runtime platform (Node.js,
+ * Cloudflare Workers, etc.).
+ */
+export interface MCPIBaseConfig {
+    /**
+     * Runtime environment setting
+     * - 'development': Enables debug logging, dev identity, relaxed security
+     * - 'production': Production security, identity from env vars, minimal logging
+     */
+    environment: 'development' | 'production';
+    /**
+     * Session configuration
+     * Controls how sessions are managed and validated
+     */
+    session?: {
+        /**
+         * Maximum time skew allowed for timestamp validation (in seconds)
+         * Helps handle clock drift between client and server
+         * @default 120
+         */
+        timestampSkewSeconds?: number;
+        /**
+         * Session time-to-live in minutes
+         * How long a session remains valid after creation
+         * @default 30
+         */
+        ttlMinutes?: number;
+        /**
+         * Absolute session lifetime in minutes (optional)
+         * Maximum lifetime regardless of activity
+         */
+        absoluteLifetime?: number;
+    };
+    /**
+     * Audit logging configuration
+     * Controls what gets logged for security and compliance
+     */
+    audit?: {
+        /**
+         * Enable audit logging
+         * @default true in production, false in development
+         */
+        enabled: boolean;
+        /**
+         * Include proof hashes in audit logs
+         * Useful for cryptographic verification but increases log size
+         * @default false
+         */
+        includeProofHashes?: boolean;
+        /**
+         * Include full payloads in audit logs
+         * WARNING: May include sensitive data
+         * @default false
+         */
+        includePayloads?: boolean;
+        /**
+         * Custom log function for audit records
+         * If not provided, uses console.log
+         */
+        logFunction?: (record: string) => void;
+    };
+    /**
+     * Well-known endpoints configuration
+     * Controls the /.well-known/* endpoints for identity discovery
+     */
+    wellKnown?: {
+        /**
+         * Enable well-known endpoints
+         * @default true
+         */
+        enabled: boolean;
+        /**
+         * Service name advertised in well-known endpoints
+         * @default 'MCP-I Service'
+         */
+        serviceName?: string;
+        /**
+         * Service endpoint URL
+         * @default 'https://example.com'
+         */
+        serviceEndpoint?: string;
+    };
+}

package/dist/config/base.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Base Configuration Types
+ *
+ * Shared configuration interfaces that are platform-agnostic and used
+ * across all XMCP-I implementations. These form the foundation of the
+ * configuration hierarchy.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });