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

package/src/env/constants.ts

@@ -1,70 +0,0 @@
-/**
- * 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

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

package/src/handshake.ts

@@ -1,125 +0,0 @@
-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

@@ -1,45 +0,0 @@
-/**
- * @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

@@ -1,31 +0,0 @@
-/**
- * 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

@@ -1,163 +0,0 @@
-/**
- * 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

@@ -1,146 +0,0 @@
-/**
- * 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

@@ -1,99 +0,0 @@
-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>;