@kya-os/contracts 1.6.18 → 1.6.19

package/dist/reputation/api.js

@@ -0,0 +1,417 @@
+"use strict";
+/**
+ * Reputation API Schemas
+ *
+ * Request and response schemas for the Reputation Engine REST API.
+ * These schemas ensure type safety and runtime validation for all API endpoints.
+ *
+ * Endpoints covered:
+ * - POST /api/reputation/calculate - Calculate single agent reputation
+ * - POST /api/reputation/batch - Calculate reputation for multiple agents
+ * - POST /api/reputation/predict - Predict score changes
+ * - GET /api/reputation/:did - Get cached reputation score
+ *
+ * Related Spec: MCP-I §5.2 (Reputation API)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BUILT_IN_REPUTATION_API_KEY = exports.DEFAULT_REPUTATION_THRESHOLD = exports.REPUTATION_ENV_VARS = exports.REPUTATION_API_LIMITS = exports.REPUTATION_API_PATHS = exports.REGISTRY_URL = exports.ReputationUpdateRequestSchema = exports.ShadowRegisterResponseSchema = exports.ShadowRegisterRequestSchema = exports.ReputationErrorResponseSchema = exports.ReputationErrorCodeSchema = exports.GetReputationResponseSchema = exports.GetReputationRequestSchema = exports.PredictScoreChangeResponseSchema = exports.PredictScoreChangeRequestSchema = exports.BatchCalculateResponseSchema = exports.BatchResultItemSchema = exports.BatchCalculateRequestSchema = exports.CalculateReputationResponseSchema = exports.CalculateReputationRequestSchema = void 0;
+exports.validateCalculateRequest = validateCalculateRequest;
+exports.validateBatchCalculateRequest = validateBatchCalculateRequest;
+exports.validatePredictRequest = validatePredictRequest;
+exports.validateGetReputationRequest = validateGetReputationRequest;
+exports.validateShadowRegisterRequest = validateShadowRegisterRequest;
+exports.validateReputationUpdateRequest = validateReputationUpdateRequest;
+const zod_1 = require("zod");
+const schemas_js_1 = require("./schemas.js");
+// ============================================================================
+// SINGLE CALCULATION API
+// ============================================================================
+/**
+ * Calculate Reputation Request Schema
+ *
+ * Request body for POST /api/reputation/calculate
+ */
+exports.CalculateReputationRequestSchema = zod_1.z.object({
+    /** Agent data for calculation */
+    agent: schemas_js_1.AgentDataSchema,
+    /** Optional calculator configuration */
+    config: schemas_js_1.CalculatorConfigSchema.optional(),
+});
+/**
+ * Calculate Reputation Response Schema
+ *
+ * Response body for POST /api/reputation/calculate
+ */
+exports.CalculateReputationResponseSchema = zod_1.z.object({
+    /** Whether the request was successful */
+    success: zod_1.z.literal(true),
+    /** Calculated reputation score */
+    data: schemas_js_1.ReputationScoreSchema,
+    /** Optional metadata */
+    metadata: zod_1.z
+        .object({
+        /** Processing time in milliseconds */
+        processingTimeMs: zod_1.z.number().nonnegative().optional(),
+        /** Calculator preset used */
+        preset: schemas_js_1.CalculatorPresetSchema.optional(),
+        /** Cache status */
+        cached: zod_1.z.boolean().optional(),
+    })
+        .optional(),
+});
+// ============================================================================
+// BATCH CALCULATION API
+// ============================================================================
+/**
+ * Batch Calculate Request Schema
+ *
+ * Request body for POST /api/reputation/batch
+ */
+exports.BatchCalculateRequestSchema = zod_1.z.object({
+    /** Array of agents to calculate reputation for */
+    agents: zod_1.z.array(schemas_js_1.AgentDataSchema).min(1).max(1000), // Limit batch size
+    /** Shared calculator configuration for all agents */
+    config: schemas_js_1.CalculatorConfigSchema.optional(),
+});
+/**
+ * Batch Result Item Schema
+ *
+ * Individual result within a batch response.
+ */
+exports.BatchResultItemSchema = zod_1.z.object({
+    /** Agent DID */
+    did: zod_1.z.string().min(1),
+    /** Calculated score (if successful) */
+    score: schemas_js_1.ReputationScoreSchema.optional(),
+    /** Error message (if failed) */
+    error: zod_1.z.string().optional(),
+    /** Whether calculation was successful */
+    success: zod_1.z.boolean(),
+});
+/**
+ * Batch Calculate Response Schema
+ *
+ * Response body for POST /api/reputation/batch
+ */
+exports.BatchCalculateResponseSchema = zod_1.z.object({
+    /** Whether the batch request was successful */
+    success: zod_1.z.literal(true),
+    /** Array of results for each agent */
+    data: zod_1.z.object({
+        /** Results for each agent */
+        results: zod_1.z.array(exports.BatchResultItemSchema),
+        /** Summary statistics */
+        summary: zod_1.z.object({
+            /** Total agents processed */
+            total: zod_1.z.number().int().nonnegative(),
+            /** Number of successful calculations */
+            successful: zod_1.z.number().int().nonnegative(),
+            /** Number of failed calculations */
+            failed: zod_1.z.number().int().nonnegative(),
+        }),
+    }),
+    /** Metadata */
+    metadata: zod_1.z
+        .object({
+        /** Total processing time in milliseconds */
+        processingTimeMs: zod_1.z.number().nonnegative().optional(),
+        /** Average time per agent */
+        avgTimePerAgentMs: zod_1.z.number().nonnegative().optional(),
+    })
+        .optional(),
+});
+// ============================================================================
+// PREDICTION API
+// ============================================================================
+/**
+ * Predict Score Change Request Schema
+ *
+ * Request body for POST /api/reputation/predict
+ */
+exports.PredictScoreChangeRequestSchema = schemas_js_1.ScoreChangePredictionRequestSchema;
+/**
+ * Predict Score Change Response Schema
+ *
+ * Response body for POST /api/reputation/predict
+ */
+exports.PredictScoreChangeResponseSchema = zod_1.z.object({
+    /** Whether the request was successful */
+    success: zod_1.z.literal(true),
+    /** Prediction data */
+    data: schemas_js_1.ScoreChangePredictionResponseSchema,
+    /** Metadata */
+    metadata: zod_1.z
+        .object({
+        /** Processing time in milliseconds */
+        processingTimeMs: zod_1.z.number().nonnegative().optional(),
+    })
+        .optional(),
+});
+// ============================================================================
+// LOOKUP API
+// ============================================================================
+/**
+ * Get Reputation Request Schema
+ *
+ * Query parameters for GET /api/reputation/:did
+ */
+exports.GetReputationRequestSchema = zod_1.z.object({
+    /** Agent DID (from URL path) */
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: 'DID must start with "did:"',
+    }),
+    /** Whether to force recalculation (bypass cache) */
+    refresh: zod_1.z.boolean().optional().default(false),
+});
+/**
+ * Get Reputation Response Schema
+ *
+ * Response body for GET /api/reputation/:did
+ */
+exports.GetReputationResponseSchema = zod_1.z.object({
+    /** Whether the request was successful */
+    success: zod_1.z.literal(true),
+    /** Reputation score data */
+    data: schemas_js_1.ReputationScoreSchema,
+    /** Metadata */
+    metadata: zod_1.z
+        .object({
+        /** Whether result was served from cache */
+        cached: zod_1.z.boolean().optional(),
+        /** Cache age in seconds (if cached) */
+        cacheAgeSeconds: zod_1.z.number().nonnegative().optional(),
+        /** When the cache entry expires (ISO 8601) */
+        cacheExpiresAt: zod_1.z.string().datetime().optional(),
+    })
+        .optional(),
+});
+// ============================================================================
+// ERROR RESPONSES
+// ============================================================================
+/**
+ * API Error Code Schema
+ *
+ * Standardized error codes for the Reputation API.
+ */
+exports.ReputationErrorCodeSchema = zod_1.z.enum([
+    "validation_error", // Invalid input data
+    "agent_not_found", // Agent DID not found
+    "calculation_error", // Error during calculation
+    "rate_limit_exceeded", // Too many requests
+    "batch_too_large", // Batch size exceeds limit
+    "internal_error", // Internal server error
+    "unauthorized", // Missing or invalid auth
+    "insufficient_data", // Not enough data for calculation
+]);
+/**
+ * API Error Response Schema
+ *
+ * Standard error response format for all Reputation API endpoints.
+ */
+exports.ReputationErrorResponseSchema = zod_1.z.object({
+    /** Whether the request was successful (always false for errors) */
+    success: zod_1.z.literal(false),
+    /** Error details */
+    error: zod_1.z.object({
+        /** Error code */
+        code: exports.ReputationErrorCodeSchema,
+        /** Human-readable error message */
+        message: zod_1.z.string().min(1),
+        /** Additional error details */
+        details: zod_1.z.record(zod_1.z.unknown()).optional(),
+        /** Validation errors (for validation_error code) */
+        validationErrors: zod_1.z
+            .array(zod_1.z.object({
+            /** Field path */
+            path: zod_1.z.string(),
+            /** Error message */
+            message: zod_1.z.string(),
+        }))
+            .optional(),
+    }),
+});
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+/**
+ * Validate calculate reputation request
+ */
+function validateCalculateRequest(data) {
+    return exports.CalculateReputationRequestSchema.safeParse(data);
+}
+/**
+ * Validate batch calculate request
+ */
+function validateBatchCalculateRequest(data) {
+    return exports.BatchCalculateRequestSchema.safeParse(data);
+}
+/**
+ * Validate predict score change request
+ */
+function validatePredictRequest(data) {
+    return exports.PredictScoreChangeRequestSchema.safeParse(data);
+}
+/**
+ * Validate get reputation request
+ */
+function validateGetReputationRequest(data) {
+    return exports.GetReputationRequestSchema.safeParse(data);
+}
+// ============================================================================
+// SHADOW REGISTRATION API (Know That AI)
+// ============================================================================
+/**
+ * Shadow Register Request Schema
+ *
+ * Used for registering did:key agents with Know That AI without public listing.
+ * Shadow registration enables reputation tracking while keeping the agent private.
+ */
+exports.ShadowRegisterRequestSchema = zod_1.z.object({
+    /** The DID to register (typically did:key) */
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: "Must be a valid DID",
+    }),
+    /** Agent type identifier */
+    agentType: zod_1.z.string().optional(),
+    /** Public key in multibase format (optional for did:key) */
+    publicKey: zod_1.z.string().optional(),
+});
+/**
+ * Shadow Register Response Schema
+ *
+ * Response from the shadow registration endpoint.
+ */
+exports.ShadowRegisterResponseSchema = zod_1.z.object({
+    /** Whether the registration was successful */
+    success: zod_1.z.boolean(),
+    /** Registration data (on success) */
+    data: zod_1.z
+        .object({
+        /** The registered DID */
+        did: zod_1.z.string(),
+        /** Whether the registration was completed */
+        registered: zod_1.z.boolean(),
+        /** Always false for shadow registration (agent is not publicly listed) */
+        isPublic: zod_1.z.literal(false),
+        /** Initial reputation score (if available) */
+        reputation: schemas_js_1.ReputationScoreSchema.optional(),
+    })
+        .optional(),
+    /** Error information (on failure) */
+    error: zod_1.z
+        .object({
+        code: zod_1.z.string(),
+        message: zod_1.z.string(),
+    })
+        .optional(),
+});
+/**
+ * Reputation Update Request Schema
+ *
+ * Used by MCP-I servers to report interaction metrics to the Reputation Engine.
+ * This is a "fire-and-forget" notification sent after tool execution.
+ */
+exports.ReputationUpdateRequestSchema = zod_1.z.object({
+    /** Total interactions to add */
+    total_interactions: zod_1.z.number().int().min(0).optional(),
+    /** Successful interactions to add */
+    successful_interactions: zod_1.z.number().int().min(0).optional(),
+    /** Failed interactions to add */
+    failed_interactions: zod_1.z.number().int().min(0).optional(),
+    /** Positive feedback received */
+    positive_feedback_received: zod_1.z.number().int().min(0).optional(),
+    /** Unique partners interacted with */
+    unique_partners: zod_1.z.number().int().min(0).optional(),
+    /** Account age in days (optional update) */
+    account_age_days: zod_1.z.number().int().min(0).optional(),
+    /** Force recalculation even if cached */
+    force_recalculate: zod_1.z.boolean().optional(),
+    /** Include detailed factors in response */
+    include_details: zod_1.z.boolean().optional(),
+});
+/**
+ * Validate shadow register request
+ */
+function validateShadowRegisterRequest(data) {
+    return exports.ShadowRegisterRequestSchema.safeParse(data);
+}
+/**
+ * Validate reputation update request
+ */
+function validateReputationUpdateRequest(data) {
+    return exports.ReputationUpdateRequestSchema.safeParse(data);
+}
+// ============================================================================
+// API CONSTANTS
+// ============================================================================
+/**
+ * Know That AI Registry URL
+ */
+exports.REGISTRY_URL = "https://knowthat.ai";
+/**
+ * API endpoint paths
+ */
+exports.REPUTATION_API_PATHS = {
+    /** Calculate single agent reputation */
+    CALCULATE: "/api/v1/reputation/calculate",
+    /** Batch calculate reputation */
+    BATCH: "/api/v1/reputation/batch",
+    /** Predict score changes */
+    PREDICT: "/api/v1/reputation/predict",
+    /** Get reputation by DID */
+    GET_BY_DID: "/api/v1/agents/:did/reputation",
+    /** Update reputation for agent (POST /api/v1/agents/{did}/reputation) */
+    REPUTATION_UPDATE: "/api/v1/agents",
+    /** Shadow registration path */
+    SHADOW_REGISTER: "/api/agents/shadow-register",
+    /** CLI registration path */
+    CLI_REGISTER: "/api/agents/cli-register",
+};
+/**
+ * API limits
+ */
+exports.REPUTATION_API_LIMITS = {
+    /** Maximum batch size */
+    MAX_BATCH_SIZE: 1000,
+    /** Default cache TTL in seconds */
+    DEFAULT_CACHE_TTL_SECONDS: 300,
+    /** Rate limit requests per minute */
+    RATE_LIMIT_PER_MINUTE: 100,
+};
+/**
+ * Environment variable names
+ */
+exports.REPUTATION_ENV_VARS = {
+    /** API key for Reputation Engine authentication */
+    API_KEY: "REPUTATION_API_KEY",
+};
+/**
+ * Default reputation threshold for trust decisions
+ */
+exports.DEFAULT_REPUTATION_THRESHOLD = 76;
+// ============================================================================
+// BUILT-IN API KEY
+// ============================================================================
+/**
+ * Built-in API key for Know That AI Reputation Engine
+ *
+ * This key is maintained by @kya-os package maintainers.
+ * Users do NOT need to configure this - registration with KTA is the gate.
+ *
+ * The key is used by ProofService to authenticate reputation updates.
+ * Only agents with `identity.kta.registered === true` will send updates.
+ *
+ * SECURITY NOTE: This is a write-only key for submitting metrics.
+ * It cannot be used to read reputation data without the agent's DID.
+ */
+/**
+ * Production API key for MCP-I framework
+ * Provisioned by Know That AI team
+ */
+exports.BUILT_IN_REPUTATION_API_KEY = "Dn/qCC/0udWcGpdnt+IzA5GpWl9JF2g/avuBxlzB";

package/dist/reputation/constants.d.ts

@@ -0,0 +1,242 @@
+/**
+ * Reputation Engine Constants
+ *
+ * Configuration constants for the reputation scoring system.
+ * These values control the behavior of the Bayesian algorithm
+ * and define standard thresholds and limits.
+ *
+ * Related Spec: MCP-I §5.1 (Reputation), CLAUDE-reputation-engine.md
+ */
+/**
+ * Prior score configuration
+ *
+ * Prior score represents the baseline reputation based on credentials
+ * before any empirical data (reviews, interactions) is considered.
+ */
+export declare const PRIOR_SCORE: {
+    /** Base prior score for all agents */
+    readonly BASE: 50;
+    /** Maximum achievable prior score */
+    readonly MAX: 80;
+    /** Minimum prior score */
+    readonly MIN: 50;
+};
+/**
+ * MCP Level bonuses to prior score
+ *
+ * Each MCP compliance level adds points to the prior score.
+ */
+export declare const MCP_LEVEL_BONUSES: {
+    /** Level 0: No MCP compliance */
+    readonly LEVEL_0: 0;
+    /** Level 1: Basic MCP compliance */
+    readonly LEVEL_1: 5;
+    /** Level 2: Standard MCP compliance */
+    readonly LEVEL_2: 10;
+    /** Level 3: Advanced MCP compliance */
+    readonly LEVEL_3: 15;
+};
+/**
+ * Credential bonuses to prior score
+ *
+ * Each verified credential adds points to the prior score.
+ */
+export declare const CREDENTIAL_BONUSES: {
+    /** Identity verification bonus */
+    readonly IDENTITY_VERIFIED: 5;
+    /** Security audit passed bonus */
+    readonly SECURITY_AUDIT: 7;
+    /** Open source bonus */
+    readonly OPEN_SOURCE: 3;
+    /** GitHub verification bonus */
+    readonly GITHUB_VERIFIED: 3;
+    /** Company email verification bonus */
+    readonly COMPANY_EMAIL: 2;
+    /** Agent age > 365 days bonus */
+    readonly AGE_OVER_YEAR: 5;
+};
+/**
+ * K values for confidence calculation
+ *
+ * Confidence is calculated as: n / (n + k)
+ * where n is the number of interactions.
+ *
+ * Higher k = slower confidence growth (more conservative)
+ * Lower k = faster confidence growth (more aggressive)
+ */
+export declare const K_VALUES: {
+    /** Testing preset: Fast confidence growth */
+    readonly TESTING: 5;
+    /** Aggressive preset: Moderate confidence growth */
+    readonly AGGRESSIVE: 10;
+    /** Conservative preset: Slow confidence growth (default) */
+    readonly CONSERVATIVE: 20;
+    /** Default k value */
+    readonly DEFAULT: 15;
+};
+/**
+ * Confidence level thresholds
+ */
+export declare const CONFIDENCE_THRESHOLDS: {
+    /** Low confidence upper bound */
+    readonly LOW: 0.25;
+    /** Medium confidence upper bound */
+    readonly MEDIUM: 0.5;
+    /** High confidence upper bound */
+    readonly HIGH: 0.75;
+};
+/**
+ * Reputation level score thresholds
+ *
+ * Maps numeric scores to human-readable reputation levels.
+ */
+export declare const REPUTATION_THRESHOLDS: {
+    /** Poor: 0-29 */
+    readonly POOR_MAX: 30;
+    /** Below Average: 30-44 */
+    readonly BELOW_AVERAGE_MAX: 45;
+    /** Average: 45-59 */
+    readonly AVERAGE_MAX: 60;
+    /** Good: 60-74 */
+    readonly GOOD_MAX: 75;
+    /** Excellent: 75-89 */
+    readonly EXCELLENT_MAX: 90;
+};
+/**
+ * Default component weights
+ *
+ * How much each factor contributes to the empirical score.
+ */
+export declare const DEFAULT_WEIGHTS: {
+    /** Weight for review-based scoring */
+    readonly REVIEWS: 0.4;
+    /** Weight for interaction-based scoring */
+    readonly INTERACTIONS: 0.3;
+    /** Weight for consistency metrics */
+    readonly CONSISTENCY: 0.3;
+};
+/**
+ * Preset configurations
+ */
+export declare const CALCULATOR_PRESETS: {
+    readonly TESTING: {
+        readonly kValue: 5;
+        readonly weights: {
+            /** Weight for review-based scoring */
+            readonly REVIEWS: 0.4;
+            /** Weight for interaction-based scoring */
+            readonly INTERACTIONS: 0.3;
+            /** Weight for consistency metrics */
+            readonly CONSISTENCY: 0.3;
+        };
+        readonly basePriorScore: 50;
+        readonly maxPriorScore: 80;
+    };
+    readonly CONSERVATIVE: {
+        readonly kValue: 20;
+        readonly weights: {
+            /** Weight for review-based scoring */
+            readonly REVIEWS: 0.4;
+            /** Weight for interaction-based scoring */
+            readonly INTERACTIONS: 0.3;
+            /** Weight for consistency metrics */
+            readonly CONSISTENCY: 0.3;
+        };
+        readonly basePriorScore: 50;
+        readonly maxPriorScore: 80;
+    };
+    readonly AGGRESSIVE: {
+        readonly kValue: 10;
+        readonly weights: {
+            /** Weight for review-based scoring */
+            readonly REVIEWS: 0.4;
+            /** Weight for interaction-based scoring */
+            readonly INTERACTIONS: 0.3;
+            /** Weight for consistency metrics */
+            readonly CONSISTENCY: 0.3;
+        };
+        readonly basePriorScore: 50;
+        readonly maxPriorScore: 80;
+    };
+};
+/**
+ * Thresholds for determining provisional scores
+ *
+ * A score is provisional when there isn't enough data
+ * for confident assessment.
+ */
+export declare const PROVISIONAL_THRESHOLDS: {
+    /** Minimum interactions for non-provisional */
+    readonly MIN_INTERACTIONS: 5;
+    /** Minimum reviews for non-provisional */
+    readonly MIN_REVIEWS: 3;
+    /** Minimum confidence for non-provisional */
+    readonly MIN_CONFIDENCE: 0.25;
+};
+/**
+ * Empirical score calculation constants
+ */
+export declare const EMPIRICAL_SCORE: {
+    /** Default score when no reviews exist */
+    readonly DEFAULT_NO_REVIEWS: 50;
+    /** Minimum average rating */
+    readonly MIN_RATING: 1;
+    /** Maximum average rating */
+    readonly MAX_RATING: 5;
+    /** Rating to score multiplier: score = (rating - 1) * 25 */
+    readonly RATING_MULTIPLIER: 25;
+};
+/**
+ * Performance targets for reputation calculation
+ */
+export declare const PERFORMANCE_TARGETS: {
+    /** Target time for single agent calculation (ms) */
+    readonly SINGLE_AGENT_MS: 1;
+    /** Target time for batch of 1000 agents (ms) */
+    readonly BATCH_1000_MS: 100;
+    /** Target time in browser/WASM (ms) */
+    readonly WASM_SINGLE_MS: 5;
+};
+/**
+ * Cache configuration
+ */
+export declare const CACHE_CONFIG: {
+    /** Default cache TTL in seconds */
+    readonly DEFAULT_TTL_SECONDS: 300;
+    /** Maximum cache TTL in seconds */
+    readonly MAX_TTL_SECONDS: 3600;
+    /** Stale-while-revalidate window in seconds */
+    readonly SWR_SECONDS: 60;
+};
+/**
+ * Rate limiting configuration
+ */
+export declare const RATE_LIMITS: {
+    /** Requests per minute for single calculations */
+    readonly SINGLE_CALCULATE_RPM: 100;
+    /** Requests per minute for batch calculations */
+    readonly BATCH_CALCULATE_RPM: 10;
+    /** Maximum batch size */
+    readonly MAX_BATCH_SIZE: 1000;
+};
+/**
+ * Reputation credential validity periods
+ */
+export declare const CREDENTIAL_VALIDITY: {
+    /** Default validity period in milliseconds (7 days) */
+    readonly DEFAULT_MS: number;
+    /** Minimum validity period in milliseconds (1 hour) */
+    readonly MIN_MS: number;
+    /** Maximum validity period in milliseconds (30 days) */
+    readonly MAX_MS: number;
+    /** Recommended freshness for scores (24 hours) */
+    readonly RECOMMENDED_FRESHNESS_MS: number;
+};
+/**
+ * Reputation contracts version
+ */
+export declare const REPUTATION_CONTRACTS_VERSION: "1.0.0";
+/**
+ * Reputation algorithm version
+ */
+export declare const REPUTATION_ALGORITHM_VERSION: "1.0.0-bayesian";