@kya-os/cli 1.8.3 → 2.0.2

package/node_modules/@kya-os/contracts/dist/handshake/schemas.d.ts

@@ -0,0 +1,557 @@
+import { z } from "zod";
+/**
+ * Handshake and session management schemas
+ */
+/**
+ * Session Identity State
+ *
+ * Tracks whether a session has been authenticated via OAuth.
+ * Phase 5: Anonymous Sessions Until OAuth
+ *
+ * - 'anonymous': No userDid assigned yet (session started without OAuth)
+ * - 'authenticated': userDid assigned via OAuth → AgentShield identity resolution
+ */
+export declare const SessionIdentityStateSchema: z.ZodEnum<["anonymous", "authenticated"]>;
+export type SessionIdentityState = z.infer<typeof SessionIdentityStateSchema>;
+declare const MCPClientCapabilitiesSchema: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+export declare const MCPClientInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodString>;
+    vendor: z.ZodOptional<z.ZodString>;
+    persistentId: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    version?: string | undefined;
+    title?: string | undefined;
+    platform?: string | undefined;
+    vendor?: string | undefined;
+    persistentId?: string | undefined;
+}, {
+    name: string;
+    version?: string | undefined;
+    title?: string | undefined;
+    platform?: string | undefined;
+    vendor?: string | undefined;
+    persistentId?: string | undefined;
+}>;
+export declare const MCPClientSessionInfoSchema: z.ZodObject<{
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    platform: z.ZodOptional<z.ZodString>;
+    vendor: z.ZodOptional<z.ZodString>;
+    persistentId: z.ZodOptional<z.ZodString>;
+} & {
+    clientId: z.ZodString;
+    protocolVersion: z.ZodOptional<z.ZodString>;
+    capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    clientId: string;
+    version?: string | undefined;
+    title?: string | undefined;
+    platform?: string | undefined;
+    vendor?: string | undefined;
+    persistentId?: string | undefined;
+    protocolVersion?: string | undefined;
+    capabilities?: Record<string, unknown> | undefined;
+}, {
+    name: string;
+    clientId: string;
+    version?: string | undefined;
+    title?: string | undefined;
+    platform?: string | undefined;
+    vendor?: string | undefined;
+    persistentId?: string | undefined;
+    protocolVersion?: string | undefined;
+    capabilities?: Record<string, unknown> | undefined;
+}>;
+export declare const HandshakeRequestSchema: z.ZodObject<{
+    nonce: z.ZodString;
+    audience: z.ZodString;
+    timestamp: z.ZodNumber;
+    agentDid: z.ZodOptional<z.ZodString>;
+    clientInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        persistentId: z.ZodOptional<z.ZodString>;
+    } & {
+        clientId: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        clientId?: string | undefined;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+    }, {
+        name: string;
+        clientId?: string | undefined;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+    }>>;
+    clientProtocolVersion: z.ZodOptional<z.ZodString>;
+    clientCapabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    timestamp: number;
+    nonce: string;
+    audience: string;
+    agentDid?: string | undefined;
+    clientInfo?: {
+        name: string;
+        clientId?: string | undefined;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+    } | undefined;
+    clientProtocolVersion?: string | undefined;
+    clientCapabilities?: Record<string, unknown> | undefined;
+}, {
+    timestamp: number;
+    nonce: string;
+    audience: string;
+    agentDid?: string | undefined;
+    clientInfo?: {
+        name: string;
+        clientId?: string | undefined;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+    } | undefined;
+    clientProtocolVersion?: string | undefined;
+    clientCapabilities?: Record<string, unknown> | undefined;
+}>;
+export declare const SessionContextSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    audience: z.ZodString;
+    nonce: z.ZodString;
+    timestamp: z.ZodNumber;
+    createdAt: z.ZodNumber;
+    lastActivity: z.ZodNumber;
+    ttlMinutes: z.ZodDefault<z.ZodNumber>;
+    agentDid: z.ZodOptional<z.ZodString>;
+    serverDid: z.ZodOptional<z.ZodString>;
+    clientDid: z.ZodOptional<z.ZodString>;
+    userDid: z.ZodOptional<z.ZodString>;
+    clientInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        version: z.ZodOptional<z.ZodString>;
+        platform: z.ZodOptional<z.ZodString>;
+        vendor: z.ZodOptional<z.ZodString>;
+        persistentId: z.ZodOptional<z.ZodString>;
+    } & {
+        clientId: z.ZodString;
+        protocolVersion: z.ZodOptional<z.ZodString>;
+        capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        clientId: string;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+        protocolVersion?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    }, {
+        name: string;
+        clientId: string;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+        protocolVersion?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    }>>;
+    /**
+     * Identity state of the session
+     * @default 'anonymous' - Sessions start anonymous until OAuth completes
+     */
+    identityState: z.ZodDefault<z.ZodEnum<["anonymous", "authenticated"]>>;
+    /**
+     * OAuth identity information (populated after successful OAuth)
+     * Contains provider, subject, email from OAuth provider
+     */
+    oauthIdentity: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        subject: z.ZodString;
+        email: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        provider: string;
+        subject: string;
+        name?: string | undefined;
+        email?: string | undefined;
+    }, {
+        provider: string;
+        subject: string;
+        name?: string | undefined;
+        email?: string | undefined;
+    }>>;
+    /**
+     * Delegation VC credential ID for the active delegation.
+     * Set after delegation verification succeeds for a protected tool call.
+     * Used by outbound fetch interceptors as the delegation reference embedded
+     * in the KYA-OS-Delegation-Chain / KYA-OS-Delegation-Proof headers.
+     */
+    delegationRef: z.ZodOptional<z.ZodString>;
+    /**
+     * Reference chain string for the delegation hierarchy.
+     * Format: "vc_id_1>del_id_1>vc_id_2>del_id_2"
+     * Used by outbound fetch interceptors to inject KYA-OS-Delegation-Chain header.
+     */
+    delegationChain: z.ZodOptional<z.ZodString>;
+    /**
+     * Scopes granted by the active delegation.
+     * Used by outbound fetch interceptors to inject KYA-OS-Granted-Scopes header.
+     */
+    delegationScopes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    timestamp: number;
+    createdAt: number;
+    nonce: string;
+    audience: string;
+    sessionId: string;
+    lastActivity: number;
+    ttlMinutes: number;
+    identityState: "authenticated" | "anonymous";
+    agentDid?: string | undefined;
+    clientInfo?: {
+        name: string;
+        clientId: string;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+        protocolVersion?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    } | undefined;
+    serverDid?: string | undefined;
+    clientDid?: string | undefined;
+    userDid?: string | undefined;
+    oauthIdentity?: {
+        provider: string;
+        subject: string;
+        name?: string | undefined;
+        email?: string | undefined;
+    } | undefined;
+    delegationRef?: string | undefined;
+    delegationChain?: string | undefined;
+    delegationScopes?: string[] | undefined;
+}, {
+    timestamp: number;
+    createdAt: number;
+    nonce: string;
+    audience: string;
+    sessionId: string;
+    lastActivity: number;
+    agentDid?: string | undefined;
+    clientInfo?: {
+        name: string;
+        clientId: string;
+        version?: string | undefined;
+        title?: string | undefined;
+        platform?: string | undefined;
+        vendor?: string | undefined;
+        persistentId?: string | undefined;
+        protocolVersion?: string | undefined;
+        capabilities?: Record<string, unknown> | undefined;
+    } | undefined;
+    ttlMinutes?: number | undefined;
+    serverDid?: string | undefined;
+    clientDid?: string | undefined;
+    userDid?: string | undefined;
+    identityState?: "authenticated" | "anonymous" | undefined;
+    oauthIdentity?: {
+        provider: string;
+        subject: string;
+        name?: string | undefined;
+        email?: string | undefined;
+    } | undefined;
+    delegationRef?: string | undefined;
+    delegationChain?: string | undefined;
+    delegationScopes?: string[] | undefined;
+}>;
+export declare const NonceCacheEntrySchema: z.ZodObject<{
+    sessionId: z.ZodString;
+    expiresAt: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    sessionId: string;
+    expiresAt: number;
+}, {
+    sessionId: string;
+    expiresAt: number;
+}>;
+export type MCPClientInfo = z.infer<typeof MCPClientInfoSchema>;
+export type MCPClientSessionInfo = z.infer<typeof MCPClientSessionInfoSchema>;
+export type HandshakeRequest = z.infer<typeof HandshakeRequestSchema>;
+export type SessionContext = z.infer<typeof SessionContextSchema>;
+export type MCPClientCapabilities = z.infer<typeof MCPClientCapabilitiesSchema>;
+export type NonceCacheEntry = z.infer<typeof NonceCacheEntrySchema>;
+/**
+ * Nonce cache interface for replay prevention
+ */
+export interface NonceCache {
+    /**
+     * Check if a nonce exists in the cache
+     * @param nonce - The nonce to check
+     * @param agentDid - Optional agent DID for agent-scoped nonces (prevents cross-agent replay attacks)
+     */
+    has(nonce: string, agentDid?: string): Promise<boolean>;
+    /**
+     * Add a nonce to the cache with TTL
+     * MUST ensure atomic add-if-absent semantics for replay prevention
+     * @param nonce - The nonce to add
+     * @param ttl - Time to live in seconds
+     * @param agentDid - Optional agent DID for agent-scoped nonces (prevents cross-agent replay attacks)
+     */
+    add(nonce: string, ttl: number, agentDid?: string): Promise<void>;
+    /**
+     * Clean up expired entries
+     * Should be safe to call frequently and should be no-op for backends that auto-expire
+     */
+    cleanup(): Promise<void>;
+}
+/**
+ * Configuration for nonce cache implementations
+ */
+export declare const NonceCacheConfigSchema: z.ZodObject<{
+    type: z.ZodOptional<z.ZodEnum<["memory", "redis", "dynamodb", "cloudflare-kv"]>>;
+    redis: z.ZodOptional<z.ZodObject<{
+        url: z.ZodString;
+        keyPrefix: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        url: string;
+        keyPrefix: string;
+    }, {
+        url: string;
+        keyPrefix?: string | undefined;
+    }>>;
+    dynamodb: z.ZodOptional<z.ZodObject<{
+        tableName: z.ZodString;
+        region: z.ZodOptional<z.ZodString>;
+        keyAttribute: z.ZodDefault<z.ZodString>;
+        ttlAttribute: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        tableName: string;
+        keyAttribute: string;
+        ttlAttribute: string;
+        region?: string | undefined;
+    }, {
+        tableName: string;
+        region?: string | undefined;
+        keyAttribute?: string | undefined;
+        ttlAttribute?: string | undefined;
+    }>>;
+    cloudflareKv: z.ZodOptional<z.ZodObject<{
+        namespace: z.ZodString;
+        keyPrefix: z.ZodDefault<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        keyPrefix: string;
+        namespace: string;
+    }, {
+        namespace: string;
+        keyPrefix?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    type?: "memory" | "redis" | "dynamodb" | "cloudflare-kv" | undefined;
+    redis?: {
+        url: string;
+        keyPrefix: string;
+    } | undefined;
+    dynamodb?: {
+        tableName: string;
+        keyAttribute: string;
+        ttlAttribute: string;
+        region?: string | undefined;
+    } | undefined;
+    cloudflareKv?: {
+        keyPrefix: string;
+        namespace: string;
+    } | undefined;
+}, {
+    type?: "memory" | "redis" | "dynamodb" | "cloudflare-kv" | undefined;
+    redis?: {
+        url: string;
+        keyPrefix?: string | undefined;
+    } | undefined;
+    dynamodb?: {
+        tableName: string;
+        region?: string | undefined;
+        keyAttribute?: string | undefined;
+        ttlAttribute?: string | undefined;
+    } | undefined;
+    cloudflareKv?: {
+        namespace: string;
+        keyPrefix?: string | undefined;
+    } | undefined;
+}>;
+export type NonceCacheConfig = z.infer<typeof NonceCacheConfigSchema>;
+export declare const DEFAULT_SESSION_TTL_MINUTES = 30;
+export declare const DEFAULT_TIMESTAMP_SKEW_SECONDS = 120;
+export declare const NONCE_LENGTH_BYTES = 16;
+/**
+ * JWS `typ` header for a DIDComm proof-of-possession.
+ *
+ * A verifier MUST reject a proof whose `typ` differs. Without that check a JWS
+ * minted for some other purpose — an API token, a delegation credential — could
+ * be replayed as a possession proof, since both are signed by the same key.
+ */
+export declare const DIDCOMM_POP_TYP = "didcomm-pop+jwt";
+/** Signature algorithm. Ed25519 throughout the platform. */
+export declare const DIDCOMM_POP_ALG = "EdDSA";
+/**
+ * Claims a proof carries.
+ *
+ * `nonce` is the hub's challenge, which makes the proof fresh and single-use.
+ * `sub` binds it to the DID that presented the key, so a valid proof for one DID
+ * cannot be replayed as another's.
+ */
+export declare const DIDCommPopClaimsSchema: z.ZodObject<{
+    /** The exact nonce the hub issued. */
+    nonce: z.ZodString;
+    /** The DID being proven. */
+    sub: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    nonce: string;
+    sub: string;
+}, {
+    nonce: string;
+    sub: string;
+}>;
+export type DIDCommPopClaims = z.infer<typeof DIDCommPopClaimsSchema>;
+/**
+ * The `observe` frame an observer sends to attach to a hub.
+ *
+ * `did` and `publicKey` are optional on the wire because a hub may admit a
+ * loopback observer without them. When the hub requires authentication, both are
+ * needed: the DID to bind the proof to, and the key to verify the binding before
+ * a challenge is spent.
+ */
+export declare const ObserverHelloSchema: z.ZodObject<{
+    type: z.ZodLiteral<"observe">;
+    did: z.ZodOptional<z.ZodString>;
+    /** JSON-serialised public JWK. */
+    publicKey: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    type: "observe";
+    did?: string | undefined;
+    publicKey?: string | undefined;
+}, {
+    type: "observe";
+    did?: string | undefined;
+    publicKey?: string | undefined;
+}>;
+export type ObserverHello = z.infer<typeof ObserverHelloSchema>;
+/** The hub's challenge, and the answer to it. */
+export declare const DIDCommChallengeSchema: z.ZodObject<{
+    type: z.ZodLiteral<"challenge">;
+    nonce: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "challenge";
+    nonce: string;
+}, {
+    type: "challenge";
+    nonce: string;
+}>;
+export type DIDCommChallenge = z.infer<typeof DIDCommChallengeSchema>;
+export declare const DIDCommProofSchema: z.ZodObject<{
+    type: z.ZodLiteral<"proof">;
+    /** Compact JWS over {@link DIDCommPopClaimsSchema}. */
+    jws: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "proof";
+    jws: string;
+}, {
+    type: "proof";
+    jws: string;
+}>;
+export type DIDCommProof = z.infer<typeof DIDCommProofSchema>;
+/**
+ * Lifecycle status kinds a wrapper reports. `dispatch_result` and
+ * `dispatch_refused` only occur for a profile whose `commandAllowlist` is
+ * non-empty (contracts has no opinion on the allowlist itself -- that lives
+ * on the profile, on disk, on the user's machine).
+ */
+export declare const AGENT_STATUS_KINDS: readonly ["started", "heartbeat", "stopped", "dispatch_result", "dispatch_refused"];
+export declare const AgentStatusKindSchema: z.ZodEnum<["started", "heartbeat", "stopped", "dispatch_result", "dispatch_refused"]>;
+export type AgentStatusKind = z.infer<typeof AgentStatusKindSchema>;
+/**
+ * A wrapper's lifecycle report, sent hub-ward over its attached connection.
+ *
+ * `detail` is deliberately an OPEN record rather than a per-status union of
+ * required fields: v1 is process-level only (started/heartbeat/stopped), and
+ * task-level detail arriving later (once a harness exposes hooks) must not
+ * require a new message `type` -- only a new key inside `detail`. Adding a
+ * required field here for one status would also make it meaningless for
+ * every other status, which `.record` avoids by construction.
+ */
+export declare const AgentStatusReportSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent_status">;
+    /** The reporting profile's DID -- who this status is about. */
+    did: z.ZodString;
+    slug: z.ZodString;
+    status: z.ZodEnum<["started", "heartbeat", "stopped", "dispatch_result", "dispatch_refused"]>;
+    timestamp: z.ZodNumber;
+    detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    type: "agent_status";
+    status: "stopped" | "started" | "heartbeat" | "dispatch_result" | "dispatch_refused";
+    timestamp: number;
+    did: string;
+    slug: string;
+    detail: Record<string, unknown>;
+}, {
+    type: "agent_status";
+    status: "stopped" | "started" | "heartbeat" | "dispatch_result" | "dispatch_refused";
+    timestamp: number;
+    did: string;
+    slug: string;
+    detail: Record<string, unknown>;
+}>;
+export type AgentStatusReport = z.infer<typeof AgentStatusReportSchema>;
+/**
+ * A hub-originated task, addressed to one wrapper. The wrapper MUST refuse
+ * (never execute) any `command` that is not an exact-match entry in its
+ * profile's on-disk `commandAllowlist` -- that gate lives entirely on the
+ * receiving side; this schema only fixes the wire shape of the proposal.
+ *
+ * /get finding (bestbrian, PR #708, P2): `taskId`/`command` were unbounded
+ * strings. Not an execution risk -- `command` still has to exact-match the
+ * allowlist to run anything -- but an unbounded frame is unbounded log and
+ * memory growth per delivery regardless of whether it is ever executed.
+ * `taskId` gets the same identifier bound this file already uses elsewhere
+ * (`subject: z.string().min(1).max(255)`); `command` gets a generous but
+ * finite bound for a shell command line.
+ */
+export declare const AgentDispatchRequestSchema: z.ZodObject<{
+    type: z.ZodLiteral<"agent_dispatch">;
+    taskId: z.ZodString;
+    command: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "agent_dispatch";
+    taskId: string;
+    command: string;
+}, {
+    type: "agent_dispatch";
+    taskId: string;
+    command: string;
+}>;
+export type AgentDispatchRequest = z.infer<typeof AgentDispatchRequestSchema>;
+export {};