@kya-os/cli 2.0.0 → 2.0.2

package/node_modules/@kya-os/contracts/dist/config/identity.js

@@ -0,0 +1,155 @@
+"use strict";
+/**
+ * Identity Configuration Types
+ *
+ * Configuration for MCP-I identity management including DID generation,
+ * key management, and environment-specific settings.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentIdentitySchema = exports.KTARegistrationSchema = exports.AuthProviderSchema = exports.OAuth2ProviderConfigSchema = exports.OAuthConfigSchema = exports.OAuthProviderSchema = exports.OAuthProviderSecretMetadataSchema = exports.CredentialProviderConfigSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Zod schema for CredentialProviderConfig validation
+ */
+exports.CredentialProviderConfigSchema = zod_1.z.object({
+    type: zod_1.z.literal("credential"),
+    displayName: zod_1.z.string().optional(),
+    authEndpoint: zod_1.z.string().url(),
+    requestBodyTemplate: zod_1.z.record(zod_1.z.string()),
+    responseFields: zod_1.z.object({
+        sessionToken: zod_1.z.string(),
+        userId: zod_1.z.string().optional(),
+        userEmail: zod_1.z.string().optional(),
+        userDisplayName: zod_1.z.string().optional(),
+        expiresIn: zod_1.z.string().optional(),
+    }),
+    successCheck: zod_1.z
+        .object({
+        path: zod_1.z.string(),
+        expectedValue: zod_1.z.union([zod_1.z.string(), zod_1.z.boolean(), zod_1.z.number()]),
+    })
+        .optional(),
+    headers: zod_1.z.record(zod_1.z.string()).optional(),
+    tokenUsage: zod_1.z.enum(["cookie", "bearer", "header"]).optional(),
+    tokenHeader: zod_1.z.string().optional(),
+    cookieFormat: zod_1.z.string().optional(),
+    apiHeaders: zod_1.z.record(zod_1.z.string()).optional(),
+    consentOverrides: zod_1.z
+        .object({
+        branding: zod_1.z.record(zod_1.z.unknown()).optional(),
+        formTitle: zod_1.z.string().optional(),
+        formDescription: zod_1.z.string().optional(),
+        identityFieldLabel: zod_1.z.string().optional(),
+        identityFieldType: zod_1.z.enum(["text", "email", "tel"]).optional(),
+        passwordFieldLabel: zod_1.z.string().optional(),
+        submitButtonText: zod_1.z.string().optional(),
+    })
+        .optional(),
+});
+/**
+ * Zod schema for OAuthProviderSecretMetadata validation
+ */
+exports.OAuthProviderSecretMetadataSchema = zod_1.z.object({
+    clientSecretName: zod_1.z.string().optional(),
+    clientIdSecretName: zod_1.z.string().optional(),
+    apiKeySecretName: zod_1.z.string().optional(),
+    clientSecretVersion: zod_1.z.number().optional(),
+    lastRotatedAt: zod_1.z.string().optional(),
+});
+/**
+ * Zod schema for OAuthProvider validation
+ */
+exports.OAuthProviderSchema = zod_1.z.object({
+    clientId: zod_1.z.string().min(1),
+    clientSecret: zod_1.z.string().nullable().optional(),
+    authorizationUrl: zod_1.z.string().url(),
+    tokenUrl: zod_1.z.string().url(),
+    userInfoUrl: zod_1.z.string().url().optional(),
+    supportsPKCE: zod_1.z.boolean(),
+    requiresClientSecret: zod_1.z.boolean(),
+    scopes: zod_1.z.array(zod_1.z.string()).optional(),
+    defaultScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    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(),
+    responseType: zod_1.z.string().optional().default("code"),
+    grantType: zod_1.z.string().optional().default("authorization_code"),
+    // MCP-I Provider Registry
+    hasClientSecret: zod_1.z.boolean().optional(),
+    metadata: exports.OAuthProviderSecretMetadataSchema.optional(),
+});
+/**
+ * Zod schema for OAuthConfig validation
+ */
+exports.OAuthConfigSchema = zod_1.z.object({
+    providers: zod_1.z.record(zod_1.z.string(), exports.OAuthProviderSchema),
+    configuredProvider: zod_1.z.string().nullable().optional(),
+});
+/**
+ * Zod schema for OAuth2ProviderConfig validation
+ */
+exports.OAuth2ProviderConfigSchema = zod_1.z.object({
+    type: zod_1.z.literal("oauth2"),
+    displayName: zod_1.z.string().optional(),
+    clientId: zod_1.z.string().min(1),
+    clientSecret: zod_1.z.string().nullable().optional(),
+    authorizationUrl: zod_1.z.string().url(),
+    tokenUrl: zod_1.z.string().url(),
+    userInfoUrl: zod_1.z.string().url().optional(),
+    supportsPKCE: zod_1.z.boolean(),
+    requiresClientSecret: zod_1.z.boolean(),
+    scopes: zod_1.z.array(zod_1.z.string()).optional(),
+    defaultScopes: zod_1.z.array(zod_1.z.string()).optional(),
+    proxyMode: zod_1.z.boolean().optional(),
+    customParams: zod_1.z.record(zod_1.z.string()).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"),
+    // MCP-I Provider Registry
+    hasClientSecret: zod_1.z.boolean().optional(),
+    metadata: exports.OAuthProviderSecretMetadataSchema.optional(),
+});
+/**
+ * Zod schema for AuthProvider validation (discriminated union)
+ */
+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/node_modules/@kya-os/contracts/dist/config/index.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Configuration Type Exports
+ *
+ * Central export point for all configuration types in the contracts package.
+ * These types form the foundation of XMCP-I's configuration architecture.
+ *
+ * @module @kya-os/contracts/config
+ */
+import type { MCPIBaseConfig } from "./base.js";
+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";
+import type { PolicyConfig } from "../policy/index.js";
+export { MCPIBaseConfig } from "./base.js";
+export { withCheckpointNames, type CheckpointSettingName } from "./checkpoint-env.js";
+export { RuntimeIdentityConfig, AgentIdentity, OAuthProvider, OAuthConfig, IdpTokens, AuthProviderType, BaseProviderConfig, CredentialProviderConfig, CredentialProviderConfigSchema, OAuth2ProviderConfig, OAuth2ProviderConfigSchema, AuthProvider, AuthProviderSchema, OAuthProviderSecretMetadata, OAuthProviderSecretMetadataSchema, OAuthProviderSchema, OAuthConfigSchema, } from "./identity.js";
+export type { ToolExecutionContext, VerifiedDelegation, } from "./tool-context.js";
+/**
+ * @deprecated Use RuntimeIdentityConfig instead
+ * This export is maintained for backward compatibility
+ */
+export type IdentityConfig = RuntimeIdentityConfig;
+export { ProofingConfig, ProofBatchQueueConfig, ProofDestination, ProofDestinationType, } from "./proofing.js";
+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 { DELEGATION_DENIAL_CODES, type DelegationDenialCode, } from "./delegation-denial.js";
+export { TOOL_REFUSAL_META_KEY, markToolRefusal, readToolRefusal, type ToolRefusal, type ToolRefusalMeta, } from "./tool-refusal.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
+ */
+export interface MCPIConfig extends MCPIBaseConfig {
+    identity?: RuntimeIdentityConfig;
+    proofing?: ProofingConfig;
+    delegation?: DelegationConfig;
+    toolProtection?: ToolProtectionSourceConfig;
+    /** Client-specific message configuration for delegation errors */
+    clientMessages?: ClientMessagesConfig;
+    /** Policy configuration for agent access control */
+    policy?: PolicyConfig;
+}

package/node_modules/@kya-os/contracts/dist/config/index.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Configuration Type Exports
+ *
+ * Central export point for all configuration types in the contracts package.
+ * These types form the foundation of XMCP-I's configuration architecture.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateClientMessagesConfig = exports.validateClientMessageTemplate = exports.isClientMessagesConfig = exports.isClientMessageTemplate = exports.ClientMessagesConfigSchema = exports.ClientMessageTemplateSchema = exports.readToolRefusal = exports.markToolRefusal = exports.TOOL_REFUSAL_META_KEY = exports.DELEGATION_DENIAL_CODES = exports.buildBaseConfig = exports.OAuthConfigSchema = exports.OAuthProviderSchema = exports.OAuthProviderSecretMetadataSchema = exports.AuthProviderSchema = exports.OAuth2ProviderConfigSchema = exports.CredentialProviderConfigSchema = exports.withCheckpointNames = void 0;
+// Checkpoint settings, read under their current names
+var checkpoint_env_js_1 = require("./checkpoint-env.js");
+Object.defineProperty(exports, "withCheckpointNames", { enumerable: true, get: function () { return checkpoint_env_js_1.withCheckpointNames; } });
+// Identity configuration
+var identity_js_1 = require("./identity.js");
+Object.defineProperty(exports, "CredentialProviderConfigSchema", { enumerable: true, get: function () { return identity_js_1.CredentialProviderConfigSchema; } });
+Object.defineProperty(exports, "OAuth2ProviderConfigSchema", { enumerable: true, get: function () { return identity_js_1.OAuth2ProviderConfigSchema; } });
+Object.defineProperty(exports, "AuthProviderSchema", { enumerable: true, get: function () { return identity_js_1.AuthProviderSchema; } });
+Object.defineProperty(exports, "OAuthProviderSecretMetadataSchema", { enumerable: true, get: function () { return identity_js_1.OAuthProviderSecretMetadataSchema; } });
+Object.defineProperty(exports, "OAuthProviderSchema", { enumerable: true, get: function () { return identity_js_1.OAuthProviderSchema; } });
+Object.defineProperty(exports, "OAuthConfigSchema", { enumerable: true, get: function () { return identity_js_1.OAuthConfigSchema; } });
+// Configuration builder utilities
+var builder_js_1 = require("./builder.js");
+Object.defineProperty(exports, "buildBaseConfig", { enumerable: true, get: function () { return builder_js_1.buildBaseConfig; } });
+// Delegation denial codes (verifier refusals surfaced to clients and audit)
+var delegation_denial_js_1 = require("./delegation-denial.js");
+Object.defineProperty(exports, "DELEGATION_DENIAL_CODES", { enumerable: true, get: function () { return delegation_denial_js_1.DELEGATION_DENIAL_CODES; } });
+// Tool refusal marker (a policy refusal, told apart from a tool error)
+var tool_refusal_js_1 = require("./tool-refusal.js");
+Object.defineProperty(exports, "TOOL_REFUSAL_META_KEY", { enumerable: true, get: function () { return tool_refusal_js_1.TOOL_REFUSAL_META_KEY; } });
+Object.defineProperty(exports, "markToolRefusal", { enumerable: true, get: function () { return tool_refusal_js_1.markToolRefusal; } });
+Object.defineProperty(exports, "readToolRefusal", { enumerable: true, get: function () { return tool_refusal_js_1.readToolRefusal; } });
+// 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; } });

package/node_modules/@kya-os/contracts/dist/config/proofing.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Proofing Configuration Types
+ *
+ * Configuration for proof generation and submission including batch
+ * processing, destinations, and retry logic.
+ *
+ * @module @kya-os/contracts/config
+ */
+/**
+ * Proof destination types
+ */
+export type ProofDestinationType = 'agentshield' | 'kta' | 'custom';
+/**
+ * Proof destination configuration
+ * Defines where proofs should be submitted
+ */
+export interface ProofDestination {
+    /**
+     * Type of destination
+     */
+    type: ProofDestinationType;
+    /**
+     * API base URL for the destination
+     * Required for 'agentshield' and 'kta' types
+     * @example 'https://kya.vouched.id'
+     */
+    apiUrl?: string;
+    /**
+     * API key for authentication
+     * Required for most destinations
+     */
+    apiKey?: string;
+    /**
+     * Custom submission function
+     * Required for 'custom' type destinations
+     */
+    submit?: (proofs: any[]) => Promise<void>;
+    /**
+     * Additional destination-specific configuration
+     */
+    options?: Record<string, unknown>;
+}
+/**
+ * Proof batch queue configuration
+ * Controls how proofs are batched and submitted
+ */
+export interface ProofBatchQueueConfig {
+    /**
+     * Destinations where proofs should be sent
+     * Multiple destinations are processed in parallel
+     */
+    destinations: ProofDestination[];
+    /**
+     * Maximum number of proofs to batch before auto-submission
+     * @default 10
+     */
+    maxBatchSize?: number;
+    /**
+     * Time interval (ms) between automatic flush attempts
+     * @default 5000
+     */
+    flushIntervalMs?: number;
+    /**
+     * Maximum number of retry attempts for failed submissions
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * Backoff multiplier for retry delays
+     * @default 2
+     */
+    retryBackoff?: number;
+    /**
+     * Enable debug logging for proof submission
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * Proofing configuration (platform-agnostic)
+ *
+ * Controls proof generation, batching, and submission to external services
+ * like AgentShield or Know That AI (KTA).
+ */
+export interface ProofingConfig {
+    /**
+     * Enable proof generation and submission
+     * @default true
+     */
+    enabled: boolean;
+    /**
+     * Proof batch queue configuration
+     * Controls batching and submission behavior
+     */
+    batchQueue?: ProofBatchQueueConfig;
+    /**
+     * Include additional metadata in proofs
+     * @default true
+     */
+    includeMetadata?: boolean;
+    /**
+     * Custom proof generation options
+     */
+    options?: {
+        /**
+         * Include timestamp in all proofs
+         * @default true
+         */
+        includeTimestamp?: boolean;
+        /**
+         * Include session context in proofs
+         * @default true
+         */
+        includeSession?: boolean;
+        /**
+         * Custom fields to include in every proof
+         */
+        customFields?: Record<string, unknown>;
+    };
+}

package/node_modules/@kya-os/contracts/dist/config/proofing.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Proofing Configuration Types
+ *
+ * Configuration for proof generation and submission including batch
+ * processing, destinations, and retry logic.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/node_modules/@kya-os/contracts/dist/config/tool-context.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Tool Execution Context
+ *
+ * Execution context passed to tool handlers, enabling tools to access
+ * IDP tokens for external API calls (GitHub, Google, etc.).
+ *
+ * All fields are optional for backward compatibility - tools that don't
+ * require OAuth will receive undefined context.
+ *
+ * @package @kya-os/contracts
+ */
+/**
+ * The delegation the verifier accepted for THIS tool call.
+ *
+ * Built by the runtime from the verify response of the current call only.
+ * Handlers that enforce grant limits (spend caps, product scope) should read
+ * `constraints` from here rather than decoding the stored delegation token:
+ * this is what the verifier checked moments ago, including live revocation.
+ */
+export interface VerifiedDelegation {
+    /** Delegation id from the verify response (the VC `jti`) */
+    id?: string;
+    /** Agent DID the delegation was issued to (`credential.agent_did`) */
+    agentDid?: string;
+    /** DID of the user who authorized the delegation (`credential.user_did`) */
+    userDid?: string;
+    /** Scopes as the verifier returned them */
+    scopes: string[];
+    /**
+     * Grant constraints as the verifier returned them (a deep copy, so a
+     * handler cannot mutate the verify response). Carries `crisp` when the
+     * grant was created with a mandate.
+     */
+    constraints?: Record<string, unknown>;
+    /** Authorization method recorded on the grant (`credential.authorization.type`) */
+    authorizationType?: string;
+    /** Expiry in unix seconds, from `constraints.not_after` when it is set and positive */
+    expiresAt?: number;
+}
+/**
+ * Execution context passed to tool handlers
+ *
+ * Enables tools to access IDP tokens for external API calls.
+ * Context is only provided when:
+ * - Tool requires OAuth (has requiredScopes) or credential-based auth
+ * - User DID is available
+ * - IDP token is successfully resolved
+ */
+export interface ToolExecutionContext {
+    /** IDP access token for external API calls (e.g., GitHub, Google) */
+    idpToken?: string;
+    /**
+     * Pre-built headers for API calls (CRED-003)
+     *
+     * For OAuth providers: typically { Authorization: "Bearer xxx" }
+     * For credential providers: based on tokenUsage configuration
+     * - cookie: { Cookie: "formatted_cookie_string" }
+     * - bearer: { Authorization: "Bearer xxx" }
+     * - header: { [customHeader]: "xxx" }
+     *
+     * Also includes any additional apiHeaders from provider config.
+     */
+    idpHeaders?: Record<string, string>;
+    /** OAuth provider name (e.g., "github", "google") or credential provider */
+    provider?: string;
+    /** Scopes granted for this token */
+    scopes?: string[];
+    /** User DID associated with this token */
+    userDid?: string;
+    /** Session ID */
+    sessionId?: string;
+    /** Delegation token (MCP-I internal authorization) */
+    delegationToken?: string;
+    /**
+     * User ID from credential provider (CRED-003)
+     *
+     * For credential providers, this is the userId extracted from the
+     * authentication response via responseFields.userId configuration.
+     * This allows tool handlers to access the external system's user ID
+     * (e.g., customer ID for an e-commerce API).
+     *
+     * For OAuth providers, this is typically not set (use userDid instead).
+     */
+    userId?: string;
+    /**
+     * The delegation verified for this call.
+     *
+     * Set only by the runtime, from this call's successful verify response.
+     * Undefined for unprotected tools and for verifiers that return no
+     * credential (KV and memory verifiers). Never populated from tool
+     * arguments, session storage or decoded tokens.
+     */
+    verifiedDelegation?: VerifiedDelegation;
+}

package/node_modules/@kya-os/contracts/dist/config/tool-context.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Tool Execution Context
+ *
+ * Execution context passed to tool handlers, enabling tools to access
+ * IDP tokens for external API calls (GitHub, Google, etc.).
+ *
+ * All fields are optional for backward compatibility - tools that don't
+ * require OAuth will receive undefined context.
+ *
+ * @package @kya-os/contracts
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/node_modules/@kya-os/contracts/dist/config/tool-protection.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Tool Protection Configuration Types
+ *
+ * Configuration for tool protection including delegation requirements,
+ * scopes, and multi-source resolution strategies.
+ *
+ * @module @kya-os/contracts/config
+ */
+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;
+export type ToolProtectionResponse = BaseToolProtectionResponse;
+/**
+ * Tool protection source types
+ */
+export type ToolProtectionSourceType = "inline" | "local" | "agentshield" | "kta" | "multi";
+/**
+ * Tool protection source configuration
+ * Defines where tool protection settings come from
+ */
+export interface ToolProtectionSourceConfig {
+    /**
+     * Type of source to use
+     */
+    source: ToolProtectionSourceType;
+    /**
+     * Inline tool protection map
+     * Used when source is 'inline'
+     */
+    inline?: BaseToolProtectionMap;
+    /**
+     * Path to local tool protections file
+     * Used when source is 'local'
+     * @example './tool-protections.json'
+     */
+    localFile?: string;
+    /**
+     * AgentShield configuration
+     * Used when source is 'agentshield'
+     */
+    agentShield?: {
+        /**
+         * AgentShield API base URL
+         * @example 'https://kya.vouched.id'
+         */
+        apiUrl: string;
+        /**
+         * API key for authentication
+         */
+        apiKey?: string;
+        /**
+         * Project ID (optional, for backward compatibility)
+         * Modern approach uses agent DID
+         */
+        projectId?: string;
+        /**
+         * Cache TTL in milliseconds
+         * @default 300000 (5 minutes)
+         */
+        cacheTtl?: number;
+    };
+    /**
+     * KTA configuration
+     * Used when source is 'kta'
+     */
+    kta?: {
+        /**
+         * KTA API base URL
+         */
+        apiUrl: string;
+        /**
+         * API key for authentication
+         */
+        apiKey?: string;
+    };
+    /**
+     * Multi-source configuration
+     * Used when source is 'multi'
+     * Sources are checked in priority order
+     */
+    sources?: Array<{
+        /**
+         * Source configuration
+         */
+        config: Omit<ToolProtectionSourceConfig, "source" | "sources">;
+        /**
+         * Priority (higher number = higher priority)
+         * @default 0
+         */
+        priority?: number;
+        /**
+         * Whether to stop after this source if found
+         * @default false
+         */
+        exclusive?: boolean;
+    }>;
+    /**
+     * 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
+     */
+    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
+     */
+    debug?: boolean;
+}
+/**
+ * Tool protection service configuration
+ * Used by provider-based implementations
+ */
+export interface ToolProtectionServiceConfig {
+    /**
+     * API base URL for fetching tool protections
+     */
+    apiUrl: string;
+    /**
+     * API key for authentication
+     */
+    apiKey: string;
+    /**
+     * Project ID (optional)
+     */
+    projectId?: string;
+    /**
+     * Cache TTL in milliseconds
+     * @default 300000 (5 minutes)
+     */
+    cacheTtl?: number;
+    /**
+     * 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)
+     */
+    offlineFallbackConfig?: BaseToolProtectionMap;
+    /**
+     * Enable debug logging
+     * @default false
+     */
+    debug?: boolean;
+}

package/node_modules/@kya-os/contracts/dist/config/tool-protection.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Tool Protection Configuration Types
+ *
+ * Configuration for tool protection including delegation requirements,
+ * scopes, and multi-source resolution strategies.
+ *
+ * @module @kya-os/contracts/config
+ */
+Object.defineProperty(exports, "__esModule", { value: true });