@kya-os/contracts 1.0.0-alpha → 1.2.2

package/dist/test.js

@@ -1,34 +1,39 @@
+"use strict";
 /**
  * Test infrastructure types and schemas for XMCP-I
  *
  * This module provides types and utilities for testing XMCP-I applications
  * without hitting external services like KTA.
  */
-import { z } from "zod";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_ERROR_CODES = exports.TEST_KEY_IDS = exports.TEST_DIDS = exports.LocalVerificationResultSchema = exports.MockIdentityProviderConfigSchema = exports.MockKTAFailureTypeSchema = exports.MockDelegationStatusSchema = exports.MockIdentitySchema = exports.TestEnvironmentSchema = void 0;
+exports.isTestEnvironment = isTestEnvironment;
+exports.getTestSeed = getTestSeed;
+const zod_1 = require("zod");
 /**
  * Test environment configuration
  */
-export const TestEnvironmentSchema = z.object({
-    mode: z.literal("test"),
-    seed: z.string().optional(),
-    deterministicKeys: z.boolean().default(true),
-    skipKTACalls: z.boolean().default(true),
+exports.TestEnvironmentSchema = zod_1.z.object({
+    mode: zod_1.z.literal("test"),
+    seed: zod_1.z.string().optional(),
+    deterministicKeys: zod_1.z.boolean().default(true),
+    skipKTACalls: zod_1.z.boolean().default(true),
 });
 /**
  * Mock identity configuration for testing
  */
-export const MockIdentitySchema = z.object({
-    did: z.string(),
-    keyId: z.string(),
-    privateKey: z.string(),
-    publicKey: z.string(),
-    createdAt: z.string(),
-    lastRotated: z.string(),
+exports.MockIdentitySchema = zod_1.z.object({
+    did: zod_1.z.string(),
+    keyId: zod_1.z.string(),
+    privateKey: zod_1.z.string(),
+    publicKey: zod_1.z.string(),
+    createdAt: zod_1.z.string(),
+    lastRotated: zod_1.z.string(),
 });
 /**
  * Mock delegation status for testing
  */
-export const MockDelegationStatusSchema = z.enum([
+exports.MockDelegationStatusSchema = zod_1.z.enum([
     "active",
     "revoked",
     "pending",
@@ -36,7 +41,7 @@ export const MockDelegationStatusSchema = z.enum([
 /**
  * Mock KTA failure scenarios for testing
  */
-export const MockKTAFailureTypeSchema = z.enum([
+exports.MockKTAFailureTypeSchema = zod_1.z.enum([
     "network",
     "auth",
     "invalid",
@@ -45,48 +50,48 @@ export const MockKTAFailureTypeSchema = z.enum([
 /**
  * Mock identity provider configuration
  */
-export const MockIdentityProviderConfigSchema = z.object({
-    identities: z.record(z.string(), MockIdentitySchema),
-    delegations: z.record(z.string(), MockDelegationStatusSchema),
-    ktaFailures: z.array(MockKTAFailureTypeSchema).default([]),
-    deterministicSeed: z.string().optional(),
+exports.MockIdentityProviderConfigSchema = zod_1.z.object({
+    identities: zod_1.z.record(zod_1.z.string(), exports.MockIdentitySchema),
+    delegations: zod_1.z.record(zod_1.z.string(), exports.MockDelegationStatusSchema),
+    ktaFailures: zod_1.z.array(exports.MockKTAFailureTypeSchema).default([]),
+    deterministicSeed: zod_1.z.string().optional(),
 });
 /**
  * Local verification result for offline testing
  */
-export const LocalVerificationResultSchema = z.object({
-    valid: z.boolean(),
-    did: z.string().optional(),
-    keyId: z.string().optional(),
-    signature: z.object({
-        valid: z.boolean(),
-        algorithm: z.string(),
-        error: z.string().optional(),
+exports.LocalVerificationResultSchema = zod_1.z.object({
+    valid: zod_1.z.boolean(),
+    did: zod_1.z.string().optional(),
+    keyId: zod_1.z.string().optional(),
+    signature: zod_1.z.object({
+        valid: zod_1.z.boolean(),
+        algorithm: zod_1.z.string(),
+        error: zod_1.z.string().optional(),
     }),
-    proof: z.object({
-        valid: z.boolean(),
-        structure: z.boolean(),
-        timestamps: z.boolean(),
-        hashes: z.boolean(),
-        error: z.string().optional(),
+    proof: zod_1.z.object({
+        valid: zod_1.z.boolean(),
+        structure: zod_1.z.boolean(),
+        timestamps: zod_1.z.boolean(),
+        hashes: zod_1.z.boolean(),
+        error: zod_1.z.string().optional(),
     }),
-    session: z.object({
-        valid: z.boolean(),
-        expired: z.boolean(),
-        error: z.string().optional(),
+    session: zod_1.z.object({
+        valid: zod_1.z.boolean(),
+        expired: zod_1.z.boolean(),
+        error: zod_1.z.string().optional(),
     }),
-    errors: z.array(z.string()).default([]),
-    warnings: z.array(z.string()).default([]),
+    errors: zod_1.z.array(zod_1.z.string()).default([]),
+    warnings: zod_1.z.array(zod_1.z.string()).default([]),
 });
 /**
  * Test DID and Key ID constants
  */
-export const TEST_DIDS = {
+exports.TEST_DIDS = {
     AGENT_1: "did:test:agent-1",
     AGENT_2: "did:test:agent-2",
     VERIFIER_1: "did:test:verifier-1",
 };
-export const TEST_KEY_IDS = {
+exports.TEST_KEY_IDS = {
     KEY_TEST_1: "key-test-1",
     KEY_TEST_2: "key-test-2",
     KEY_VERIFIER_1: "key-verifier-1",
@@ -94,19 +99,19 @@ export const TEST_KEY_IDS = {
 /**
  * Test environment detection
  */
-export function isTestEnvironment() {
+function isTestEnvironment() {
     return process.env.XMCP_ENV === "test";
 }
 /**
  * Get test seed from environment or test name
  */
-export function getTestSeed(testName) {
+function getTestSeed(testName) {
     return process.env.XMCP_TEST_SEED || testName || "default-test-seed";
 }
 /**
  * Error codes for test infrastructure
  */
-export const TEST_ERROR_CODES = {
+exports.TEST_ERROR_CODES = {
     MOCK_KTA_FAILURE: "XMCP_I_TEST_MOCK_KTA_FAILURE",
     DETERMINISTIC_KEY_GENERATION_FAILED: "XMCP_I_TEST_DETERMINISTIC_KEY_FAILED",
     LOCAL_VERIFICATION_FAILED: "XMCP_I_TEST_LOCAL_VERIFICATION_FAILED",

package/dist/tlkrc/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * TLKRC Module Exports
+ */
+export * from './rotation.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tlkrc/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * TLKRC Module Exports
+ */
+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("./rotation.js"), exports);
+//# sourceMappingURL=index.js.map

package/dist/tlkrc/rotation.d.ts

@@ -0,0 +1,246 @@
+/**
+ * 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
+ */
+import { z } from '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`.
+ */
+export declare const RotationEventSchema: z.ZodEffects<z.ZodObject<{
+    /** DID of the issuer performing the rotation */
+    issuerDid: z.ZodString;
+    /** Previous key ID being rotated out */
+    prevKeyId: z.ZodString;
+    /** New key ID being rotated in */
+    nextKeyId: z.ZodString;
+    /** Timestamp when new key becomes effective (Unix seconds) */
+    effectiveAt: z.ZodNumber;
+    /** Timestamp when event was issued (Unix seconds) */
+    issuedAt: z.ZodNumber;
+    /** Sequence number (monotonically increasing) */
+    seq: z.ZodNumber;
+    /** Hash of previous rotation event (null for first rotation) */
+    prevEventHash: z.ZodOptional<z.ZodString>;
+    /** Signature over the event (using prevKeyId) */
+    signature: z.ZodString;
+    /** Optional metadata */
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, "strip", z.ZodTypeAny, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    prevEventHash?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+}, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    prevEventHash?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+}>, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    prevEventHash?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+}, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    prevEventHash?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+}>;
+export type RotationEvent = z.infer<typeof RotationEventSchema>;
+/**
+ * Rotation Chain
+ *
+ * Represents a chain of rotation events
+ */
+export declare const RotationChainSchema: z.ZodObject<{
+    /** Issuer DID */
+    issuerDid: z.ZodString;
+    /** All rotation events in order */
+    events: z.ZodArray<z.ZodEffects<z.ZodObject<{
+        /** DID of the issuer performing the rotation */
+        issuerDid: z.ZodString;
+        /** Previous key ID being rotated out */
+        prevKeyId: z.ZodString;
+        /** New key ID being rotated in */
+        nextKeyId: z.ZodString;
+        /** Timestamp when new key becomes effective (Unix seconds) */
+        effectiveAt: z.ZodNumber;
+        /** Timestamp when event was issued (Unix seconds) */
+        issuedAt: z.ZodNumber;
+        /** Sequence number (monotonically increasing) */
+        seq: z.ZodNumber;
+        /** Hash of previous rotation event (null for first rotation) */
+        prevEventHash: z.ZodOptional<z.ZodString>;
+        /** Signature over the event (using prevKeyId) */
+        signature: z.ZodString;
+        /** Optional metadata */
+        metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    }, "strip", z.ZodTypeAny, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        prevEventHash?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+    }, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        prevEventHash?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+    }>, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        prevEventHash?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+    }, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        prevEventHash?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+    }>, "many">;
+    /** Current active key ID */
+    currentKeyId: z.ZodString;
+    /** Whether chain is valid */
+    valid: z.ZodBoolean;
+    /** Optional validation errors */
+    errors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    valid: boolean;
+    issuerDid: string;
+    events: {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        prevEventHash?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+    }[];
+    currentKeyId: string;
+    errors?: string[] | undefined;
+}, {
+    valid: boolean;
+    issuerDid: string;
+    events: {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        prevEventHash?: string | undefined;
+        metadata?: Record<string, any> | undefined;
+    }[];
+    currentKeyId: string;
+    errors?: string[] | undefined;
+}>;
+export type RotationChain = z.infer<typeof RotationChainSchema>;
+/**
+ * Validation Helpers
+ */
+/**
+ * Validate a rotation event
+ *
+ * @param event - The event to validate
+ * @returns Validation result
+ */
+export declare function validateRotationEvent(event: unknown): z.SafeParseReturnType<{
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    prevEventHash?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+}, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    prevEventHash?: string | undefined;
+    metadata?: Record<string, any> | undefined;
+}>;
+/**
+ * Validate rotation chain integrity
+ *
+ * @param chain - The chain to validate
+ * @returns true if chain is valid
+ */
+export declare function isRotationChainValid(chain: RotationChain): boolean;
+/**
+ * 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
+ */
+export declare function getActiveKeyAt(chain: RotationChain, timestamp: number): string | null;
+/**
+ * Constants
+ */
+/**
+ * Default grace period for dual-key validity (24 hours)
+ */
+export declare const DEFAULT_GRACE_PERIOD_SEC: number;
+/**
+ * Maximum reasonable grace period (30 days)
+ */
+export declare const MAX_GRACE_PERIOD_SEC: number;
+//# sourceMappingURL=rotation.d.ts.map

package/dist/tlkrc/rotation.js

@@ -0,0 +1,127 @@
+"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;
+//# sourceMappingURL=rotation.js.map

package/dist/utils/validation.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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;
+    keyId: (value: string) => boolean;
+    url: (value: string) => boolean;
+    projectName: (value: string) => boolean;
+};
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.js

@@ -0,0 +1,70 @@
+"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),
+    keyId: (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,
+};
+//# sourceMappingURL=validation.js.map

package/dist/vc/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Verifiable Credentials Module Exports
+ *
+ * W3C Verifiable Credentials types, schemas, and utilities
+ */
+export * from './schemas.js';
+export * from './statuslist.js';
+//# sourceMappingURL=index.d.ts.map