@kya-os/contracts 1.3.4 → 1.4.0

package/dist/cli.d.ts

@@ -0,0 +1,388 @@
+import { z } from "zod";
+/**
+ * CLI command schemas and results
+ */
+/**
+ * CLI Identity File Format Schema
+ *
+ * Format for identity.json files stored on disk.
+ * Used by CLI tools for identity management.
+ */
+export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObject<{
+    version: z.ZodLiteral<"1.0">;
+    did: z.ZodString;
+    kid: z.ZodOptional<z.ZodString>;
+    keyId: z.ZodOptional<z.ZodString>;
+    privateKey: z.ZodString;
+    publicKey: z.ZodString;
+    createdAt: z.ZodString;
+    lastRotated: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    version: "1.0";
+    did: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    kid?: string | undefined;
+    keyId?: string | undefined;
+    lastRotated?: string | undefined;
+}, {
+    version: "1.0";
+    did: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    kid?: string | undefined;
+    keyId?: string | undefined;
+    lastRotated?: string | undefined;
+}>, {
+    version: "1.0";
+    did: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    kid?: string | undefined;
+    keyId?: string | undefined;
+    lastRotated?: string | undefined;
+}, {
+    version: "1.0";
+    did: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    kid?: string | undefined;
+    keyId?: string | undefined;
+    lastRotated?: string | undefined;
+}>, {
+    version: "1.0";
+    did: string;
+    kid: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    lastRotated: string | undefined;
+}, {
+    version: "1.0";
+    did: string;
+    privateKey: string;
+    publicKey: string;
+    createdAt: string;
+    kid?: string | undefined;
+    keyId?: string | undefined;
+    lastRotated?: string | undefined;
+}>;
+export declare const KeyRotationResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    oldKeyId: z.ZodString;
+    newKeyId: z.ZodString;
+    did: z.ZodString;
+    mode: z.ZodEnum<["dev", "prod"]>;
+    delegated: z.ZodBoolean;
+    forced: z.ZodBoolean;
+    auditLine: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    success: boolean;
+    oldKeyId: string;
+    newKeyId: string;
+    mode: "dev" | "prod";
+    delegated: boolean;
+    forced: boolean;
+    auditLine: string;
+}, {
+    did: string;
+    success: boolean;
+    oldKeyId: string;
+    newKeyId: string;
+    mode: "dev" | "prod";
+    delegated: boolean;
+    forced: boolean;
+    auditLine: string;
+}>;
+export declare const StatusReportSchema: z.ZodObject<{
+    did: z.ZodString;
+    kid: z.ZodString;
+    ktaURL: z.ZodString;
+    mirrorStatus: z.ZodEnum<["pending", "success", "error"]>;
+    lastHandshake: z.ZodOptional<z.ZodNumber>;
+    environment: z.ZodEnum<["dev", "prod"]>;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    kid: string;
+    ktaURL: string;
+    mirrorStatus: "success" | "pending" | "error";
+    environment: "dev" | "prod";
+    lastHandshake?: number | undefined;
+}, {
+    did: string;
+    kid: string;
+    ktaURL: string;
+    mirrorStatus: "success" | "pending" | "error";
+    environment: "dev" | "prod";
+    lastHandshake?: number | undefined;
+}>;
+export declare const PackageInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    version: z.ZodString;
+    compatible: z.ZodBoolean;
+    issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    name: string;
+    compatible: boolean;
+    issues?: string[] | undefined;
+}, {
+    version: string;
+    name: string;
+    compatible: boolean;
+    issues?: string[] | undefined;
+}>;
+export declare const XMCPUpstreamInfoSchema: z.ZodObject<{
+    version: z.ZodString;
+    compatible: z.ZodBoolean;
+    issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    compatible: boolean;
+    issues?: string[] | undefined;
+}, {
+    version: string;
+    compatible: boolean;
+    issues?: string[] | undefined;
+}>;
+export declare const EnvironmentInfoSchema: z.ZodObject<{
+    valid: z.ZodBoolean;
+    missing: z.ZodArray<z.ZodString, "many">;
+    issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    valid: boolean;
+    missing: string[];
+    issues?: string[] | undefined;
+}, {
+    valid: boolean;
+    missing: string[];
+    issues?: string[] | undefined;
+}>;
+export declare const KTAInfoSchema: z.ZodObject<{
+    reachable: z.ZodBoolean;
+    authenticated: z.ZodBoolean;
+    issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    reachable: boolean;
+    authenticated: boolean;
+    issues?: string[] | undefined;
+}, {
+    reachable: boolean;
+    authenticated: boolean;
+    issues?: string[] | undefined;
+}>;
+export declare const CacheInfoSchema: z.ZodObject<{
+    type: z.ZodString;
+    functional: z.ZodBoolean;
+    issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    type: string;
+    functional: boolean;
+    issues?: string[] | undefined;
+}, {
+    type: string;
+    functional: boolean;
+    issues?: string[] | undefined;
+}>;
+export declare const DoctorResultSchema: z.ZodObject<{
+    packages: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodString;
+        compatible: z.ZodBoolean;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        name: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    }, {
+        version: string;
+        name: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    }>, "many">;
+    xmcpUpstream: z.ZodObject<{
+        version: z.ZodString;
+        compatible: z.ZodBoolean;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        version: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    }, {
+        version: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    }>;
+    environment: z.ZodObject<{
+        valid: z.ZodBoolean;
+        missing: z.ZodArray<z.ZodString, "many">;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        valid: boolean;
+        missing: string[];
+        issues?: string[] | undefined;
+    }, {
+        valid: boolean;
+        missing: string[];
+        issues?: string[] | undefined;
+    }>;
+    kta: z.ZodObject<{
+        reachable: z.ZodBoolean;
+        authenticated: z.ZodBoolean;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        reachable: boolean;
+        authenticated: boolean;
+        issues?: string[] | undefined;
+    }, {
+        reachable: boolean;
+        authenticated: boolean;
+        issues?: string[] | undefined;
+    }>;
+    cache: z.ZodObject<{
+        type: z.ZodString;
+        functional: z.ZodBoolean;
+        issues: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        functional: boolean;
+        issues?: string[] | undefined;
+    }, {
+        type: string;
+        functional: boolean;
+        issues?: string[] | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    environment: {
+        valid: boolean;
+        missing: string[];
+        issues?: string[] | undefined;
+    };
+    packages: {
+        version: string;
+        name: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    }[];
+    xmcpUpstream: {
+        version: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    };
+    kta: {
+        reachable: boolean;
+        authenticated: boolean;
+        issues?: string[] | undefined;
+    };
+    cache: {
+        type: string;
+        functional: boolean;
+        issues?: string[] | undefined;
+    };
+}, {
+    environment: {
+        valid: boolean;
+        missing: string[];
+        issues?: string[] | undefined;
+    };
+    packages: {
+        version: string;
+        name: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    }[];
+    xmcpUpstream: {
+        version: string;
+        compatible: boolean;
+        issues?: string[] | undefined;
+    };
+    kta: {
+        reachable: boolean;
+        authenticated: boolean;
+        issues?: string[] | undefined;
+    };
+    cache: {
+        type: string;
+        functional: boolean;
+        issues?: string[] | undefined;
+    };
+}>;
+export declare const ScaffolderOptionsSchema: z.ZodObject<{
+    projectName: z.ZodString;
+    xmcpVersion: z.ZodOptional<z.ZodString>;
+    xmcpChannel: z.ZodOptional<z.ZodEnum<["latest", "next"]>>;
+    noIdentity: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    projectName: string;
+    noIdentity: boolean;
+    xmcpVersion?: string | undefined;
+    xmcpChannel?: "latest" | "next" | undefined;
+}, {
+    projectName: string;
+    xmcpVersion?: string | undefined;
+    xmcpChannel?: "latest" | "next" | undefined;
+    noIdentity?: boolean | undefined;
+}>;
+export declare const ScaffolderResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    projectPath: z.ZodString;
+    xmcpVersion: z.ZodString;
+    identityEnabled: z.ZodBoolean;
+    warnings: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    xmcpVersion: string;
+    projectPath: string;
+    identityEnabled: boolean;
+    warnings?: string[] | undefined;
+}, {
+    success: boolean;
+    xmcpVersion: string;
+    projectPath: string;
+    identityEnabled: boolean;
+    warnings?: string[] | undefined;
+}>;
+export type CLIIdentityFile = z.infer<typeof CLIIdentityFileSchema>;
+export type KeyRotationResult = z.infer<typeof KeyRotationResultSchema>;
+export type StatusReport = z.infer<typeof StatusReportSchema>;
+export type PackageInfo = z.infer<typeof PackageInfoSchema>;
+export type XMCPUpstreamInfo = z.infer<typeof XMCPUpstreamInfoSchema>;
+export type EnvironmentInfo = z.infer<typeof EnvironmentInfoSchema>;
+export type KTAInfo = z.infer<typeof KTAInfoSchema>;
+export type CacheInfo = z.infer<typeof CacheInfoSchema>;
+export type DoctorResult = z.infer<typeof DoctorResultSchema>;
+export type ScaffolderOptions = z.infer<typeof ScaffolderOptionsSchema>;
+export type ScaffolderResult = z.infer<typeof ScaffolderResultSchema>;
+/**
+ * @deprecated Use CLIIdentityFile instead
+ * This export is maintained for backward compatibility
+ */
+export type IdentityConfig = CLIIdentityFile;
+export declare const ERROR_CODES: {
+    readonly XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF";
+    readonly XMCP_I_ENOIDENTITY: "XMCP_I_ENOIDENTITY";
+    readonly XMCP_I_EMIRRORPENDING: "XMCP_I_EMIRRORPENDING";
+    readonly XMCP_I_EHANDSHAKE: "XMCP_I_EHANDSHAKE";
+    readonly XMCP_I_ESESSION: "XMCP_I_ESESSION";
+    readonly XMCP_I_ECLAIM: "XMCP_I_ECLAIM";
+    readonly XMCP_I_ECONFIG: "XMCP_I_ECONFIG";
+    readonly XMCP_I_ERUNTIME: "XMCP_I_ERUNTIME";
+};
+export type ErrorCode = keyof typeof ERROR_CODES;
+export declare const CLI_EXIT_CODES: {
+    readonly SUCCESS: 0;
+    readonly GENERAL_ERROR: 1;
+    readonly BADPROOF: 20;
+    readonly NOIDENTITY: 21;
+    readonly HANDSHAKE: 22;
+    readonly SESSION: 23;
+    readonly CLAIM: 24;
+    readonly CONFIG: 25;
+    readonly RUNTIME: 26;
+};

package/dist/cli.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CLI_EXIT_CODES = exports.ERROR_CODES = exports.ScaffolderResultSchema = exports.ScaffolderOptionsSchema = exports.DoctorResultSchema = exports.CacheInfoSchema = exports.KTAInfoSchema = exports.EnvironmentInfoSchema = exports.XMCPUpstreamInfoSchema = exports.PackageInfoSchema = exports.StatusReportSchema = exports.KeyRotationResultSchema = exports.CLIIdentityFileSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * CLI command schemas and results
+ */
+/**
+ * CLI Identity File Format Schema
+ *
+ * Format for identity.json files stored on disk.
+ * Used by CLI tools for identity management.
+ */
+exports.CLIIdentityFileSchema = zod_1.z.object({
+    version: zod_1.z.literal("1.0"),
+    did: zod_1.z.string().min(1),
+    // Accept both kid and keyId for backward compatibility with pre-1.3 identity files
+    kid: zod_1.z.string().min(1).optional(),
+    keyId: zod_1.z.string().min(1).optional(),
+    privateKey: zod_1.z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 private key (44 characters)"),
+    publicKey: zod_1.z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 public key (44 characters)"),
+    createdAt: zod_1.z.string().datetime(),
+    lastRotated: zod_1.z.string().datetime().optional(),
+}).refine((data) => data.kid || data.keyId, {
+    message: "Either kid or keyId must be provided",
+}).transform((data) => ({
+    version: data.version,
+    did: data.did,
+    kid: data.kid || data.keyId,
+    privateKey: data.privateKey,
+    publicKey: data.publicKey,
+    createdAt: data.createdAt,
+    lastRotated: data.lastRotated,
+}));
+exports.KeyRotationResultSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    oldKeyId: zod_1.z.string().min(1),
+    newKeyId: zod_1.z.string().min(1),
+    did: zod_1.z.string().min(1),
+    mode: zod_1.z.enum(["dev", "prod"]),
+    delegated: zod_1.z.boolean(),
+    forced: zod_1.z.boolean(),
+    auditLine: zod_1.z.string().min(1),
+});
+exports.StatusReportSchema = zod_1.z.object({
+    did: zod_1.z.string().min(1),
+    kid: zod_1.z.string().min(1), // Changed from keyId to kid for spec compliance
+    ktaURL: zod_1.z.string().url(),
+    mirrorStatus: zod_1.z.enum(["pending", "success", "error"]),
+    lastHandshake: zod_1.z.number().int().positive().optional(),
+    environment: zod_1.z.enum(["dev", "prod"]),
+});
+exports.PackageInfoSchema = zod_1.z.object({
+    name: zod_1.z.string(),
+    version: zod_1.z.string(),
+    compatible: zod_1.z.boolean(),
+    issues: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.XMCPUpstreamInfoSchema = zod_1.z.object({
+    version: zod_1.z.string(),
+    compatible: zod_1.z.boolean(),
+    issues: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.EnvironmentInfoSchema = zod_1.z.object({
+    valid: zod_1.z.boolean(),
+    missing: zod_1.z.array(zod_1.z.string()),
+    issues: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.KTAInfoSchema = zod_1.z.object({
+    reachable: zod_1.z.boolean(),
+    authenticated: zod_1.z.boolean(),
+    issues: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.CacheInfoSchema = zod_1.z.object({
+    type: zod_1.z.string(),
+    functional: zod_1.z.boolean(),
+    issues: zod_1.z.array(zod_1.z.string()).optional(),
+});
+exports.DoctorResultSchema = zod_1.z.object({
+    packages: zod_1.z.array(exports.PackageInfoSchema),
+    xmcpUpstream: exports.XMCPUpstreamInfoSchema,
+    environment: exports.EnvironmentInfoSchema,
+    kta: exports.KTAInfoSchema,
+    cache: exports.CacheInfoSchema,
+});
+exports.ScaffolderOptionsSchema = zod_1.z.object({
+    projectName: zod_1.z.string().min(1),
+    xmcpVersion: zod_1.z.string().optional(),
+    xmcpChannel: zod_1.z.enum(["latest", "next"]).optional(),
+    noIdentity: zod_1.z.boolean().default(false),
+});
+exports.ScaffolderResultSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    projectPath: zod_1.z.string().min(1),
+    xmcpVersion: zod_1.z.string().min(1),
+    identityEnabled: zod_1.z.boolean(),
+    warnings: zod_1.z.array(zod_1.z.string()).optional(),
+});
+// Error codes as string literal union
+exports.ERROR_CODES = {
+    XMCP_I_EBADPROOF: "XMCP_I_EBADPROOF",
+    XMCP_I_ENOIDENTITY: "XMCP_I_ENOIDENTITY",
+    XMCP_I_EMIRRORPENDING: "XMCP_I_EMIRRORPENDING",
+    XMCP_I_EHANDSHAKE: "XMCP_I_EHANDSHAKE",
+    XMCP_I_ESESSION: "XMCP_I_ESESSION",
+    XMCP_I_ECLAIM: "XMCP_I_ECLAIM",
+    XMCP_I_ECONFIG: "XMCP_I_ECONFIG",
+    XMCP_I_ERUNTIME: "XMCP_I_ERUNTIME",
+};
+// CLI exit codes
+exports.CLI_EXIT_CODES = {
+    SUCCESS: 0,
+    GENERAL_ERROR: 1,
+    BADPROOF: 20,
+    NOIDENTITY: 21,
+    HANDSHAKE: 22,
+    SESSION: 23,
+    CLAIM: 24,
+    CONFIG: 25,
+    RUNTIME: 26,
+};

package/dist/config/base.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Base Configuration Types
+ *
+ * Shared configuration interfaces that are platform-agnostic and used
+ * across all XMCP-I implementations. These form the foundation of the
+ * configuration hierarchy.
+ *
+ * @module @kya-os/contracts/config
+ */
+/**
+ * Base configuration shared across ALL platforms
+ *
+ * This interface defines the core configuration options that are
+ * universally applicable regardless of the runtime platform (Node.js,
+ * Cloudflare Workers, etc.).
+ */
+export interface MCPIBaseConfig {
+    /**
+     * Runtime environment setting
+     * - 'development': Enables debug logging, dev identity, relaxed security
+     * - 'production': Production security, identity from env vars, minimal logging
+     */
+    environment: 'development' | 'production';
+    /**
+     * Session configuration
+     * Controls how sessions are managed and validated
+     */
+    session?: {
+        /**
+         * Maximum time skew allowed for timestamp validation (in seconds)
+         * Helps handle clock drift between client and server
+         * @default 120
+         */
+        timestampSkewSeconds?: number;
+        /**
+         * Session time-to-live in minutes
+         * How long a session remains valid after creation
+         * @default 30
+         */
+        ttlMinutes?: number;
+        /**
+         * Absolute session lifetime in minutes (optional)
+         * Maximum lifetime regardless of activity
+         */
+        absoluteLifetime?: number;
+    };
+    /**
+     * Audit logging configuration
+     * Controls what gets logged for security and compliance
+     */
+    audit?: {
+        /**
+         * Enable audit logging
+         * @default true in production, false in development
+         */
+        enabled: boolean;
+        /**
+         * Include proof hashes in audit logs
+         * Useful for cryptographic verification but increases log size
+         * @default false
+         */
+        includeProofHashes?: boolean;
+        /**
+         * Include full payloads in audit logs
+         * WARNING: May include sensitive data
+         * @default false
+         */
+        includePayloads?: boolean;
+        /**
+         * Custom log function for audit records
+         * If not provided, uses console.log
+         */
+        logFunction?: (record: string) => void;
+    };
+    /**
+     * Well-known endpoints configuration
+     * Controls the /.well-known/* endpoints for identity discovery
+     */
+    wellKnown?: {
+        /**
+         * Enable well-known endpoints
+         * @default true
+         */
+        enabled: boolean;
+        /**
+         * Service name advertised in well-known endpoints
+         * @default 'MCP-I Service'
+         */
+        serviceName?: string;
+        /**
+         * Service endpoint URL
+         * @default 'https://example.com'
+         */
+        serviceEndpoint?: string;
+    };
+}

package/dist/config/base.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Base Configuration Types
+ *
+ * Shared configuration interfaces that are platform-agnostic and used
+ * across all XMCP-I implementations. These form the foundation of the
+ * configuration hierarchy.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });