@kya-os/cli 2.0.0 → 2.0.3

package/node_modules/@kya-os/contracts/dist/reputation/schemas.js

@@ -0,0 +1,499 @@
+"use strict";
+/**
+ * Reputation Engine Schemas
+ *
+ * Zod schemas and TypeScript types for the Bayesian reputation scoring system.
+ * These schemas define the data structures for agent reputation calculation,
+ * including input data, score outputs, and configuration options.
+ *
+ * The reputation system uses a Bayesian approach:
+ *   final_score = (1 - confidence) × prior_score + confidence × empirical_score
+ *
+ * Related Spec: MCP-I §5.1 (Reputation), CLAUDE-reputation-engine.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScoreChangePredictionResponseSchema = exports.ScoreChangePredictionRequestSchema = exports.CalculatorConfigSchema = exports.CalculatorWeightsSchema = exports.CalculatorPresetSchema = exports.ReputationScoreSchema = exports.SimpleReputationLevelSchema = exports.ReputationLevelSchema = exports.ConfidenceLevelSchema = exports.ReputationFactorsSchema = exports.ScoreComponentsSchema = exports.PartialAgentDataSchema = exports.AgentDataSchema = exports.IssueMetricsSchema = exports.ReviewMetricsSchema = exports.InteractionMetricsSchema = exports.CredentialFlagsSchema = exports.MCPLevelSchema = void 0;
+exports.toSimpleReputationLevel = toSimpleReputationLevel;
+exports.getSimpleReputationLevel = getSimpleReputationLevel;
+exports.validateAgentData = validateAgentData;
+exports.validateReputationScore = validateReputationScore;
+exports.validateCalculatorConfig = validateCalculatorConfig;
+exports.getReputationLevel = getReputationLevel;
+exports.getConfidenceLevel = getConfidenceLevel;
+exports.calculateConfidence = calculateConfidence;
+exports.isProvisionalScore = isProvisionalScore;
+const zod_1 = require("zod");
+// ============================================================================
+// MCP LEVEL & CREDENTIALS
+// ============================================================================
+/**
+ * MCP Compliance Level
+ *
+ * Levels 0-3 representing increasing levels of MCP compliance:
+ * - 0: No MCP compliance
+ * - 1: Basic MCP compliance (+5 prior points)
+ * - 2: Standard MCP compliance (+10 prior points)
+ * - 3: Advanced MCP compliance (+15 prior points)
+ */
+exports.MCPLevelSchema = zod_1.z.number().int().min(0).max(3);
+/**
+ * Credential Flags Schema
+ *
+ * Boolean flags representing various verified credentials and certifications.
+ * Each flag contributes to the prior score calculation.
+ */
+exports.CredentialFlagsSchema = zod_1.z.object({
+    /** Identity has been verified through a trusted provider */
+    identityVerified: zod_1.z.boolean().default(false),
+    /** Agent has passed a security audit */
+    securityAuditPassed: zod_1.z.boolean().default(false),
+    /** Agent source code is open source */
+    openSource: zod_1.z.boolean().default(false),
+    /** GitHub account is verified */
+    githubVerified: zod_1.z.boolean().default(false),
+    /** Company email has been verified */
+    companyEmailVerified: zod_1.z.boolean().default(false),
+});
+// ============================================================================
+// INTERACTION METRICS
+// ============================================================================
+/**
+ * Interaction Metrics Schema
+ *
+ * Quantitative metrics about an agent's interactions with other agents/users.
+ * Used in calculating empirical score and confidence level.
+ */
+exports.InteractionMetricsSchema = zod_1.z.object({
+    /** Total number of interactions */
+    totalInteractions: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of successful interactions */
+    successfulInteractions: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of failed interactions */
+    failedInteractions: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of unique interaction partners */
+    uniquePartners: zod_1.z.number().int().nonnegative().default(0),
+    /** Total transaction/interaction volume (monetary or unit-based) */
+    totalVolume: zod_1.z.number().nonnegative().default(0),
+});
+// ============================================================================
+// REVIEW METRICS
+// ============================================================================
+/**
+ * Review Metrics Schema
+ *
+ * Metrics derived from user/agent reviews.
+ * Primary source for empirical score calculation.
+ */
+exports.ReviewMetricsSchema = zod_1.z.object({
+    /** Total number of reviews received */
+    totalReviews: zod_1.z.number().int().nonnegative().default(0),
+    /** Average rating (1.0 to 5.0 scale) */
+    averageRating: zod_1.z.number().min(1).max(5).optional(),
+    /** Number of positive reviews (4+ stars) */
+    positiveReviews: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of negative reviews (2 or fewer stars) */
+    negativeReviews: zod_1.z.number().int().nonnegative().default(0),
+});
+// ============================================================================
+// ISSUE METRICS
+// ============================================================================
+/**
+ * Issue Metrics Schema
+ *
+ * Metrics related to disputes, abuse reports, and other issues.
+ * Negatively impacts reputation score.
+ */
+exports.IssueMetricsSchema = zod_1.z.object({
+    /** Number of disputes filed against this agent */
+    disputesFiled: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of disputes lost (decided against this agent) */
+    disputesLost: zod_1.z.number().int().nonnegative().default(0),
+    /** Number of verified abuse reports */
+    abuseReportsVerified: zod_1.z.number().int().nonnegative().default(0),
+});
+// ============================================================================
+// AGENT DATA (INPUT)
+// ============================================================================
+/**
+ * Agent Data Schema
+ *
+ * Complete input data structure for reputation calculation.
+ * Combines identity, credentials, interactions, reviews, and issues.
+ *
+ * This is the primary input to the reputation calculation engine.
+ */
+exports.AgentDataSchema = zod_1.z.object({
+    // === Identity ===
+    /** Decentralized Identifier (DID) of the agent */
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: 'DID must start with "did:"',
+    }),
+    /** Timestamp when the agent was registered (ISO 8601) */
+    createdAt: zod_1.z.string().datetime().optional(),
+    // === Credentials ===
+    /** MCP compliance level (0-3) */
+    mcpLevel: exports.MCPLevelSchema.default(0),
+    /** Credential flags */
+    credentials: exports.CredentialFlagsSchema.optional().default({}),
+    // === Metrics ===
+    /** Interaction metrics */
+    interactions: exports.InteractionMetricsSchema.optional().default({}),
+    /** Review metrics */
+    reviews: exports.ReviewMetricsSchema.optional().default({}),
+    /** Issue metrics */
+    issues: exports.IssueMetricsSchema.optional().default({}),
+    // === Extensibility ===
+    /** Optional metadata for custom extensions */
+    metadata: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+/**
+ * Partial Agent Data Schema
+ *
+ * For updates and partial data scenarios.
+ * All fields are optional except DID.
+ */
+exports.PartialAgentDataSchema = exports.AgentDataSchema.partial().extend({
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: 'DID must start with "did:"',
+    }),
+});
+// ============================================================================
+// SCORE COMPONENTS (OUTPUT)
+// ============================================================================
+/**
+ * Score Components Schema (Bayesian Algorithm)
+ *
+ * Breakdown of how the final score was calculated using the Bayesian algorithm.
+ * Provides transparency into the scoring algorithm.
+ *
+ * Formula: final_score = (1 - confidence) × prior_score + confidence × empirical_score
+ */
+exports.ScoreComponentsSchema = zod_1.z.object({
+    /** Prior score based on credentials (50-80 points) */
+    priorScore: zod_1.z.number().min(0).max(100),
+    /** Empirical score based on interactions and reviews (0-100 points) */
+    empiricalScore: zod_1.z.number().min(0).max(100),
+    /** Weight applied to confidence (derived from interactions) */
+    confidenceWeight: zod_1.z.number().min(0).max(1),
+    /** Weight applied to prior (1 - confidenceWeight) */
+    priorWeight: zod_1.z.number().min(0).max(1),
+});
+/**
+ * Reputation Factors Schema
+ *
+ * Detailed breakdown of factors contributing to the reputation score.
+ * This provides a human-readable explanation of why an agent has a particular score.
+ *
+ * Compatible with Know That AI API response format.
+ */
+exports.ReputationFactorsSchema = zod_1.z.object({
+    /** Score based on successful vs failed interactions (0-100) */
+    interactionScore: zod_1.z.number().min(0).max(100),
+    /** Score based on consistency of behavior over time (0-100) */
+    consistencyScore: zod_1.z.number().min(0).max(100),
+    /** Score based on account age / longevity (0-100) */
+    longevityScore: zod_1.z.number().min(0).max(100),
+    /** Score based on diversity of interaction partners (0-100) */
+    partnerDiversityScore: zod_1.z.number().min(0).max(100),
+    /** Score based on positive feedback received (0-100) */
+    feedbackScore: zod_1.z.number().min(0).max(100),
+});
+/**
+ * Confidence Level Schema
+ *
+ * Human-readable confidence categories.
+ */
+exports.ConfidenceLevelSchema = zod_1.z.enum([
+    "Low",
+    "Medium",
+    "High",
+    "VeryHigh",
+]);
+/**
+ * Reputation Level Schema (Detailed)
+ *
+ * Human-readable reputation categories based on score ranges.
+ * Uses granular levels for detailed reputation assessment.
+ */
+exports.ReputationLevelSchema = zod_1.z.enum([
+    "Unknown", // Score not calculable or insufficient data
+    "Poor", // 0-30
+    "BelowAverage", // 30-45
+    "Average", // 45-60
+    "Good", // 60-75
+    "Excellent", // 75-90
+    "Outstanding", // 90-100
+]);
+/**
+ * Simple Reputation Level Schema
+ *
+ * Human-readable reputation categories matching Know That AI API.
+ * Uses 5-tier levels for simplified reputation display.
+ */
+exports.SimpleReputationLevelSchema = zod_1.z.enum([
+    "Very Low", // 0-20
+    "Low", // 20-40
+    "Medium", // 40-60
+    "High", // 60-80
+    "Very High", // 80-100
+]);
+/**
+ * Convert detailed ReputationLevel to SimpleReputationLevel
+ *
+ * Maps the 7-tier detailed levels to the 5-tier simple levels.
+ */
+function toSimpleReputationLevel(level) {
+    switch (level) {
+        case "Unknown":
+        case "Poor":
+            return "Very Low";
+        case "BelowAverage":
+            return "Low";
+        case "Average":
+            return "Medium";
+        case "Good":
+            return "High";
+        case "Excellent":
+        case "Outstanding":
+            return "Very High";
+    }
+}
+/**
+ * Get simple reputation level from numeric score
+ *
+ * @param score - Numeric score (0-100)
+ * @returns Simple reputation level
+ */
+function getSimpleReputationLevel(score) {
+    if (score < 0 || !Number.isFinite(score))
+        return "Very Low";
+    if (score < 20)
+        return "Very Low";
+    if (score < 40)
+        return "Low";
+    if (score < 60)
+        return "Medium";
+    if (score < 80)
+        return "High";
+    return "Very High";
+}
+// ============================================================================
+// REPUTATION SCORE (OUTPUT)
+// ============================================================================
+/**
+ * Reputation Score Schema
+ *
+ * Complete output from the reputation calculation engine.
+ * Includes the final score, confidence metrics, and component breakdown.
+ */
+exports.ReputationScoreSchema = zod_1.z.object({
+    /** Final reputation score (0-100) */
+    score: zod_1.z.number().min(0).max(100),
+    /** Confidence in the score (0-1) */
+    confidence: zod_1.z.number().min(0).max(1),
+    /** Human-readable confidence level */
+    confidenceLevel: exports.ConfidenceLevelSchema,
+    /** Human-readable reputation level */
+    level: exports.ReputationLevelSchema,
+    /** Detailed score component breakdown (Bayesian algorithm) */
+    components: exports.ScoreComponentsSchema,
+    /** Optional detailed factors breakdown (for Know That AI API compatibility) */
+    factors: exports.ReputationFactorsSchema.optional(),
+    /** Whether this score is provisional (limited data) */
+    isProvisional: zod_1.z.boolean(),
+    /** Timestamp when the score was calculated (ISO 8601) */
+    calculatedAt: zod_1.z.string().datetime(),
+    /** DID of the agent this score belongs to */
+    agentDid: zod_1.z.string().min(1),
+});
+// ============================================================================
+// CALCULATOR CONFIGURATION
+// ============================================================================
+/**
+ * Calculator Preset Schema
+ *
+ * Pre-defined calculator configurations for different use cases.
+ */
+exports.CalculatorPresetSchema = zod_1.z.enum([
+    "Testing", // k=5, fast confidence growth (for testing)
+    "Conservative", // k=20, slow confidence growth (production default)
+    "Aggressive", // k=10, moderate confidence growth
+]);
+/**
+ * Calculator Weights Schema
+ *
+ * Weight distribution for scoring components.
+ * All weights should sum to 1.0.
+ */
+exports.CalculatorWeightsSchema = zod_1.z
+    .object({
+    /** Weight for review-based scoring */
+    reviews: zod_1.z.number().min(0).max(1).default(0.4),
+    /** Weight for interaction-based scoring */
+    interactions: zod_1.z.number().min(0).max(1).default(0.3),
+    /** Weight for consistency metrics */
+    consistency: zod_1.z.number().min(0).max(1).default(0.3),
+})
+    .refine((weights) => {
+    const sum = weights.reviews + weights.interactions + weights.consistency;
+    return Math.abs(sum - 1.0) < 0.001; // Allow small floating point variance
+}, {
+    message: "Weights must sum to 1.0",
+});
+/**
+ * Calculator Config Schema
+ *
+ * Configuration options for the reputation calculator.
+ */
+exports.CalculatorConfigSchema = zod_1.z.object({
+    /** K value for confidence calculation: confidence = n / (n + k) */
+    kValue: zod_1.z.number().positive().default(15),
+    /** Optional preset (overrides other settings) */
+    preset: exports.CalculatorPresetSchema.optional(),
+    /** Component weights */
+    weights: exports.CalculatorWeightsSchema.optional(),
+    /** Base prior score (default: 50) */
+    basePriorScore: zod_1.z.number().min(0).max(100).default(50),
+    /** Maximum prior score (default: 80) */
+    maxPriorScore: zod_1.z.number().min(0).max(100).default(80),
+});
+// ============================================================================
+// SCORE PREDICTION
+// ============================================================================
+/**
+ * Score Change Prediction Schema
+ *
+ * Input for predicting how a score would change given hypothetical changes.
+ */
+exports.ScoreChangePredictionRequestSchema = zod_1.z.object({
+    /** Current agent data */
+    current: exports.AgentDataSchema,
+    /** Hypothetical changes to apply */
+    changes: zod_1.z.object({
+        /** Additional reviews to add */
+        additionalReviews: zod_1.z.number().int().nonnegative().optional(),
+        /** New average rating after changes */
+        newAverageRating: zod_1.z.number().min(1).max(5).optional(),
+        /** Additional interactions */
+        additionalInteractions: zod_1.z.number().int().nonnegative().optional(),
+        /** Additional successful interactions */
+        additionalSuccessfulInteractions: zod_1.z.number().int().nonnegative().optional(),
+    }),
+    /** Optional calculator configuration */
+    config: exports.CalculatorConfigSchema.optional(),
+});
+/**
+ * Score Change Prediction Response Schema
+ */
+exports.ScoreChangePredictionResponseSchema = zod_1.z.object({
+    /** Current score */
+    currentScore: exports.ReputationScoreSchema,
+    /** Predicted score after changes */
+    predictedScore: exports.ReputationScoreSchema,
+    /** Score difference */
+    scoreDelta: zod_1.z.number(),
+    /** Confidence difference */
+    confidenceDelta: zod_1.z.number(),
+});
+// ============================================================================
+// VALIDATION HELPERS
+// ============================================================================
+/**
+ * Validate agent data
+ *
+ * @param data - The data to validate
+ * @returns Validation result
+ */
+function validateAgentData(data) {
+    return exports.AgentDataSchema.safeParse(data);
+}
+/**
+ * Validate reputation score
+ *
+ * @param score - The score to validate
+ * @returns Validation result
+ */
+function validateReputationScore(score) {
+    return exports.ReputationScoreSchema.safeParse(score);
+}
+/**
+ * Validate calculator config
+ *
+ * @param config - The config to validate
+ * @returns Validation result
+ */
+function validateCalculatorConfig(config) {
+    return exports.CalculatorConfigSchema.safeParse(config);
+}
+// ============================================================================
+// SCORE LEVEL HELPERS
+// ============================================================================
+/**
+ * Get reputation level from score
+ *
+ * @param score - Numeric score (0-100)
+ * @returns Reputation level
+ */
+function getReputationLevel(score) {
+    if (score < 0 || !Number.isFinite(score))
+        return "Unknown";
+    if (score < 30)
+        return "Poor";
+    if (score < 45)
+        return "BelowAverage";
+    if (score < 60)
+        return "Average";
+    if (score < 75)
+        return "Good";
+    if (score < 90)
+        return "Excellent";
+    return "Outstanding";
+}
+/**
+ * Get confidence level from confidence value
+ *
+ * @param confidence - Numeric confidence (0-1)
+ * @returns Confidence level
+ */
+function getConfidenceLevel(confidence) {
+    if (confidence < 0.25)
+        return "Low";
+    if (confidence < 0.5)
+        return "Medium";
+    if (confidence < 0.75)
+        return "High";
+    return "VeryHigh";
+}
+/**
+ * Calculate confidence from interaction count using the k formula
+ *
+ * confidence = n / (n + k)
+ *
+ * @param interactionCount - Number of interactions
+ * @param kValue - K value (default: 15)
+ * @returns Confidence value (0-1)
+ */
+function calculateConfidence(interactionCount, kValue = 15) {
+    if (interactionCount < 0 || kValue <= 0)
+        return 0;
+    return interactionCount / (interactionCount + kValue);
+}
+/**
+ * Check if agent data indicates a provisional score
+ * (insufficient data for high confidence)
+ *
+ * @param data - Agent data
+ * @returns true if score should be marked provisional
+ */
+function isProvisionalScore(data) {
+    const interactions = data.interactions?.totalInteractions ?? 0;
+    const reviews = data.reviews?.totalReviews ?? 0;
+    // Provisional if less than 5 interactions AND less than 3 reviews
+    return interactions < 5 && reviews < 3;
+}

package/node_modules/@kya-os/contracts/dist/review/canonicalize.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Review Verdict Canonicalization
+ *
+ * Canonical string construction and digest computation for review
+ * verdicts. Isolated from `schemas.ts` so the Zod schemas there stay free
+ * of Node.js dependencies — same split as `agent-deployment-utils.ts` vs
+ * `agent-deployment.ts` in this package — while every producer and
+ * verifier of a `ReviewVerdictBody` computes `findingsDigest` and the
+ * signing input from this one implementation. Two implementations that
+ * canonicalize differently produce signatures that verify on one side and
+ * fail on the other; that failure presents as a security incident, not a
+ * serialization bug, so do not re-derive this logic at a call site.
+ *
+ * **Node.js only** — uses `crypto.createHash`. This runs in the DIDComm
+ * reviewer/hub path (`packages/compute`), which is server-side. If an
+ * edge/browser producer or verifier is ever needed, port to
+ * `crypto.subtle.digest` and add a parity test asserting byte-identical
+ * output against this implementation (see `didToSlug`'s JSDoc in
+ * `agent-deployment-utils.ts` for the same caveat on the same tradeoff).
+ *
+ * ## Canonicalization scheme
+ *
+ * Every scalar field value is passed through `JSON.stringify`: strings are
+ * quoted and escaped (so a raw `\n`, `"`, or unicode control character in
+ * `summary`/`detail` can never appear literally in the output), and numbers
+ * print as plain digits. An **absent** optional field becomes the empty
+ * string `''`, which can never collide with a **present** field —
+ * `JSON.stringify` never returns `''` for a defined value (an empty string
+ * value stringifies to `'""'`, two characters). Because no token can ever
+ * contain a raw `\n` (JSON.stringify escapes it inside the string), joining
+ * tokens with `\n` is unambiguous: two different `findings` arrays can
+ * never produce the same token stream.
+ *
+ * Field order per finding: `path, line, severity, summary, detail`
+ * (`FINDING_FIELD_ORDER`), matching the order `ReviewFinding` is declared
+ * in `schemas.ts`.
+ *
+ * ### Worked example
+ *
+ * ```ts
+ * const findings: ReviewFinding[] = [
+ *   { path: 'src/foo.ts', line: 42, severity: 'major', summary: 'off by one' },
+ * ];
+ * // detail is absent -> its token is ''
+ * // tokens:  '"src/foo.ts"', '42', '"major"', '"off by one"', ''
+ * canonicalizeFindings(findings)
+ *   // => '"src/foo.ts"\n42\n"major"\n"off by one"\n'
+ * computeFindingsDigest(findings)
+ *   // => base64url(SHA-256('"src/foo.ts"\n42\n"major"\n"off by one"\n'))
+ * ```
+ *
+ * The verdict signing input follows the identical scheme over the fixed
+ * field order `[repo, prNumber, headSha, verdict, findingsDigest]`
+ * (`VERDICT_SIGNING_ORDER`) — see `getVerdictCanonicalSigningString`.
+ *
+ * @package @kya-os/contracts/review
+ */
+import type { ReviewFinding, ReviewSubject, ReviewVerdict } from './schemas.js';
+/**
+ * Field order for a single `ReviewFinding`. Changing this order changes
+ * every existing `findingsDigest`.
+ */
+export declare const FINDING_FIELD_ORDER: readonly ["path", "line", "severity", "summary", "detail"];
+/**
+ * Field order for the verdict signing input. Changing this order changes
+ * every existing signature.
+ */
+export declare const VERDICT_SIGNING_ORDER: readonly ["repo", "prNumber", "headSha", "verdict", "findingsDigest"];
+/**
+ * Build the canonical string for a `findings` array. Exported so callers
+ * that need to reason about the exact bytes being hashed (tests, audit
+ * tooling) do not have to re-derive it.
+ */
+export declare function canonicalizeFindings(findings: readonly ReviewFinding[]): string;
+/**
+ * Compute `findingsDigest`: base64url SHA-256 over the canonicalized
+ * `findings` array. This is the single implementation every producer and
+ * verifier of a `ReviewVerdictBody` must call.
+ */
+export declare function computeFindingsDigest(findings: readonly ReviewFinding[]): string;
+/**
+ * Build the canonical signing input for a review verdict's detached JWS:
+ * `subject.repo`, `subject.prNumber`, `subject.headSha`, `verdict`,
+ * `findingsDigest`, in that fixed order (`VERDICT_SIGNING_ORDER`). The
+ * `proof` in `ReviewVerdictBody` signs exactly this string.
+ */
+export declare function getVerdictCanonicalSigningString(subject: ReviewSubject, verdict: ReviewVerdict, findingsDigest: string): string;