@kya-os/contracts 1.3.2 → 1.3.3

package/dist/delegation/schemas.js

@@ -1,19 +1,4 @@
 "use strict";
-/**
- * Delegation Record Schemas
- *
- * Types and schemas for delegation records that link VCs with CRISP constraints.
- * Delegations represent the transfer of authority from one DID to another.
- *
- * **IMPORTANT**: Per Python POC design (Delegation-Service.md:136-146),
- * delegations SHOULD be issued as W3C Verifiable Credentials, not just reference them.
- * This file provides both:
- * - DelegationRecord: Legacy/internal format (contains delegation data)
- * - DelegationCredential: W3C VC format (delegation as credentialSubject)
- *
- * Related Spec: MCP-I §4.1, §4.2, W3C VC Data Model 1.1
- * 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.validateDelegationRecord = validateDelegationRecord;
@@ -29,163 +14,63 @@ exports.isDelegationCredentialNotYetValid = isDelegationCredentialNotYetValid;
 const zod_1 = require("zod");
 const constraints_js_1 = require("./constraints.js");
 const schemas_js_1 = require("../vc/schemas.js");
-/**
- * Delegation Status
- *
- * Lifecycle status of a delegation
- */
 exports.DelegationStatusSchema = zod_1.z.enum(['active', 'revoked', 'expired']);
-/**
- * Delegation Record Schema
- *
- * Complete delegation record linking issuer (delegator) to subject (delegatee)
- * with backing VC and CRISP constraints.
- *
- * **Key Invariants:**
- * - Delegation MUST reference a live VC via `vcId`
- * - Revocation of VC invalidates all linked delegations
- * - Chain: no cycles allowed
- * - Child `notAfter` ≤ parent `notAfter`
- * - Child scopes ⊆ parent scopes
- * - Child budgets ≤ parent budgets (same unit)
- */
 exports.DelegationRecordSchema = zod_1.z.object({
-    /** Unique identifier for the delegation */
     id: zod_1.z.string().min(1),
-    /** DID of the delegator (issuer, e.g., merchant/user) */
     issuerDid: zod_1.z.string().min(1),
-    /** DID of the delegatee (subject, e.g., agent) */
     subjectDid: zod_1.z.string().min(1),
-    /** Optional controller (user account ID or DID) */
     controller: zod_1.z.string().optional(),
-    /** ID of the backing Verifiable Credential */
     vcId: zod_1.z.string().min(1),
-    /** Optional parent delegation ID for chain tracking */
     parentId: zod_1.z.string().optional(),
-    /** CRISP constraints on this delegation */
     constraints: constraints_js_1.DelegationConstraintsSchema,
-    /** Detached JWS signature over canonical delegation document */
     signature: zod_1.z.string().min(1),
-    /** Current status of the delegation */
     status: exports.DelegationStatusSchema,
-    /** Timestamp when created (milliseconds since epoch) */
     createdAt: zod_1.z.number().int().positive().optional(),
-    /** Timestamp when revoked (if status is revoked) */
     revokedAt: zod_1.z.number().int().positive().optional(),
-    /** Optional reason for revocation */
     revokedReason: zod_1.z.string().optional(),
-    /** Optional metadata */
     metadata: zod_1.z.record(zod_1.z.any()).optional(),
-}).passthrough(); // Allow extensibility
-/**
- * Delegation Chain Entry
- *
- * Represents a single link in a delegation chain
- */
+}).passthrough();
 exports.DelegationChainEntrySchema = zod_1.z.object({
-    /** Delegation ID */
     delegationId: zod_1.z.string().min(1),
-    /** Issuer DID */
     issuerDid: zod_1.z.string().min(1),
-    /** Subject DID */
     subjectDid: zod_1.z.string().min(1),
-    /** VC ID */
     vcId: zod_1.z.string().min(1),
-    /** Depth in chain (0 = root) */
     depth: zod_1.z.number().int().nonnegative(),
-    /** Constraints */
     constraints: constraints_js_1.DelegationConstraintsSchema,
-    /** Status */
     status: exports.DelegationStatusSchema,
 });
-/**
- * Delegation Chain
- *
- * Represents a complete delegation chain from root to leaf
- */
 exports.DelegationChainSchema = zod_1.z.object({
-    /** Root issuer DID */
     rootIssuer: zod_1.z.string().min(1),
-    /** Leaf subject DID */
     leafSubject: zod_1.z.string().min(1),
-    /** All delegations in the chain, ordered root to leaf */
     chain: zod_1.z.array(exports.DelegationChainEntrySchema).min(1),
-    /** Total chain depth */
     depth: zod_1.z.number().int().nonnegative(),
-    /** Whether the entire chain is valid */
     valid: zod_1.z.boolean(),
-    /** Optional validation errors */
     errors: zod_1.z.array(zod_1.z.string()).optional(),
 });
-/**
- * Delegation Creation Request
- *
- * Input for creating a new delegation
- */
 exports.DelegationCreationRequestSchema = zod_1.z.object({
-    /** Delegator DID */
     issuerDid: zod_1.z.string().min(1),
-    /** Delegatee DID */
     subjectDid: zod_1.z.string().min(1),
-    /** Optional controller */
     controller: zod_1.z.string().optional(),
-    /** Constraints */
     constraints: constraints_js_1.DelegationConstraintsSchema,
-    /** Optional parent delegation ID */
     parentId: zod_1.z.string().optional(),
-    /** Optional VC ID (if not provided, will be created) */
     vcId: zod_1.z.string().optional(),
 });
-/**
- * Delegation Verification Result
- *
- * Result of delegation verification
- */
 exports.DelegationVerificationResultSchema = zod_1.z.object({
-    /** Whether delegation is valid */
     valid: zod_1.z.boolean(),
-    /** Delegation ID */
     delegationId: zod_1.z.string().min(1),
-    /** Status */
     status: exports.DelegationStatusSchema,
-    /** Optional reason for invalid status */
     reason: zod_1.z.string().optional(),
-    /** Whether backing VC is valid */
     credentialValid: zod_1.z.boolean().optional(),
-    /** Whether chain is valid (if part of chain) */
     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(),
 });
-/**
- * Validation Helpers
- */
-/**
- * Validate a delegation record
- *
- * @param record - The delegation record to validate
- * @returns Validation result
- */
 function validateDelegationRecord(record) {
     return exports.DelegationRecordSchema.safeParse(record);
 }
-/**
- * Validate a delegation chain
- *
- * @param chain - The delegation chain to validate
- * @returns Validation result
- */
 function validateDelegationChain(chain) {
     return exports.DelegationChainSchema.safeParse(chain);
 }
-/**
- * Check if a delegation is expired based on constraints
- *
- * @param delegation - The delegation to check
- * @returns true if expired
- */
 function isDelegationExpired(delegation) {
     if (!delegation.constraints.notAfter) {
         return false;
@@ -193,12 +78,6 @@ function isDelegationExpired(delegation) {
     const nowSec = Math.floor(Date.now() / 1000);
     return nowSec > delegation.constraints.notAfter;
 }
-/**
- * Check if a delegation is not yet valid based on constraints
- *
- * @param delegation - The delegation to check
- * @returns true if not yet valid
- */
 function isDelegationNotYetValid(delegation) {
     if (!delegation.constraints.notBefore) {
         return false;
@@ -206,12 +85,6 @@ function isDelegationNotYetValid(delegation) {
     const nowSec = Math.floor(Date.now() / 1000);
     return nowSec < delegation.constraints.notBefore;
 }
-/**
- * Check if a delegation is currently valid (active and within time bounds)
- *
- * @param delegation - The delegation to check
- * @returns true if currently valid
- */
 function isDelegationCurrentlyValid(delegation) {
     if (delegation.status !== 'active') {
         return false;
@@ -224,145 +97,55 @@ function isDelegationCurrentlyValid(delegation) {
     }
     return true;
 }
-/**
- * Constants
- */
-/**
- * Maximum reasonable delegation chain depth
- */
 exports.MAX_DELEGATION_CHAIN_DEPTH = 10;
-/**
- * Default delegation status for new delegations
- */
 exports.DEFAULT_DELEGATION_STATUS = 'active';
-/**
- * Supported delegation statuses
- */
 exports.DELEGATION_STATUSES = ['active', 'revoked', 'expired'];
-// ============================================================================
-// W3C VC-BASED DELEGATION CREDENTIALS (Phase 3 Implementation)
-// ============================================================================
-/**
- * Delegation Credential Context
- *
- * Additional JSON-LD context for delegation credentials
- */
 exports.DELEGATION_CREDENTIAL_CONTEXT = 'https://schemas.kya-os.ai/xmcp-i/credentials/delegation.v1.0.0.json';
-/**
- * Delegation Credential Subject Schema
- *
- * The credentialSubject of a DelegationCredential contains:
- * - id: The delegatee DID (subject of the delegation)
- * - delegation: The complete delegation record
- *
- * Per Python POC (Delegation-Service.md:136-146), delegations are issued AS
- * W3C VCs, with the delegation data embedded in the credentialSubject.
- */
 exports.DelegationCredentialSubjectSchema = zod_1.z.object({
-    /** Subject DID (delegatee) */
     id: zod_1.z.string().min(1),
-    /** The delegation information */
     delegation: zod_1.z.object({
-        /** Unique identifier for the delegation */
         id: zod_1.z.string().min(1),
-        /** DID of the delegator (issuer, e.g., merchant/user) */
         issuerDid: zod_1.z.string().min(1),
-        /** DID of the delegatee (subject, e.g., agent) */
         subjectDid: zod_1.z.string().min(1),
-        /** Optional controller (user account ID or DID) */
         controller: zod_1.z.string().optional(),
-        /** Optional parent delegation ID for chain tracking */
         parentId: zod_1.z.string().optional(),
-        /** CRISP constraints on this delegation */
         constraints: constraints_js_1.DelegationConstraintsSchema,
-        /** Current status of the delegation */
         status: exports.DelegationStatusSchema.default('active'),
-        /** Timestamp when created (milliseconds since epoch) */
         createdAt: zod_1.z.number().int().positive().optional(),
-        /** Optional metadata */
         metadata: zod_1.z.record(zod_1.z.any()).optional(),
     }),
 });
-/**
- * Delegation Credential Schema
- *
- * W3C Verifiable Credential for delegations.
- * This is the PRIMARY format for delegation issuance and verification.
- *
- * Structure:
- * - @context: [...W3C VC contexts, delegation context]
- * - type: ['VerifiableCredential', 'DelegationCredential']
- * - issuer: Delegator DID
- * - issuanceDate: When delegation was created
- * - expirationDate: Maps to delegation.constraints.notAfter
- * - credentialSubject: Contains delegatee DID + delegation data
- * - credentialStatus: StatusList2021Entry for revocation checking
- * - proof: Ed25519Signature2020
- *
- * Per Python POC design (Delegation-Service.md:136-163):
- * - Every delegation MUST be issued as a VC
- * - Verification checks BOTH the VC signature AND delegation constraints
- * - Revocation updates the StatusList2021
- *
- * Related Spec: MCP-I §4.1, §4.2, W3C VC Data Model 1.1
- */
 exports.DelegationCredentialSchema = schemas_js_1.VerifiableCredentialSchema.extend({
-    /** @context MUST include delegation context */
     '@context': zod_1.z
         .array(zod_1.z.union([zod_1.z.string().url(), zod_1.z.record(zod_1.z.any())]))
         .refine((contexts) => {
-        // Check for W3C VC context (first)
         const firstContext = contexts[0];
         if (typeof firstContext !== 'string' ||
             firstContext !== 'https://www.w3.org/2018/credentials/v1') {
             return false;
         }
-        // Optionally include delegation context (recommended)
         return true;
     }, {
         message: 'First @context must be W3C VC context',
     }),
-    /** type MUST include both VerifiableCredential and DelegationCredential */
     type: zod_1.z
         .array(zod_1.z.string())
         .refine((types) => types.includes('VerifiableCredential') &&
         types.includes('DelegationCredential'), {
         message: 'type must include both "VerifiableCredential" and "DelegationCredential"',
     }),
-    /** issuer is the delegator DID */
     issuer: schemas_js_1.IssuerSchema,
-    /** issuanceDate maps to delegation creation time */
     issuanceDate: zod_1.z.string().datetime(),
-    /** expirationDate maps to delegation.constraints.notAfter */
     expirationDate: zod_1.z.string().datetime().optional(),
-    /** credentialSubject contains delegatee DID + delegation data */
     credentialSubject: exports.DelegationCredentialSubjectSchema,
-    /** credentialStatus for StatusList2021 revocation checking */
     credentialStatus: schemas_js_1.CredentialStatusSchema.optional(),
-    /** proof is Ed25519Signature2020 */
     proof: schemas_js_1.ProofSchema.optional(),
 });
-/**
- * Validate a delegation credential
- *
- * @param credential - The delegation credential to validate
- * @returns Validation result
- */
 function validateDelegationCredential(credential) {
     return exports.DelegationCredentialSchema.safeParse(credential);
 }
-/**
- * Extract DelegationRecord from DelegationCredential
- *
- * Utility to extract the legacy DelegationRecord format from a W3C VC.
- * Useful for backward compatibility and internal processing.
- *
- * @param vc - The delegation credential
- * @returns DelegationRecord
- */
 function extractDelegationFromVC(vc) {
     const delegation = vc.credentialSubject.delegation;
-    // Extract signature from proof (may be in different formats)
     let signature = '';
     if (vc.proof) {
         const proof = vc.proof;
@@ -373,33 +156,22 @@ function extractDelegationFromVC(vc) {
         issuerDid: delegation.issuerDid,
         subjectDid: delegation.subjectDid,
         controller: delegation.controller,
-        vcId: vc.id || `vc:${delegation.id}`, // VC id becomes vcId
+        vcId: vc.id || `vc:${delegation.id}`,
         parentId: delegation.parentId,
         constraints: delegation.constraints,
         signature,
         status: delegation.status,
         createdAt: delegation.createdAt,
-        revokedAt: undefined, // Revocation status comes from credentialStatus
+        revokedAt: undefined,
         revokedReason: undefined,
         metadata: delegation.metadata,
     };
 }
-/**
- * Create DelegationCredential from DelegationRecord (unsigned)
- *
- * Wraps a DelegationRecord in a W3C VC structure (without proof).
- * The caller must sign this to create a valid DelegationCredential.
- *
- * @param delegation - The delegation record
- * @param options - Optional VC options (id, issuanceDate, etc.)
- * @returns Unsigned DelegationCredential
- */
 function wrapDelegationAsVC(delegation, options) {
     const now = new Date().toISOString();
     const expirationDate = delegation.constraints.notAfter
         ? new Date(delegation.constraints.notAfter * 1000).toISOString()
         : options?.expirationDate;
-    // Compute issuanceDate
     let issuanceDate = options?.issuanceDate || now;
     if (!options?.issuanceDate && delegation.createdAt) {
         issuanceDate = new Date(delegation.createdAt).toISOString();
@@ -431,14 +203,7 @@ function wrapDelegationAsVC(delegation, options) {
         credentialStatus: options?.credentialStatus,
     };
 }
-/**
- * Check if a delegation credential is expired
- *
- * @param vc - The delegation credential
- * @returns true if expired
- */
 function isDelegationCredentialExpired(vc) {
-    // Check VC expiration
     if (vc.expirationDate) {
         const expirationDate = new Date(vc.expirationDate);
         const now = new Date();
@@ -446,7 +211,6 @@ function isDelegationCredentialExpired(vc) {
             return true;
         }
     }
-    // Check delegation constraints notAfter
     const delegation = vc.credentialSubject.delegation;
     if (delegation.constraints.notAfter) {
         const nowSec = Math.floor(Date.now() / 1000);
@@ -456,15 +220,8 @@ function isDelegationCredentialExpired(vc) {
     }
     return false;
 }
-/**
- * Check if a delegation credential is not yet valid
- *
- * @param vc - The delegation credential
- * @returns true if not yet valid
- */
 function isDelegationCredentialNotYetValid(vc) {
     const delegation = vc.credentialSubject.delegation;
-    // Check delegation constraints notBefore
     if (delegation.constraints.notBefore) {
         const nowSec = Math.floor(Date.now() / 1000);
         if (nowSec < delegation.constraints.notBefore) {
@@ -473,4 +230,3 @@ function isDelegationCredentialNotYetValid(vc) {
     }
     return false;
 }
-//# sourceMappingURL=schemas.js.map

package/dist/did/index.d.ts

@@ -1,9 +1,3 @@
-/**
- * DID Module Exports
- *
- * Types and contracts for W3C Decentralized Identifiers (DIDs)
- */
 export * from './types.js';
 export * from './resolve-contract.js';
 export * from './schemas.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/did/index.js

@@ -1,9 +1,4 @@
 "use strict";
-/**
- * DID Module Exports
- *
- * Types and contracts for W3C Decentralized Identifiers (DIDs)
- */
 var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
     if (k2 === undefined) k2 = k;
     var desc = Object.getOwnPropertyDescriptor(m, k);
@@ -22,4 +17,3 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./types.js"), exports);
 __exportStar(require("./resolve-contract.js"), exports);
 __exportStar(require("./schemas.js"), exports);
-//# sourceMappingURL=index.js.map

package/dist/did/resolve-contract.d.ts

@@ -1,220 +1,53 @@
-/**
- * DID Resolver Contract
- *
- * Interface contracts for DID resolution across different implementations.
- * This file contains ONLY interfaces and types - no functional code.
- *
- * Related Spec: MCP-I §2.3
- * Python Reference: DID-Service.md
- */
 import type { DidDocument } from './types.js';
-/**
- * Options for DID resolution
- */
 export interface ResolveOptions {
-    /**
-     * Maximum time in milliseconds to wait for resolution
-     * Default: 500ms (as per env/constants.ts)
-     */
     timeoutMs?: number;
-    /**
-     * Whether to accept cached resolution results
-     * If false, forces a fresh resolution
-     * Default: true
-     */
     acceptCache?: boolean;
-    /**
-     * Desired cache TTL for this resolution in seconds
-     * Implementation may ignore if not applicable
-     */
     cacheTtlSec?: number;
-    /**
-     * Additional metadata to pass to the resolver
-     * Used for method-specific resolution options
-     */
     metadata?: Record<string, any>;
 }
-/**
- * Result of DID resolution
- *
- * Contains the resolved DID Document and metadata about the resolution.
- */
 export interface ResolveResult {
-    /**
-     * The resolved DID Document
-     */
     doc: DidDocument;
-    /**
-     * Timestamp (milliseconds since epoch) when the document was fetched
-     */
     fetchedAt: number;
-    /**
-     * Cache TTL in seconds (if applicable)
-     * Indicates how long this result may be cached
-     */
     cacheTtlSec?: number;
-    /**
-     * Metadata about the resolution process
-     * May include method-specific information
-     */
     metadata?: {
-        /** Source of the resolution (e.g., "cache", "network", "local") */
         source?: string;
-        /** Method used for resolution */
         method?: string;
-        /** Whether the document was retrieved from cache */
         fromCache?: boolean;
-        /** Additional method-specific metadata */
         [key: string]: any;
     };
 }
-/**
- * Resolution Error Details
- *
- * Structure for errors during DID resolution.
- */
 export interface ResolutionError {
-    /** Error code (e.g., "notFound", "invalidDid", "methodNotSupported") */
     code: string;
-    /** Human-readable error message */
     message: string;
-    /** Original error if available */
     cause?: Error;
-    /** Additional error details */
     details?: Record<string, any>;
 }
-/**
- * DID Resolver Interface
- *
- * Defines the contract for resolving DIDs to DID Documents.
- * Implementations must handle different DID methods and provide caching.
- *
- * **Implementation Notes:**
- * - Resolvers SHOULD support caching to improve performance
- * - Resolvers MUST respect timeoutMs to prevent hanging
- * - Resolvers MUST validate DID format before attempting resolution
- * - Resolvers MAY support multiple DID methods via a registry pattern
- *
- * **Edge Compatibility:**
- * Implementations intended for edge environments should:
- * - Minimize dependencies
- * - Support offline resolution where possible (e.g., did:key)
- * - Use efficient caching strategies
- * - Handle network failures gracefully
- */
 export interface DidResolver {
-    /**
-     * Resolve a DID to its DID Document
-     *
-     * @param did - The DID to resolve (e.g., "did:key:z6Mk...")
-     * @param opts - Resolution options
-     * @returns Promise resolving to the DID Document and metadata
-     * @throws {ResolutionError} If resolution fails
-     */
     resolve(did: string, opts?: ResolveOptions): Promise<ResolveResult>;
 }
-/**
- * DID Method Resolver Interface
- *
- * Interface for method-specific resolvers.
- * A universal resolver delegates to method resolvers based on the DID method.
- */
 export interface DidMethodResolver {
-    /**
-     * The DID method this resolver handles (e.g., "key", "web")
-     */
     readonly method: string;
-    /**
-     * Resolve a DID using this method
-     *
-     * @param did - The DID to resolve
-     * @param opts - Resolution options
-     * @returns Promise resolving to the DID Document and metadata
-     * @throws {ResolutionError} If resolution fails
-     */
     resolve(did: string, opts?: ResolveOptions): Promise<ResolveResult>;
-    /**
-     * Check if this resolver supports the given DID
-     *
-     * @param did - The DID to check
-     * @returns true if this resolver can handle the DID
-     */
     supports(did: string): boolean;
 }
-/**
- * DID Resolution Cache Interface
- *
- * Interface for caching resolved DID Documents.
- */
 export interface DidResolutionCache {
-    /**
-     * Get a cached resolution result
-     *
-     * @param did - The DID to look up
-     * @returns Promise resolving to cached result or null if not found/expired
-     */
     get(did: string): Promise<ResolveResult | null>;
-    /**
-     * Store a resolution result in cache
-     *
-     * @param did - The DID being cached
-     * @param result - The resolution result
-     * @param ttlSec - TTL in seconds
-     * @returns Promise resolving when stored
-     */
     set(did: string, result: ResolveResult, ttlSec: number): Promise<void>;
-    /**
-     * Invalidate cached result for a DID
-     *
-     * @param did - The DID to invalidate
-     * @returns Promise resolving when invalidated
-     */
     invalidate(did: string): Promise<void>;
-    /**
-     * Clear all cached results
-     *
-     * @returns Promise resolving when cleared
-     */
     clear(): Promise<void>;
 }
-/**
- * Universal DID Resolver Configuration
- *
- * Configuration for a universal resolver that delegates to method-specific resolvers.
- */
 export interface UniversalResolverConfig {
-    /**
-     * Method-specific resolvers
-     * Key is the method name (e.g., "key", "web")
-     */
     methodResolvers?: Map<string, DidMethodResolver> | Record<string, DidMethodResolver>;
-    /**
-     * Optional cache implementation
-     */
     cache?: DidResolutionCache;
-    /**
-     * Default resolution options
-     */
     defaultOptions?: ResolveOptions;
 }
-/**
- * Common resolution error codes
- */
 export declare const RESOLUTION_ERROR_CODES: {
-    /** DID not found */
     readonly NOT_FOUND: "notFound";
-    /** Invalid DID format */
     readonly INVALID_DID: "invalidDid";
-    /** DID method not supported */
     readonly METHOD_NOT_SUPPORTED: "methodNotSupported";
-    /** Resolution timeout */
     readonly TIMEOUT: "timeout";
-    /** Network error during resolution */
     readonly NETWORK_ERROR: "networkError";
-    /** Invalid DID Document structure */
     readonly INVALID_DOCUMENT: "invalidDocument";
-    /** Internal resolver error */
     readonly INTERNAL_ERROR: "internalError";
 };
 export type ResolutionErrorCode = (typeof RESOLUTION_ERROR_CODES)[keyof typeof RESOLUTION_ERROR_CODES];
-//# sourceMappingURL=resolve-contract.d.ts.map