@kya-os/contracts 1.6.17 → 1.6.19

package/dist/reputation/credentials.js

@@ -0,0 +1,302 @@
+"use strict";
+/**
+ * Reputation Credential Schemas
+ *
+ * W3C Verifiable Credential schemas for reputation attestations.
+ * These credentials allow reputation scores to be cryptographically signed
+ * and verified as portable, tamper-proof attestations.
+ *
+ * Credential Types:
+ * - ReputationCredential: Attests to an agent's reputation score at a point in time
+ * - ReputationAttestation: Lighter-weight attestation for specific contexts
+ *
+ * Related Spec: MCP-I §3.1 (VC Structure), §5.3 (Reputation Credentials)
+ * W3C Reference: Verifiable Credentials Data Model 1.1
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOMMENDED_REPUTATION_FRESHNESS_MS = exports.DEFAULT_REPUTATION_CREDENTIAL_VALIDITY_MS = exports.ReputationAttestationSchema = exports.ReputationAttestationSubjectSchema = exports.ReputationCredentialSchema = exports.ReputationCredentialSubjectSchema = exports.REPUTATION_ATTESTATION_TYPE = exports.REPUTATION_CREDENTIAL_TYPE = exports.REPUTATION_CREDENTIAL_CONTEXT = void 0;
+exports.validateReputationCredential = validateReputationCredential;
+exports.validateReputationAttestation = validateReputationAttestation;
+exports.createUnsignedReputationCredential = createUnsignedReputationCredential;
+exports.extractReputationFromCredential = extractReputationFromCredential;
+exports.isReputationCredentialExpired = isReputationCredentialExpired;
+exports.isReputationCredentialStale = isReputationCredentialStale;
+const zod_1 = require("zod");
+const schemas_js_1 = require("../vc/schemas.js");
+const schemas_js_2 = require("./schemas.js");
+// ============================================================================
+// CONTEXTS
+// ============================================================================
+/**
+ * Reputation Credential JSON-LD Context
+ */
+exports.REPUTATION_CREDENTIAL_CONTEXT = "https://schemas.kya-os.ai/xmcp-i/credentials/reputation.v1.0.0.json";
+/**
+ * Reputation Credential Type
+ */
+exports.REPUTATION_CREDENTIAL_TYPE = "ReputationCredential";
+/**
+ * Reputation Attestation Type
+ */
+exports.REPUTATION_ATTESTATION_TYPE = "ReputationAttestation";
+// ============================================================================
+// CREDENTIAL SUBJECT
+// ============================================================================
+/**
+ * Reputation Credential Subject Schema
+ *
+ * The credentialSubject of a ReputationCredential contains:
+ * - id: The agent DID being attested
+ * - reputation: The complete reputation score at time of issuance
+ */
+exports.ReputationCredentialSubjectSchema = zod_1.z.object({
+    /** Subject DID (the agent whose reputation is being attested) */
+    id: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: "Subject ID must be a valid DID",
+    }),
+    /** The reputation score being attested */
+    reputation: 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: schemas_js_2.ConfidenceLevelSchema,
+        /** Human-readable reputation level */
+        level: schemas_js_2.ReputationLevelSchema,
+        /** Whether this is a provisional score */
+        isProvisional: zod_1.z.boolean(),
+        /** Timestamp when the score was calculated (ISO 8601) */
+        calculatedAt: zod_1.z.string().datetime(),
+        /** Optional score components (for transparency) */
+        components: zod_1.z
+            .object({
+            priorScore: zod_1.z.number().min(0).max(100),
+            empiricalScore: zod_1.z.number().min(0).max(100),
+            confidenceWeight: zod_1.z.number().min(0).max(1),
+            priorWeight: zod_1.z.number().min(0).max(1),
+        })
+            .optional(),
+    }),
+    /** Context in which this reputation applies */
+    context: zod_1.z
+        .object({
+        /** Scope of the reputation (e.g., 'global', 'domain-specific') */
+        scope: zod_1.z.string().default("global"),
+        /** Domain or category (e.g., 'e-commerce', 'healthcare') */
+        domain: zod_1.z.string().optional(),
+        /** Geographic region (if applicable) */
+        region: zod_1.z.string().optional(),
+    })
+        .optional(),
+});
+// ============================================================================
+// REPUTATION CREDENTIAL (W3C VC)
+// ============================================================================
+/**
+ * Reputation Credential Schema
+ *
+ * W3C Verifiable Credential for reputation attestation.
+ * This is the PRIMARY format for portable reputation scores.
+ *
+ * Structure:
+ * - @context: [...W3C VC contexts, reputation context]
+ * - type: ['VerifiableCredential', 'ReputationCredential']
+ * - issuer: Reputation authority DID (e.g., KYA platform)
+ * - issuanceDate: When the reputation was calculated
+ * - expirationDate: When this attestation expires
+ * - credentialSubject: Contains agent DID + reputation data
+ * - credentialStatus: StatusList2021Entry for revocation
+ * - proof: Ed25519Signature2020 or similar
+ */
+exports.ReputationCredentialSchema = schemas_js_1.VerifiableCredentialSchema.extend({
+    /** @context MUST include reputation context */
+    "@context": zod_1.z.array(zod_1.z.union([zod_1.z.string().url(), zod_1.z.record(zod_1.z.any())])).refine((contexts) => {
+        // First context must be W3C VC context
+        const firstContext = contexts[0];
+        return (typeof firstContext === "string" &&
+            firstContext === "https://www.w3.org/2018/credentials/v1");
+    }, {
+        message: "First @context must be W3C VC context",
+    }),
+    /** type MUST include both VerifiableCredential and ReputationCredential */
+    type: zod_1.z
+        .array(zod_1.z.string())
+        .refine((types) => types.includes("VerifiableCredential") &&
+        types.includes(exports.REPUTATION_CREDENTIAL_TYPE), {
+        message: `type must include both "VerifiableCredential" and "${exports.REPUTATION_CREDENTIAL_TYPE}"`,
+    }),
+    /** issuer is the reputation authority DID */
+    issuer: schemas_js_1.IssuerSchema,
+    /** issuanceDate is when the reputation was calculated */
+    issuanceDate: zod_1.z.string().datetime(),
+    /** expirationDate is when this attestation expires */
+    expirationDate: zod_1.z.string().datetime().optional(),
+    /** credentialSubject contains agent DID + reputation data */
+    credentialSubject: exports.ReputationCredentialSubjectSchema,
+    /** credentialStatus for StatusList2021 revocation checking */
+    credentialStatus: schemas_js_1.CredentialStatusSchema.optional(),
+    /** proof is Ed25519Signature2020 or similar */
+    proof: schemas_js_1.ProofSchema.optional(),
+});
+// ============================================================================
+// REPUTATION ATTESTATION (LIGHTWEIGHT)
+// ============================================================================
+/**
+ * Reputation Attestation Subject Schema
+ *
+ * Lighter-weight attestation for specific use cases.
+ * Contains only essential reputation information.
+ */
+exports.ReputationAttestationSubjectSchema = zod_1.z.object({
+    /** Subject DID */
+    id: zod_1.z.string().min(1),
+    /** Reputation level (human-readable) */
+    level: schemas_js_2.ReputationLevelSchema,
+    /** Numeric score (0-100) */
+    score: zod_1.z.number().min(0).max(100),
+    /** Whether the attestation issuer has high confidence */
+    highConfidence: zod_1.z.boolean(),
+    /** Specific capability or context being attested */
+    capability: zod_1.z.string().optional(),
+});
+/**
+ * Reputation Attestation Schema
+ *
+ * Lightweight attestation for embedding in other contexts.
+ */
+exports.ReputationAttestationSchema = schemas_js_1.VerifiableCredentialSchema.extend({
+    type: zod_1.z
+        .array(zod_1.z.string())
+        .refine((types) => types.includes("VerifiableCredential") &&
+        types.includes(exports.REPUTATION_ATTESTATION_TYPE), {
+        message: `type must include both "VerifiableCredential" and "${exports.REPUTATION_ATTESTATION_TYPE}"`,
+    }),
+    credentialSubject: exports.ReputationAttestationSubjectSchema,
+});
+// ============================================================================
+// CREDENTIAL HELPERS
+// ============================================================================
+/**
+ * Validate a reputation credential
+ *
+ * @param credential - The credential to validate
+ * @returns Validation result
+ */
+function validateReputationCredential(credential) {
+    return exports.ReputationCredentialSchema.safeParse(credential);
+}
+/**
+ * Validate a reputation attestation
+ *
+ * @param attestation - The attestation to validate
+ * @returns Validation result
+ */
+function validateReputationAttestation(attestation) {
+    return exports.ReputationAttestationSchema.safeParse(attestation);
+}
+/**
+ * Create an unsigned reputation credential (requires signing)
+ *
+ * @param agentDid - DID of the agent
+ * @param score - Reputation score
+ * @param issuerDid - DID of the issuing authority
+ * @param options - Optional credential options
+ * @returns Unsigned ReputationCredential
+ */
+function createUnsignedReputationCredential(agentDid, score, issuerDid, options) {
+    const now = new Date().toISOString();
+    return {
+        "@context": [
+            "https://www.w3.org/2018/credentials/v1",
+            exports.REPUTATION_CREDENTIAL_CONTEXT,
+        ],
+        id: options?.id ||
+            `urn:uuid:rep-${agentDid.replace(/[^a-zA-Z0-9]/g, "-")}-${Date.now()}`,
+        type: ["VerifiableCredential", exports.REPUTATION_CREDENTIAL_TYPE],
+        issuer: issuerDid,
+        issuanceDate: now,
+        expirationDate: options?.expirationDate,
+        credentialSubject: {
+            id: agentDid,
+            reputation: {
+                score: score.score,
+                confidence: score.confidence,
+                confidenceLevel: score.confidenceLevel,
+                level: score.level,
+                isProvisional: score.isProvisional,
+                calculatedAt: score.calculatedAt,
+                components: score.components,
+            },
+            context: options?.context,
+        },
+        credentialStatus: options?.credentialStatus,
+    };
+}
+/**
+ * Extract reputation score from a reputation credential
+ *
+ * @param credential - The reputation credential
+ * @returns Reputation score data
+ */
+function extractReputationFromCredential(credential) {
+    const rep = credential.credentialSubject.reputation;
+    return {
+        score: rep.score,
+        confidence: rep.confidence,
+        confidenceLevel: rep.confidenceLevel,
+        level: rep.level,
+        isProvisional: rep.isProvisional,
+        calculatedAt: rep.calculatedAt,
+        agentDid: credential.credentialSubject.id,
+        components: rep.components || {
+            priorScore: 50,
+            empiricalScore: rep.score,
+            confidenceWeight: rep.confidence,
+            priorWeight: 1 - rep.confidence,
+        },
+    };
+}
+/**
+ * Check if a reputation credential has expired
+ *
+ * @param credential - The credential to check
+ * @returns true if expired
+ */
+function isReputationCredentialExpired(credential) {
+    if (!credential.expirationDate) {
+        return false;
+    }
+    const expiration = new Date(credential.expirationDate);
+    const now = new Date();
+    return expiration < now;
+}
+/**
+ * Check if the reputation score in a credential is stale
+ * (calculated too long ago to be reliable)
+ *
+ * @param credential - The credential to check
+ * @param maxAgeMs - Maximum age in milliseconds (default: 24 hours)
+ * @returns true if stale
+ */
+function isReputationCredentialStale(credential, maxAgeMs = 24 * 60 * 60 * 1000 // 24 hours
+) {
+    const calculatedAt = new Date(credential.credentialSubject.reputation.calculatedAt);
+    const now = new Date();
+    const age = now.getTime() - calculatedAt.getTime();
+    return age > maxAgeMs;
+}
+// ============================================================================
+// CONSTANTS
+// ============================================================================
+/**
+ * Default reputation credential validity period (7 days)
+ */
+exports.DEFAULT_REPUTATION_CREDENTIAL_VALIDITY_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Recommended maximum age for reputation scores (24 hours)
+ */
+exports.RECOMMENDED_REPUTATION_FRESHNESS_MS = 24 * 60 * 60 * 1000;

package/dist/reputation/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Reputation Module Exports
+ *
+ * This module provides types, schemas, and utilities for the Bayesian
+ * reputation scoring system. It includes:
+ *
+ * - Core schemas for AgentData, ReputationScore, and components
+ * - API request/response schemas for REST endpoints
+ * - W3C Verifiable Credential schemas for reputation attestations
+ * - Configuration constants and presets
+ *
+ * Usage:
+ *   import { AgentDataSchema, ReputationScore } from '@kya-os/contracts/reputation';
+ *
+ * Related Spec: MCP-I §5 (Reputation)
+ */
+export * from "./schemas.js";
+export * from "./api.js";
+export * from "./credentials.js";
+export * from "./constants.js";

package/dist/reputation/index.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Reputation Module Exports
+ *
+ * This module provides types, schemas, and utilities for the Bayesian
+ * reputation scoring system. It includes:
+ *
+ * - Core schemas for AgentData, ReputationScore, and components
+ * - API request/response schemas for REST endpoints
+ * - W3C Verifiable Credential schemas for reputation attestations
+ * - Configuration constants and presets
+ *
+ * Usage:
+ *   import { AgentDataSchema, ReputationScore } from '@kya-os/contracts/reputation';
+ *
+ * Related Spec: MCP-I §5 (Reputation)
+ */
+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 });
+// Core schemas and types
+__exportStar(require("./schemas.js"), exports);
+// API schemas
+__exportStar(require("./api.js"), exports);
+// Credential schemas (W3C VC)
+__exportStar(require("./credentials.js"), exports);
+// Constants and configuration
+__exportStar(require("./constants.js"), exports);