@kya-os/contracts 1.3.5 → 1.4.0

package/dist/runtime/headers.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Runtime Header Contracts
+ *
+ * Header contracts for downstream services
+ *
+ * Related Spec: MCP-I §6
+ * Python Reference: Core-Documentation.md
+ */
+/**
+ * Downstream Headers Interface
+ *
+ * Headers passed to downstream services after verification
+ */
+export interface DownstreamHeaders {
+    /** DID of the verified agent */
+    'X-Agent-DID': string;
+    /** Optional delegation ID */
+    'X-Delegation-Id'?: string;
+    /** Optional delegation chain (format: vc_id>del_id>...) */
+    'X-Delegation-Chain'?: string;
+    /** Proof ID for audit trail */
+    'X-MCPI-Proof-Id': string;
+    /** Optional CRISP spend info (JSON string: {unit, delta, remaining}) */
+    'X-CRISP-Spend'?: string;
+    /** Optional session ID */
+    'X-Session-Id'?: string;
+    /** Optional scopes */
+    'X-Scopes'?: string;
+}
+/**
+ * Header names as constants for type safety
+ */
+export declare const DOWNSTREAM_HEADER_NAMES: Readonly<{
+    readonly AGENT_DID: "X-Agent-DID";
+    readonly DELEGATION_ID: "X-Delegation-Id";
+    readonly DELEGATION_CHAIN: "X-Delegation-Chain";
+    readonly PROOF_ID: "X-MCPI-Proof-Id";
+    readonly CRISP_SPEND: "X-CRISP-Spend";
+    readonly SESSION_ID: "X-Session-Id";
+    readonly SCOPES: "X-Scopes";
+}>;
+/**
+ * CRISP Spend Info
+ *
+ * Structure for X-CRISP-Spend header value
+ */
+export interface CrispSpendInfo {
+    /** Unit of spending */
+    unit: 'USD' | 'ops' | 'points';
+    /** Amount spent in this request */
+    delta?: number;
+    /** Remaining budget */
+    remaining?: number;
+}
+/**
+ * Helper to serialize CRISP spend info to header value
+ *
+ * @param info - CRISP spend info
+ * @returns JSON string for header
+ */
+export declare function serializeCrispSpend(info: CrispSpendInfo): string;
+/**
+ * Helper to parse CRISP spend info from header value
+ *
+ * @param headerValue - JSON string from header
+ * @returns Parsed CRISP spend info or null if invalid
+ */
+export declare function parseCrispSpend(headerValue: string): CrispSpendInfo | null;
+/**
+ * Helper to create downstream headers
+ *
+ * @param config - Configuration for headers
+ * @returns DownstreamHeaders object
+ */
+export declare function createDownstreamHeaders(config: {
+    agentDid: string;
+    proofId: string;
+    delegationId?: string;
+    delegationChain?: string;
+    crispSpend?: CrispSpendInfo;
+    sessionId?: string;
+    scopes?: string[];
+}): DownstreamHeaders;

package/dist/runtime/headers.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Runtime Header Contracts
+ *
+ * Header contracts for downstream services
+ *
+ * Related Spec: MCP-I §6
+ * Python Reference: Core-Documentation.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DOWNSTREAM_HEADER_NAMES = void 0;
+exports.serializeCrispSpend = serializeCrispSpend;
+exports.parseCrispSpend = parseCrispSpend;
+exports.createDownstreamHeaders = createDownstreamHeaders;
+/**
+ * Header names as constants for type safety
+ */
+exports.DOWNSTREAM_HEADER_NAMES = Object.freeze({
+    AGENT_DID: 'X-Agent-DID',
+    DELEGATION_ID: 'X-Delegation-Id',
+    DELEGATION_CHAIN: 'X-Delegation-Chain',
+    PROOF_ID: 'X-MCPI-Proof-Id',
+    CRISP_SPEND: 'X-CRISP-Spend',
+    SESSION_ID: 'X-Session-Id',
+    SCOPES: 'X-Scopes',
+});
+/**
+ * Helper to serialize CRISP spend info to header value
+ *
+ * @param info - CRISP spend info
+ * @returns JSON string for header
+ */
+function serializeCrispSpend(info) {
+    return JSON.stringify(info);
+}
+/**
+ * Helper to parse CRISP spend info from header value
+ *
+ * @param headerValue - JSON string from header
+ * @returns Parsed CRISP spend info or null if invalid
+ */
+function parseCrispSpend(headerValue) {
+    try {
+        const parsed = JSON.parse(headerValue);
+        if (parsed && typeof parsed.unit === 'string') {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Helper to create downstream headers
+ *
+ * @param config - Configuration for headers
+ * @returns DownstreamHeaders object
+ */
+function createDownstreamHeaders(config) {
+    const headers = {
+        'X-Agent-DID': config.agentDid,
+        'X-MCPI-Proof-Id': config.proofId,
+    };
+    if (config.delegationId) {
+        headers['X-Delegation-Id'] = config.delegationId;
+    }
+    if (config.delegationChain) {
+        headers['X-Delegation-Chain'] = config.delegationChain;
+    }
+    if (config.crispSpend) {
+        headers['X-CRISP-Spend'] = serializeCrispSpend(config.crispSpend);
+    }
+    if (config.sessionId) {
+        headers['X-Session-Id'] = config.sessionId;
+    }
+    if (config.scopes && config.scopes.length > 0) {
+        headers['X-Scopes'] = config.scopes.join(',');
+    }
+    return headers;
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Runtime Module Exports
+ */
+export * from './errors.js';
+export * from './headers.js';

package/dist/runtime/index.js

@@ -0,0 +1,21 @@
+"use strict";
+/**
+ * Runtime 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("./errors.js"), exports);
+__exportStar(require("./headers.js"), exports);

package/dist/test.d.ts

@@ -1,4 +1,13 @@
+/**
+ * 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";
+/**
+ * Test environment configuration
+ */
 export declare const TestEnvironmentSchema: z.ZodObject<{
     mode: z.ZodLiteral<"test">;
     seed: z.ZodOptional<z.ZodString>;
@@ -16,6 +25,9 @@ export declare const TestEnvironmentSchema: z.ZodObject<{
     skipKTACalls?: boolean | undefined;
 }>;
 export type TestEnvironment = z.infer<typeof TestEnvironmentSchema>;
+/**
+ * Mock identity configuration for testing
+ */
 export declare const MockIdentitySchema: z.ZodObject<{
     did: z.ZodString;
     kid: z.ZodString;
@@ -39,10 +51,19 @@ export declare const MockIdentitySchema: z.ZodObject<{
     lastRotated?: string | undefined;
 }>;
 export type MockIdentity = z.infer<typeof MockIdentitySchema>;
+/**
+ * Mock delegation status for testing
+ */
 export declare const MockDelegationStatusSchema: z.ZodEnum<["active", "revoked", "pending"]>;
 export type MockDelegationStatus = z.infer<typeof MockDelegationStatusSchema>;
+/**
+ * Mock KTA failure scenarios for testing
+ */
 export declare const MockKTAFailureTypeSchema: z.ZodEnum<["network", "auth", "invalid", "timeout"]>;
 export type MockKTAFailureType = z.infer<typeof MockKTAFailureTypeSchema>;
+/**
+ * Mock identity provider configuration
+ */
 export declare const MockIdentityProviderConfigSchema: z.ZodObject<{
     identities: z.ZodRecord<z.ZodString, z.ZodObject<{
         did: z.ZodString;
@@ -95,6 +116,9 @@ export declare const MockIdentityProviderConfigSchema: z.ZodObject<{
     deterministicSeed?: string | undefined;
 }>;
 export type MockIdentityProviderConfig = z.infer<typeof MockIdentityProviderConfigSchema>;
+/**
+ * Local verification result for offline testing
+ */
 export declare const LocalVerificationResultSchema: z.ZodObject<{
     valid: z.ZodBoolean;
     did: z.ZodOptional<z.ZodString>;
@@ -194,6 +218,9 @@ export declare const LocalVerificationResultSchema: z.ZodObject<{
     errors?: string[] | undefined;
 }>;
 export type LocalVerificationResult = z.infer<typeof LocalVerificationResultSchema>;
+/**
+ * Test DID and Key ID constants
+ */
 export declare const TEST_DIDS: {
     readonly AGENT_1: "did:test:agent-1";
     readonly AGENT_2: "did:test:agent-2";
@@ -204,8 +231,17 @@ export declare const TEST_KEY_IDS: {
     readonly KEY_TEST_2: "key-test-2";
     readonly KEY_VERIFIER_1: "key-verifier-1";
 };
+/**
+ * Test environment detection
+ */
 export declare function isTestEnvironment(): boolean;
+/**
+ * Get test seed from environment or test name
+ */
 export declare function getTestSeed(testName?: string): string;
+/**
+ * Error codes for test infrastructure
+ */
 export declare const TEST_ERROR_CODES: {
     readonly MOCK_KTA_FAILURE: "XMCP_I_TEST_MOCK_KTA_FAILURE";
     readonly DETERMINISTIC_KEY_GENERATION_FAILED: "XMCP_I_TEST_DETERMINISTIC_KEY_FAILED";

package/dist/test.js

@@ -1,15 +1,27 @@
 "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.
+ */
 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
+ */
 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
+ */
 exports.MockIdentitySchema = zod_1.z.object({
     did: zod_1.z.string(),
     kid: zod_1.z.string(),
@@ -18,23 +30,35 @@ exports.MockIdentitySchema = zod_1.z.object({
     createdAt: zod_1.z.string(),
     lastRotated: zod_1.z.string().optional(),
 });
+/**
+ * Mock delegation status for testing
+ */
 exports.MockDelegationStatusSchema = zod_1.z.enum([
     "active",
     "revoked",
     "pending",
 ]);
+/**
+ * Mock KTA failure scenarios for testing
+ */
 exports.MockKTAFailureTypeSchema = zod_1.z.enum([
     "network",
     "auth",
     "invalid",
     "timeout",
 ]);
+/**
+ * Mock identity provider configuration
+ */
 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
+ */
 exports.LocalVerificationResultSchema = zod_1.z.object({
     valid: zod_1.z.boolean(),
     did: zod_1.z.string().optional(),
@@ -59,6 +83,9 @@ exports.LocalVerificationResultSchema = zod_1.z.object({
     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
+ */
 exports.TEST_DIDS = {
     AGENT_1: "did:test:agent-1",
     AGENT_2: "did:test:agent-2",
@@ -69,12 +96,21 @@ exports.TEST_KEY_IDS = {
     KEY_TEST_2: "key-test-2",
     KEY_VERIFIER_1: "key-verifier-1",
 };
+/**
+ * Test environment detection
+ */
 function isTestEnvironment() {
     return process.env.XMCP_ENV === "test";
 }
+/**
+ * Get test seed from environment or test name
+ */
 function getTestSeed(testName) {
     return process.env.XMCP_TEST_SEED || testName || "default-test-seed";
 }
+/**
+ * Error codes for test infrastructure
+ */
 exports.TEST_ERROR_CODES = {
     MOCK_KTA_FAILURE: "XMCP_I_TEST_MOCK_KTA_FAILURE",
     DETERMINISTIC_KEY_GENERATION_FAILED: "XMCP_I_TEST_DETERMINISTIC_KEY_FAILED",

package/dist/tlkrc/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * TLKRC Module Exports
+ */
+export * from './rotation.js';

package/dist/tlkrc/index.js

@@ -0,0 +1,20 @@
+"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);

package/dist/tlkrc/rotation.d.ts

@@ -0,0 +1,245 @@
+/**
+ * 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;
+    metadata?: Record<string, any> | undefined;
+    prevEventHash?: string | undefined;
+}, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    metadata?: Record<string, any> | undefined;
+    prevEventHash?: string | undefined;
+}>, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    metadata?: Record<string, any> | undefined;
+    prevEventHash?: string | undefined;
+}, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    metadata?: Record<string, any> | undefined;
+    prevEventHash?: string | 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;
+        metadata?: Record<string, any> | undefined;
+        prevEventHash?: string | undefined;
+    }, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        metadata?: Record<string, any> | undefined;
+        prevEventHash?: string | undefined;
+    }>, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        metadata?: Record<string, any> | undefined;
+        prevEventHash?: string | undefined;
+    }, {
+        signature: string;
+        issuerDid: string;
+        prevKeyId: string;
+        nextKeyId: string;
+        effectiveAt: number;
+        issuedAt: number;
+        seq: number;
+        metadata?: Record<string, any> | undefined;
+        prevEventHash?: string | 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;
+        metadata?: Record<string, any> | undefined;
+        prevEventHash?: string | 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;
+        metadata?: Record<string, any> | undefined;
+        prevEventHash?: string | 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;
+    metadata?: Record<string, any> | undefined;
+    prevEventHash?: string | undefined;
+}, {
+    signature: string;
+    issuerDid: string;
+    prevKeyId: string;
+    nextKeyId: string;
+    effectiveAt: number;
+    issuedAt: number;
+    seq: number;
+    metadata?: Record<string, any> | undefined;
+    prevEventHash?: string | 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;