@kya-os/contracts 1.3.4 → 1.4.0

package/dist/verifier.d.ts

@@ -0,0 +1,205 @@
+import { z } from "zod";
+/**
+ * Verifier middleware schemas and headers
+ */
+export declare const AgentContextSchema: z.ZodObject<{
+    did: z.ZodString;
+    kid: z.ZodString;
+    subject: z.ZodOptional<z.ZodString>;
+    scopes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    session: z.ZodString;
+    confidence: z.ZodLiteral<"verified">;
+    delegationRef: z.ZodOptional<z.ZodString>;
+    registry: z.ZodString;
+    verifiedAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    kid: string;
+    session: string;
+    scopes: string[];
+    confidence: "verified";
+    registry: string;
+    verifiedAt: number;
+    delegationRef?: string | undefined;
+    subject?: string | undefined;
+}, {
+    did: string;
+    kid: string;
+    session: string;
+    confidence: "verified";
+    registry: string;
+    verifiedAt: number;
+    delegationRef?: string | undefined;
+    subject?: string | undefined;
+    scopes?: string[] | undefined;
+}>;
+export declare const VerifierResultSchema: z.ZodObject<{
+    success: z.ZodBoolean;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    agentContext: z.ZodOptional<z.ZodObject<{
+        did: z.ZodString;
+        kid: z.ZodString;
+        subject: z.ZodOptional<z.ZodString>;
+        scopes: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        session: z.ZodString;
+        confidence: z.ZodLiteral<"verified">;
+        delegationRef: z.ZodOptional<z.ZodString>;
+        registry: z.ZodString;
+        verifiedAt: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        did: string;
+        kid: string;
+        session: string;
+        scopes: string[];
+        confidence: "verified";
+        registry: string;
+        verifiedAt: number;
+        delegationRef?: string | undefined;
+        subject?: string | undefined;
+    }, {
+        did: string;
+        kid: string;
+        session: string;
+        confidence: "verified";
+        registry: string;
+        verifiedAt: number;
+        delegationRef?: string | undefined;
+        subject?: string | undefined;
+        scopes?: string[] | undefined;
+    }>>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodString;
+        message: z.ZodString;
+        details: z.ZodOptional<z.ZodAny>;
+        httpStatus: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        code: string;
+        message: string;
+        httpStatus: number;
+        details?: any;
+    }, {
+        code: string;
+        message: string;
+        httpStatus: number;
+        details?: any;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        httpStatus: number;
+        details?: any;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    agentContext?: {
+        did: string;
+        kid: string;
+        session: string;
+        scopes: string[];
+        confidence: "verified";
+        registry: string;
+        verifiedAt: number;
+        delegationRef?: string | undefined;
+        subject?: string | undefined;
+    } | undefined;
+}, {
+    success: boolean;
+    error?: {
+        code: string;
+        message: string;
+        httpStatus: number;
+        details?: any;
+    } | undefined;
+    headers?: Record<string, string> | undefined;
+    agentContext?: {
+        did: string;
+        kid: string;
+        session: string;
+        confidence: "verified";
+        registry: string;
+        verifiedAt: number;
+        delegationRef?: string | undefined;
+        subject?: string | undefined;
+        scopes?: string[] | undefined;
+    } | undefined;
+}>;
+export declare const StructuredErrorSchema: z.ZodObject<{
+    code: z.ZodString;
+    message: z.ZodString;
+    httpStatus: z.ZodNumber;
+    details: z.ZodOptional<z.ZodObject<{
+        reason: z.ZodOptional<z.ZodString>;
+        expected: z.ZodOptional<z.ZodAny>;
+        received: z.ZodOptional<z.ZodAny>;
+        remediation: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        expected?: any;
+        received?: any;
+        reason?: string | undefined;
+        remediation?: string | undefined;
+    }, {
+        expected?: any;
+        received?: any;
+        reason?: string | undefined;
+        remediation?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    code: string;
+    message: string;
+    httpStatus: number;
+    details?: {
+        expected?: any;
+        received?: any;
+        reason?: string | undefined;
+        remediation?: string | undefined;
+    } | undefined;
+}, {
+    code: string;
+    message: string;
+    httpStatus: number;
+    details?: {
+        expected?: any;
+        received?: any;
+        reason?: string | undefined;
+        remediation?: string | undefined;
+    } | undefined;
+}>;
+export type AgentContext = z.infer<typeof AgentContextSchema>;
+export type VerifierResult = z.infer<typeof VerifierResultSchema>;
+export type StructuredError = z.infer<typeof StructuredErrorSchema>;
+export declare const AGENT_HEADERS: {
+    readonly DID: "X-Agent-DID";
+    readonly KEY_ID: "X-Agent-KeyId";
+    readonly SUBJECT: "X-Agent-Subject";
+    readonly SCOPES: "X-Agent-Scopes";
+    readonly SESSION: "X-Agent-Session";
+    readonly CONFIDENCE: "X-Agent-Confidence";
+    readonly DELEGATION_REF: "X-Agent-Delegation-Ref";
+    readonly REGISTRY: "X-Agent-Registry";
+    readonly VERIFIED_AT: "X-Agent-Verified-At";
+};
+export declare const VERIFIER_ERROR_CODES: {
+    readonly PROOF_INVALID_TS: "XMCP_I_PROOF_INVALID_TS";
+    readonly PROOF_FUTURE_TS: "XMCP_I_PROOF_FUTURE_TS";
+    readonly PROOF_TOO_OLD: "XMCP_I_PROOF_TOO_OLD";
+    readonly PROOF_SKEW_EXCEEDED: "XMCP_I_PROOF_SKEW_EXCEEDED";
+    readonly SESSION_IDLE_EXPIRED: "XMCP_I_SESSION_IDLE_EXPIRED";
+    readonly SERVER_TIME_INVALID: "XMCP_I_SERVER_TIME_INVALID";
+};
+export declare const ERROR_HTTP_STATUS: {
+    readonly XMCP_I_EBADPROOF: 403;
+    readonly XMCP_I_ENOIDENTITY: 500;
+    readonly XMCP_I_EMIRRORPENDING: 200;
+    readonly XMCP_I_EHANDSHAKE: 401;
+    readonly XMCP_I_ESESSION: 401;
+    readonly XMCP_I_ECLAIM: 400;
+    readonly XMCP_I_ECONFIG: 500;
+    readonly XMCP_I_ERUNTIME: 500;
+    readonly XMCP_I_PROOF_INVALID_TS: 403;
+    readonly XMCP_I_PROOF_FUTURE_TS: 403;
+    readonly XMCP_I_PROOF_TOO_OLD: 403;
+    readonly XMCP_I_PROOF_SKEW_EXCEEDED: 401;
+    readonly XMCP_I_SESSION_IDLE_EXPIRED: 401;
+    readonly XMCP_I_SERVER_TIME_INVALID: 500;
+};

package/dist/verifier.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ERROR_HTTP_STATUS = exports.VERIFIER_ERROR_CODES = exports.AGENT_HEADERS = exports.StructuredErrorSchema = exports.VerifierResultSchema = exports.AgentContextSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Verifier middleware schemas and headers
+ */
+exports.AgentContextSchema = zod_1.z.object({
+    did: zod_1.z.string().min(1),
+    kid: zod_1.z.string().min(1),
+    subject: zod_1.z.string().optional(),
+    scopes: zod_1.z.array(zod_1.z.string()).default([]),
+    session: zod_1.z.string().min(1),
+    confidence: zod_1.z.literal("verified"),
+    delegationRef: zod_1.z.string().optional(),
+    registry: zod_1.z.string().url(),
+    verifiedAt: zod_1.z.number().int().positive(),
+});
+exports.VerifierResultSchema = zod_1.z.object({
+    success: zod_1.z.boolean(),
+    headers: zod_1.z.record(zod_1.z.string()).optional(),
+    agentContext: exports.AgentContextSchema.optional(),
+    error: zod_1.z
+        .object({
+        code: zod_1.z.string(),
+        message: zod_1.z.string(),
+        details: zod_1.z.any().optional(),
+        httpStatus: zod_1.z.number().int().min(400).max(599),
+    })
+        .optional(),
+});
+exports.StructuredErrorSchema = zod_1.z.object({
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    httpStatus: zod_1.z.number().int().min(400).max(599),
+    details: zod_1.z
+        .object({
+        reason: zod_1.z.string().optional(),
+        expected: zod_1.z.any().optional(),
+        received: zod_1.z.any().optional(),
+        remediation: zod_1.z.string().optional(),
+    })
+        .optional(),
+});
+// Header constants (frozen names)
+exports.AGENT_HEADERS = {
+    DID: "X-Agent-DID",
+    KEY_ID: "X-Agent-KeyId",
+    SUBJECT: "X-Agent-Subject",
+    SCOPES: "X-Agent-Scopes",
+    SESSION: "X-Agent-Session",
+    CONFIDENCE: "X-Agent-Confidence",
+    DELEGATION_REF: "X-Agent-Delegation-Ref",
+    REGISTRY: "X-Agent-Registry",
+    VERIFIED_AT: "X-Agent-Verified-At",
+};
+// Verifier-specific error codes
+exports.VERIFIER_ERROR_CODES = {
+    PROOF_INVALID_TS: "XMCP_I_PROOF_INVALID_TS",
+    PROOF_FUTURE_TS: "XMCP_I_PROOF_FUTURE_TS",
+    PROOF_TOO_OLD: "XMCP_I_PROOF_TOO_OLD",
+    PROOF_SKEW_EXCEEDED: "XMCP_I_PROOF_SKEW_EXCEEDED",
+    SESSION_IDLE_EXPIRED: "XMCP_I_SESSION_IDLE_EXPIRED",
+    SERVER_TIME_INVALID: "XMCP_I_SERVER_TIME_INVALID",
+};
+// HTTP status mappings
+exports.ERROR_HTTP_STATUS = {
+    XMCP_I_EBADPROOF: 403,
+    XMCP_I_ENOIDENTITY: 500,
+    XMCP_I_EMIRRORPENDING: 200,
+    XMCP_I_EHANDSHAKE: 401,
+    XMCP_I_ESESSION: 401,
+    XMCP_I_ECLAIM: 400,
+    XMCP_I_ECONFIG: 500,
+    XMCP_I_ERUNTIME: 500,
+    // Verifier-specific codes
+    [exports.VERIFIER_ERROR_CODES.PROOF_INVALID_TS]: 403,
+    [exports.VERIFIER_ERROR_CODES.PROOF_FUTURE_TS]: 403,
+    [exports.VERIFIER_ERROR_CODES.PROOF_TOO_OLD]: 403,
+    [exports.VERIFIER_ERROR_CODES.PROOF_SKEW_EXCEEDED]: 401,
+    [exports.VERIFIER_ERROR_CODES.SESSION_IDLE_EXPIRED]: 401,
+    [exports.VERIFIER_ERROR_CODES.SERVER_TIME_INVALID]: 500,
+};

package/dist/well-known/index.d.ts

@@ -0,0 +1,308 @@
+/**
+ * MCP-I Well-Known Endpoints Specification
+ *
+ * This module defines the types for well-known endpoints as specified in the
+ * MCP-I protocol. These endpoints provide identity discovery and verification
+ * capabilities for MCP-I agents.
+ *
+ * @module @kya-os/contracts/well-known
+ */
+import { z } from 'zod';
+/**
+ * DID Document as per W3C DID specification
+ * Returned from /.well-known/did.json
+ */
+export interface DIDDocument {
+    '@context': string[];
+    id: string;
+    verificationMethod: Array<{
+        id: string;
+        type: string;
+        controller: string;
+        publicKeyBase64?: string;
+        publicKeyMultibase?: string;
+    }>;
+    authentication?: string[];
+    assertionMethod?: string[];
+    capabilityInvocation?: string[];
+    capabilityDelegation?: string[];
+    keyAgreement?: string[];
+    service?: Array<{
+        id: string;
+        type: string;
+        serviceEndpoint: string;
+    }>;
+}
+/**
+ * Agent Document for MCP-I capability discovery
+ * Returned from /.well-known/agent.json
+ */
+export interface AgentDocument {
+    /** The agent's DID */
+    id: string;
+    /** Capabilities supported by this agent */
+    capabilities: {
+        'mcp-i': Array<'handshake' | 'signing' | 'verification' | 'delegation' | 'proof-generation'>;
+        [key: string]: string[];
+    };
+    /** Optional metadata about the agent */
+    metadata?: {
+        name?: string;
+        serviceEndpoint?: string;
+        version?: string;
+        description?: string;
+    };
+}
+/**
+ * MCP Identity information
+ * Returned from /.well-known/mcp-identity
+ */
+export interface MCPIdentity {
+    /** The agent's DID */
+    did: string;
+    /** The agent's public key */
+    publicKey: string;
+    /** Service name */
+    serviceName: string;
+    /** Service endpoint URL */
+    serviceEndpoint: string;
+    /** Timestamp of when this was generated */
+    timestamp: number;
+    /** Optional additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Well-known endpoint handler configuration
+ */
+export interface WellKnownConfig {
+    /** Service name to advertise */
+    serviceName?: string;
+    /** Service endpoint URL */
+    serviceEndpoint?: string;
+    /** Additional metadata to include */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Well-known endpoint response
+ */
+export interface WellKnownResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+/**
+ * Well-known endpoint paths
+ */
+export declare enum WellKnownPath {
+    DID_DOCUMENT = "/.well-known/did.json",
+    AGENT_DOCUMENT = "/.well-known/agent.json",
+    MCP_IDENTITY = "/.well-known/mcp-identity",
+    TOOL_PROTECTIONS = "/.well-known/tool-protections.json"
+}
+/**
+ * Zod Schemas for Validation
+ */
+export declare const DIDDocumentSchema: z.ZodObject<{
+    '@context': z.ZodArray<z.ZodString, "many">;
+    id: z.ZodString;
+    verificationMethod: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        controller: z.ZodString;
+        publicKeyBase64: z.ZodOptional<z.ZodString>;
+        publicKeyMultibase: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+        controller: string;
+        publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
+    }, {
+        type: string;
+        id: string;
+        controller: string;
+        publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
+    }>, "many">;
+    authentication: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    assertionMethod: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    capabilityInvocation: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    capabilityDelegation: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    keyAgreement: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    service: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        serviceEndpoint: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        type: string;
+        id: string;
+        serviceEndpoint: string;
+    }, {
+        type: string;
+        id: string;
+        serviceEndpoint: string;
+    }>, "many">>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    verificationMethod: {
+        type: string;
+        id: string;
+        controller: string;
+        publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
+    }[];
+    '@context': string[];
+    authentication?: string[] | undefined;
+    assertionMethod?: string[] | undefined;
+    keyAgreement?: string[] | undefined;
+    capabilityInvocation?: string[] | undefined;
+    capabilityDelegation?: string[] | undefined;
+    service?: {
+        type: string;
+        id: string;
+        serviceEndpoint: string;
+    }[] | undefined;
+}, {
+    id: string;
+    verificationMethod: {
+        type: string;
+        id: string;
+        controller: string;
+        publicKeyMultibase?: string | undefined;
+        publicKeyBase64?: string | undefined;
+    }[];
+    '@context': string[];
+    authentication?: string[] | undefined;
+    assertionMethod?: string[] | undefined;
+    keyAgreement?: string[] | undefined;
+    capabilityInvocation?: string[] | undefined;
+    capabilityDelegation?: string[] | undefined;
+    service?: {
+        type: string;
+        id: string;
+        serviceEndpoint: string;
+    }[] | undefined;
+}>;
+export declare const AgentDocumentSchema: z.ZodObject<{
+    id: z.ZodString;
+    capabilities: z.ZodObject<{
+        'mcp-i': z.ZodArray<z.ZodEnum<["handshake", "signing", "verification", "delegation", "proof-generation"]>, "many">;
+    }, "strip", z.ZodArray<z.ZodString, "many">, z.objectOutputType<{
+        'mcp-i': z.ZodArray<z.ZodEnum<["handshake", "signing", "verification", "delegation", "proof-generation"]>, "many">;
+    }, z.ZodArray<z.ZodString, "many">, "strip">, z.objectInputType<{
+        'mcp-i': z.ZodArray<z.ZodEnum<["handshake", "signing", "verification", "delegation", "proof-generation"]>, "many">;
+    }, z.ZodArray<z.ZodString, "many">, "strip">>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        serviceEndpoint: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        version?: string | undefined;
+        name?: string | undefined;
+        serviceEndpoint?: string | undefined;
+        description?: string | undefined;
+    }, {
+        version?: string | undefined;
+        name?: string | undefined;
+        serviceEndpoint?: string | undefined;
+        description?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    id: string;
+    capabilities: {
+        'mcp-i': ("handshake" | "signing" | "verification" | "delegation" | "proof-generation")[];
+    } & {
+        [k: string]: string[];
+    };
+    metadata?: {
+        version?: string | undefined;
+        name?: string | undefined;
+        serviceEndpoint?: string | undefined;
+        description?: string | undefined;
+    } | undefined;
+}, {
+    id: string;
+    capabilities: {
+        'mcp-i': ("handshake" | "signing" | "verification" | "delegation" | "proof-generation")[];
+    } & {
+        [k: string]: string[];
+    };
+    metadata?: {
+        version?: string | undefined;
+        name?: string | undefined;
+        serviceEndpoint?: string | undefined;
+        description?: string | undefined;
+    } | undefined;
+}>;
+export declare const MCPIdentitySchema: z.ZodObject<{
+    did: z.ZodString;
+    publicKey: z.ZodString;
+    serviceName: z.ZodString;
+    serviceEndpoint: z.ZodString;
+    timestamp: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    publicKey: string;
+    timestamp: number;
+    serviceEndpoint: string;
+    serviceName: string;
+    metadata?: Record<string, unknown> | undefined;
+}, {
+    did: string;
+    publicKey: string;
+    timestamp: number;
+    serviceEndpoint: string;
+    serviceName: string;
+    metadata?: Record<string, unknown> | undefined;
+}>;
+export declare const WellKnownConfigSchema: z.ZodObject<{
+    serviceName: z.ZodOptional<z.ZodString>;
+    serviceEndpoint: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    metadata?: Record<string, unknown> | undefined;
+    serviceEndpoint?: string | undefined;
+    serviceName?: string | undefined;
+}, {
+    metadata?: Record<string, unknown> | undefined;
+    serviceEndpoint?: string | undefined;
+    serviceName?: string | undefined;
+}>;
+export declare const WellKnownResponseSchema: z.ZodObject<{
+    status: z.ZodNumber;
+    headers: z.ZodRecord<z.ZodString, z.ZodString>;
+    body: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}, {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}>;
+/**
+ * Type Guards
+ */
+export declare function isDIDDocument(obj: any): obj is DIDDocument;
+export declare function isAgentDocument(obj: any): obj is AgentDocument;
+export declare function isMCPIdentity(obj: any): obj is MCPIdentity;
+/**
+ * Validation Functions
+ */
+export declare function validateDIDDocument(obj: any): DIDDocument;
+export declare function validateAgentDocument(obj: any): AgentDocument;
+export declare function validateMCPIdentity(obj: any): MCPIdentity;
+/**
+ * Utility Functions
+ */
+/**
+ * Check if a path is a well-known endpoint
+ */
+export declare function isWellKnownPath(path: string): boolean;
+/**
+ * Get the content type for a well-known endpoint
+ */
+export declare function getWellKnownContentType(path: WellKnownPath | string): string;