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

package/src/audit/index.ts

@@ -0,0 +1,128 @@
+/**
+ * Audit Types and Schemas
+ *
+ * Types and Zod schemas for audit logging in the MCP-I framework.
+ * These types are platform-agnostic and used across all implementations.
+ */
+
+import { z } from "zod";
+import type { AgentIdentity } from "../config/identity.js";
+import type { SessionContext } from "../handshake.js";
+
+/**
+ * Audit context schema for logging audit records
+ *
+ * Contains all metadata needed to generate an audit record.
+ * Privacy Note: Only metadata is extracted from these objects.
+ * The identity's private key, session's nonce, and other sensitive
+ * fields are NEVER included in the audit log.
+ */
+export const AuditContextSchema = z.object({
+  /**
+   * Agent identity
+   * Only `did` and `keyId` are logged. Private key is NEVER logged.
+   */
+  identity: z
+    .object({
+      did: z.string().min(1),
+      kid: z.string().min(1),
+    })
+    .passthrough(), // Allow additional fields but only did/kid are used
+
+  /**
+   * Session context
+   * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
+   */
+  session: z
+    .object({
+      sessionId: z.string().min(1),
+      audience: z.string().min(1),
+    })
+    .passthrough(), // Allow additional fields but only sessionId/audience are used
+
+  /**
+   * Request hash (SHA-256 with `sha256:` prefix)
+   */
+  requestHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+
+  /**
+   * Response hash (SHA-256 with `sha256:` prefix)
+   */
+  responseHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+
+  /**
+   * Verification result
+   * - 'yes': Proof was verified successfully
+   * - 'no': Proof verification failed
+   */
+  verified: z.enum(["yes", "no"]),
+
+  /**
+   * Optional scope identifier
+   * Application-level scope (e.g., 'orders.create', 'users.read').
+   * If not provided, '-' is used in the audit log.
+   */
+  scopeId: z.string().optional(),
+});
+
+export type AuditContext = {
+  identity: AgentIdentity;
+  session: SessionContext;
+  requestHash: string;
+  responseHash: string;
+  verified: "yes" | "no";
+  scopeId?: string;
+};
+
+/**
+ * Event context schema for logging events that bypass session deduplication
+ *
+ * Used for consent events where multiple events occur in the same session.
+ * Unlike AuditContext, this allows multiple events per session.
+ */
+export const AuditEventContextSchema = z.object({
+  /**
+   * Event type identifier
+   * @example "consent:page_viewed", "consent:approved", "runtime:initialized"
+   */
+  eventType: z.string().min(1),
+
+  /**
+   * Agent identity
+   * Only `did` and `keyId` are logged. Private key is NEVER logged.
+   */
+  identity: z
+    .object({
+      did: z.string().min(1),
+      kid: z.string().min(1),
+    })
+    .passthrough(), // Allow additional fields but only did/kid are used
+
+  /**
+   * Session context
+   * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
+   */
+  session: z
+    .object({
+      sessionId: z.string().min(1),
+      audience: z.string().min(1),
+    })
+    .passthrough(), // Allow additional fields but only sessionId/audience are used
+
+  /**
+   * Optional event-specific data
+   * Used for generating event hash. Not logged directly.
+   */
+  eventData: z.record(z.unknown()).optional(),
+});
+
+export type AuditEventContext = {
+  eventType: string;
+  identity: AgentIdentity;
+  session: SessionContext;
+  eventData?: Record<string, any>;
+};
+
+// Re-export AuditRecord from proof module
+export type { AuditRecord } from "../proof.js";
+export { AuditRecordSchema } from "../proof.js";

package/src/cli.ts

@@ -0,0 +1,156 @@
+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 const CLIIdentityFileSchema = z.object({
+  version: z.literal("1.0"),
+  did: z.string().min(1),
+  // Accept both kid and keyId for backward compatibility with pre-1.3 identity files
+  kid: z.string().min(1).optional(),
+  keyId: z.string().min(1).optional(),
+  privateKey: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 private key (44 characters)"),
+  publicKey: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 public key (44 characters)"),
+  createdAt: z.string().datetime(),
+  lastRotated: z.string().datetime().optional(),
+}).refine(
+  (data) => data.kid || data.keyId,
+  {
+    message: "Either kid or keyId must be provided",
+  }
+).transform((data) => ({
+  version: data.version,
+  did: data.did,
+  kid: data.kid || data.keyId!,
+  privateKey: data.privateKey,
+  publicKey: data.publicKey,
+  createdAt: data.createdAt,
+  lastRotated: data.lastRotated,
+}));
+
+export const KeyRotationResultSchema = z.object({
+  success: z.boolean(),
+  oldKeyId: z.string().min(1),
+  newKeyId: z.string().min(1),
+  did: z.string().min(1),
+  mode: z.enum(["dev", "prod"]),
+  delegated: z.boolean(),
+  forced: z.boolean(),
+  auditLine: z.string().min(1),
+});
+
+export const StatusReportSchema = z.object({
+  did: z.string().min(1),
+  kid: z.string().min(1), // Changed from keyId to kid for spec compliance
+  ktaURL: z.string().url(),
+  mirrorStatus: z.enum(["pending", "success", "error"]),
+  lastHandshake: z.number().int().positive().optional(),
+  environment: z.enum(["dev", "prod"]),
+});
+
+export const PackageInfoSchema = z.object({
+  name: z.string(),
+  version: z.string(),
+  compatible: z.boolean(),
+  issues: z.array(z.string()).optional(),
+});
+
+export const XMCPUpstreamInfoSchema = z.object({
+  version: z.string(),
+  compatible: z.boolean(),
+  issues: z.array(z.string()).optional(),
+});
+
+export const EnvironmentInfoSchema = z.object({
+  valid: z.boolean(),
+  missing: z.array(z.string()),
+  issues: z.array(z.string()).optional(),
+});
+
+export const KTAInfoSchema = z.object({
+  reachable: z.boolean(),
+  authenticated: z.boolean(),
+  issues: z.array(z.string()).optional(),
+});
+
+export const CacheInfoSchema = z.object({
+  type: z.string(),
+  functional: z.boolean(),
+  issues: z.array(z.string()).optional(),
+});
+
+export const DoctorResultSchema = z.object({
+  packages: z.array(PackageInfoSchema),
+  xmcpUpstream: XMCPUpstreamInfoSchema,
+  environment: EnvironmentInfoSchema,
+  kta: KTAInfoSchema,
+  cache: CacheInfoSchema,
+});
+
+export const ScaffolderOptionsSchema = z.object({
+  projectName: z.string().min(1),
+  xmcpVersion: z.string().optional(),
+  xmcpChannel: z.enum(["latest", "next"]).optional(),
+  noIdentity: z.boolean().default(false),
+});
+
+export const ScaffolderResultSchema = z.object({
+  success: z.boolean(),
+  projectPath: z.string().min(1),
+  xmcpVersion: z.string().min(1),
+  identityEnabled: z.boolean(),
+  warnings: z.array(z.string()).optional(),
+});
+
+// Type exports
+export type CLIIdentityFile = z.infer<typeof CLIIdentityFileSchema>;
+export type KeyRotationResult = z.infer<typeof KeyRotationResultSchema>;
+export type StatusReport = z.infer<typeof StatusReportSchema>;
+export type PackageInfo = z.infer<typeof PackageInfoSchema>;
+export type XMCPUpstreamInfo = z.infer<typeof XMCPUpstreamInfoSchema>;
+export type EnvironmentInfo = z.infer<typeof EnvironmentInfoSchema>;
+export type KTAInfo = z.infer<typeof KTAInfoSchema>;
+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;
+
+// Error codes as string literal union
+export const ERROR_CODES = {
+  XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF",
+  XMCP_I_ENOIDENTITY: "XMCP_I_ENOIDENTITY",
+  XMCP_I_EMIRRORPENDING: "XMCP_I_EMIRRORPENDING",
+  XMCP_I_EHANDSHAKE: "XMCP_I_EHANDSHAKE",
+  XMCP_I_ESESSION: "XMCP_I_ESESSION",
+  XMCP_I_ECLAIM: "XMCP_I_ECLAIM",
+  XMCP_I_ECONFIG: "XMCP_I_ECONFIG",
+  XMCP_I_ERUNTIME: "XMCP_I_ERUNTIME",
+} as const;
+
+export type ErrorCode = keyof typeof ERROR_CODES;
+
+// CLI exit codes
+export const CLI_EXIT_CODES = {
+  SUCCESS: 0,
+  GENERAL_ERROR: 1,
+  BADPROOF: 20,
+  NOIDENTITY: 21,
+  HANDSHAKE: 22,
+  SESSION: 23,
+  CLAIM: 24,
+  CONFIG: 25,
+  RUNTIME: 26,
+} as const;

package/src/config/base.ts

@@ -0,0 +1,107 @@
+/**
+ * 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/src/config/builder.ts

@@ -0,0 +1,97 @@
+/**
+ * Configuration Builder Utilities
+ *
+ * Shared utilities for building MCP-I configuration objects with sensible defaults.
+ * These functions are platform-agnostic and can be used by any adapter/platform.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+import type { MCPIBaseConfig } from './base.js';
+import type { RuntimeIdentityConfig } from './identity.js';
+import type { ProofingConfig } from './proofing.js';
+import type { DelegationConfig, DelegationVerifierConfig, AuthorizationConfig } from './delegation.js';
+import type { ToolProtectionSourceConfig } from './tool-protection.js';
+
+/**
+ * Complete runtime configuration type
+ * This can be extended by platform-specific configs
+ */
+export interface MCPIConfig extends MCPIBaseConfig {
+  identity?: RuntimeIdentityConfig;
+  proofing?: ProofingConfig;
+  delegation?: DelegationConfig;
+  toolProtection?: ToolProtectionSourceConfig;
+}
+
+/**
+ * Build base MCPIConfig that works across all platforms
+ *
+ * Creates a platform-agnostic configuration object with sensible defaults
+ * for identity, proofing, delegation, audit, and session management.
+ *
+ * @param env - Environment variables object (works with process.env or Cloudflare env)
+ * @returns Complete MCPIConfig object
+ */
+export function buildBaseConfig(env: Record<string, any>): MCPIConfig {
+  const environment = (env.MCPI_ENV || env.ENVIRONMENT || 'development') as 'development' | 'production';
+  const isDevelopment = environment === 'development';
+
+  const baseConfig: MCPIConfig = {
+    environment,
+
+    identity: {
+      enabled: true,
+      environment,
+      devIdentityPath: '.mcpi/identity.json'
+    } as RuntimeIdentityConfig,
+
+    proofing: {
+      enabled: true,
+      batchQueue: {
+        destinations: [
+          {
+            type: 'agentshield' as const,
+            apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+            apiKey: env.AGENTSHIELD_API_KEY
+          }
+        ],
+        maxBatchSize: 10,
+        flushIntervalMs: 5000,
+        maxRetries: 3,
+        debug: isDevelopment
+      }
+    } as ProofingConfig,
+
+    delegation: {
+      enabled: true,
+      enforceDelegations: true,
+      verifier: {
+        type: 'agentshield' as const,
+        apiUrl: env.AGENTSHIELD_API_URL || 'https://kya.vouched.id',
+        apiKey: env.AGENTSHIELD_API_KEY || '',
+        cacheTtl: 60000, // 1 minute cache
+        debug: isDevelopment
+      } as DelegationVerifierConfig,
+      authorization: {
+        authorizationUrl: env.AUTHORIZATION_URL || `${env.AGENTSHIELD_API_URL || 'https://kya.vouched.id'}/authorize`,
+        resumeTokenTtl: 600000, // 10 minutes
+        minReputationScore: 76
+      } as AuthorizationConfig
+    } as DelegationConfig,
+
+    audit: {
+      enabled: true,
+      includeProofHashes: false,
+      includePayloads: false
+    },
+
+    session: {
+      timestampSkewSeconds: 120,
+      ttlMinutes: 30
+    }
+  };
+
+  return baseConfig;
+}
+

package/src/config/delegation.ts

@@ -0,0 +1,232 @@
+/**
+ * Delegation Configuration Types
+ *
+ * Configuration for delegation verification, authorization flows,
+ * and consent management in MCP-I.
+ *
+ * @module @kya-os/contracts/config
+ */
+
+/**
+ * Delegation verifier types
+ */
+export type DelegationVerifierType =
+  | 'agentshield'    // AgentShield API
+  | 'kta'            // Know That AI
+  | 'memory'         // In-memory (development)
+  | 'cloudflare-kv'  // Cloudflare KV storage
+  | 'redis'          // Redis cache
+  | 'dynamodb'       // AWS DynamoDB
+  | 'custom';        // Custom implementation
+
+/**
+ * Delegation verifier configuration
+ * Controls how delegations are verified and cached
+ */
+export interface DelegationVerifierConfig {
+  /**
+   * Type of verifier to use
+   */
+  type: DelegationVerifierType;
+
+  /**
+   * API URL for remote verifiers (agentshield, kta)
+   * @example 'https://kya.vouched.id'
+   */
+  apiUrl?: string;
+
+  /**
+   * API key for authentication with remote verifiers
+   */
+  apiKey?: string;
+
+  /**
+   * Cache time-to-live in milliseconds
+   * How long to cache delegation verification results
+   * @default 300000 (5 minutes)
+   */
+  cacheTtl?: number;
+
+  /**
+   * Custom verifier implementation
+   * Required when type is 'custom'
+   */
+  customVerifier?: {
+    verify: (agentDid: string, scopes: string[]) => Promise<boolean>;
+    invalidate?: (agentDid: string) => Promise<void>;
+  };
+
+  /**
+   * Additional verifier-specific options
+   */
+  options?: Record<string, unknown>;
+}
+
+/**
+ * Authorization configuration
+ * Controls consent flows and authorization requirements
+ */
+export interface AuthorizationConfig {
+  /**
+   * Base URL for authorization/consent flow
+   * Users are redirected here when delegation is required
+   * @example 'https://kya.vouched.id/bouncer/consent'
+   */
+  authorizationUrl?: string;
+
+  /**
+   * KTA (Know That AI) configuration for reputation checks
+   */
+  kta?: {
+    /**
+     * KTA API base URL
+     */
+    apiUrl: string;
+
+    /**
+     * API key for KTA
+     */
+    apiKey?: string;
+  };
+
+  /**
+   * Minimum reputation score to bypass authorization
+   * Agents with reputation above this threshold don't need explicit consent
+   * Range: 0-100
+   * @default 80
+   */
+  minReputationScore?: number;
+
+  /**
+   * Resume token TTL in milliseconds
+   * How long a resume token remains valid
+   * @default 3600000 (1 hour)
+   */
+  resumeTokenTtl?: number;
+
+  /**
+   * Require authorization for unknown agents
+   * If false, unknown agents are allowed by default
+   * @default true
+   */
+  requireAuthForUnknown?: boolean;
+
+  /**
+   * Custom authorization URL builder
+   * Allows customization of consent URL generation
+   */
+  buildAuthUrl?: (toolName: string, scopes: string[], context: any) => string;
+}
+
+/**
+ * Delegation configuration (platform-agnostic)
+ *
+ * Controls delegation verification, authorization flows, and
+ * tool protection enforcement.
+ */
+export interface DelegationConfig {
+  /**
+   * Enable delegation features
+   * When false, all tools are accessible without delegation
+   * @default false (for backward compatibility)
+   */
+  enabled: boolean;
+
+  /**
+   * Enforce delegation requirements strictly
+   * When true, tools requiring delegation will fail without valid delegation
+   * When false, logs warnings but allows execution
+   * @default true in production, false in development
+   */
+  enforceDelegations?: boolean;
+
+  /**
+   * Delegation verifier configuration
+   * Controls how delegations are verified
+   */
+  verifier: DelegationVerifierConfig;
+
+  /**
+   * Authorization configuration
+   * Controls consent flows and reputation checks
+   */
+  authorization?: AuthorizationConfig;
+
+  /**
+   * Enable debug logging for delegation operations
+   * @default false
+   */
+  debug?: boolean;
+}
+
+/**
+ * Delegation record structure
+ * Represents a delegation from a user to an agent
+ */
+export interface DelegationRecord {
+  /**
+   * Unique identifier for this delegation
+   */
+  id: string;
+
+  /**
+   * User who granted the delegation
+   */
+  userId: string;
+
+  /**
+   * Agent DID receiving the delegation
+   */
+  agentDid: string;
+
+  /**
+   * Scopes granted in this delegation
+   * @example ['files:read', 'files:write']
+   */
+  scopes: string[];
+
+  /**
+   * ISO 8601 timestamp when delegation was created
+   */
+  createdAt: string;
+
+  /**
+   * ISO 8601 timestamp when delegation expires
+   */
+  expiresAt?: string;
+
+  /**
+   * Whether this delegation has been revoked
+   */
+  revoked?: boolean;
+
+  /**
+   * Additional constraints on the delegation
+   */
+  constraints?: {
+    /**
+     * IP addresses allowed to use this delegation
+     */
+    allowedIps?: string[];
+
+    /**
+     * Origins allowed to use this delegation
+     */
+    allowedOrigins?: string[];
+
+    /**
+     * Maximum number of uses
+     */
+    maxUses?: number;
+
+    /**
+     * Current number of uses
+     */
+    currentUses?: number;
+
+    /**
+     * Additional custom constraints
+     */
+    [key: string]: unknown;
+  };
+}