@kya-os/contracts 1.3.5 → 1.4.0

package/dist/did/types.js

@@ -0,0 +1,70 @@
+"use strict";
+/**
+ * DID Document Types (W3C Compliant)
+ *
+ * These types conform to the W3C DID Core specification and provide
+ * TypeScript parity with the Python implementation.
+ *
+ * Related Spec: MCP-I §2.1, §2.3
+ * Python Reference: DID-Documentation.md, DID-Service.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isVerificationMethod = isVerificationMethod;
+exports.isVerificationMethodReference = isVerificationMethodReference;
+exports.isDidDocument = isDidDocument;
+exports.extractDidMethod = extractDidMethod;
+exports.extractKeyId = extractKeyId;
+/**
+ * Helper type guards
+ */
+/**
+ * Type guard to check if a value is a VerificationMethod
+ */
+function isVerificationMethod(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string' &&
+        typeof value.type === 'string' &&
+        typeof value.controller === 'string');
+}
+/**
+ * Type guard to check if a value is a string reference to a verification method
+ */
+function isVerificationMethodReference(value) {
+    return typeof value === 'string';
+}
+/**
+ * Type guard to check if a DID Document is valid (basic structural check)
+ */
+function isDidDocument(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        typeof value.id === 'string' &&
+        value.id.startsWith('did:'));
+}
+/**
+ * Extract DID method from a DID string
+ *
+ * @param did - The DID string (e.g., "did:key:z6Mk...")
+ * @returns The method name (e.g., "key") or null if invalid
+ */
+function extractDidMethod(did) {
+    const parts = did.split(':');
+    if (parts.length < 3 || parts[0] !== 'did') {
+        return null;
+    }
+    return parts[1];
+}
+/**
+ * Extract key ID from a DID URL
+ *
+ * @param didUrl - A DID URL with fragment (e.g., "did:key:z6Mk...#key-1")
+ * @returns The fragment part (e.g., "key-1") or null if no fragment
+ */
+function extractKeyId(didUrl) {
+    const hashIndex = didUrl.indexOf('#');
+    if (hashIndex === -1) {
+        return null;
+    }
+    return didUrl.substring(hashIndex + 1);
+}

package/dist/env/constants.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Environment Constants
+ *
+ * System-wide constants for algorithms, TTLs, and limits
+ *
+ * Related Spec: MCP-I §8
+ * Python Reference: All service documentation files
+ */
+/**
+ * Hash algorithm for cryptographic operations
+ */
+export declare const HASH_ALGO: "SHA-256";
+/**
+ * Supported signature algorithms
+ */
+export declare const SIG_ALGOS: readonly ["Ed25519", "ES256"];
+export type SignatureAlgorithm = (typeof SIG_ALGOS)[number];
+/**
+ * Nonce TTL in milliseconds (5 minutes)
+ */
+export declare const NONCE_TTL_MS: number;
+/**
+ * Resume token TTL in milliseconds (10 minutes)
+ */
+export declare const RESUME_TOKEN_TTL_MS: number;
+/**
+ * StatusList2021 cache TTL in seconds (1 minute)
+ */
+export declare const STATUSLIST_CACHE_SEC = 60;
+/**
+ * DID resolution timeout in milliseconds (500ms)
+ */
+export declare const DID_RESOLVE_TIMEOUT_MS = 500;
+/**
+ * Default session TTL in minutes (30 minutes)
+ */
+export declare const DEFAULT_SESSION_TTL_MINUTES = 30;
+/**
+ * Maximum timestamp skew in seconds (2 minutes)
+ */
+export declare const MAX_TIMESTAMP_SKEW_SEC = 120;
+/**
+ * Maximum delegation chain depth
+ */
+export declare const MAX_DELEGATION_CHAIN_DEPTH = 10;
+/**
+ * Maximum status list size (1 million entries)
+ */
+export declare const MAX_STATUSLIST_SIZE = 1000000;
+/**
+ * Proof archive TTL in seconds (30 days)
+ */
+export declare const PROOF_ARCHIVE_TTL_SEC: number;
+/**
+ * Key rotation grace period in seconds (24 hours)
+ */
+export declare const KEY_ROTATION_GRACE_PERIOD_SEC: number;

package/dist/env/constants.js

@@ -0,0 +1,59 @@
+"use strict";
+/**
+ * Environment Constants
+ *
+ * System-wide constants for algorithms, TTLs, and limits
+ *
+ * Related Spec: MCP-I §8
+ * Python Reference: All service documentation files
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KEY_ROTATION_GRACE_PERIOD_SEC = exports.PROOF_ARCHIVE_TTL_SEC = exports.MAX_STATUSLIST_SIZE = exports.MAX_DELEGATION_CHAIN_DEPTH = exports.MAX_TIMESTAMP_SKEW_SEC = exports.DEFAULT_SESSION_TTL_MINUTES = exports.DID_RESOLVE_TIMEOUT_MS = exports.STATUSLIST_CACHE_SEC = exports.RESUME_TOKEN_TTL_MS = exports.NONCE_TTL_MS = exports.SIG_ALGOS = exports.HASH_ALGO = void 0;
+/**
+ * Hash algorithm for cryptographic operations
+ */
+exports.HASH_ALGO = 'SHA-256';
+/**
+ * Supported signature algorithms
+ */
+exports.SIG_ALGOS = ['Ed25519', 'ES256'];
+/**
+ * Nonce TTL in milliseconds (5 minutes)
+ */
+exports.NONCE_TTL_MS = 5 * 60 * 1000;
+/**
+ * Resume token TTL in milliseconds (10 minutes)
+ */
+exports.RESUME_TOKEN_TTL_MS = 10 * 60 * 1000;
+/**
+ * StatusList2021 cache TTL in seconds (1 minute)
+ */
+exports.STATUSLIST_CACHE_SEC = 60;
+/**
+ * DID resolution timeout in milliseconds (500ms)
+ */
+exports.DID_RESOLVE_TIMEOUT_MS = 500;
+/**
+ * Default session TTL in minutes (30 minutes)
+ */
+exports.DEFAULT_SESSION_TTL_MINUTES = 30;
+/**
+ * Maximum timestamp skew in seconds (2 minutes)
+ */
+exports.MAX_TIMESTAMP_SKEW_SEC = 120;
+/**
+ * Maximum delegation chain depth
+ */
+exports.MAX_DELEGATION_CHAIN_DEPTH = 10;
+/**
+ * Maximum status list size (1 million entries)
+ */
+exports.MAX_STATUSLIST_SIZE = 1000000;
+/**
+ * Proof archive TTL in seconds (30 days)
+ */
+exports.PROOF_ARCHIVE_TTL_SEC = 30 * 24 * 60 * 60;
+/**
+ * Key rotation grace period in seconds (24 hours)
+ */
+exports.KEY_ROTATION_GRACE_PERIOD_SEC = 24 * 60 * 60;

package/dist/env/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Environment Constants Module
+ */
+export * from './constants.js';

package/dist/env/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Environment Constants Module
+ */
+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("./constants.js"), exports);

package/dist/handshake.d.ts

@@ -1,4 +1,7 @@
 import { z } from "zod";
+/**
+ * Handshake and session management schemas
+ */
 export declare const HandshakeRequestSchema: z.ZodObject<{
     nonce: z.ZodString;
     audience: z.ZodString;
@@ -56,11 +59,28 @@ export declare const NonceCacheEntrySchema: z.ZodObject<{
 export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
 export type SessionContext = z.infer<typeof SessionContextSchema>;
 export type NonceCacheEntry = z.infer<typeof NonceCacheEntrySchema>;
+/**
+ * Nonce cache interface for replay prevention
+ */
 export interface NonceCache {
+    /**
+     * Check if a nonce exists in the cache
+     */
     has(nonce: string): Promise<boolean>;
+    /**
+     * Add a nonce to the cache with TTL
+     * MUST ensure atomic add-if-absent semantics for replay prevention
+     */
     add(nonce: string, ttl: number): Promise<void>;
+    /**
+     * Clean up expired entries
+     * Should be safe to call frequently and should be no-op for backends that auto-expire
+     */
     cleanup(): Promise<void>;
 }
+/**
+ * Configuration for nonce cache implementations
+ */
 export declare const NonceCacheConfigSchema: z.ZodObject<{
     type: z.ZodOptional<z.ZodEnum<["memory", "redis", "dynamodb", "cloudflare-kv"]>>;
     redis: z.ZodOptional<z.ZodObject<{

package/dist/handshake.js

@@ -2,11 +2,14 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NONCE_LENGTH_BYTES = exports.DEFAULT_TIMESTAMP_SKEW_SECONDS = exports.DEFAULT_SESSION_TTL_MINUTES = exports.NonceCacheConfigSchema = exports.NonceCacheEntrySchema = exports.SessionContextSchema = exports.HandshakeRequestSchema = void 0;
 const zod_1 = require("zod");
+/**
+ * Handshake and session management schemas
+ */
 exports.HandshakeRequestSchema = zod_1.z.object({
     nonce: zod_1.z.string().min(1),
     audience: zod_1.z.string().min(1),
     timestamp: zod_1.z.number().int().positive(),
-    agentDid: zod_1.z.string().startsWith("did:").optional(),
+    agentDid: zod_1.z.string().startsWith("did:").optional(), // Agent DID for delegation verification
 });
 exports.SessionContextSchema = zod_1.z.object({
     sessionId: zod_1.z.string().min(1),
@@ -16,12 +19,15 @@ exports.SessionContextSchema = zod_1.z.object({
     createdAt: zod_1.z.number().int().positive(),
     lastActivity: zod_1.z.number().int().positive(),
     ttlMinutes: zod_1.z.number().int().positive().default(30),
-    agentDid: zod_1.z.string().optional(),
+    agentDid: zod_1.z.string().optional(), // Agent DID for delegation verification
 });
 exports.NonceCacheEntrySchema = zod_1.z.object({
     sessionId: zod_1.z.string().min(1),
     expiresAt: zod_1.z.number().int().positive(),
 });
+/**
+ * Configuration for nonce cache implementations
+ */
 exports.NonceCacheConfigSchema = zod_1.z.object({
     type: zod_1.z.enum(["memory", "redis", "dynamodb", "cloudflare-kv"]).optional(),
     redis: zod_1.z
@@ -45,6 +51,7 @@ exports.NonceCacheConfigSchema = zod_1.z.object({
     })
         .optional(),
 });
+// Constants
 exports.DEFAULT_SESSION_TTL_MINUTES = 30;
 exports.DEFAULT_TIMESTAMP_SKEW_SECONDS = 120;
-exports.NONCE_LENGTH_BYTES = 16;
+exports.NONCE_LENGTH_BYTES = 16; // 128-bit

package/dist/index.d.ts

@@ -1,3 +1,17 @@
+/**
+ * @kya-os/contracts - Shared types and schemas for XMCP-I ecosystem
+ *
+ * This package provides a single source of truth for all types and contracts
+ * used across the XMCP-I ecosystem, including runtime, CLI, verifier, and registry.
+ *
+ * NOTE: Some exports may conflict. Use subpath imports for new modules:
+ * - import { ... } from '@kya-os/contracts/did'
+ * - import { ... } from '@kya-os/contracts/vc'
+ * - import { ... } from '@kya-os/contracts/delegation'
+ * - import { ... } from '@kya-os/contracts/runtime'
+ * - import { ... } from '@kya-os/contracts/tlkrc'
+ * - import { ... } from '@kya-os/contracts/env'
+ */
 export * from "./handshake.js";
 export * from "./proof.js";
 export * from "./verifier.js";

package/dist/index.js

@@ -1,4 +1,18 @@
 "use strict";
+/**
+ * @kya-os/contracts - Shared types and schemas for XMCP-I ecosystem
+ *
+ * This package provides a single source of truth for all types and contracts
+ * used across the XMCP-I ecosystem, including runtime, CLI, verifier, and registry.
+ *
+ * NOTE: Some exports may conflict. Use subpath imports for new modules:
+ * - import { ... } from '@kya-os/contracts/did'
+ * - import { ... } from '@kya-os/contracts/vc'
+ * - import { ... } from '@kya-os/contracts/delegation'
+ * - import { ... } from '@kya-os/contracts/runtime'
+ * - import { ... } from '@kya-os/contracts/tlkrc'
+ * - import { ... } from '@kya-os/contracts/env'
+ */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -15,6 +29,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SUPPORTED_XMCP_I_VERSION = exports.CONTRACTS_VERSION = void 0;
+// Legacy exports (maintain backward compatibility)
 __exportStar(require("./handshake.js"), exports);
 __exportStar(require("./proof.js"), exports);
 __exportStar(require("./verifier.js"), exports);
@@ -22,7 +37,20 @@ __exportStar(require("./registry.js"), exports);
 __exportStar(require("./cli.js"), exports);
 __exportStar(require("./test.js"), exports);
 __exportStar(require("./utils/validation.js"), exports);
+// W3C VC and Delegation exports (for mcp-i-core compatibility)
 __exportStar(require("./vc/index.js"), exports);
 __exportStar(require("./delegation/index.js"), exports);
+// Version information
 exports.CONTRACTS_VERSION = "1.2.1";
 exports.SUPPORTED_XMCP_I_VERSION = "^1.0.0";
+// New MCP-I contract types are available via subpath imports:
+// import { ... } from '@kya-os/contracts/did'
+// import { ... } from '@kya-os/contracts/vc'
+// import { ... } from '@kya-os/contracts/delegation'
+// import { ... } from '@kya-os/contracts/runtime'
+// import { ... } from '@kya-os/contracts/tlkrc'
+// import { ... } from '@kya-os/contracts/env'
+// import { ... } from '@kya-os/contracts/agentshield-api'
+// import { ... } from '@kya-os/contracts/tool-protection'
+// import { ... } from '@kya-os/contracts/well-known'
+//# sourceMappingURL=index.js.map

package/dist/proof/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Proof Module Exports
+ *
+ * Note: This module exports proof record and signing spec types.
+ * The existing proof.ts file with DetachedProofSchema is separate.
+ */
+export * from './signing-spec.js';
+export * from './proof-record.js';

package/dist/proof/index.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Proof Module Exports
+ *
+ * Note: This module exports proof record and signing spec types.
+ * The existing proof.ts file with DetachedProofSchema is separate.
+ */
+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("./signing-spec.js"), exports);
+__exportStar(require("./proof-record.js"), exports);