@kya-os/contracts 1.3.4 → 1.4.0

package/dist/tlkrc/rotation.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_GRACE_PERIOD_SEC = exports.DEFAULT_GRACE_PERIOD_SEC = exports.RotationChainSchema = exports.RotationEventSchema = void 0;
+exports.validateRotationEvent = validateRotationEvent;
+exports.isRotationChainValid = isRotationChainValid;
+exports.getActiveKeyAt = getActiveKeyAt;
+const zod_1 = require("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`.
+ */
+exports.RotationEventSchema = zod_1.z.object({
+    /** DID of the issuer performing the rotation */
+    issuerDid: zod_1.z.string().min(1),
+    /** Previous key ID being rotated out */
+    prevKeyId: zod_1.z.string().min(1),
+    /** New key ID being rotated in */
+    nextKeyId: zod_1.z.string().min(1),
+    /** Timestamp when new key becomes effective (Unix seconds) */
+    effectiveAt: zod_1.z.number().int().positive(),
+    /** Timestamp when event was issued (Unix seconds) */
+    issuedAt: zod_1.z.number().int().positive(),
+    /** Sequence number (monotonically increasing) */
+    seq: zod_1.z.number().int().nonnegative(),
+    /** Hash of previous rotation event (null for first rotation) */
+    prevEventHash: zod_1.z.string().optional(),
+    /** Signature over the event (using prevKeyId) */
+    signature: zod_1.z.string().min(1),
+    /** Optional metadata */
+    metadata: zod_1.z.record(zod_1.z.any()).optional(),
+}).refine((event) => event.effectiveAt >= event.issuedAt, {
+    message: 'effectiveAt must be >= issuedAt',
+});
+/**
+ * Rotation Chain
+ *
+ * Represents a chain of rotation events
+ */
+exports.RotationChainSchema = zod_1.z.object({
+    /** Issuer DID */
+    issuerDid: zod_1.z.string().min(1),
+    /** All rotation events in order */
+    events: zod_1.z.array(exports.RotationEventSchema).min(1),
+    /** Current active key ID */
+    currentKeyId: zod_1.z.string().min(1),
+    /** Whether chain is valid */
+    valid: zod_1.z.boolean(),
+    /** Optional validation errors */
+    errors: zod_1.z.array(zod_1.z.string()).optional(),
+});
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a rotation event
+ *
+ * @param event - The event to validate
+ * @returns Validation result
+ */
+function validateRotationEvent(event) {
+    return exports.RotationEventSchema.safeParse(event);
+}
+/**
+ * Validate rotation chain integrity
+ *
+ * @param chain - The chain to validate
+ * @returns true if chain is valid
+ */
+function isRotationChainValid(chain) {
+    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
+ */
+function getActiveKeyAt(chain, timestamp) {
+    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)
+ */
+exports.DEFAULT_GRACE_PERIOD_SEC = 24 * 60 * 60;
+/**
+ * Maximum reasonable grace period (30 days)
+ */
+exports.MAX_GRACE_PERIOD_SEC = 30 * 24 * 60 * 60;

package/dist/tool-protection/index.d.ts

@@ -0,0 +1,227 @@
+/**
+ * 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';
+/**
+ * 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';
+}
+/**
+ * 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 declare const ToolProtectionSchema: z.ZodObject<{
+    requiresDelegation: z.ZodBoolean;
+    requiredScopes: z.ZodArray<z.ZodString, "many">;
+    riskLevel: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+}, "strip", z.ZodTypeAny, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+}, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+}>;
+export declare const ToolProtectionMapSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    requiresDelegation: z.ZodBoolean;
+    requiredScopes: z.ZodArray<z.ZodString, "many">;
+    riskLevel: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+}, "strip", z.ZodTypeAny, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+}, {
+    requiresDelegation: boolean;
+    requiredScopes: string[];
+    riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+}>>;
+export declare const ToolProtectionResponseSchema: z.ZodObject<{
+    toolProtections: z.ZodRecord<z.ZodString, z.ZodObject<{
+        requiresDelegation: z.ZodBoolean;
+        requiredScopes: z.ZodArray<z.ZodString, "many">;
+        riskLevel: z.ZodOptional<z.ZodEnum<["low", "medium", "high", "critical"]>>;
+    }, "strip", z.ZodTypeAny, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    }, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    }>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        lastUpdated: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        source: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    }, {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    toolProtections: Record<string, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    }>;
+    metadata?: {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    } | undefined;
+}, {
+    toolProtections: Record<string, {
+        requiresDelegation: boolean;
+        requiredScopes: string[];
+        riskLevel?: "low" | "medium" | "high" | "critical" | undefined;
+    }>;
+    metadata?: {
+        version?: string | undefined;
+        lastUpdated?: string | undefined;
+        source?: string | undefined;
+    } | undefined;
+}>;
+export declare const DelegationRequiredErrorDataSchema: z.ZodObject<{
+    toolName: z.ZodString;
+    requiredScopes: z.ZodArray<z.ZodString, "many">;
+    consentUrl: z.ZodOptional<z.ZodString>;
+    authorizationUrl: z.ZodOptional<z.ZodString>;
+    reason: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requiredScopes: string[];
+    toolName: string;
+    reason?: string | undefined;
+    consentUrl?: string | undefined;
+    authorizationUrl?: string | undefined;
+}, {
+    requiredScopes: string[];
+    toolName: string;
+    reason?: string | undefined;
+    consentUrl?: string | undefined;
+    authorizationUrl?: string | undefined;
+}>;
+/**
+ * Type Guards
+ */
+export declare function isToolProtection(obj: any): obj is ToolProtection;
+export declare function isToolProtectionMap(obj: any): obj is ToolProtectionMap;
+export declare function isToolProtectionResponse(obj: any): obj is ToolProtectionResponse;
+export declare function isDelegationRequiredErrorData(obj: any): obj is DelegationRequiredErrorData;
+/**
+ * Validation Functions
+ */
+export declare function validateToolProtection(obj: any): ToolProtection;
+export declare function validateToolProtectionMap(obj: any): ToolProtectionMap;
+export declare function validateToolProtectionResponse(obj: any): ToolProtectionResponse;
+export declare function validateDelegationRequiredErrorData(obj: any): DelegationRequiredErrorData;
+/**
+ * Utility Functions
+ */
+/**
+ * Check if a tool requires delegation
+ */
+export declare function toolRequiresDelegation(toolName: string, protections: ToolProtectionMap): boolean;
+/**
+ * Get required scopes for a tool
+ */
+export declare function getToolRequiredScopes(toolName: string, protections: ToolProtectionMap): string[];
+/**
+ * Get risk level for a tool
+ */
+export declare function getToolRiskLevel(toolName: string, protections: ToolProtectionMap): ToolProtection['riskLevel'] | undefined;
+/**
+ * Create a delegation required error
+ */
+export declare function createDelegationRequiredError(toolName: string, requiredScopes: string[], consentUrl?: string): DelegationRequiredErrorData;

package/dist/tool-protection/index.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DelegationRequiredErrorDataSchema = exports.ToolProtectionResponseSchema = exports.ToolProtectionMapSchema = exports.ToolProtectionSchema = void 0;
+exports.isToolProtection = isToolProtection;
+exports.isToolProtectionMap = isToolProtectionMap;
+exports.isToolProtectionResponse = isToolProtectionResponse;
+exports.isDelegationRequiredErrorData = isDelegationRequiredErrorData;
+exports.validateToolProtection = validateToolProtection;
+exports.validateToolProtectionMap = validateToolProtectionMap;
+exports.validateToolProtectionResponse = validateToolProtectionResponse;
+exports.validateDelegationRequiredErrorData = validateDelegationRequiredErrorData;
+exports.toolRequiresDelegation = toolRequiresDelegation;
+exports.getToolRequiredScopes = getToolRequiredScopes;
+exports.getToolRiskLevel = getToolRiskLevel;
+exports.createDelegationRequiredError = createDelegationRequiredError;
+const zod_1 = require("zod");
+/**
+ * Zod Schemas for Validation
+ */
+exports.ToolProtectionSchema = zod_1.z.object({
+    requiresDelegation: zod_1.z.boolean(),
+    requiredScopes: zod_1.z.array(zod_1.z.string()),
+    riskLevel: zod_1.z.enum(['low', 'medium', 'high', 'critical']).optional()
+});
+exports.ToolProtectionMapSchema = zod_1.z.record(zod_1.z.string(), exports.ToolProtectionSchema);
+exports.ToolProtectionResponseSchema = zod_1.z.object({
+    toolProtections: exports.ToolProtectionMapSchema,
+    metadata: zod_1.z.object({
+        lastUpdated: zod_1.z.string().optional(),
+        version: zod_1.z.string().optional(),
+        source: zod_1.z.string().optional()
+    }).optional()
+});
+exports.DelegationRequiredErrorDataSchema = zod_1.z.object({
+    toolName: zod_1.z.string(),
+    requiredScopes: zod_1.z.array(zod_1.z.string()),
+    consentUrl: zod_1.z.string().optional(),
+    authorizationUrl: zod_1.z.string().optional(),
+    reason: zod_1.z.string().optional()
+});
+/**
+ * Type Guards
+ */
+function isToolProtection(obj) {
+    return exports.ToolProtectionSchema.safeParse(obj).success;
+}
+function isToolProtectionMap(obj) {
+    return exports.ToolProtectionMapSchema.safeParse(obj).success;
+}
+function isToolProtectionResponse(obj) {
+    return exports.ToolProtectionResponseSchema.safeParse(obj).success;
+}
+function isDelegationRequiredErrorData(obj) {
+    return exports.DelegationRequiredErrorDataSchema.safeParse(obj).success;
+}
+/**
+ * Validation Functions
+ */
+function validateToolProtection(obj) {
+    return exports.ToolProtectionSchema.parse(obj);
+}
+function validateToolProtectionMap(obj) {
+    return exports.ToolProtectionMapSchema.parse(obj);
+}
+function validateToolProtectionResponse(obj) {
+    return exports.ToolProtectionResponseSchema.parse(obj);
+}
+function validateDelegationRequiredErrorData(obj) {
+    return exports.DelegationRequiredErrorDataSchema.parse(obj);
+}
+/**
+ * Utility Functions
+ */
+/**
+ * Check if a tool requires delegation
+ */
+function toolRequiresDelegation(toolName, protections) {
+    const protection = protections[toolName];
+    return protection?.requiresDelegation ?? false;
+}
+/**
+ * Get required scopes for a tool
+ */
+function getToolRequiredScopes(toolName, protections) {
+    const protection = protections[toolName];
+    return protection?.requiredScopes ?? [];
+}
+/**
+ * Get risk level for a tool
+ */
+function getToolRiskLevel(toolName, protections) {
+    return protections[toolName]?.riskLevel;
+}
+/**
+ * Create a delegation required error
+ */
+function createDelegationRequiredError(toolName, requiredScopes, consentUrl) {
+    return {
+        toolName,
+        requiredScopes,
+        consentUrl,
+        authorizationUrl: consentUrl // Include both for compatibility
+    };
+}

package/dist/utils/validation.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 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 declare function validateInput<T>(schema: z.ZodSchema<T>, data: unknown, context?: string): ValidationResult<T>;
+/**
+ * Validate object has required properties
+ */
+export declare function hasRequiredProperties(obj: any, properties: string[], context?: string): ValidationResult;
+/**
+ * Validate string format patterns
+ */
+export declare const StringValidators: {
+    did: (value: string) => boolean;
+    kid: (value: string) => boolean;
+    url: (value: string) => boolean;
+    projectName: (value: string) => boolean;
+};

package/dist/utils/validation.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Shared validation utilities for mcpi packages
+ * Consolidates common validation patterns to follow DRY principles
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StringValidators = void 0;
+exports.validateInput = validateInput;
+exports.hasRequiredProperties = hasRequiredProperties;
+/**
+ * Generic validation function with helpful error messages
+ */
+function validateInput(schema, data, context) {
+    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
+ */
+function hasRequiredProperties(obj, properties, context) {
+    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
+ */
+exports.StringValidators = {
+    did: (value) => /^did:[a-z0-9]+:[a-zA-Z0-9._-]+$/.test(value),
+    kid: (value) => /^[a-zA-Z0-9._-]+$/.test(value),
+    url: (value) => {
+        try {
+            new URL(value);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    },
+    projectName: (value) => /^[a-z0-9-]+$/.test(value) && value.length >= 1 && value.length <= 214,
+};

package/dist/vc/index.d.ts

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

package/dist/vc/index.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Verifiable Credentials Module Exports
+ *
+ * W3C Verifiable Credentials types, schemas, and utilities
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./schemas.js"), exports);
+__exportStar(require("./statuslist.js"), exports);