@kya-os/contracts 1.7.0 → 1.7.2

package/dist/audit/index.d.ts

@@ -65,38 +65,38 @@ export declare const AuditContextSchema: z.ZodObject<{
      */
     scopeId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    requestHash: string;
-    responseHash: string;
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
     session: {
         audience: string;
         sessionId: string;
     } & {
         [k: string]: unknown;
     };
+    requestHash: string;
+    responseHash: string;
     verified: "yes" | "no";
+    scopeId?: string | undefined;
+}, {
     identity: {
         did: string;
         kid: string;
     } & {
         [k: string]: unknown;
     };
-    scopeId?: string | undefined;
-}, {
-    requestHash: string;
-    responseHash: string;
     session: {
         audience: string;
         sessionId: string;
     } & {
         [k: string]: unknown;
     };
+    requestHash: string;
+    responseHash: string;
     verified: "yes" | "no";
-    identity: {
-        did: string;
-        kid: string;
-    } & {
-        [k: string]: unknown;
-    };
     scopeId?: string | undefined;
 }>;
 export type AuditContext = {
@@ -153,33 +153,33 @@ export declare const AuditEventContextSchema: z.ZodObject<{
      */
     eventData: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    session: {
-        audience: string;
-        sessionId: string;
-    } & {
-        [k: string]: unknown;
-    };
     identity: {
         did: string;
         kid: string;
     } & {
         [k: string]: unknown;
     };
-    eventType: string;
-    eventData?: Record<string, unknown> | undefined;
-}, {
     session: {
         audience: string;
         sessionId: string;
     } & {
         [k: string]: unknown;
     };
+    eventType: string;
+    eventData?: Record<string, unknown> | undefined;
+}, {
     identity: {
         did: string;
         kid: string;
     } & {
         [k: string]: unknown;
     };
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
     eventType: string;
     eventData?: Record<string, unknown> | undefined;
 }>;

package/dist/config/client-messages.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Client Messages Configuration Types
+ *
+ * Types for configuring client-specific delegation error messages.
+ * Different MCP clients (Claude, ChatGPT, Cursor, etc.) may benefit from
+ * different message formats based on their capabilities.
+ *
+ * @module @kya-os/contracts/config/client-messages
+ */
+import { z } from "zod";
+/**
+ * Template configuration for a specific client's messages
+ */
+export interface ClientMessageTemplate {
+    /**
+     * Message template with placeholders: {toolName}, {consentUrl}, {scopes}
+     *
+     * @example "I need your permission to use {toolName}.\n\n[Click to authorize]({consentUrl})"
+     */
+    message?: string;
+    /**
+     * Message template when no consent URL is available
+     *
+     * @example "Authorization required for {toolName} but no consent URL is available."
+     */
+    noUrlMessage?: string;
+    /**
+     * OAuth-specific message template with placeholders: {toolName}, {oauthUrl}, {provider}, {scopes}
+     *
+     * @example "Sign in with {provider} to use {toolName}.\n\n[Authorize]({oauthUrl})"
+     */
+    oauthMessage?: string;
+    /**
+     * Message template when OAuth URL is unavailable
+     *
+     * @example "Sign-in required for {toolName} but {provider} is not configured."
+     */
+    noOAuthUrlMessage?: string;
+    /**
+     * Custom consent URL format (optional override)
+     * Can include placeholders: {baseUrl}, {toolName}, {sessionId}, etc.
+     */
+    consentUrlFormat?: string;
+    /**
+     * Extra URL parameters to append to consent URL
+     *
+     * @example { utm_source: "chatgpt", utm_campaign: "delegation" }
+     */
+    extraParams?: Record<string, string>;
+    /**
+     * Whether client supports markdown formatting
+     * When false, markdown links [text](url) are converted to "text: url"
+     *
+     * @default true
+     */
+    supportsMarkdown?: boolean;
+}
+/**
+ * Configuration for client-specific messages
+ */
+export interface ClientMessagesConfig {
+    /**
+     * Default template for unknown/unrecognized clients
+     */
+    default?: ClientMessageTemplate;
+    /**
+     * Per-client overrides keyed by canonical client ID
+     *
+     * Known client IDs: "claude", "chatgpt", "cursor", "perplexity",
+     * "mcp-inspector", "windsurf", "cline", "zed"
+     */
+    clients?: Record<string, ClientMessageTemplate>;
+}
+export declare const ClientMessageTemplateSchema: z.ZodObject<{
+    message: z.ZodOptional<z.ZodString>;
+    noUrlMessage: z.ZodOptional<z.ZodString>;
+    oauthMessage: z.ZodOptional<z.ZodString>;
+    noOAuthUrlMessage: z.ZodOptional<z.ZodString>;
+    consentUrlFormat: z.ZodOptional<z.ZodString>;
+    extraParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    supportsMarkdown: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    message?: string | undefined;
+    noUrlMessage?: string | undefined;
+    oauthMessage?: string | undefined;
+    noOAuthUrlMessage?: string | undefined;
+    consentUrlFormat?: string | undefined;
+    extraParams?: Record<string, string> | undefined;
+    supportsMarkdown?: boolean | undefined;
+}, {
+    message?: string | undefined;
+    noUrlMessage?: string | undefined;
+    oauthMessage?: string | undefined;
+    noOAuthUrlMessage?: string | undefined;
+    consentUrlFormat?: string | undefined;
+    extraParams?: Record<string, string> | undefined;
+    supportsMarkdown?: boolean | undefined;
+}>;
+export declare const ClientMessagesConfigSchema: z.ZodObject<{
+    default: z.ZodOptional<z.ZodObject<{
+        message: z.ZodOptional<z.ZodString>;
+        noUrlMessage: z.ZodOptional<z.ZodString>;
+        oauthMessage: z.ZodOptional<z.ZodString>;
+        noOAuthUrlMessage: z.ZodOptional<z.ZodString>;
+        consentUrlFormat: z.ZodOptional<z.ZodString>;
+        extraParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supportsMarkdown: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    }, {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    }>>;
+    clients: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        message: z.ZodOptional<z.ZodString>;
+        noUrlMessage: z.ZodOptional<z.ZodString>;
+        oauthMessage: z.ZodOptional<z.ZodString>;
+        noOAuthUrlMessage: z.ZodOptional<z.ZodString>;
+        consentUrlFormat: z.ZodOptional<z.ZodString>;
+        extraParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        supportsMarkdown: z.ZodOptional<z.ZodBoolean>;
+    }, "strip", z.ZodTypeAny, {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    }, {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    }>>>;
+}, "strip", z.ZodTypeAny, {
+    default?: {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    } | undefined;
+    clients?: Record<string, {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    }> | undefined;
+}, {
+    default?: {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    } | undefined;
+    clients?: Record<string, {
+        message?: string | undefined;
+        noUrlMessage?: string | undefined;
+        oauthMessage?: string | undefined;
+        noOAuthUrlMessage?: string | undefined;
+        consentUrlFormat?: string | undefined;
+        extraParams?: Record<string, string> | undefined;
+        supportsMarkdown?: boolean | undefined;
+    }> | undefined;
+}>;
+export declare function isClientMessageTemplate(obj: unknown): obj is ClientMessageTemplate;
+export declare function isClientMessagesConfig(obj: unknown): obj is ClientMessagesConfig;
+export declare function validateClientMessageTemplate(obj: unknown): ClientMessageTemplate;
+export declare function validateClientMessagesConfig(obj: unknown): ClientMessagesConfig;

package/dist/config/client-messages.js

@@ -0,0 +1,45 @@
+"use strict";
+/**
+ * Client Messages Configuration Types
+ *
+ * Types for configuring client-specific delegation error messages.
+ * Different MCP clients (Claude, ChatGPT, Cursor, etc.) may benefit from
+ * different message formats based on their capabilities.
+ *
+ * @module @kya-os/contracts/config/client-messages
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ClientMessagesConfigSchema = exports.ClientMessageTemplateSchema = void 0;
+exports.isClientMessageTemplate = isClientMessageTemplate;
+exports.isClientMessagesConfig = isClientMessagesConfig;
+exports.validateClientMessageTemplate = validateClientMessageTemplate;
+exports.validateClientMessagesConfig = validateClientMessagesConfig;
+const zod_1 = require("zod");
+// Zod Schemas for validation
+exports.ClientMessageTemplateSchema = zod_1.z.object({
+    message: zod_1.z.string().optional(),
+    noUrlMessage: zod_1.z.string().optional(),
+    oauthMessage: zod_1.z.string().optional(),
+    noOAuthUrlMessage: zod_1.z.string().optional(),
+    consentUrlFormat: zod_1.z.string().optional(),
+    extraParams: zod_1.z.record(zod_1.z.string(), zod_1.z.string()).optional(),
+    supportsMarkdown: zod_1.z.boolean().optional(),
+});
+exports.ClientMessagesConfigSchema = zod_1.z.object({
+    default: exports.ClientMessageTemplateSchema.optional(),
+    clients: zod_1.z.record(zod_1.z.string(), exports.ClientMessageTemplateSchema).optional(),
+});
+// Type guards
+function isClientMessageTemplate(obj) {
+    return exports.ClientMessageTemplateSchema.safeParse(obj).success;
+}
+function isClientMessagesConfig(obj) {
+    return exports.ClientMessagesConfigSchema.safeParse(obj).success;
+}
+// Validation functions
+function validateClientMessageTemplate(obj) {
+    return exports.ClientMessageTemplateSchema.parse(obj);
+}
+function validateClientMessagesConfig(obj) {
+    return exports.ClientMessagesConfigSchema.parse(obj);
+}

package/dist/config/index.d.ts

@@ -11,6 +11,7 @@ import type { RuntimeIdentityConfig } from "./identity.js";
 import type { ProofingConfig } from "./proofing.js";
 import type { DelegationConfig } from "./delegation.js";
 import type { ToolProtectionSourceConfig } from "./tool-protection.js";
+import type { ClientMessagesConfig } from "./client-messages.js";
 export { MCPIBaseConfig } from "./base.js";
 export { RuntimeIdentityConfig, AgentIdentity, OAuthProvider, OAuthConfig, IdpTokens, AuthProviderType, BaseProviderConfig, CredentialProviderConfig, CredentialProviderConfigSchema, OAuth2ProviderConfig, OAuth2ProviderConfigSchema, AuthProvider, AuthProviderSchema, } from "./identity.js";
 export type { ToolExecutionContext } from "./tool-context.js";
@@ -23,6 +24,7 @@ export { ProofingConfig, ProofBatchQueueConfig, ProofDestination, ProofDestinati
 export { DelegationConfig, DelegationVerifierConfig, DelegationVerifierType, AuthorizationConfig, DelegationRecord, } from "./delegation.js";
 export { ToolProtection, ToolProtectionMap, ToolProtectionSourceConfig, ToolProtectionSourceType, ToolProtectionServiceConfig, DelegationRequiredErrorData, ToolProtectionResponse, } from "./tool-protection.js";
 export { buildBaseConfig } from "./builder.js";
+export { ClientMessageTemplate, ClientMessagesConfig, ClientMessageTemplateSchema, ClientMessagesConfigSchema, isClientMessageTemplate, isClientMessagesConfig, validateClientMessageTemplate, validateClientMessagesConfig, } from "./client-messages.js";
 /**
  * Complete runtime configuration type
  * This can be extended by platform-specific configs
@@ -32,4 +34,6 @@ export interface MCPIConfig extends MCPIBaseConfig {
     proofing?: ProofingConfig;
     delegation?: DelegationConfig;
     toolProtection?: ToolProtectionSourceConfig;
+    /** Client-specific message configuration for delegation errors */
+    clientMessages?: ClientMessagesConfig;
 }

package/dist/config/index.js

@@ -8,7 +8,7 @@
  * @module @kya-os/contracts/config
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildBaseConfig = exports.AuthProviderSchema = exports.OAuth2ProviderConfigSchema = exports.CredentialProviderConfigSchema = void 0;
+exports.validateClientMessagesConfig = exports.validateClientMessageTemplate = exports.isClientMessagesConfig = exports.isClientMessageTemplate = exports.ClientMessagesConfigSchema = exports.ClientMessageTemplateSchema = exports.buildBaseConfig = exports.AuthProviderSchema = exports.OAuth2ProviderConfigSchema = exports.CredentialProviderConfigSchema = void 0;
 // Identity configuration
 var identity_js_1 = require("./identity.js");
 Object.defineProperty(exports, "CredentialProviderConfigSchema", { enumerable: true, get: function () { return identity_js_1.CredentialProviderConfigSchema; } });
@@ -17,3 +17,11 @@ Object.defineProperty(exports, "AuthProviderSchema", { enumerable: true, get: fu
 // Configuration builder utilities
 var builder_js_1 = require("./builder.js");
 Object.defineProperty(exports, "buildBaseConfig", { enumerable: true, get: function () { return builder_js_1.buildBaseConfig; } });
+// Client-specific message configuration
+var client_messages_js_1 = require("./client-messages.js");
+Object.defineProperty(exports, "ClientMessageTemplateSchema", { enumerable: true, get: function () { return client_messages_js_1.ClientMessageTemplateSchema; } });
+Object.defineProperty(exports, "ClientMessagesConfigSchema", { enumerable: true, get: function () { return client_messages_js_1.ClientMessagesConfigSchema; } });
+Object.defineProperty(exports, "isClientMessageTemplate", { enumerable: true, get: function () { return client_messages_js_1.isClientMessageTemplate; } });
+Object.defineProperty(exports, "isClientMessagesConfig", { enumerable: true, get: function () { return client_messages_js_1.isClientMessagesConfig; } });
+Object.defineProperty(exports, "validateClientMessageTemplate", { enumerable: true, get: function () { return client_messages_js_1.validateClientMessageTemplate; } });
+Object.defineProperty(exports, "validateClientMessagesConfig", { enumerable: true, get: function () { return client_messages_js_1.validateClientMessagesConfig; } });