@kya-os/contracts 1.5.4-canary.3 → 1.6.0

package/dist/audit/index.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Audit Types and Schemas
+ *
+ * Types and Zod schemas for audit logging in the MCP-I framework.
+ * These types are platform-agnostic and used across all implementations.
+ */
+import { z } from "zod";
+import type { AgentIdentity } from "../config/identity.js";
+import type { SessionContext } from "../handshake.js";
+/**
+ * Audit context schema for logging audit records
+ *
+ * Contains all metadata needed to generate an audit record.
+ * Privacy Note: Only metadata is extracted from these objects.
+ * The identity's private key, session's nonce, and other sensitive
+ * fields are NEVER included in the audit log.
+ */
+export declare const AuditContextSchema: z.ZodObject<{
+    /**
+     * Agent identity
+     * Only `did` and `keyId` are logged. Private key is NEVER logged.
+     */
+    identity: z.ZodObject<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Session context
+     * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
+     */
+    session: z.ZodObject<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Request hash (SHA-256 with `sha256:` prefix)
+     */
+    requestHash: z.ZodString;
+    /**
+     * Response hash (SHA-256 with `sha256:` prefix)
+     */
+    responseHash: z.ZodString;
+    /**
+     * Verification result
+     * - 'yes': Proof was verified successfully
+     * - 'no': Proof verification failed
+     */
+    verified: z.ZodEnum<["yes", "no"]>;
+    /**
+     * Optional scope identifier
+     * Application-level scope (e.g., 'orders.create', 'users.read').
+     * If not provided, '-' is used in the audit log.
+     */
+    scopeId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    requestHash: string;
+    responseHash: string;
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
+    verified: "yes" | "no";
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    scopeId?: string | undefined;
+}, {
+    requestHash: string;
+    responseHash: string;
+    session: {
+        audience: string;
+        sessionId: string;
+    } & {
+        [k: string]: unknown;
+    };
+    verified: "yes" | "no";
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    scopeId?: string | undefined;
+}>;
+export type AuditContext = {
+    identity: AgentIdentity;
+    session: SessionContext;
+    requestHash: string;
+    responseHash: string;
+    verified: "yes" | "no";
+    scopeId?: string;
+};
+/**
+ * Event context schema for logging events that bypass session deduplication
+ *
+ * Used for consent events where multiple events occur in the same session.
+ * Unlike AuditContext, this allows multiple events per session.
+ */
+export declare const AuditEventContextSchema: z.ZodObject<{
+    /**
+     * Event type identifier
+     * @example "consent:page_viewed", "consent:approved", "runtime:initialized"
+     */
+    eventType: z.ZodString;
+    /**
+     * Agent identity
+     * Only `did` and `keyId` are logged. Private key is NEVER logged.
+     */
+    identity: z.ZodObject<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        did: z.ZodString;
+        kid: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Session context
+     * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
+     */
+    session: z.ZodObject<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        sessionId: z.ZodString;
+        audience: z.ZodString;
+    }, z.ZodTypeAny, "passthrough">>;
+    /**
+     * Optional event-specific data
+     * Used for generating event hash. Not logged directly.
+     */
+    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;
+    };
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    eventType: string;
+    eventData?: Record<string, unknown> | undefined;
+}>;
+export type AuditEventContext = {
+    eventType: string;
+    identity: AgentIdentity;
+    session: SessionContext;
+    eventData?: Record<string, any>;
+};
+export type { AuditRecord } from "../proof.js";
+export { AuditRecordSchema } from "../proof.js";

package/dist/audit/index.js

@@ -0,0 +1,100 @@
+"use strict";
+/**
+ * Audit Types and Schemas
+ *
+ * Types and Zod schemas for audit logging in the MCP-I framework.
+ * These types are platform-agnostic and used across all implementations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditRecordSchema = exports.AuditEventContextSchema = exports.AuditContextSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * Audit context schema for logging audit records
+ *
+ * Contains all metadata needed to generate an audit record.
+ * Privacy Note: Only metadata is extracted from these objects.
+ * The identity's private key, session's nonce, and other sensitive
+ * fields are NEVER included in the audit log.
+ */
+exports.AuditContextSchema = zod_1.z.object({
+    /**
+     * Agent identity
+     * Only `did` and `keyId` are logged. Private key is NEVER logged.
+     */
+    identity: zod_1.z
+        .object({
+        did: zod_1.z.string().min(1),
+        kid: zod_1.z.string().min(1),
+    })
+        .passthrough(), // Allow additional fields but only did/kid are used
+    /**
+     * Session context
+     * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
+     */
+    session: zod_1.z
+        .object({
+        sessionId: zod_1.z.string().min(1),
+        audience: zod_1.z.string().min(1),
+    })
+        .passthrough(), // Allow additional fields but only sessionId/audience are used
+    /**
+     * Request hash (SHA-256 with `sha256:` prefix)
+     */
+    requestHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    /**
+     * Response hash (SHA-256 with `sha256:` prefix)
+     */
+    responseHash: zod_1.z.string().regex(/^sha256:[a-f0-9]{64}$/),
+    /**
+     * Verification result
+     * - 'yes': Proof was verified successfully
+     * - 'no': Proof verification failed
+     */
+    verified: zod_1.z.enum(["yes", "no"]),
+    /**
+     * Optional scope identifier
+     * Application-level scope (e.g., 'orders.create', 'users.read').
+     * If not provided, '-' is used in the audit log.
+     */
+    scopeId: zod_1.z.string().optional(),
+});
+/**
+ * Event context schema for logging events that bypass session deduplication
+ *
+ * Used for consent events where multiple events occur in the same session.
+ * Unlike AuditContext, this allows multiple events per session.
+ */
+exports.AuditEventContextSchema = zod_1.z.object({
+    /**
+     * Event type identifier
+     * @example "consent:page_viewed", "consent:approved", "runtime:initialized"
+     */
+    eventType: zod_1.z.string().min(1),
+    /**
+     * Agent identity
+     * Only `did` and `keyId` are logged. Private key is NEVER logged.
+     */
+    identity: zod_1.z
+        .object({
+        did: zod_1.z.string().min(1),
+        kid: zod_1.z.string().min(1),
+    })
+        .passthrough(), // Allow additional fields but only did/kid are used
+    /**
+     * Session context
+     * Only `sessionId` and `audience` are logged. Nonce is NEVER logged.
+     */
+    session: zod_1.z
+        .object({
+        sessionId: zod_1.z.string().min(1),
+        audience: zod_1.z.string().min(1),
+    })
+        .passthrough(), // Allow additional fields but only sessionId/audience are used
+    /**
+     * Optional event-specific data
+     * Used for generating event hash. Not logged directly.
+     */
+    eventData: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+var proof_js_1 = require("../proof.js");
+Object.defineProperty(exports, "AuditRecordSchema", { enumerable: true, get: function () { return proof_js_1.AuditRecordSchema; } });

package/dist/config/identity.d.ts

@@ -6,6 +6,7 @@
  *
  * @module @kya-os/contracts/config
  */
+import { z } from "zod";
 /**
  * Runtime Identity Configuration
  *
@@ -25,7 +26,7 @@ export interface RuntimeIdentityConfig {
      * Runtime environment for identity
      * Determines where keys come from and how they're managed
      */
-    environment: 'development' | 'production';
+    environment: "development" | "production";
     /**
      * Production identity configuration
      * Used when environment is 'production'
@@ -71,7 +72,209 @@ export interface RuntimeIdentityConfig {
      * - 'persistent': User DIDs are persisted in storage (requires did:web setup)
      * @default 'ephemeral'
      */
-    userDidStorage?: 'ephemeral' | 'persistent';
+    userDidStorage?: "ephemeral" | "persistent";
+}
+/**
+ * OAuth Provider Configuration
+ *
+ * Configuration for a single OAuth provider (GitHub, Google, etc.)
+ */
+export interface OAuthProvider {
+    /** OAuth client ID (public, safe to expose) */
+    clientId: string;
+    /** OAuth client secret (NOT returned in API response for security) */
+    clientSecret?: string | null;
+    /** OAuth authorization URL */
+    authorizationUrl: string;
+    /** OAuth token exchange URL */
+    tokenUrl: string;
+    /** OAuth user info endpoint URL */
+    userInfoUrl?: string;
+    /** Whether provider supports PKCE (Proof Key for Code Exchange) */
+    supportsPKCE: boolean;
+    /** Whether provider requires client secret (false for PKCE-only providers) */
+    requiresClientSecret: boolean;
+    /** Available scopes for this provider */
+    scopes?: string[];
+    /** Default scopes to request */
+    defaultScopes?: string[];
+    /** Whether provider uses proxy mode (via AgentShield) */
+    proxyMode?: boolean;
+    /** Custom OAuth parameters to include in authorization URL (e.g., audience, acr_values) */
+    customParams?: Record<string, string>;
+    /** Token endpoint authentication method */
+    tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic";
+    /** OAuth response type (default: "code") */
+    responseType?: string;
+    /** OAuth grant type (default: "authorization_code") */
+    grantType?: string;
+}
+/**
+ * OAuth Configuration
+ *
+ * Configuration for OAuth providers fetched from AgentShield API.
+ * Contains all available providers for a project.
+ *
+ * Note: API does NOT return a defaultProvider field (Phase 1 architecture).
+ * Phase 1 uses configured provider as temporary fallback.
+ * Phase 2+ requires tools to explicitly specify oauthProvider.
+ */
+export interface OAuthConfig {
+    /** Map of provider names to provider configurations */
+    providers: Record<string, OAuthProvider>;
+}
+/**
+ * Zod schema for OAuthProvider validation
+ */
+export declare const OAuthProviderSchema: z.ZodObject<{
+    clientId: z.ZodString;
+    clientSecret: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    authorizationUrl: z.ZodString;
+    tokenUrl: z.ZodString;
+    userInfoUrl: z.ZodOptional<z.ZodString>;
+    supportsPKCE: z.ZodBoolean;
+    requiresClientSecret: z.ZodBoolean;
+    scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    defaultScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    proxyMode: z.ZodOptional<z.ZodBoolean>;
+    customParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    tokenEndpointAuthMethod: z.ZodOptional<z.ZodEnum<["client_secret_post", "client_secret_basic"]>>;
+    responseType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    grantType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    clientId: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    supportsPKCE: boolean;
+    requiresClientSecret: boolean;
+    responseType: string;
+    grantType: string;
+    scopes?: string[] | undefined;
+    clientSecret?: string | null | undefined;
+    userInfoUrl?: string | undefined;
+    defaultScopes?: string[] | undefined;
+    proxyMode?: boolean | undefined;
+    customParams?: Record<string, string> | undefined;
+    tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+}, {
+    clientId: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    supportsPKCE: boolean;
+    requiresClientSecret: boolean;
+    scopes?: string[] | undefined;
+    clientSecret?: string | null | undefined;
+    userInfoUrl?: string | undefined;
+    defaultScopes?: string[] | undefined;
+    proxyMode?: boolean | undefined;
+    customParams?: Record<string, string> | undefined;
+    tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+    responseType?: string | undefined;
+    grantType?: string | undefined;
+}>;
+/**
+ * Zod schema for OAuthConfig validation
+ */
+export declare const OAuthConfigSchema: z.ZodObject<{
+    providers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        clientId: z.ZodString;
+        clientSecret: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        authorizationUrl: z.ZodString;
+        tokenUrl: z.ZodString;
+        userInfoUrl: z.ZodOptional<z.ZodString>;
+        supportsPKCE: z.ZodBoolean;
+        requiresClientSecret: z.ZodBoolean;
+        scopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        defaultScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        proxyMode: z.ZodOptional<z.ZodBoolean>;
+        customParams: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        tokenEndpointAuthMethod: z.ZodOptional<z.ZodEnum<["client_secret_post", "client_secret_basic"]>>;
+        responseType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        grantType: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        responseType: string;
+        grantType: string;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+    }, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+        responseType?: string | undefined;
+        grantType?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    providers: Record<string, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        responseType: string;
+        grantType: string;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+    }>;
+}, {
+    providers: Record<string, {
+        clientId: string;
+        authorizationUrl: string;
+        tokenUrl: string;
+        supportsPKCE: boolean;
+        requiresClientSecret: boolean;
+        scopes?: string[] | undefined;
+        clientSecret?: string | null | undefined;
+        userInfoUrl?: string | undefined;
+        defaultScopes?: string[] | undefined;
+        proxyMode?: boolean | undefined;
+        customParams?: Record<string, string> | undefined;
+        tokenEndpointAuthMethod?: "client_secret_post" | "client_secret_basic" | undefined;
+        responseType?: string | undefined;
+        grantType?: string | undefined;
+    }>;
+}>;
+/**
+ * IDP Tokens
+ *
+ * Tokens received from OAuth provider (IDP = Identity Provider)
+ */
+export interface IdpTokens {
+    /** OAuth access token for API calls */
+    access_token: string;
+    /** OAuth refresh token (optional) */
+    refresh_token?: string;
+    /** Token expiration time in seconds */
+    expires_in?: number;
+    /** Token expiration timestamp (milliseconds since epoch) */
+    expires_at: number;
+    /** Token type (usually "Bearer") */
+    token_type: string;
+    /** Granted scopes */
+    scope?: string;
 }
 /**
  * Agent identity representation

package/dist/config/identity.js

@@ -8,3 +8,31 @@
  * @module @kya-os/contracts/config
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.OAuthConfigSchema = exports.OAuthProviderSchema = void 0;
+const zod_1 = require("zod");
+/**
+ * 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"),
+});
+/**
+ * Zod schema for OAuthConfig validation
+ */
+exports.OAuthConfigSchema = zod_1.z.object({
+    providers: zod_1.z.record(zod_1.z.string(), exports.OAuthProviderSchema),
+});

package/dist/config/index.d.ts

@@ -12,7 +12,8 @@ import type { ProofingConfig } from "./proofing.js";
 import type { DelegationConfig } from "./delegation.js";
 import type { ToolProtectionSourceConfig } from "./tool-protection.js";
 export { MCPIBaseConfig } from "./base.js";
-export { RuntimeIdentityConfig, AgentIdentity } from "./identity.js";
+export { RuntimeIdentityConfig, AgentIdentity, OAuthProvider, OAuthConfig, IdpTokens, } from "./identity.js";
+export type { ToolExecutionContext } from "./tool-context.js";
 /**
  * @deprecated Use RuntimeIdentityConfig instead
  * This export is maintained for backward compatibility

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

@@ -0,0 +1,34 @@
+/**
+ * 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
+ */
+/**
+ * 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)
+ * - 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;
+    /** OAuth provider name (e.g., "github", "google") */
+    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;
+}

package/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 });