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

package/src/tlkrc/rotation.ts

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

@@ -1,406 +0,0 @@
-/**
- * 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>;
-
-/**
- * Partial tool protection for updates (all fields optional)
- * Use this when accepting partial updates to tool protection settings
- */
-export type PartialToolProtection = Partial<ToolProtection>;
-
-/**
- * Tool protection with explicit optional fields
- * Useful when TypeScript's Partial<T> doesn't preserve optional property access
- * Supports explicit null values to clear fields
- */
-export type ToolProtectionUpdate = {
-  requiresDelegation?: boolean;
-  requiredScopes?: string[];
-  riskLevel?: 'low' | 'medium' | 'high' | 'critical';
-  oauthProvider?: string | null; // null explicitly clears the field
-  authorization?: AuthorizationRequirement | null; // null explicitly clears the field
-};
-
-/**
- * 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;
-}
-
-/**
- * Legacy tool protection format (pre-authorization field)
- * Used during migration period to support both old and new formats
- */
-export type LegacyToolProtection = Omit<ToolProtection, 'authorization'> & {
-  oauthProvider?: string;
-};
-
-/**
- * Union type for both legacy and new formats
- * Useful during migration period when accepting tool protection input
- */
-export type ToolProtectionInput = ToolProtection | LegacyToolProtection;
-
-/**
- * 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;
-}
-
-/**
- * Type guard to check if an object is a valid AuthorizationRequirement
- */
-export function isAuthorizationRequirement(obj: unknown): obj is AuthorizationRequirement {
-  return AuthorizationRequirementSchema.safeParse(obj).success;
-}
-
-/**
- * Type guard to check if a ToolProtection has OAuth authorization
- */
-export function hasOAuthAuthorization(
-  protection: ToolProtection
-): protection is ToolProtection & { authorization: { type: 'oauth' } } {
-  return protection.authorization?.type === 'oauth';
-}
-
-/**
- * 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
- * 
- * - Migrates `oauthProvider` → `authorization: { type: 'oauth', provider: ... }`
- * - Ensures `authorization` field is present when `requiresDelegation=true`
- * - Returns fully normalized ToolProtection object
- * 
- * @param raw - Raw tool protection data (may have legacy fields or be partial)
- * @returns Normalized ToolProtection object
- * 
- * // TODO: Remove normalizeToolProtection() when all tools migrated (target: Phase 3)
- */
-export function normalizeToolProtection(
-  raw: ToolProtection | PartialToolProtection
-): ToolProtection {
-  // Ensure we have required fields (provide defaults for partial input)
-  const normalized: ToolProtection = {
-    requiresDelegation: raw.requiresDelegation ?? false,
-    requiredScopes: raw.requiredScopes ?? [],
-    ...(raw.riskLevel && { riskLevel: raw.riskLevel }),
-    ...(raw.oauthProvider && { oauthProvider: raw.oauthProvider }),
-  };
-
-  // If authorization is already present, use it
-  if (raw.authorization) {
-    normalized.authorization = raw.authorization;
-    return normalized;
-  }
-
-  // Migrate oauthProvider to authorization
-  if (raw.oauthProvider) {
-    normalized.authorization = {
-      type: 'oauth',
-      provider: raw.oauthProvider,
-    };
-    // Keep oauthProvider for backward compatibility until Phase 3
-    return normalized;
-  }
-
-  // Default for requiresDelegation=true without specific auth: type='none' (consent only)
-  // But ONLY if authorization is missing entirely
-  if (normalized.requiresDelegation && !normalized.authorization && !normalized.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 normalized;
-  }
-
-  return normalized;
-}

package/src/utils/validation.ts

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

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