@kya-os/cli 2.0.0 → 2.0.3

package/node_modules/@kya-os/contracts/dist/agentshield-api/schemas.js

@@ -0,0 +1,340 @@
+"use strict";
+/**
+ * AgentShield/Bouncer API Zod Validation Schemas
+ *
+ * Runtime validation schemas matching the API contract types.
+ * These schemas ensure request/response validation before sending/receiving.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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 index_js_1 = require("../proof/index.js");
+const index_js_2 = require("../delegation/index.js");
+/**
+ * Standard error schema
+ */
+exports.agentShieldAPIErrorSchema = zod_1.z.object({
+    code: zod_1.z.string(),
+    message: zod_1.z.string(),
+    details: zod_1.z.record(zod_1.z.unknown()).optional(),
+});
+/**
+ * Standard API response wrapper schema
+ */
+const agentShieldAPIResponseSchema = (dataSchema) => zod_1.z.object({
+    success: zod_1.z.boolean(),
+    data: dataSchema,
+    metadata: zod_1.z
+        .object({
+        requestId: zod_1.z.string(),
+        timestamp: zod_1.z.string(),
+    })
+        .optional(),
+});
+exports.agentShieldAPIResponseSchema = agentShieldAPIResponseSchema;
+// ============================================================================
+// Proof Submission Schemas
+// ============================================================================
+/**
+ * Tool Call Context Schema (AgentShield Extension)
+ * Optional plaintext context for dashboard enrichment
+ */
+const toolCallContextSchema = zod_1.z.object({
+    tool: zod_1.z.string().min(1, "Tool name is required"),
+    args: zod_1.z.record(zod_1.z.unknown()),
+    result: zod_1.z.unknown().optional(),
+    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",
+        "auth:credential_success",
+        "auth:credential_failed",
+        "auth:oauth_success",
+        "auth:oauth_failed"
+    ]),
+    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
+ */
+exports.proofSubmissionRequestSchema = zod_1.z.object({
+    session_id: zod_1.z.string().max(100), // AgentShield session ID (may differ from MCP-I sessionId)
+    delegation_id: zod_1.z.string().uuid().nullish(),
+    proofs: zod_1.z.array(index_js_1.DetachedProofSchema).min(1),
+    // AgentShield extension: Optional context for dashboard enrichment
+    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(),
+});
+/**
+ * Proof submission response schema
+ */
+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)).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),
+        error: zod_1.z.object({
+            code: zod_1.z.string(),
+            message: zod_1.z.string(),
+            details: zod_1.z.record(zod_1.z.unknown()).optional(),
+        }),
+    }))
+        .optional(),
+});
+// ============================================================================
+// Delegation Verification Schemas
+// ============================================================================
+/**
+ * Delegation credential schema
+ */
+exports.delegationCredentialSchema = zod_1.z.object({
+    agent_did: zod_1.z.string(),
+    user_did: zod_1.z.string().min(1), // REQUIRED: DID of authorizing user
+    user_id: zod_1.z.string().optional(),
+    user_identifier: zod_1.z.string().optional(),
+    scopes: zod_1.z.array(zod_1.z.string()),
+    constraints: zod_1.z.record(zod_1.z.unknown()).optional(),
+    issued_at: zod_1.z.number().int().positive(),
+    created_at: zod_1.z.number().int().positive(),
+    credential_jwt: zod_1.z.string().optional(),
+    authorization: zod_1.z.object({
+        // 'oauth' is deprecated, use 'oauth2' instead (will be removed in v2.0.0)
+        // 'webauthn' and 'siwe' added in v1.7.16
+        type: zod_1.z.enum(['oauth', 'oauth2', 'password', 'credential', 'webauthn', 'siwe', 'none']),
+        provider: zod_1.z.string().optional(),
+        credentialType: zod_1.z.string().optional(),
+        // WebAuthn-specific fields
+        rpId: zod_1.z.string().optional(),
+        userVerification: zod_1.z.enum(['required', 'preferred', 'discouraged']).optional(),
+        // SIWE-specific fields
+        chainId: zod_1.z.number().optional(),
+        domain: zod_1.z.string().optional(),
+    }),
+});
+/**
+ * Delegation verification request schema
+ */
+exports.verifyDelegationRequestSchema = zod_1.z.object({
+    agent_did: zod_1.z.string(),
+    // User DID for user-scoped delegation verification (RECOMMENDED)
+    // Prevents cross-user delegation leakage where User B could use User A's delegation
+    user_did: zod_1.z.string().optional(),
+    credential_jwt: zod_1.z.string().optional(), // Optional, omit (don't set to empty string) when not available for OAuth flow
+    delegation_token: zod_1.z.string().optional(), // Optional, for stateless MCP servers
+    scopes: zod_1.z.array(zod_1.z.string()).optional(), // Optional, can be empty array
+    timestamp: zod_1.z.number().int().positive().optional(),
+    client_info: zod_1.z
+        .object({
+        ip_address: zod_1.z.string().ip().optional(),
+        origin: zod_1.z.string().url().optional(),
+        user_agent: zod_1.z.string().optional(),
+    })
+        .optional(),
+}).partial({ scopes: true }); // Make scopes truly optional by using partial
+/**
+ * Delegation verification response schema
+ */
+exports.verifyDelegationResponseSchema = zod_1.z.object({
+    valid: zod_1.z.boolean(),
+    delegation: index_js_2.DelegationRecordSchema.optional(),
+    delegation_id: zod_1.z.string().uuid().optional(),
+    credential: exports.delegationCredentialSchema.optional(),
+    error: exports.agentShieldAPIErrorSchema.optional(),
+    reason: zod_1.z.string().optional(),
+});
+/**
+ * Wrapped verification response schema
+ */
+exports.verifyDelegationAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.verifyDelegationResponseSchema);
+// ============================================================================
+// Tool Protection Configuration Schemas
+// ============================================================================
+/**
+ * AgentShield tool protection schema (supports both snake_case and camelCase)
+ * This is the API-specific format, not the MCP-I spec schema
+ */
+exports.agentShieldToolProtectionSchema = zod_1.z
+    .object({
+    scopes: zod_1.z.array(zod_1.z.string()),
+    requires_delegation: zod_1.z.boolean().optional(),
+    requiresDelegation: zod_1.z.boolean().optional(),
+    required_scopes: zod_1.z.array(zod_1.z.string()).optional(),
+})
+    .passthrough(); // Allow additional properties
+/**
+ * Tool protection config response schema
+ */
+exports.toolProtectionConfigResponseSchema = zod_1.z.object({
+    agent_did: zod_1.z.string(),
+    tools: zod_1.z.record(zod_1.z.string(), exports.agentShieldToolProtectionSchema),
+    reputation_threshold: zod_1.z.number().min(0).max(1).optional(),
+    denied_agents: zod_1.z.array(zod_1.z.string()).optional(),
+    crisp_budget: zod_1.z
+        .object({
+        max_tokens: zod_1.z.number(),
+        max_cost: zod_1.z.number(),
+        currency: zod_1.z.string(),
+        time_window: zod_1.z.string(),
+    })
+        .optional(),
+});
+/**
+ * Wrapped config response schema
+ */
+exports.toolProtectionConfigAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.toolProtectionConfigResponseSchema);
+// ============================================================================
+// Delegation Management Schemas
+// ============================================================================
+/**
+ * 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, user_identifier, custom_fields
+ *
+ * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
+ */
+exports.createDelegationRequestSchema = zod_1.z
+    .object({
+    agent_did: zod_1.z.string().min(1),
+    scopes: zod_1.z.array(zod_1.z.string()).min(1),
+    expires_in_days: zod_1.z.number().int().positive().optional(),
+    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()
+    .refine((data) => {
+    // expires_in_days and expires_at are mutually exclusive
+    const hasExpiresInDays = data.expires_in_days !== undefined;
+    const hasExpiresAt = data.expires_at !== undefined;
+    return !(hasExpiresInDays && hasExpiresAt);
+}, {
+    message: "expires_in_days and expires_at are mutually exclusive - use one or the other, not both",
+    path: ["expires_in_days", "expires_at"],
+});
+/**
+ * Create delegation response schema
+ *
+ * Canonical format returned by POST /api/v1/bouncer/delegations
+ *
+ * As of AgentShield v2.x, delegation_token (JWT) IS returned for stateless verification.
+ * The JWT enables MCP-I servers to verify delegations without database lookups.
+ */
+exports.createDelegationResponseSchema = zod_1.z.object({
+    delegation_id: zod_1.z.string().uuid(),
+    agent_did: zod_1.z.string().min(1),
+    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.enum(['active', 'expired', 'revoked']), // Matches AgentShield's actual API behavior
+    issued_at: zod_1.z.string().datetime(),
+    expires_at: zod_1.z.string().datetime().nullable().optional(), // AgentShield allows null values
+    created_at: zod_1.z.string().datetime(),
+    // JWT for stateless verification (added in AgentShield v2.x)
+    delegation_token: zod_1.z.string().optional(),
+    token_type: zod_1.z.string().optional(), // "Bearer"
+    expires_in: zod_1.z.number().int().positive().optional(), // Seconds until token expiry
+});
+/**
+ * Wrapped creation response schema
+ */
+exports.createDelegationAPIResponseSchema = (0, exports.agentShieldAPIResponseSchema)(exports.createDelegationResponseSchema);
+/**
+ * Revoke delegation request schema
+ */
+exports.revokeDelegationRequestSchema = zod_1.z.object({
+    reason: zod_1.z.string().optional(),
+});
+/**
+ * Revoke delegation response schema
+ */
+exports.revokeDelegationResponseSchema = zod_1.z.object({
+    delegation_id: zod_1.z.string().uuid(),
+    revoked: zod_1.z.boolean(),
+    revoked_at: zod_1.z.number().int().positive(),
+});
+/**
+ * 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"),
+    agent_name: zod_1.z.string().optional(), // Human-readable agent name for dashboard display
+    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/node_modules/@kya-os/contracts/dist/agentshield-api/types.d.ts

@@ -0,0 +1,344 @@
+/**
+ * AgentShield/Bouncer API Type Definitions
+ *
+ * TypeScript interfaces matching the AgentShield dashboard API contract.
+ * These types ensure parity between xmcp-i clients and the AgentShield service.
+ *
+ * @package @kya-os/contracts/agentshield-api
+ */
+import type { DetachedProof } from "../proof/index.js";
+import type { DelegationRecord } from "../delegation/index.js";
+/**
+ * Standard AgentShield API response wrapper
+ */
+export interface AgentShieldAPIResponse<T> {
+    success: boolean;
+    data: T;
+    metadata?: {
+        requestId: string;
+        timestamp: string;
+    };
+}
+/**
+ * Standard AgentShield API error response structure
+ * (Use AgentShieldAPIError class for runtime errors)
+ */
+export interface AgentShieldAPIErrorResponse {
+    code: string;
+    message: string;
+    details?: Record<string, unknown>;
+}
+/**
+ * Tool Call Context (AgentShield Extension to MCP-I)
+ *
+ * Optional plaintext context for dashboard enrichment.
+ * Links to MCP-I proof via scopeId.
+ */
+export interface ToolCallContext {
+    tool: string;
+    args: Record<string, unknown>;
+    result?: unknown;
+    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" | "auth:credential_success" | "auth:credential_failed" | "auth:oauth_success" | "auth:oauth_failed";
+    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
+ */
+export interface ProofSubmissionRequest {
+    /** Delegation ID (nullable, optional - null if no delegation context) */
+    delegation_id?: string | null;
+    /** Session ID for grouping proofs (AgentShield session ID, may differ from MCP-I sessionId) */
+    session_id: string;
+    /** Array of proofs to submit */
+    proofs: DetachedProof[];
+    /** AgentShield extension: Optional context for dashboard enrichment */
+    context?: {
+        toolCalls?: ToolCallContext[];
+        consentEvents?: ConsentEventContext[];
+        mcpServerUrl?: string;
+    };
+}
+/**
+ * Bouncer outcome types
+ */
+export type BouncerOutcome = "success" | "failed" | "blocked" | "error";
+/**
+ * Response from proof submission endpoint
+ */
+export interface ProofSubmissionResponse {
+    success: boolean;
+    accepted: number;
+    rejected: number;
+    outcomes?: Record<BouncerOutcome, number>;
+    errors?: Array<{
+        proof_index: number;
+        error: {
+            code: string;
+            message: string;
+            details?: Record<string, unknown>;
+        };
+    }>;
+}
+/**
+ * Request body for delegation verification endpoint
+ * POST /api/v1/bouncer/delegations/verify
+ */
+export interface VerifyDelegationRequest {
+    /** Agent DID to verify */
+    agent_did: string;
+    /**
+     * User DID for user-scoped delegation verification (RECOMMENDED)
+     *
+     * When provided, AgentShield validates that the delegation belongs to this specific user.
+     * This prevents cross-user delegation leakage where User B could use User A's delegation.
+     *
+     * Without user_did, verification relies on delegation_token alone which may not provide
+     * user-level isolation in all scenarios (e.g., legacy agent-only delegations).
+     */
+    user_did?: string;
+    /** Credential JWT (optional, defaults to empty string for OAuth flow) */
+    credential_jwt?: string;
+    /** Delegation token from OAuth flow (optional, for stateless MCP servers) */
+    delegation_token?: string;
+    /** Required scopes (optional, can be empty array) */
+    scopes?: string[];
+    /** Optional timestamp for verification */
+    timestamp?: number;
+    /** Optional client info for IP/origin checking */
+    client_info?: {
+        ip_address?: string;
+        origin?: string;
+        user_agent?: string;
+    };
+}
+/**
+ * Credential information returned in verification response
+ */
+export interface DelegationCredential {
+    agent_did: string;
+    user_did: string;
+    user_id?: string;
+    user_identifier?: string;
+    scopes: string[];
+    constraints?: Record<string, unknown>;
+    issued_at: number;
+    created_at: number;
+    credential_jwt?: string;
+    authorization: {
+        type: 'oauth' | 'oauth2' | 'password' | 'credential' | 'webauthn' | 'siwe' | 'none';
+        provider?: string;
+        credentialType?: string;
+        rpId?: string;
+        userVerification?: 'required' | 'preferred' | 'discouraged';
+        chainId?: number;
+        domain?: string;
+    };
+}
+/**
+ * Response from delegation verification endpoint
+ */
+export interface VerifyDelegationResponse {
+    valid: boolean;
+    delegation?: DelegationRecord;
+    delegation_id?: string;
+    credential?: DelegationCredential;
+    error?: AgentShieldAPIErrorResponse;
+    reason?: string;
+}
+/**
+ * Wrapped verification response (AgentShield wraps in success/data)
+ */
+export type VerifyDelegationAPIResponse = AgentShieldAPIResponse<VerifyDelegationResponse>;
+/**
+ * AgentShield API tool protection format for a single tool
+ * This is the API-specific format, not the MCP-I spec type
+ */
+export interface AgentShieldToolProtection {
+    scopes: string[];
+    requires_delegation?: boolean;
+    requiresDelegation?: boolean;
+    required_scopes?: string[];
+}
+/**
+ * Response from tool protection config endpoint
+ * GET /api/v1/bouncer/projects/{projectId}/config
+ */
+export interface ToolProtectionConfigResponse {
+    agent_did: string;
+    tools: Record<string, AgentShieldToolProtection>;
+    reputation_threshold?: number;
+    denied_agents?: string[];
+    crisp_budget?: {
+        max_tokens: number;
+        max_cost: number;
+        currency: string;
+        time_window: string;
+    };
+}
+/**
+ * Wrapped config response
+ */
+export type ToolProtectionConfigAPIResponse = AgentShieldAPIResponse<ToolProtectionConfigResponse>;
+/**
+ * Request body for creating a delegation
+ * 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, user_identifier, custom_fields
+ *
+ * IMPORTANT: expires_in_days and expires_at are mutually exclusive - use one or the other, not both.
+ */
+export interface CreateDelegationRequest {
+    agent_did: string;
+    scopes: string[];
+    /** Number of days until expiration (1-365). Mutually exclusive with expires_at. */
+    expires_in_days?: number;
+    /** ISO 8601 datetime when delegation expires. Mutually exclusive with expires_in_days. */
+    expires_at?: string;
+    session_id?: string;
+    project_id?: string;
+    /** User identifier string, max 200 chars, optional */
+    user_identifier?: string;
+    custom_fields?: Record<string, unknown>;
+}
+/**
+ * Response from delegation creation endpoint
+ *
+ * Canonical format returned by POST /api/v1/bouncer/delegations
+ *
+ * IMPORTANT: delegation_token is NOT returned by this endpoint.
+ * delegation_token is only available via OAuth callback flow (/api/v1/bouncer/oauth/callback)
+ * and is passed as a URL parameter, not in the API response body.
+ */
+export interface CreateDelegationResponse {
+    delegation_id: string;
+    agent_did: string;
+    user_id?: string;
+    user_identifier?: string;
+    scopes: string[];
+    status: "active" | "expired" | "revoked";
+    issued_at: string;
+    expires_at?: string | null;
+    created_at: string;
+}
+/**
+ * Wrapped creation response
+ */
+export type CreateDelegationAPIResponse = AgentShieldAPIResponse<CreateDelegationResponse>;
+/**
+ * Request body for revoking a delegation
+ * POST /api/v1/bouncer/delegations/{id}/revoke
+ */
+export interface RevokeDelegationRequest {
+    reason?: string;
+}
+/**
+ * Response from delegation revocation endpoint
+ */
+export interface RevokeDelegationResponse {
+    delegation_id: string;
+    revoked: boolean;
+    revoked_at: number;
+}
+/**
+ * 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;
+    /** Human-readable agent name for dashboard display (optional) */
+    agent_name?: 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
+ */
+export declare class AgentShieldAPIError extends Error {
+    readonly code: string;
+    readonly details?: Record<string, unknown> | undefined;
+    constructor(code: string, message: string, details?: Record<string, unknown> | undefined);
+}