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

package/src/env/constants.ts

@@ -0,0 +1,70 @@
+/**
+ * Environment Constants
+ *
+ * System-wide constants for algorithms, TTLs, and limits
+ *
+ * Related Spec: MCP-I §8
+ * Python Reference: All service documentation files
+ */
+
+/**
+ * Hash algorithm for cryptographic operations
+ */
+export const HASH_ALGO = 'SHA-256' as const;
+
+/**
+ * Supported signature algorithms
+ */
+export const SIG_ALGOS = ['Ed25519', 'ES256'] as const;
+
+export type SignatureAlgorithm = (typeof SIG_ALGOS)[number];
+
+/**
+ * Nonce TTL in milliseconds (5 minutes)
+ */
+export const NONCE_TTL_MS = 5 * 60 * 1000;
+
+/**
+ * Resume token TTL in milliseconds (10 minutes)
+ */
+export const RESUME_TOKEN_TTL_MS = 10 * 60 * 1000;
+
+/**
+ * StatusList2021 cache TTL in seconds (1 minute)
+ */
+export const STATUSLIST_CACHE_SEC = 60;
+
+/**
+ * DID resolution timeout in milliseconds (500ms)
+ */
+export const DID_RESOLVE_TIMEOUT_MS = 500;
+
+/**
+ * Default session TTL in minutes (30 minutes)
+ */
+export const DEFAULT_SESSION_TTL_MINUTES = 30;
+
+/**
+ * Maximum timestamp skew in seconds (2 minutes)
+ */
+export const MAX_TIMESTAMP_SKEW_SEC = 120;
+
+/**
+ * Maximum delegation chain depth
+ */
+export const MAX_DELEGATION_CHAIN_DEPTH = 10;
+
+/**
+ * Maximum status list size (1 million entries)
+ */
+export const MAX_STATUSLIST_SIZE = 1000000;
+
+/**
+ * Proof archive TTL in seconds (30 days)
+ */
+export const PROOF_ARCHIVE_TTL_SEC = 30 * 24 * 60 * 60;
+
+/**
+ * Key rotation grace period in seconds (24 hours)
+ */
+export const KEY_ROTATION_GRACE_PERIOD_SEC = 24 * 60 * 60;

package/src/env/index.ts

@@ -0,0 +1,5 @@
+/**
+ * Environment Constants Module
+ */
+
+export * from './constants.js';

package/src/handshake.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+
+/**
+ * Handshake and session management schemas
+ */
+
+const MCPClientCapabilitiesSchema = z.record(z.string(), z.unknown());
+
+export const MCPClientInfoSchema = z.object({
+  name: z.string().min(1), // e.g., "Claude Desktop"
+  title: z.string().optional(), // Human-readable display name
+  version: z.string().optional(), // e.g., "1.0.0"
+  platform: z.string().optional(), // e.g., "desktop", "web", "mobile"
+  vendor: z.string().optional(), // e.g., "Anthropic"
+  persistentId: z.string().optional(), // Client-provided stable identifier
+});
+
+const MCPHandshakeClientInfoSchema = MCPClientInfoSchema.extend({
+  clientId: z.string().optional(), // Server-generated identifier (optional in request)
+});
+
+export const MCPClientSessionInfoSchema = MCPClientInfoSchema.extend({
+  clientId: z.string(), // Generated by server
+  protocolVersion: z.string().optional(), // Negotiated protocol version
+  capabilities: MCPClientCapabilitiesSchema.optional(), // Negotiated capabilities snapshot
+});
+
+export const HandshakeRequestSchema = z.object({
+  nonce: z.string().min(1),
+  audience: z.string().min(1),
+  timestamp: z.number().int().positive(),
+  agentDid: z.string().startsWith("did:").optional(), // Agent DID for delegation verification
+  clientInfo: MCPHandshakeClientInfoSchema.optional(), // Optional client information from MCP initialize
+  clientProtocolVersion: z.string().min(1).optional(), // Protocol version negotiated during initialize
+  clientCapabilities: MCPClientCapabilitiesSchema.optional(), // Client capability advertisement
+});
+
+export const SessionContextSchema = z.object({
+  sessionId: z.string().min(1),
+  audience: z.string().min(1),
+  nonce: z.string().min(1),
+  timestamp: z.number().int().positive(),
+  createdAt: z.number().int().positive(),
+  lastActivity: z.number().int().positive(),
+  ttlMinutes: z.number().int().positive().default(30),
+  agentDid: z.string().optional(), // MCP Client/Agent DID (from handshake)
+  serverDid: z.string().min(1).optional(), // MCP-I Server DID (optional for backward compatibility)
+  clientDid: z.string().optional(), // Client app DID (if different from agent)
+  userDid: z.string().optional(), // User DID (delegator)
+  clientInfo: MCPClientSessionInfoSchema.optional(), // MCP client information with negotiated metadata
+});
+
+export const NonceCacheEntrySchema = z.object({
+  sessionId: z.string().min(1),
+  expiresAt: z.number().int().positive(),
+});
+
+// Type exports
+export type MCPClientInfo = z.infer<typeof MCPClientInfoSchema>;
+export type MCPClientSessionInfo = z.infer<typeof MCPClientSessionInfoSchema>;
+export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
+export type SessionContext = z.infer<typeof SessionContextSchema>;
+export type MCPClientCapabilities = z.infer<typeof MCPClientCapabilitiesSchema>;
+export type NonceCacheEntry = z.infer<typeof NonceCacheEntrySchema>;
+
+/**
+ * Nonce cache interface for replay prevention
+ */
+export interface NonceCache {
+  /**
+   * Check if a nonce exists in the cache
+   * @param nonce - The nonce to check
+   * @param agentDid - Optional agent DID for agent-scoped nonces (prevents cross-agent replay attacks)
+   */
+  has(nonce: string, agentDid?: string): Promise<boolean>;
+
+  /**
+   * Add a nonce to the cache with TTL
+   * MUST ensure atomic add-if-absent semantics for replay prevention
+   * @param nonce - The nonce to add
+   * @param ttl - Time to live in seconds
+   * @param agentDid - Optional agent DID for agent-scoped nonces (prevents cross-agent replay attacks)
+   */
+  add(nonce: string, ttl: number, agentDid?: string): Promise<void>;
+
+  /**
+   * Clean up expired entries
+   * Should be safe to call frequently and should be no-op for backends that auto-expire
+   */
+  cleanup(): Promise<void>;
+}
+
+/**
+ * Configuration for nonce cache implementations
+ */
+export const NonceCacheConfigSchema = z.object({
+  type: z.enum(["memory", "redis", "dynamodb", "cloudflare-kv"]).optional(),
+  redis: z
+    .object({
+      url: z.string().url(),
+      keyPrefix: z.string().default("mcpi:nonce:"),
+    })
+    .optional(),
+  dynamodb: z
+    .object({
+      tableName: z.string(),
+      region: z.string().optional(),
+      keyAttribute: z.string().default("nonce"),
+      ttlAttribute: z.string().default("expiresAt"),
+    })
+    .optional(),
+  cloudflareKv: z
+    .object({
+      namespace: z.string(),
+      keyPrefix: z.string().default("nonce:"),
+    })
+    .optional(),
+});
+
+export type NonceCacheConfig = z.infer<typeof NonceCacheConfigSchema>;
+
+// Constants
+export const DEFAULT_SESSION_TTL_MINUTES = 30;
+export const DEFAULT_TIMESTAMP_SKEW_SECONDS = 120;
+export const NONCE_LENGTH_BYTES = 16; // 128-bit

package/src/index.ts

@@ -0,0 +1,45 @@
+/**
+ * @kya-os/contracts - Shared types and schemas for XMCP-I ecosystem
+ *
+ * This package provides a single source of truth for all types and contracts
+ * used across the XMCP-I ecosystem, including runtime, CLI, verifier, and registry.
+ *
+ * NOTE: Some exports may conflict. Use subpath imports for new modules:
+ * - import { ... } from '@kya-os/contracts/did'
+ * - import { ... } from '@kya-os/contracts/vc'
+ * - import { ... } from '@kya-os/contracts/delegation'
+ * - import { ... } from '@kya-os/contracts/runtime'
+ * - import { ... } from '@kya-os/contracts/tlkrc'
+ * - import { ... } from '@kya-os/contracts/env'
+ */
+
+// Legacy exports (maintain backward compatibility)
+export * from "./handshake.js";
+export * from "./proof.js";
+export * from "./verifier.js";
+export * from "./registry.js";
+export * from "./cli.js";
+export * from "./test.js";
+export * from "./utils/validation.js";
+
+// W3C VC and Delegation exports (for mcp-i-core compatibility)
+export * from "./vc/index.js";
+export * from "./delegation/index.js";
+
+// Audit types (platform-agnostic)
+export * from "./audit/index.js";
+
+// Version information
+export const CONTRACTS_VERSION = "1.2.1";
+export const SUPPORTED_XMCP_I_VERSION = "^1.0.0";
+
+// New MCP-I contract types are available via subpath imports:
+// import { ... } from '@kya-os/contracts/did'
+// import { ... } from '@kya-os/contracts/vc'
+// import { ... } from '@kya-os/contracts/delegation'
+// import { ... } from '@kya-os/contracts/runtime'
+// import { ... } from '@kya-os/contracts/tlkrc'
+// import { ... } from '@kya-os/contracts/env'
+// import { ... } from '@kya-os/contracts/agentshield-api'
+// import { ... } from '@kya-os/contracts/tool-protection'
+// import { ... } from '@kya-os/contracts/well-known'

package/src/proof/index.ts

@@ -0,0 +1,31 @@
+/**
+ * Proof Module Exports
+ *
+ * This module exports all proof-related types including DetachedProof,
+ * proof records, and signing specs.
+ */
+
+// Export DetachedProof and related schemas from root proof.ts
+export {
+  DetachedProofSchema,
+  ProofMetaSchema,
+  CanonicalHashesSchema,
+  AuditRecordSchema,
+  ToolCallContextSchema,
+  ProofSubmissionContextSchema,
+  ProofSubmissionRequestSchema,
+  JWS_ALGORITHM,
+  HASH_ALGORITHM,
+  AUDIT_VERSION,
+  type DetachedProof,
+  type ProofMeta,
+  type CanonicalHashes,
+  type AuditRecord,
+  type ToolCallContext,
+  type ProofSubmissionContext,
+  type ProofSubmissionRequest,
+} from '../proof.js';
+
+// Export proof record and signing spec types
+export * from './signing-spec.js';
+export * from './proof-record.js';

package/src/proof/proof-record.ts

@@ -0,0 +1,163 @@
+/**
+ * Proof Record (Archive)
+ *
+ * Schema for proof records stored in KV/archive for audit trails
+ *
+ * Related Spec: MCP-I §5
+ * Python Reference: Edge-Delegation-Verification.md
+ */
+
+import { z } from 'zod';
+
+/**
+ * Request Info Schema
+ *
+ * Information about the request that was proven
+ */
+export const RequestInfoSchema = z.object({
+  method: z.string(),
+  url: z.string().url(),
+  bodyHash: z.string().optional(),
+  headersHash: z.string().optional(),
+});
+
+export type RequestInfo = z.infer<typeof RequestInfoSchema>;
+
+/**
+ * Response Info Schema
+ *
+ * Information about the response
+ */
+export const ResponseInfoSchema = z.object({
+  status: z.number().int(),
+  bodyHash: z.string().optional(),
+});
+
+export type ResponseInfo = z.infer<typeof ResponseInfoSchema>;
+
+/**
+ * Proof Details Schema
+ *
+ * Core proof information
+ */
+export const ProofDetailsSchema = z.object({
+  timestamp: z.number().int().positive(),
+  nonce: z.string().min(1),
+  did: z.string().min(1),
+  signature: z.string().regex(/^[A-Za-z0-9_-]+$/),
+  algorithm: z.enum(['Ed25519', 'ES256']),
+  sessionId: z.string().min(1),
+  audience: z.string().min(1),
+  request: RequestInfoSchema.optional(),
+  response: ResponseInfoSchema.optional(),
+});
+
+export type ProofDetails = z.infer<typeof ProofDetailsSchema>;
+
+/**
+ * Linkage Info Schema
+ *
+ * Links to delegations and credentials
+ */
+export const LinkageInfoSchema = z.object({
+  delegationId: z.string().optional(),
+  credentialId: z.string().optional(),
+  chainDepth: z.number().int().nonnegative().optional(),
+});
+
+export type LinkageInfo = z.infer<typeof LinkageInfoSchema>;
+
+/**
+ * CRISP Info Schema
+ *
+ * CRISP spending information
+ */
+export const CrispInfoSchema = z.object({
+  unit: z.enum(['USD', 'ops', 'points']),
+  delta: z.number().optional(),
+  remaining: z.number().optional(),
+});
+
+export type CrispInfo = z.infer<typeof CrispInfoSchema>;
+
+/**
+ * Verification Info Schema
+ *
+ * Verification result for the proof
+ */
+export const VerificationInfoSchema = z.object({
+  result: z.enum(['pending', 'pass', 'fail']),
+  reason: z.string().optional(),
+  checkedAt: z.number().int().positive().optional(),
+});
+
+export type VerificationInfo = z.infer<typeof VerificationInfoSchema>;
+
+/**
+ * Proof Record Schema
+ *
+ * Complete proof record for archive/KV storage
+ */
+export const ProofRecordSchema = z.object({
+  /** Unique identifier for the proof record */
+  id: z.string().min(1),
+
+  /** Tool/service name that created the proof */
+  toolName: z.string().min(1),
+
+  /** Timestamp when stored (milliseconds since epoch) */
+  storedAt: z.number().int().positive(),
+
+  /** Expiration timestamp (milliseconds since epoch) */
+  expiresAt: z.number().int().positive(),
+
+  /** Core proof details */
+  proof: ProofDetailsSchema,
+
+  /** Optional linkage to delegations/credentials */
+  linkage: LinkageInfoSchema.optional(),
+
+  /** Optional CRISP spending info */
+  crisp: CrispInfoSchema.optional(),
+
+  /** Optional verification info */
+  verification: VerificationInfoSchema.optional(),
+
+  /** Optional metadata */
+  metadata: z.record(z.any()).optional(),
+}).passthrough();
+
+export type ProofRecord = z.infer<typeof ProofRecordSchema>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate a proof record
+ *
+ * @param record - The record to validate
+ * @returns Validation result
+ */
+export function validateProofRecord(record: unknown) {
+  return ProofRecordSchema.safeParse(record);
+}
+
+/**
+ * Check if proof record is expired
+ *
+ * @param record - The record to check
+ * @returns true if expired
+ */
+export function isProofRecordExpired(record: ProofRecord): boolean {
+  return Date.now() > record.expiresAt;
+}
+
+/**
+ * Constants
+ */
+
+/**
+ * Default proof record TTL (30 days in milliseconds)
+ */
+export const DEFAULT_PROOF_RECORD_TTL_MS = 30 * 24 * 60 * 60 * 1000;

package/src/proof/signing-spec.ts

@@ -0,0 +1,146 @@
+/**
+ * Proof Signing Specification
+ *
+ * Canonical signing order and detached JWS contracts for proofs
+ *
+ * Related Spec: MCP-I §5
+ * Python Reference: Edge-Delegation-Verification.md
+ */
+
+import { z } from 'zod';
+
+/**
+ * Canonical Request Parts Schema
+ *
+ * Parts of a request that are canonically signed
+ */
+export const CanonicalRequestPartsSchema = z.object({
+  /** HTTP method (uppercased) */
+  method: z.string().toUpperCase(),
+
+  /** Absolute URL */
+  url: z.string().url(),
+
+  /** Optional body hash (base64url of SHA-256) */
+  bodyHash: z.string().regex(/^[A-Za-z0-9_-]+$/).optional(),
+
+  /** Optional headers hash (base64url of SHA-256 of allowlisted headers) */
+  headersHash: z.string().regex(/^[A-Za-z0-9_-]+$/).optional(),
+
+  /** Nonce (base64) */
+  nonce: z.string().min(1),
+
+  /** Timestamp (milliseconds since epoch) */
+  timestamp: z.number().int().positive(),
+
+  /** Audience (e.g., 'mcp-client') */
+  audience: z.string().min(1),
+});
+
+export type CanonicalRequestParts = z.infer<typeof CanonicalRequestPartsSchema>;
+
+/**
+ * Detached JWS Schema
+ *
+ * Detached JSON Web Signature for proofs
+ */
+export const DetachedJwsSchema = z.object({
+  /** Algorithm (Ed25519 or ES256) */
+  alg: z.enum(['Ed25519', 'ES256']),
+
+  /** Optional key ID (fragment from DID) */
+  kid: z.string().optional(),
+
+  /** Base64url-encoded signature */
+  signature: z.string().regex(/^[A-Za-z0-9_-]+$/),
+});
+
+export type DetachedJws = z.infer<typeof DetachedJwsSchema>;
+
+/**
+ * Signing Order
+ *
+ * **CRITICAL**: This order MUST be used for canonical string generation.
+ * Changing this order breaks signature verification.
+ */
+export const SIGNING_ORDER = Object.freeze([
+  'method',
+  'url',
+  'bodyHash',
+  'headersHash',
+  'nonce',
+  'timestamp',
+  'audience',
+] as const);
+
+/**
+ * Type for signing order fields
+ */
+export type SigningOrderField = (typeof SIGNING_ORDER)[number];
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate canonical request parts
+ *
+ * @param parts - The parts to validate
+ * @returns Validation result
+ */
+export function validateCanonicalRequestParts(parts: unknown) {
+  return CanonicalRequestPartsSchema.safeParse(parts);
+}
+
+/**
+ * Validate detached JWS
+ *
+ * @param jws - The JWS to validate
+ * @returns Validation result
+ */
+export function validateDetachedJws(jws: unknown) {
+  return DetachedJwsSchema.safeParse(jws);
+}
+
+/**
+ * Generate canonical signing string from parts
+ *
+ * **NOTE**: This is a type-level spec. Actual implementation
+ * requires runtime string concatenation.
+ *
+ * @param parts - Canonical request parts
+ * @returns Canonical string for signing
+ */
+export function getCanonicalSigningString(parts: CanonicalRequestParts): string {
+  const values: string[] = [];
+
+  for (const field of SIGNING_ORDER) {
+    const value = parts[field];
+    if (value !== undefined) {
+      values.push(String(value));
+    } else {
+      values.push('');
+    }
+  }
+
+  return values.join('\n');
+}
+
+/**
+ * Constants
+ */
+
+/**
+ * Supported signing algorithms
+ */
+export const SUPPORTED_SIGNING_ALGORITHMS = ['Ed25519', 'ES256'] as const;
+
+/**
+ * Hash algorithm for body/headers
+ */
+export const SIGNING_HASH_ALGORITHM = 'SHA-256';
+
+/**
+ * Base64url pattern for validation
+ */
+export const BASE64URL_PATTERN = /^[A-Za-z0-9_-]+$/;

package/src/proof.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+
+/**
+ * Proof and signature schemas for MCP-I
+ *
+ * Note: The type name "DetachedProof" is maintained for backward compatibility,
+ * but the JWS format is actually FULL compact JWS (header.payload.signature),
+ * not detached format (header..signature).
+ *
+ * The JWS payload contains JWT standard claims (aud, sub, iss) plus custom
+ * proof claims (requestHash, responseHash, nonce, etc.).
+ */
+
+export const ProofMetaSchema = z.object({
+  did: z.string().min(1),
+  kid: z.string().min(1),
+  ts: z.number().int().positive(),
+  nonce: z.string().min(1),
+  audience: z.string().min(1),
+  sessionId: z.string().min(1),
+  requestHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  responseHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  scopeId: z.string().optional(),
+  delegationRef: z.string().optional(),
+  clientDid: z.string().optional(), // Optional for backward compatibility
+});
+
+export const DetachedProofSchema = z.object({
+  jws: z.string().min(1), // Full compact JWS format (header.payload.signature)
+  meta: ProofMetaSchema,   // Convenience metadata (duplicates signed payload data)
+});
+
+export const CanonicalHashesSchema = z.object({
+  requestHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  responseHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+});
+
+export const AuditRecordSchema = z.object({
+  version: z.literal("audit.v1"),
+  ts: z.number().int().positive(),
+  session: z.string().min(1),
+  audience: z.string().min(1),
+  did: z.string().min(1),
+  kid: z.string().min(1),
+  reqHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  resHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
+  verified: z.enum(["yes", "no"]),
+  scope: z.string().min(1), // "-" for no scope
+});
+
+// Type exports
+export type ProofMeta = z.infer<typeof ProofMetaSchema>;
+export type DetachedProof = z.infer<typeof DetachedProofSchema>;
+export type CanonicalHashes = z.infer<typeof CanonicalHashesSchema>;
+export type AuditRecord = z.infer<typeof AuditRecordSchema>;
+
+// Constants
+export const JWS_ALGORITHM = "EdDSA";
+export const HASH_ALGORITHM = "sha256";
+export const AUDIT_VERSION = "audit.v1";
+
+/**
+ * Tool call context for AgentShield dashboard integration
+ * Provides plaintext tool execution data alongside cryptographic proofs
+ */
+export const ToolCallContextSchema = z.object({
+  tool: z.string().min(1),
+  args: z.record(z.unknown()),
+  result: z.unknown().optional(),
+  scopeId: z.string(),
+  userId: z.string().optional(),
+});
+
+/**
+ * Proof submission context for AgentShield API
+ * Includes tool calls and optional MCP server URL for tool discovery
+ */
+export const ProofSubmissionContextSchema = z.object({
+  toolCalls: z.array(ToolCallContextSchema),
+  mcpServerUrl: z.string().url().optional(),
+});
+
+/**
+ * Complete proof submission request to AgentShield
+ */
+export const ProofSubmissionRequestSchema = z.object({
+  session_id: z.string().min(1),
+  delegation_id: z.string().nullable().optional(),
+  proofs: z.array(z.object({
+    jws: z.string().min(1),
+    meta: ProofMetaSchema,
+  })),
+  context: ProofSubmissionContextSchema.optional(),
+});
+
+// Type exports
+export type ToolCallContext = z.infer<typeof ToolCallContextSchema>;
+export type ProofSubmissionContext = z.infer<typeof ProofSubmissionContextSchema>;
+export type ProofSubmissionRequest = z.infer<typeof ProofSubmissionRequestSchema>;