@kya-os/contracts 1.5.3-canary.16 → 1.5.3-canary.17

package/src/agentshield-api/types.ts

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

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;
+  };
+}