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

package/src/tlkrc/rotation.ts

@@ -0,0 +1,153 @@
+/**
+ * TLKRC (Transparent Log Key Rotation Contract)
+ *
+ * Types for key rotation events in a transparent, auditable manner
+ *
+ * Related Spec: MCP-I Core
+ * Python Reference: Core-Documentation.md
+ */
+
+import { z } from 'zod';
+
+/**
+ * Rotation Event Schema
+ *
+ * Represents a key rotation event in a transparent log.
+ * Events form a hash-linked chain for auditability.
+ *
+ * **Dual-Key Grace Window:**
+ * During rotation, both `prevKeyId` and `nextKeyId` are valid
+ * from `effectiveAt` until `effectiveAt + grace period`.
+ */
+export const RotationEventSchema = z.object({
+  /** DID of the issuer performing the rotation */
+  issuerDid: z.string().min(1),
+
+  /** Previous key ID being rotated out */
+  prevKeyId: z.string().min(1),
+
+  /** New key ID being rotated in */
+  nextKeyId: z.string().min(1),
+
+  /** Timestamp when new key becomes effective (Unix seconds) */
+  effectiveAt: z.number().int().positive(),
+
+  /** Timestamp when event was issued (Unix seconds) */
+  issuedAt: z.number().int().positive(),
+
+  /** Sequence number (monotonically increasing) */
+  seq: z.number().int().nonnegative(),
+
+  /** Hash of previous rotation event (null for first rotation) */
+  prevEventHash: z.string().optional(),
+
+  /** Signature over the event (using prevKeyId) */
+  signature: z.string().min(1),
+
+  /** Optional metadata */
+  metadata: z.record(z.any()).optional(),
+}).refine(
+  (event) => event.effectiveAt >= event.issuedAt,
+  {
+    message: 'effectiveAt must be >= issuedAt',
+  }
+);
+
+export type RotationEvent = z.infer<typeof RotationEventSchema>;
+
+/**
+ * Rotation Chain
+ *
+ * Represents a chain of rotation events
+ */
+export const RotationChainSchema = z.object({
+  /** Issuer DID */
+  issuerDid: z.string().min(1),
+
+  /** All rotation events in order */
+  events: z.array(RotationEventSchema).min(1),
+
+  /** Current active key ID */
+  currentKeyId: z.string().min(1),
+
+  /** Whether chain is valid */
+  valid: z.boolean(),
+
+  /** Optional validation errors */
+  errors: z.array(z.string()).optional(),
+});
+
+export type RotationChain = z.infer<typeof RotationChainSchema>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate a rotation event
+ *
+ * @param event - The event to validate
+ * @returns Validation result
+ */
+export function validateRotationEvent(event: unknown) {
+  return RotationEventSchema.safeParse(event);
+}
+
+/**
+ * Validate rotation chain integrity
+ *
+ * @param chain - The chain to validate
+ * @returns true if chain is valid
+ */
+export function isRotationChainValid(chain: RotationChain): boolean {
+  if (chain.events.length === 0) {
+    return false;
+  }
+
+  // Check sequence numbers are monotonic
+  for (let i = 1; i < chain.events.length; i++) {
+    if (chain.events[i].seq <= chain.events[i - 1].seq) {
+      return false;
+    }
+  }
+
+  return chain.valid;
+}
+
+/**
+ * Get active key at a specific timestamp
+ *
+ * @param chain - The rotation chain
+ * @param timestamp - Timestamp in seconds
+ * @returns Active key ID at that time, or null if none
+ */
+export function getActiveKeyAt(chain: RotationChain, timestamp: number): string | null {
+  if (chain.events.length === 0) {
+    return null;
+  }
+
+  // Find the most recent event that's effective at the timestamp
+  for (let i = chain.events.length - 1; i >= 0; i--) {
+    const event = chain.events[i];
+    if (event.effectiveAt <= timestamp) {
+      return event.nextKeyId;
+    }
+  }
+
+  // If no event is effective yet, use the initial key
+  return chain.events[0].prevKeyId;
+}
+
+/**
+ * Constants
+ */
+
+/**
+ * Default grace period for dual-key validity (24 hours)
+ */
+export const DEFAULT_GRACE_PERIOD_SEC = 24 * 60 * 60;
+
+/**
+ * Maximum reasonable grace period (30 days)
+ */
+export const MAX_GRACE_PERIOD_SEC = 30 * 24 * 60 * 60;

package/src/tool-protection/index.ts

@@ -0,0 +1,343 @@
+/**
+ * MCP-I Tool Protection Specification
+ *
+ * This module defines the core tool protection types as specified in the
+ * MCP-I protocol. These are pure specification types that define how tools
+ * can be protected with delegation requirements and scopes.
+ *
+ * @module @kya-os/contracts/tool-protection
+ */
+
+import { z } from 'zod';
+
+/**
+ * Authorization Requirement (Discriminated Union)
+ *
+ * Defines the type of authorization required for a tool.
+ * Extensible design to support OAuth, MDL, IDV, credentials, etc.
+ */
+export type AuthorizationRequirement =
+  | {
+      type: 'oauth';
+      provider: string; // "github", "google", etc.
+      requiredScopes?: string[]; // Provider-specific scopes
+    }
+  | {
+      type: 'mdl';
+      issuer: string; // MDL issuer DID or identifier
+      credentialType?: string; // Specific MDL credential type
+    }
+  | {
+      type: 'idv';
+      provider: string; // IDV provider name
+      verificationLevel?: 'basic' | 'enhanced' | 'loa3';
+    }
+  | {
+      type: 'credential';
+      credentialType: string; // Generic credential type
+      issuer?: string; // Optional issuer constraint
+    }
+  | {
+      type: 'none'; // Just consent checkbox, no external auth
+    };
+
+/**
+ * Tool Protection Definition
+ *
+ * Defines the protection requirements for a tool as per MCP-I spec.
+ * This is the canonical definition that all implementations must follow.
+ */
+export interface ToolProtection {
+  /**
+   * Whether this tool requires explicit delegation from the user
+   */
+  requiresDelegation: boolean;
+
+  /**
+   * The scopes required to execute this tool
+   * Format: "resource:action" (e.g., "files:read", "payment:send")
+   */
+  requiredScopes: string[];
+
+  /**
+   * Risk level classification for the tool
+   * Used to determine appropriate authorization flows
+   */
+  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
+
+  /**
+   * OAuth provider name for this tool (Phase 2+)
+   * If specified, this tool will use the specified OAuth provider.
+   * If not specified, provider will be resolved via fallback strategies.
+   * @example "github", "google", "microsoft"
+   * @deprecated Use `authorization` field instead. Will be removed in Phase 3.
+   */
+  oauthProvider?: string;
+
+  /**
+   * Authorization requirement for this tool
+   * If requiresDelegation=true, authorization must be specified (or inferred from legacy fields)
+   */
+  authorization?: AuthorizationRequirement;
+}
+
+/**
+ * Tool Protection Map
+ *
+ * A mapping of tool names to their protection configurations.
+ * This is how tool protections are typically stored and transmitted.
+ */
+export type ToolProtectionMap = Record<string, ToolProtection>;
+
+/**
+ * Tool Protection Response
+ *
+ * The response format when querying for tool protections.
+ * Used by tool protection services and APIs.
+ */
+export interface ToolProtectionResponse {
+  /**
+   * The tool protections keyed by tool name
+   */
+  toolProtections: ToolProtectionMap;
+
+  /**
+   * Optional metadata about the response
+   */
+  metadata?: {
+    /**
+     * When this configuration was last updated
+     */
+    lastUpdated?: string;
+
+    /**
+     * Version of the configuration
+     */
+    version?: string;
+
+    /**
+     * Source of the configuration
+     */
+    source?: string;
+  };
+}
+
+/**
+ * Delegation Required Error Data
+ *
+ * The standardized error data returned when a tool requires delegation
+ * but none was provided. This is part of the MCP-I error protocol.
+ */
+export interface DelegationRequiredErrorData {
+  /**
+   * The name of the tool that requires delegation
+   */
+  toolName: string;
+
+  /**
+   * The scopes required for this tool
+   */
+  requiredScopes: string[];
+
+  /**
+   * URL where the user can provide consent/delegation
+   */
+  consentUrl?: string;
+
+  /**
+   * Alternative field for consent URL (for compatibility)
+   */
+  authorizationUrl?: string;
+
+  /**
+   * Additional context about why delegation is required
+   */
+  reason?: string;
+}
+
+/**
+ * Zod Schemas for Validation
+ */
+
+export const AuthorizationRequirementSchema = z.discriminatedUnion('type', [
+  z.object({
+    type: z.literal('oauth'),
+    provider: z.string(),
+    requiredScopes: z.array(z.string()).optional(),
+  }),
+  z.object({
+    type: z.literal('mdl'),
+    issuer: z.string(),
+    credentialType: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('idv'),
+    provider: z.string(),
+    verificationLevel: z.enum(['basic', 'enhanced', 'loa3']).optional(),
+  }),
+  z.object({
+    type: z.literal('credential'),
+    credentialType: z.string(),
+    issuer: z.string().optional(),
+  }),
+  z.object({
+    type: z.literal('none'),
+  }),
+]);
+
+export const ToolProtectionSchema = z.object({
+  requiresDelegation: z.boolean(),
+  requiredScopes: z.array(z.string()),
+  riskLevel: z.enum(['low', 'medium', 'high', 'critical']).optional(),
+  oauthProvider: z.string().optional(), // Phase 2: Tool-specific OAuth provider
+  authorization: AuthorizationRequirementSchema.optional(),
+});
+
+export const ToolProtectionMapSchema = z.record(z.string(), ToolProtectionSchema);
+
+export const ToolProtectionResponseSchema = z.object({
+  toolProtections: ToolProtectionMapSchema,
+  metadata: z.object({
+    lastUpdated: z.string().optional(),
+    version: z.string().optional(),
+    source: z.string().optional()
+  }).optional()
+});
+
+export const DelegationRequiredErrorDataSchema = z.object({
+  toolName: z.string(),
+  requiredScopes: z.array(z.string()),
+  consentUrl: z.string().optional(),
+  authorizationUrl: z.string().optional(),
+  reason: z.string().optional()
+});
+
+/**
+ * Type Guards
+ */
+
+export function isToolProtection(obj: any): obj is ToolProtection {
+  return ToolProtectionSchema.safeParse(obj).success;
+}
+
+export function isToolProtectionMap(obj: any): obj is ToolProtectionMap {
+  return ToolProtectionMapSchema.safeParse(obj).success;
+}
+
+export function isToolProtectionResponse(obj: any): obj is ToolProtectionResponse {
+  return ToolProtectionResponseSchema.safeParse(obj).success;
+}
+
+export function isDelegationRequiredErrorData(obj: any): obj is DelegationRequiredErrorData {
+  return DelegationRequiredErrorDataSchema.safeParse(obj).success;
+}
+
+/**
+ * Validation Functions
+ */
+
+export function validateToolProtection(obj: any): ToolProtection {
+  return ToolProtectionSchema.parse(obj);
+}
+
+export function validateToolProtectionMap(obj: any): ToolProtectionMap {
+  return ToolProtectionMapSchema.parse(obj);
+}
+
+export function validateToolProtectionResponse(obj: any): ToolProtectionResponse {
+  return ToolProtectionResponseSchema.parse(obj);
+}
+
+export function validateDelegationRequiredErrorData(obj: any): DelegationRequiredErrorData {
+  return DelegationRequiredErrorDataSchema.parse(obj);
+}
+
+/**
+ * Utility Functions
+ */
+
+/**
+ * Check if a tool requires delegation
+ */
+export function toolRequiresDelegation(
+  toolName: string,
+  protections: ToolProtectionMap
+): boolean {
+  const protection = protections[toolName];
+  return protection?.requiresDelegation ?? false;
+}
+
+/**
+ * Get required scopes for a tool
+ */
+export function getToolRequiredScopes(
+  toolName: string,
+  protections: ToolProtectionMap
+): string[] {
+  const protection = protections[toolName];
+  return protection?.requiredScopes ?? [];
+}
+
+/**
+ * Get risk level for a tool
+ */
+export function getToolRiskLevel(
+  toolName: string,
+  protections: ToolProtectionMap
+): ToolProtection['riskLevel'] | undefined {
+  return protections[toolName]?.riskLevel;
+}
+
+/**
+ * Create a delegation required error
+ */
+export function createDelegationRequiredError(
+  toolName: string,
+  requiredScopes: string[],
+  consentUrl?: string
+): DelegationRequiredErrorData {
+  return {
+    toolName,
+    requiredScopes,
+    consentUrl,
+    authorizationUrl: consentUrl // Include both for compatibility
+  };
+}
+
+/**
+ * Normalize tool protection configuration
+ * Migrates legacy oauthProvider field to authorization object
+ *
+ * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
+ */
+export function normalizeToolProtection(
+  raw: ToolProtection
+): ToolProtection {
+  // If authorization is already present, return as is
+  if (raw.authorization) {
+    return raw;
+  }
+
+  // Migrate oauthProvider to authorization
+  if (raw.oauthProvider) {
+    return {
+      ...raw,
+      authorization: {
+        type: 'oauth',
+        provider: raw.oauthProvider,
+      },
+      // Keep oauthProvider for backward compatibility until Phase 3
+    };
+  }
+
+  // Default for requiresDelegation=true without specific auth: type='none' (consent only)
+  // But ONLY if authorization is missing entirely
+  if (raw.requiresDelegation && !raw.authorization && !raw.oauthProvider) {
+    // We don't automatically set type='none' here to allow
+    // ProviderResolver to do its scope inference fallback logic.
+    // The fallback logic will eventually be moved into an AuthorizationService.
+    return raw;
+  }
+
+  return raw;
+}

package/src/utils/validation.ts

@@ -0,0 +1,93 @@
+/**
+ * Shared validation utilities for mcpi packages
+ * Consolidates common validation patterns to follow DRY principles
+ */
+
+import { z } from "zod";
+
+/**
+ * Generic validation result type
+ */
+export interface ValidationResult<T = any> {
+  valid: boolean;
+  data?: T;
+  errors: string[];
+}
+
+/**
+ * Generic validation function with helpful error messages
+ */
+export function validateInput<T>(
+  schema: z.ZodSchema<T>,
+  data: unknown,
+  context?: string
+): ValidationResult<T> {
+  const result = schema.safeParse(data);
+
+  if (result.success) {
+    return {
+      valid: true,
+      data: result.data,
+      errors: [],
+    };
+  }
+
+  const errors = result.error.errors.map((err) => {
+    const path = err.path.length > 0 ? ` at ${err.path.join(".")}` : "";
+    const contextStr = context ? ` (${context})` : "";
+    return `${err.message}${path}${contextStr}`;
+  });
+
+  return {
+    valid: false,
+    errors,
+  };
+}
+
+/**
+ * Validate object has required properties
+ */
+export function hasRequiredProperties(
+  obj: any,
+  properties: string[],
+  context?: string
+): ValidationResult {
+  if (typeof obj !== "object" || obj === null) {
+    return {
+      valid: false,
+      errors: [`Expected object${context ? ` for ${context}` : ""}`],
+    };
+  }
+
+  const missing = properties.filter((prop) => !(prop in obj));
+
+  if (missing.length > 0) {
+    return {
+      valid: false,
+      errors: [
+        `Missing required properties: ${missing.join(", ")}${context ? ` in ${context}` : ""}`,
+      ],
+    };
+  }
+
+  return { valid: true, errors: [] };
+}
+
+/**
+ * Validate string format patterns
+ */
+export const StringValidators = {
+  did: (value: string): boolean =>
+    /^did:[a-z0-9]+:[a-zA-Z0-9._-]+$/.test(value),
+  kid: (value: string): boolean => /^[a-zA-Z0-9._-]+$/.test(value),
+  url: (value: string): boolean => {
+    try {
+      new URL(value);
+      return true;
+    } catch {
+      return false;
+    }
+  },
+  projectName: (value: string): boolean =>
+    /^[a-z0-9-]+$/.test(value) && value.length >= 1 && value.length <= 214,
+};

package/src/vc/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Verifiable Credentials Module Exports
+ *
+ * W3C Verifiable Credentials types, schemas, and utilities
+ */
+
+export * from './schemas.js';
+export * from './statuslist.js';