@kya-os/contracts 1.5.3-canary.1 → 1.5.3-canary.11

package/dist/agentshield-api/schemas.js

@@ -48,6 +48,32 @@ const toolCallContextSchema = zod_1.z.object({
     scopeId: zod_1.z.string().min(1, "scopeId is required to link context to proof"),
     userIdentifier: zod_1.z.string().optional(),
 });
+/**
+ * Consent Event Context Schema
+ * Represents consent-related events for audit tracking
+ */
+const consentEventContextSchema = zod_1.z.object({
+    eventType: zod_1.z.enum([
+        "consent:page_viewed",
+        "consent:approved",
+        "consent:delegation_created",
+        "consent:credential_required"
+    ]),
+    timestamp: zod_1.z.number().int().positive(),
+    sessionId: zod_1.z.string().min(1),
+    userDid: zod_1.z.string().optional(),
+    agentDid: zod_1.z.string().min(1),
+    targetTools: zod_1.z.array(zod_1.z.string()).min(1), // ALWAYS array
+    scopes: zod_1.z.array(zod_1.z.string()).min(0),
+    delegationId: zod_1.z.string().uuid().optional(),
+    projectId: zod_1.z.string().uuid(),
+    termsAccepted: zod_1.z.boolean().optional(),
+    credentialStatus: zod_1.z.enum(["present", "required", "obtained"]).optional(),
+    oauthIdentity: zod_1.z.object({
+        provider: zod_1.z.string(),
+        identifier: zod_1.z.string(),
+    }).optional(),
+});
 /**
  * Proof submission request schema
  */
@@ -59,6 +85,7 @@ exports.proofSubmissionRequestSchema = zod_1.z.object({
     context: zod_1.z
         .object({
         toolCalls: zod_1.z.array(toolCallContextSchema).optional(),
+        consentEvents: zod_1.z.array(consentEventContextSchema).optional(), // NEW: Consent events for audit tracking
         mcpServerUrl: zod_1.z.string().url().optional(), // MCP server URL for tool discovery
     })
         .optional(),
@@ -172,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.
  */
@@ -184,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()
@@ -211,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(),
 });
 /**

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

@@ -41,6 +41,30 @@ export interface ToolCallContext {
     scopeId: string;
     userIdentifier?: string;
 }
+/**
+ * Consent Event Context
+ *
+ * Represents consent-related events that occur during the consent flow.
+ * These events are logged separately from tool executions and allow
+ * multiple events per session (unlike regular audit logs).
+ */
+export interface ConsentEventContext {
+    eventType: "consent:page_viewed" | "consent:approved" | "consent:delegation_created" | "consent:credential_required";
+    timestamp: number;
+    sessionId: string;
+    userDid?: string;
+    agentDid: string;
+    targetTools: string[];
+    scopes: string[];
+    delegationId?: string;
+    projectId: string;
+    termsAccepted?: boolean;
+    credentialStatus?: "present" | "required" | "obtained";
+    oauthIdentity?: {
+        provider: string;
+        identifier: string;
+    };
+}
 /**
  * Request body for proof submission endpoint
  * POST /api/v1/bouncer/proofs
@@ -55,6 +79,7 @@ export interface ProofSubmissionRequest {
     /** AgentShield extension: Optional context for dashboard enrichment */
     context?: {
         toolCalls?: ToolCallContext[];
+        consentEvents?: ConsentEventContext[];
         mcpServerUrl?: string;
     };
 }
@@ -163,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.
  */
@@ -176,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>;
 }
 /**
@@ -193,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;
 }
 /**

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, {
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    session: {
+        sessionId: string;
+        audience: string;
+    } & {
+        [k: string]: unknown;
+    };
+    requestHash: string;
+    responseHash: string;
+    verified: "yes" | "no";
+    scopeId?: string | undefined;
+}, {
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    session: {
+        sessionId: string;
+        audience: string;
+    } & {
+        [k: string]: unknown;
+    };
+    requestHash: string;
+    responseHash: string;
+    verified: "yes" | "no";
+    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, {
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    session: {
+        sessionId: string;
+        audience: string;
+    } & {
+        [k: string]: unknown;
+    };
+    eventType: string;
+    eventData?: Record<string, unknown> | undefined;
+}, {
+    identity: {
+        did: string;
+        kid: string;
+    } & {
+        [k: string]: unknown;
+    };
+    session: {
+        sessionId: string;
+        audience: 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,92 @@
+"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/consent/schemas.d.ts

@@ -6,7 +6,7 @@
  *
  * Related Spec: MCP-I Phase 0 Implementation Plan
  */
-import { z } from 'zod';
+import { z } from "zod";
 /**
  * Consent Branding Schema
  */
@@ -357,8 +357,11 @@ export declare const consentApprovalRequestSchema: z.ZodObject<{
     /**
      * OAuth provider identity information (optional)
      * Used to link OAuth accounts to persistent User DIDs
+     *
+     * CRITICAL: Uses .nullish() to accept null, undefined, or OAuthIdentity
+     * This matches JSON parsing behavior where missing fields become null
      */
-    oauth_identity: z.ZodOptional<z.ZodObject<{
+    oauth_identity: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         /**
          * OAuth provider name (e.g., "google", "github", "microsoft")
          */
@@ -386,7 +389,7 @@ export declare const consentApprovalRequestSchema: z.ZodObject<{
         subject: string;
         name?: string | undefined;
         email?: string | undefined;
-    }>>;
+    }>>>;
     /**
      * User DID (optional)
      * If provided, represents the persistent User DID for this user
@@ -394,11 +397,11 @@ export declare const consentApprovalRequestSchema: z.ZodObject<{
      */
     user_did: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    agent_did: string;
-    project_id: string;
     tool: string;
     scopes: string[];
+    agent_did: string;
     session_id: string;
+    project_id: string;
     termsAccepted: boolean;
     customFields?: Record<string, string | boolean> | undefined;
     termsVersion?: string | undefined;
@@ -407,14 +410,14 @@ export declare const consentApprovalRequestSchema: z.ZodObject<{
         subject: string;
         name?: string | undefined;
         email?: string | undefined;
-    } | undefined;
+    } | null | undefined;
     user_did?: string | undefined;
 }, {
-    agent_did: string;
-    project_id: string;
     tool: string;
     scopes: string[];
+    agent_did: string;
     session_id: string;
+    project_id: string;
     termsAccepted: boolean;
     customFields?: Record<string, string | boolean> | undefined;
     termsVersion?: string | undefined;
@@ -423,7 +426,7 @@ export declare const consentApprovalRequestSchema: z.ZodObject<{
         subject: string;
         name?: string | undefined;
         email?: string | undefined;
-    } | undefined;
+    } | null | undefined;
     user_did?: string | undefined;
 }>;
 export type ConsentApprovalRequest = z.infer<typeof consentApprovalRequestSchema>;
@@ -723,11 +726,11 @@ export declare function validateConsentPageConfig(config: unknown): z.SafeParseR
  * @returns Validation result
  */
 export declare function validateConsentApprovalRequest(request: unknown): z.SafeParseReturnType<{
-    agent_did: string;
-    project_id: string;
     tool: string;
     scopes: string[];
+    agent_did: string;
     session_id: string;
+    project_id: string;
     termsAccepted: boolean;
     customFields?: Record<string, string | boolean> | undefined;
     termsVersion?: string | undefined;
@@ -736,14 +739,14 @@ export declare function validateConsentApprovalRequest(request: unknown): z.Safe
         subject: string;
         name?: string | undefined;
         email?: string | undefined;
-    } | undefined;
+    } | null | undefined;
     user_did?: string | undefined;
 }, {
-    agent_did: string;
-    project_id: string;
     tool: string;
     scopes: string[];
+    agent_did: string;
     session_id: string;
+    project_id: string;
     termsAccepted: boolean;
     customFields?: Record<string, string | boolean> | undefined;
     termsVersion?: string | undefined;
@@ -752,7 +755,7 @@ export declare function validateConsentApprovalRequest(request: unknown): z.Safe
         subject: string;
         name?: string | undefined;
         email?: string | undefined;
-    } | undefined;
+    } | null | undefined;
     user_did?: string | undefined;
 }>;
 /**