@kya-os/contracts 1.6.17 → 1.6.19

package/dist/cli.d.ts

@@ -1,7 +1,9 @@
 import { z } from "zod";
+import { KTARegistrationSchema } from "./config/identity.js";
 /**
  * CLI command schemas and results
  */
+export { KTARegistration, KTARegistrationSchema } from "./config/identity.js";
 /**
  * CLI Identity File Format Schema
  *
@@ -17,6 +19,23 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     publicKey: z.ZodString;
     createdAt: z.ZodString;
     lastRotated: z.ZodOptional<z.ZodString>;
+    /**
+     * Know That AI registration information
+     * Present when agent is registered with KTA for reputation tracking
+     */
+    kta: z.ZodOptional<z.ZodObject<{
+        registered: z.ZodBoolean;
+        registeredAt: z.ZodString;
+        claimUrl: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    }, {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    }>>;
 }, "strip", z.ZodTypeAny, {
     version: "1.0";
     did: string;
@@ -26,6 +45,11 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     kid?: string | undefined;
     keyId?: string | undefined;
     lastRotated?: string | undefined;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
 }, {
     version: "1.0";
     did: string;
@@ -35,6 +59,11 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     kid?: string | undefined;
     keyId?: string | undefined;
     lastRotated?: string | undefined;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
 }>, {
     version: "1.0";
     did: string;
@@ -44,6 +73,11 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     kid?: string | undefined;
     keyId?: string | undefined;
     lastRotated?: string | undefined;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
 }, {
     version: "1.0";
     did: string;
@@ -53,6 +87,11 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     kid?: string | undefined;
     keyId?: string | undefined;
     lastRotated?: string | undefined;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
 }>, {
     version: "1.0";
     did: string;
@@ -60,7 +99,8 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     privateKey: string;
     publicKey: string;
     createdAt: string;
-    lastRotated: string | undefined;
+    lastRotated?: string;
+    kta?: z.infer<typeof KTARegistrationSchema>;
 }, {
     version: "1.0";
     did: string;
@@ -70,6 +110,11 @@ export declare const CLIIdentityFileSchema: z.ZodEffects<z.ZodEffects<z.ZodObjec
     kid?: string | undefined;
     keyId?: string | undefined;
     lastRotated?: string | undefined;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
 }>;
 export declare const KeyRotationResultSchema: z.ZodObject<{
     success: z.ZodBoolean;
@@ -259,6 +304,11 @@ export declare const DoctorResultSchema: z.ZodObject<{
         issues?: string[] | undefined;
     }>;
 }, "strip", z.ZodTypeAny, {
+    kta: {
+        reachable: boolean;
+        authenticated: boolean;
+        issues?: string[] | undefined;
+    };
     environment: {
         valid: boolean;
         missing: string[];
@@ -275,17 +325,17 @@ export declare const DoctorResultSchema: z.ZodObject<{
         compatible: boolean;
         issues?: string[] | undefined;
     };
-    kta: {
-        reachable: boolean;
-        authenticated: boolean;
-        issues?: string[] | undefined;
-    };
     cache: {
         type: string;
         functional: boolean;
         issues?: string[] | undefined;
     };
 }, {
+    kta: {
+        reachable: boolean;
+        authenticated: boolean;
+        issues?: string[] | undefined;
+    };
     environment: {
         valid: boolean;
         missing: string[];
@@ -302,11 +352,6 @@ export declare const DoctorResultSchema: z.ZodObject<{
         compatible: boolean;
         issues?: string[] | undefined;
     };
-    kta: {
-        reachable: boolean;
-        authenticated: boolean;
-        issues?: string[] | undefined;
-    };
     cache: {
         type: string;
         functional: boolean;

package/dist/cli.js

@@ -1,37 +1,61 @@
 "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;
+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 = exports.KTARegistrationSchema = void 0;
 const zod_1 = require("zod");
+const identity_js_1 = require("./config/identity.js");
 /**
  * CLI command schemas and results
  */
+// Re-export KTARegistration types for convenience
+var identity_js_2 = require("./config/identity.js");
+Object.defineProperty(exports, "KTARegistrationSchema", { enumerable: true, get: function () { return identity_js_2.KTARegistrationSchema; } });
 /**
  * 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({
+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)"),
+    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, {
+    /**
+     * Know That AI registration information
+     * Present when agent is registered with KTA for reputation tracking
+     */
+    kta: identity_js_1.KTARegistrationSchema.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,
-}));
+})
+    .transform((data) => {
+    const result = {
+        version: data.version,
+        did: data.did,
+        kid: data.kid || data.keyId,
+        privateKey: data.privateKey,
+        publicKey: data.publicKey,
+        createdAt: data.createdAt,
+    };
+    if (data.lastRotated) {
+        result.lastRotated = data.lastRotated;
+    }
+    if (data.kta) {
+        result.kta = data.kta;
+    }
+    return result;
+});
 exports.KeyRotationResultSchema = zod_1.z.object({
     success: zod_1.z.boolean(),
     oldKeyId: zod_1.z.string().min(1),

package/dist/config/identity.d.ts

@@ -772,6 +772,51 @@ export interface IdpTokens {
     /** Granted scopes */
     scope?: string;
 }
+/**
+ * Know That AI Registration
+ *
+ * Tracks whether and when this agent was registered with Know That AI
+ * for reputation tracking and discovery.
+ *
+ * Present when agent is registered via:
+ * - CLI: `mcpi register`
+ * - Scaffolder: `create-mcpi-app --register`
+ * - Shadow registration (automatic for did:key)
+ */
+export interface KTARegistration {
+    /**
+     * Whether registration was successful
+     */
+    registered: boolean;
+    /**
+     * ISO 8601 timestamp of when the agent was registered
+     * @example '2025-01-15T10:30:00.000Z'
+     */
+    registeredAt: string;
+    /**
+     * Claim URL for did:web identity verification
+     * - For did:web agents: URL to claim public listing
+     * - For did:key agents: null (shadow registration, no public listing)
+     * @example 'https://knowthat.ai/agents/claim/abc123'
+     */
+    claimUrl: string | null;
+}
+/**
+ * Zod schema for KTARegistration
+ */
+export declare const KTARegistrationSchema: z.ZodObject<{
+    registered: z.ZodBoolean;
+    registeredAt: z.ZodString;
+    claimUrl: z.ZodNullable<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    registered: boolean;
+    registeredAt: string;
+    claimUrl: string | null;
+}, {
+    registered: boolean;
+    registeredAt: string;
+    claimUrl: string | null;
+}>;
 /**
  * Agent identity representation
  * The actual identity data structure used at runtime
@@ -795,6 +840,18 @@ export interface AgentIdentity {
      * ISO 8601 timestamp of when the identity was created
      */
     createdAt: string;
+    /**
+     * Know That AI registration information
+     * Present when agent is registered with KTA for reputation tracking.
+     *
+     * @example
+     * ```typescript
+     * if (identity.kta?.registered) {
+     *   // Agent is registered, reputation tracking is enabled
+     * }
+     * ```
+     */
+    kta?: KTARegistration;
     /**
      * Optional metadata about the identity
      */
@@ -813,3 +870,63 @@ export interface AgentIdentity {
         [key: string]: unknown;
     };
 }
+/**
+ * Zod schema for AgentIdentity validation
+ */
+export declare const AgentIdentitySchema: z.ZodObject<{
+    did: z.ZodEffects<z.ZodString, string, string>;
+    publicKey: z.ZodString;
+    privateKey: z.ZodString;
+    createdAt: z.ZodString;
+    kta: z.ZodOptional<z.ZodObject<{
+        registered: z.ZodBoolean;
+        registeredAt: z.ZodString;
+        claimUrl: z.ZodNullable<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    }, {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    }>>;
+    metadata: z.ZodOptional<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough">>>;
+}, "strip", z.ZodTypeAny, {
+    did: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: string;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
+    metadata?: z.objectOutputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+}, {
+    did: string;
+    publicKey: string;
+    privateKey: string;
+    createdAt: string;
+    kta?: {
+        registered: boolean;
+        registeredAt: string;
+        claimUrl: string | null;
+    } | undefined;
+    metadata?: z.objectInputType<{
+        name: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.ZodTypeAny, "passthrough"> | undefined;
+}>;

package/dist/config/identity.js

@@ -8,7 +8,7 @@
  * @module @kya-os/contracts/config
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AuthProviderSchema = exports.OAuth2ProviderConfigSchema = exports.OAuthConfigSchema = exports.OAuthProviderSchema = exports.CredentialProviderConfigSchema = void 0;
+exports.AgentIdentitySchema = exports.KTARegistrationSchema = exports.AuthProviderSchema = exports.OAuth2ProviderConfigSchema = exports.OAuthConfigSchema = exports.OAuthProviderSchema = exports.CredentialProviderConfigSchema = void 0;
 const zod_1 = require("zod");
 /**
  * Zod schema for CredentialProviderConfig validation
@@ -64,7 +64,9 @@ exports.OAuthProviderSchema = zod_1.z.object({
     proxyMode: zod_1.z.boolean().optional(),
     // Phase 3: Custom IDP Support
     customParams: zod_1.z.record(zod_1.z.string()).optional(),
-    tokenEndpointAuthMethod: zod_1.z.enum(["client_secret_post", "client_secret_basic"]).optional(),
+    tokenEndpointAuthMethod: zod_1.z
+        .enum(["client_secret_post", "client_secret_basic"])
+        .optional(),
     responseType: zod_1.z.string().optional().default("code"),
     grantType: zod_1.z.string().optional().default("authorization_code"),
 });
@@ -105,3 +107,33 @@ exports.AuthProviderSchema = zod_1.z.discriminatedUnion("type", [
     exports.OAuth2ProviderConfigSchema,
     exports.CredentialProviderConfigSchema,
 ]);
+/**
+ * Zod schema for KTARegistration
+ */
+exports.KTARegistrationSchema = zod_1.z.object({
+    registered: zod_1.z.boolean(),
+    registeredAt: zod_1.z.string().datetime(),
+    claimUrl: zod_1.z.string().url().nullable(),
+});
+/**
+ * Zod schema for AgentIdentity validation
+ */
+exports.AgentIdentitySchema = zod_1.z.object({
+    did: zod_1.z
+        .string()
+        .min(1)
+        .refine((val) => val.startsWith("did:"), {
+        message: 'DID must start with "did:"',
+    }),
+    publicKey: zod_1.z.string().min(1),
+    privateKey: zod_1.z.string().min(1),
+    createdAt: zod_1.z.string().datetime(),
+    kta: exports.KTARegistrationSchema.optional(),
+    metadata: zod_1.z
+        .object({
+        name: zod_1.z.string().optional(),
+        version: zod_1.z.string().optional(),
+    })
+        .passthrough()
+        .optional(),
+});

package/dist/config/tool-protection.d.ts

@@ -6,7 +6,7 @@
  *
  * @module @kya-os/contracts/config
  */
-import type { ToolProtection as BaseToolProtection, ToolProtectionMap as BaseToolProtectionMap, DelegationRequiredErrorData as BaseDelegationRequiredErrorData, ToolProtectionResponse as BaseToolProtectionResponse } from '../tool-protection/index.js';
+import type { ToolProtection as BaseToolProtection, ToolProtectionMap as BaseToolProtectionMap, DelegationRequiredErrorData as BaseDelegationRequiredErrorData, ToolProtectionResponse as BaseToolProtectionResponse } from "../tool-protection/index.js";
 export type ToolProtection = BaseToolProtection;
 export type ToolProtectionMap = BaseToolProtectionMap;
 export type DelegationRequiredErrorData = BaseDelegationRequiredErrorData;
@@ -14,7 +14,7 @@ export type ToolProtectionResponse = BaseToolProtectionResponse;
 /**
  * Tool protection source types
  */
-export type ToolProtectionSourceType = 'inline' | 'local' | 'agentshield' | 'kta' | 'multi';
+export type ToolProtectionSourceType = "inline" | "local" | "agentshield" | "kta" | "multi";
 /**
  * Tool protection source configuration
  * Defines where tool protection settings come from
@@ -83,7 +83,7 @@ export interface ToolProtectionSourceConfig {
         /**
          * Source configuration
          */
-        config: Omit<ToolProtectionSourceConfig, 'source' | 'sources'>;
+        config: Omit<ToolProtectionSourceConfig, "source" | "sources">;
         /**
          * Priority (higher number = higher priority)
          * @default 0
@@ -96,9 +96,29 @@ export interface ToolProtectionSourceConfig {
         exclusive?: boolean;
     }>;
     /**
-     * Fallback configuration if all sources fail
+     * Local configuration (LOWEST priority after defaults)
+     *
+     * This config serves as a base that gets OVERRIDDEN by remote config.
+     * Use this for development defaults or project-specific base settings.
+     *
+     * Precedence order (highest to lowest):
+     * 1. Remote config (AgentShield API) - WINS
+     * 2. Local config (this field)
+     * 3. Framework defaults
      */
-    fallback?: BaseToolProtectionMap;
+    localConfig?: BaseToolProtectionMap;
+    /**
+     * Offline fallback configuration (ONLY used when API is unavailable)
+     *
+     * Unlike localConfig, this is NOT merged with remote config.
+     * It's only used as a complete replacement when the API cannot be reached.
+     *
+     * Fallback order when API fails:
+     * 1. Stale cache (if allowStaleCache=true)
+     * 2. This offlineFallbackConfig
+     * 3. failSafeBehavior (deny-all or allow-all)
+     */
+    offlineFallbackConfig?: BaseToolProtectionMap;
     /**
      * Enable debug logging
      * @default false
@@ -128,9 +148,14 @@ export interface ToolProtectionServiceConfig {
      */
     cacheTtl?: number;
     /**
-     * Fallback configuration if API is unavailable
+     * Local configuration (LOWEST priority after defaults)
+     * Gets OVERRIDDEN by remote config from AgentShield API.
+     */
+    localConfig?: BaseToolProtectionMap;
+    /**
+     * Offline fallback configuration (ONLY used when API is unavailable)
      */
-    fallbackConfig?: BaseToolProtectionMap;
+    offlineFallbackConfig?: BaseToolProtectionMap;
     /**
      * Enable debug logging
      * @default false