@kya-os/contracts 1.7.15 → 1.7.17

package/dist/delegation/schemas.js

@@ -15,7 +15,7 @@
  * Python Reference: Delegation-Documentation.md, Delegation-Service.md
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.DelegationCredentialSchema = exports.DelegationCredentialSubjectSchema = exports.DELEGATION_CREDENTIAL_CONTEXT = exports.DELEGATION_STATUSES = exports.DEFAULT_DELEGATION_STATUS = exports.MAX_DELEGATION_CHAIN_DEPTH = exports.DelegationVerificationResultSchema = exports.DelegationCreationRequestSchema = exports.DelegationChainSchema = exports.DelegationChainEntrySchema = exports.DelegationRecordSchema = exports.DelegationStatusSchema = void 0;
+exports.DelegationCredentialSchema = exports.DelegationCredentialSubjectSchema = exports.DELEGATION_CREDENTIAL_CONTEXT = exports.DELEGATION_STATUSES = exports.DEFAULT_DELEGATION_STATUS = exports.MAX_DELEGATION_CHAIN_DEPTH = exports.DelegationVerificationResultSchema = exports.DelegationVerificationDetailsSchema = exports.AuthorizationInfoSchema = exports.DelegationCreationRequestSchema = exports.DelegationChainSchema = exports.DelegationChainEntrySchema = exports.DelegationRecordSchema = exports.DelegationStatusSchema = void 0;
 exports.validateDelegationRecord = validateDelegationRecord;
 exports.validateDelegationChain = validateDelegationChain;
 exports.isDelegationExpired = isDelegationExpired;
@@ -136,6 +136,71 @@ exports.DelegationCreationRequestSchema = zod_1.z.object({
     /** Optional VC ID (if not provided, will be created) */
     vcId: zod_1.z.string().optional(),
 });
+/**
+ * Authorization Info Schema
+ *
+ * Captures HOW the user verified their identity during consent.
+ * This is runtime verification metadata, separate from tool requirements.
+ *
+ * Note: This schema describes authorization info in verification results,
+ * not tool protection requirements (which use AuthorizationRequirementSchema).
+ */
+exports.AuthorizationInfoSchema = zod_1.z.object({
+    /**
+     * The authorization method used during consent
+     *
+     * - 'oauth2': OAuth 2.0 provider authentication (canonical)
+     * - 'oauth': Deprecated, use 'oauth2' (will be removed in v2.0.0)
+     * - 'password': Password/credential authentication
+     * - 'credential': Deprecated, use 'verifiable_credential' (will be removed in v2.0.0)
+     * - 'verifiable_credential': W3C Verifiable Credential
+     * - 'mdl': Mobile Driver's License
+     * - 'idv': Identity Verification
+     * - 'webauthn': WebAuthn/Passkey authentication
+     * - 'siwe': Sign-In with Ethereum (EIP-4361)
+     * - 'none': Consent-only (no authentication)
+     */
+    type: zod_1.z.enum([
+        'oauth',
+        'oauth2',
+        'password',
+        'credential',
+        'verifiable_credential',
+        'mdl',
+        'idv',
+        'webauthn',
+        'siwe',
+        'none',
+    ]),
+    /** OAuth/Password/IDV provider name (e.g., 'github', 'google', 'credentials') */
+    provider: zod_1.z.string().optional(),
+    /** Credential type for verifiable_credential or mdl auth */
+    credentialType: zod_1.z.string().optional(),
+    /** MDL issuer DID or identifier */
+    issuer: zod_1.z.string().optional(),
+    /** IDV verification level */
+    verificationLevel: zod_1.z.enum(['basic', 'enhanced', 'loa3']).optional(),
+    /** WebAuthn Relying Party ID */
+    rpId: zod_1.z.string().optional(),
+    /** WebAuthn user verification level */
+    userVerification: zod_1.z.enum(['required', 'preferred', 'discouraged']).optional(),
+    /** SIWE Ethereum chain ID */
+    chainId: zod_1.z.number().optional(),
+    /** SIWE domain */
+    domain: zod_1.z.string().optional(),
+    /** Timestamp when authorization was verified (milliseconds since epoch) */
+    verifiedAt: zod_1.z.number().int().positive().optional(),
+});
+/**
+ * Delegation Verification Details Schema
+ *
+ * Typed details object for verification results
+ */
+exports.DelegationVerificationDetailsSchema = zod_1.z.object({
+    /** Authorization info - how identity was verified during consent */
+    authorization: exports.AuthorizationInfoSchema.optional(),
+    /** Additional metadata fields (extensible) */
+}).passthrough();
 /**
  * Delegation Verification Result
  *
@@ -156,8 +221,8 @@ exports.DelegationVerificationResultSchema = zod_1.z.object({
     chainValid: zod_1.z.boolean().optional(),
     /** Timestamp of verification */
     verifiedAt: zod_1.z.number().int().positive(),
-    /** Optional verification details */
-    details: zod_1.z.record(zod_1.z.any()).optional(),
+    /** Verification details including authorization info */
+    details: exports.DelegationVerificationDetailsSchema.optional(),
 });
 /**
  * Validation Helpers
@@ -257,6 +322,9 @@ exports.DELEGATION_CREDENTIAL_CONTEXT = 'https://schemas.kya-os.ai/xmcp-i/creden
  *
  * Per Python POC (Delegation-Service.md:136-146), delegations are issued AS
  * W3C VCs, with the delegation data embedded in the credentialSubject.
+ *
+ * Phase 7 Update: Added userDid, userIdentifier, sessionId, and scopes
+ * to support Agent Shield VC-JWT tokens and MCP session tracking.
  */
 exports.DelegationCredentialSubjectSchema = zod_1.z.object({
     /** Subject DID (delegatee) */
@@ -269,6 +337,38 @@ exports.DelegationCredentialSubjectSchema = zod_1.z.object({
         issuerDid: zod_1.z.string().min(1),
         /** DID of the delegatee (subject, e.g., agent) */
         subjectDid: zod_1.z.string().min(1),
+        /**
+         * DID of the user who granted the delegation.
+         *
+         * This is the authorizing user's identity. In simple cases, this equals
+         * issuerDid. In delegated scenarios (e.g., AgentShield issuing on behalf
+         * of a user), userDid identifies the actual user who consented.
+         *
+         * Required by Agent Shield API for user-scoped delegations.
+         * @see delegationCredentialSchema in agentshield-api/schemas.ts
+         */
+        userDid: zod_1.z.string().optional(),
+        /**
+         * Human-readable identifier for the user (e.g., email, OAuth subject).
+         *
+         * Used for backward compatibility and display purposes.
+         * Should not be used for cryptographic identity verification.
+         */
+        userIdentifier: zod_1.z.string().optional(),
+        /**
+         * MCP session ID for session tracking and integration.
+         *
+         * Links the delegation to a specific MCP session, enabling
+         * session-scoped token caching and audit trails.
+         */
+        sessionId: zod_1.z.string().optional(),
+        /**
+         * Authorized scopes for this delegation.
+         *
+         * Array of scope strings (e.g., ['tool:execute', 'resource:read']).
+         * When present, defines what actions the delegatee is authorized to perform.
+         */
+        scopes: zod_1.z.array(zod_1.z.string()).optional(),
         /** Optional controller (user account ID or DID) */
         controller: zod_1.z.string().optional(),
         /** Optional parent delegation ID for chain tracking */
@@ -391,7 +491,7 @@ function extractDelegationFromVC(vc) {
  * The caller must sign this to create a valid DelegationCredential.
  *
  * @param delegation - The delegation record
- * @param options - Optional VC options (id, issuanceDate, etc.)
+ * @param options - Optional VC options (id, issuanceDate, userDid, sessionId, etc.)
  * @returns Unsigned DelegationCredential
  */
 function wrapDelegationAsVC(delegation, options) {
@@ -404,6 +504,8 @@ function wrapDelegationAsVC(delegation, options) {
     if (!options?.issuanceDate && delegation.createdAt) {
         issuanceDate = new Date(delegation.createdAt).toISOString();
     }
+    // Extract scopes from constraints if not provided
+    const scopes = options?.scopes || delegation.constraints.scopes;
     return {
         '@context': [
             'https://www.w3.org/2018/credentials/v1',
@@ -420,6 +522,14 @@ function wrapDelegationAsVC(delegation, options) {
                 id: delegation.id,
                 issuerDid: delegation.issuerDid,
                 subjectDid: delegation.subjectDid,
+                // Include userDid if provided or fallback to controller
+                ...(options?.userDid && { userDid: options.userDid }),
+                // Include userIdentifier if provided
+                ...(options?.userIdentifier && { userIdentifier: options.userIdentifier }),
+                // Include sessionId if provided
+                ...(options?.sessionId && { sessionId: options.sessionId }),
+                // Include scopes if available
+                ...(scopes && scopes.length > 0 && { scopes }),
                 controller: delegation.controller,
                 parentId: delegation.parentId,
                 constraints: delegation.constraints,

package/dist/handshake.d.ts

@@ -23,15 +23,15 @@ export declare const MCPClientInfoSchema: z.ZodObject<{
     persistentId: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     name: string;
-    version?: string | undefined;
     title?: string | undefined;
+    version?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
 }, {
     name: string;
-    version?: string | undefined;
     title?: string | undefined;
+    version?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
@@ -48,20 +48,20 @@ export declare const MCPClientSessionInfoSchema: z.ZodObject<{
     protocolVersion: z.ZodOptional<z.ZodString>;
     capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
-    clientId: string;
     name: string;
-    version?: string | undefined;
+    clientId: string;
     title?: string | undefined;
+    version?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
     protocolVersion?: string | undefined;
     capabilities?: Record<string, unknown> | undefined;
 }, {
-    clientId: string;
     name: string;
-    version?: string | undefined;
+    clientId: string;
     title?: string | undefined;
+    version?: string | undefined;
     platform?: string | undefined;
     vendor?: string | undefined;
     persistentId?: string | undefined;
@@ -84,20 +84,20 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
         clientId: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
         name: string;
-        clientId?: string | undefined;
-        version?: string | undefined;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
+        clientId?: string | undefined;
     }, {
         name: string;
-        clientId?: string | undefined;
-        version?: string | undefined;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
+        clientId?: string | undefined;
     }>>;
     clientProtocolVersion: z.ZodOptional<z.ZodString>;
     clientCapabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
@@ -108,12 +108,12 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
-        clientId?: string | undefined;
-        version?: string | undefined;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
+        clientId?: string | undefined;
     } | undefined;
     clientProtocolVersion?: string | undefined;
     clientCapabilities?: Record<string, unknown> | undefined;
@@ -124,12 +124,12 @@ export declare const HandshakeRequestSchema: z.ZodObject<{
     agentDid?: string | undefined;
     clientInfo?: {
         name: string;
-        clientId?: string | undefined;
-        version?: string | undefined;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
+        clientId?: string | undefined;
     } | undefined;
     clientProtocolVersion?: string | undefined;
     clientCapabilities?: Record<string, unknown> | undefined;
@@ -158,20 +158,20 @@ export declare const SessionContextSchema: z.ZodObject<{
         protocolVersion: z.ZodOptional<z.ZodString>;
         capabilities: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     }, "strip", z.ZodTypeAny, {
-        clientId: string;
         name: string;
-        version?: string | undefined;
+        clientId: string;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
         protocolVersion?: string | undefined;
         capabilities?: Record<string, unknown> | undefined;
     }, {
-        clientId: string;
         name: string;
-        version?: string | undefined;
+        clientId: string;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -195,29 +195,29 @@ export declare const SessionContextSchema: z.ZodObject<{
     }, "strip", z.ZodTypeAny, {
         provider: string;
         subject: string;
-        email?: string | undefined;
         name?: string | undefined;
+        email?: string | undefined;
     }, {
         provider: string;
         subject: string;
-        email?: string | undefined;
         name?: string | undefined;
+        email?: string | undefined;
     }>>;
 }, "strip", z.ZodTypeAny, {
-    createdAt: number;
     nonce: string;
     audience: string;
     timestamp: number;
     sessionId: string;
+    createdAt: number;
     lastActivity: number;
     ttlMinutes: number;
-    identityState: "authenticated" | "anonymous";
+    identityState: "anonymous" | "authenticated";
     agentDid?: string | undefined;
     clientInfo?: {
-        clientId: string;
         name: string;
-        version?: string | undefined;
+        clientId: string;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -230,22 +230,22 @@ export declare const SessionContextSchema: z.ZodObject<{
     oauthIdentity?: {
         provider: string;
         subject: string;
-        email?: string | undefined;
         name?: string | undefined;
+        email?: string | undefined;
     } | undefined;
 }, {
-    createdAt: number;
     nonce: string;
     audience: string;
     timestamp: number;
     sessionId: string;
+    createdAt: number;
     lastActivity: number;
     agentDid?: string | undefined;
     clientInfo?: {
-        clientId: string;
         name: string;
-        version?: string | undefined;
+        clientId: string;
         title?: string | undefined;
+        version?: string | undefined;
         platform?: string | undefined;
         vendor?: string | undefined;
         persistentId?: string | undefined;
@@ -256,12 +256,12 @@ export declare const SessionContextSchema: z.ZodObject<{
     serverDid?: string | undefined;
     clientDid?: string | undefined;
     userDid?: string | undefined;
-    identityState?: "authenticated" | "anonymous" | undefined;
+    identityState?: "anonymous" | "authenticated" | undefined;
     oauthIdentity?: {
         provider: string;
         subject: string;
-        email?: string | undefined;
         name?: string | undefined;
+        email?: string | undefined;
     } | undefined;
 }>;
 export declare const NonceCacheEntrySchema: z.ZodObject<{

package/dist/handshake.js

@@ -2,7 +2,16 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.NONCE_LENGTH_BYTES = exports.DEFAULT_TIMESTAMP_SKEW_SECONDS = exports.DEFAULT_SESSION_TTL_MINUTES = exports.NonceCacheConfigSchema = exports.NonceCacheEntrySchema = exports.SessionContextSchema = exports.HandshakeRequestSchema = exports.MCPClientSessionInfoSchema = exports.MCPClientInfoSchema = exports.SessionIdentityStateSchema = void 0;
 const zod_1 = require("zod");
-const consent_1 = require("./consent");
+/**
+ * OAuth Identity schema (inlined to avoid ESM/CJS boundary issues with @kya-os/consent)
+ * This is a copy of OAuthIdentitySchema from @kya-os/consent for use in handshake types.
+ */
+const oauthIdentitySchema = zod_1.z.object({
+    provider: zod_1.z.string().min(1).max(50),
+    subject: zod_1.z.string().min(1).max(255),
+    email: zod_1.z.string().email().max(255).optional(),
+    name: zod_1.z.string().max(255).optional(),
+});
 /**
  * Handshake and session management schemas
  */
@@ -65,7 +74,7 @@ exports.SessionContextSchema = zod_1.z.object({
      * OAuth identity information (populated after successful OAuth)
      * Contains provider, subject, email from OAuth provider
      */
-    oauthIdentity: consent_1.oauthIdentitySchema.optional(),
+    oauthIdentity: oauthIdentitySchema.optional(),
 });
 exports.NonceCacheEntrySchema = zod_1.z.object({
     sessionId: zod_1.z.string().min(1),