@kya-os/contracts 1.6.2-canary.0 → 1.6.2

package/dist/agentshield-api/schemas.js

@@ -8,7 +8,7 @@
  * @package @kya-os/contracts/agentshield-api
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.revokeDelegationAPIResponseSchema = exports.revokeDelegationResponseSchema = exports.revokeDelegationRequestSchema = exports.createDelegationAPIResponseSchema = exports.createDelegationResponseSchema = exports.createDelegationRequestSchema = exports.toolProtectionConfigAPIResponseSchema = exports.toolProtectionConfigResponseSchema = exports.agentShieldToolProtectionSchema = exports.verifyDelegationAPIResponseSchema = exports.verifyDelegationResponseSchema = exports.verifyDelegationRequestSchema = exports.delegationCredentialSchema = exports.proofSubmissionResponseSchema = exports.proofSubmissionRequestSchema = exports.agentShieldAPIResponseSchema = exports.agentShieldAPIErrorSchema = void 0;
+exports.registerSessionAPIResponseSchema = exports.registerSessionResponseSchema = exports.registerSessionRequestSchema = exports.sessionClientIdentitySchema = exports.sessionClientInfoSchema = exports.revokeDelegationAPIResponseSchema = exports.revokeDelegationResponseSchema = exports.revokeDelegationRequestSchema = exports.createDelegationAPIResponseSchema = exports.createDelegationResponseSchema = exports.createDelegationRequestSchema = exports.toolProtectionConfigAPIResponseSchema = exports.toolProtectionConfigResponseSchema = exports.agentShieldToolProtectionSchema = exports.verifyDelegationAPIResponseSchema = exports.verifyDelegationResponseSchema = exports.verifyDelegationRequestSchema = exports.delegationCredentialSchema = exports.proofSubmissionResponseSchema = exports.proofSubmissionRequestSchema = exports.agentShieldAPIResponseSchema = exports.agentShieldAPIErrorSchema = void 0;
 const zod_1 = require("zod");
 const proof_js_1 = require("../proof.js");
 const index_js_1 = require("../delegation/index.js");
@@ -97,7 +97,7 @@ exports.proofSubmissionResponseSchema = zod_1.z.object({
     success: zod_1.z.boolean(),
     accepted: zod_1.z.number().int().min(0),
     rejected: zod_1.z.number().int().min(0),
-    outcomes: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().min(0)), // Record<BouncerOutcome, number>
+    outcomes: zod_1.z.record(zod_1.z.string(), zod_1.z.number().int().min(0)).optional(), // Record<BouncerOutcome, number> - Optional because API may return empty object or omit it
     errors: zod_1.z
         .array(zod_1.z.object({
         proof_index: zod_1.z.number().int().min(0),
@@ -199,7 +199,7 @@ exports.toolProtectionConfigAPIResponseSchema = (0, exports.agentShieldAPIRespon
  * Create delegation request schema
  *
  * Note: AgentShield API accepts a simplified format, not the full DelegationRecord.
- * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, custom_fields
+ * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, user_identifier, custom_fields
  *
  * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
  */
@@ -211,6 +211,7 @@ exports.createDelegationRequestSchema = zod_1.z
     expires_at: zod_1.z.string().datetime().optional(),
     session_id: zod_1.z.string().optional(),
     project_id: zod_1.z.string().uuid().optional(),
+    user_identifier: zod_1.z.string().max(200).optional(), // Matches AgentShield's max(200)
     custom_fields: zod_1.z.record(zod_1.z.unknown()).optional(),
 })
     .passthrough()
@@ -238,9 +239,9 @@ exports.createDelegationResponseSchema = zod_1.z.object({
     user_id: zod_1.z.string().optional(),
     user_identifier: zod_1.z.string().optional(),
     scopes: zod_1.z.array(zod_1.z.string()),
-    status: zod_1.z.literal("active"),
+    status: zod_1.z.enum(['active', 'expired', 'revoked']), // Matches AgentShield's actual API behavior
     issued_at: zod_1.z.string().datetime(),
-    expires_at: zod_1.z.string().datetime().optional(),
+    expires_at: zod_1.z.string().datetime().nullable().optional(), // AgentShield allows null values
     created_at: zod_1.z.string().datetime(),
 });
 /**
@@ -265,3 +266,49 @@ exports.revokeDelegationResponseSchema = zod_1.z.object({
  * Wrapped revocation response schema
  */
 exports.revokeDelegationAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.revokeDelegationResponseSchema);
+// ============================================================================
+// Session Registration Schemas
+// ============================================================================
+/**
+ * Session client info schema
+ */
+exports.sessionClientInfoSchema = zod_1.z.object({
+    name: zod_1.z.string().min(1, "Client name is required"),
+    version: zod_1.z.string().optional(),
+    protocol_version: zod_1.z.string().optional(),
+    platform: zod_1.z.string().optional(),
+    vendor: zod_1.z.string().optional(),
+});
+/**
+ * Session client identity schema
+ */
+exports.sessionClientIdentitySchema = zod_1.z.object({
+    did: zod_1.z.string().min(1, "Client DID is required"),
+    source: zod_1.z.enum(["knowthat.ai", "kta-lookup", "generated"]),
+    registered: zod_1.z.boolean(),
+});
+/**
+ * Register session request schema
+ */
+exports.registerSessionRequestSchema = zod_1.z.object({
+    session_id: zod_1.z.string().min(1, "Session ID is required"),
+    agent_did: zod_1.z.string().min(1, "Agent DID is required"),
+    project_id: zod_1.z.string().min(1, "Project ID is required"),
+    created_at: zod_1.z.number().int().positive("Created at must be a positive timestamp"),
+    client_info: exports.sessionClientInfoSchema,
+    client_identity: exports.sessionClientIdentitySchema.optional(),
+    server_did: zod_1.z.string().optional(),
+    ttl_minutes: zod_1.z.number().int().positive().optional(),
+});
+/**
+ * Register session response schema
+ */
+exports.registerSessionResponseSchema = zod_1.z.object({
+    session_id: zod_1.z.string().min(1),
+    registered: zod_1.z.boolean(),
+    created_at: zod_1.z.string().datetime(),
+});
+/**
+ * Wrapped session registration response schema
+ */
+exports.registerSessionAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.registerSessionResponseSchema);

package/dist/agentshield-api/types.d.ts

@@ -94,7 +94,7 @@ export interface ProofSubmissionResponse {
     success: boolean;
     accepted: number;
     rejected: number;
-    outcomes: Record<BouncerOutcome, number>;
+    outcomes?: Record<BouncerOutcome, number>;
     errors?: Array<{
         proof_index: number;
         error: {
@@ -188,7 +188,7 @@ export type ToolProtectionConfigAPIResponse = AgentShieldAPIResponse<ToolProtect
  * POST /api/v1/bouncer/delegations
  *
  * Note: AgentShield API accepts a simplified format, not the full DelegationRecord.
- * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, custom_fields
+ * The API accepts: agent_did, scopes, expires_in_days, expires_at, session_id, project_id, user_identifier, custom_fields
  *
  * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
  */
@@ -201,6 +201,8 @@ export interface CreateDelegationRequest {
     expires_at?: string;
     session_id?: string;
     project_id?: string;
+    /** User identifier string, max 200 chars, optional */
+    user_identifier?: string;
     custom_fields?: Record<string, unknown>;
 }
 /**
@@ -218,9 +220,9 @@ export interface CreateDelegationResponse {
     user_id?: string;
     user_identifier?: string;
     scopes: string[];
-    status: "active";
+    status: "active" | "expired" | "revoked";
     issued_at: string;
-    expires_at?: string;
+    expires_at?: string | null;
     created_at: string;
 }
 /**
@@ -246,6 +248,69 @@ export interface RevokeDelegationResponse {
  * Wrapped revocation response
  */
 export type RevokeDelegationAPIResponse = AgentShieldAPIResponse<RevokeDelegationResponse>;
+/**
+ * MCP Client information from the initialize message
+ */
+export interface SessionClientInfo {
+    /** Client application name (e.g., "Claude Desktop", "Anthropic/ClaudeAI") */
+    name: string;
+    /** Client version (e.g., "1.0.0") */
+    version?: string;
+    /** MCP protocol version (e.g., "2025-06-18") */
+    protocol_version?: string;
+    /** Platform (e.g., "darwin", "win32") */
+    platform?: string;
+    /** Vendor name (e.g., "Anthropic") */
+    vendor?: string;
+}
+/**
+ * Client identity resolution information
+ */
+export interface SessionClientIdentity {
+    /** Resolved DID for the client */
+    did: string;
+    /** Source of the DID */
+    source: "knowthat.ai" | "kta-lookup" | "generated";
+    /** Whether client is registered on knowthat.ai */
+    registered: boolean;
+}
+/**
+ * Request body for session registration endpoint
+ * POST /api/v1/bouncer/sessions
+ */
+export interface RegisterSessionRequest {
+    /** Unique session identifier (matches proof.meta.sessionId) */
+    session_id: string;
+    /** Agent's DID */
+    agent_did: string;
+    /** AgentShield project ID */
+    project_id: string;
+    /** Unix timestamp in milliseconds when session was created */
+    created_at: number;
+    /** MCP client information */
+    client_info: SessionClientInfo;
+    /** Client identity resolution (optional) */
+    client_identity?: SessionClientIdentity;
+    /** MCP server's DID (optional) */
+    server_did?: string;
+    /** Session TTL in minutes (default: 30) */
+    ttl_minutes?: number;
+}
+/**
+ * Response from session registration endpoint
+ */
+export interface RegisterSessionResponse {
+    /** The registered session ID */
+    session_id: string;
+    /** Whether registration was successful */
+    registered: boolean;
+    /** ISO 8601 timestamp of registration */
+    created_at: string;
+}
+/**
+ * Wrapped session registration response
+ */
+export type RegisterSessionAPIResponse = AgentShieldAPIResponse<RegisterSessionResponse>;
 /**
  * AgentShield API error class
  */

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