@kya-os/contracts 1.2.1 → 1.2.2

package/dist/delegation/schemas.js

@@ -0,0 +1,230 @@
+"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.
+ *
+ * Related Spec: MCP-I §4.1, §4.2
+ * Python Reference: Delegation-Documentation.md, Delegation-Service.md
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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;
+exports.validateDelegationChain = validateDelegationChain;
+exports.isDelegationExpired = isDelegationExpired;
+exports.isDelegationNotYetValid = isDelegationNotYetValid;
+exports.isDelegationCurrentlyValid = isDelegationCurrentlyValid;
+const zod_1 = require("zod");
+const constraints_js_1 = require("./constraints.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
+ */
+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;
+    }
+    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;
+    }
+    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;
+    }
+    if (isDelegationExpired(delegation)) {
+        return false;
+    }
+    if (isDelegationNotYetValid(delegation)) {
+        return false;
+    }
+    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'];
+//# sourceMappingURL=schemas.js.map

package/dist/did/index.d.ts

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

package/dist/did/index.js

@@ -0,0 +1,24 @@
+"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);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types.js"), exports);
+__exportStar(require("./resolve-contract.js"), exports);
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,220 @@
+/**
+ * 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

package/dist/did/resolve-contract.js

@@ -0,0 +1,32 @@
+"use strict";
+/**
+ * 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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RESOLUTION_ERROR_CODES = void 0;
+/**
+ * Common resolution error codes
+ */
+exports.RESOLUTION_ERROR_CODES = {
+    /** DID not found */
+    NOT_FOUND: 'notFound',
+    /** Invalid DID format */
+    INVALID_DID: 'invalidDid',
+    /** DID method not supported */
+    METHOD_NOT_SUPPORTED: 'methodNotSupported',
+    /** Resolution timeout */
+    TIMEOUT: 'timeout',
+    /** Network error during resolution */
+    NETWORK_ERROR: 'networkError',
+    /** Invalid DID Document structure */
+    INVALID_DOCUMENT: 'invalidDocument',
+    /** Internal resolver error */
+    INTERNAL_ERROR: 'internalError',
+};
+//# sourceMappingURL=resolve-contract.js.map

package/dist/did/types.d.ts

@@ -0,0 +1,164 @@
+/**
+ * DID Document Types (W3C Compliant)
+ *
+ * These types conform to the W3C DID Core specification and provide
+ * TypeScript parity with the Python implementation.
+ *
+ * Related Spec: MCP-I §2.1, §2.3
+ * Python Reference: DID-Documentation.md, DID-Service.md
+ */
+/**
+ * Verification Method Types
+ *
+ * Supported types for verification methods in DID Documents.
+ */
+export type VerificationMethodType = 'Ed25519VerificationKey2020' | 'JsonWebKey2020' | 'EcdsaSecp256k1VerificationKey2019';
+/**
+ * Verification Method
+ *
+ * A verification method as defined in the W3C DID Core specification.
+ * Used for cryptographic verification of signatures and authentication.
+ *
+ * **kid Derivation Guidelines:**
+ * - For did:key: kid = `${did}#${multibaseKey}`
+ * - For did:web: kid = `${did}#${keyId}` where keyId is from DID Document
+ * - The kid MUST be resolvable to a verification method in the DID Document
+ */
+export interface VerificationMethod {
+    /** Verification method identifier (e.g., "#key-1" or full DID URL) */
+    id: string;
+    /** Type of verification method */
+    type: VerificationMethodType;
+    /** DID of the controller of this verification method */
+    controller: string;
+    /**
+     * Public key encoded as multibase for Ed25519VerificationKey2020
+     * Format: z + base58btc(public key bytes)
+     */
+    publicKeyMultibase?: string;
+    /**
+     * Public key as JSON Web Key for JsonWebKey2020
+     * See RFC 7517 for JWK format
+     */
+    publicKeyJwk?: {
+        kty: string;
+        crv: string;
+        x: string;
+        y?: string;
+        [key: string]: any;
+    };
+}
+/**
+ * DID Service
+ *
+ * A service endpoint as defined in the W3C DID Core specification.
+ * Services enable discovery of service endpoints for the DID subject.
+ */
+export interface DidService {
+    /** Service identifier (e.g., "#service-1") */
+    id: string;
+    /** Service type (e.g., "LinkedDomains", "CredentialRegistry") */
+    type: string | string[];
+    /** Service endpoint URL(s) or endpoint descriptor object */
+    serviceEndpoint: string | string[] | Record<string, any>;
+}
+/**
+ * DID Document
+ *
+ * A DID Document as defined in the W3C DID Core specification.
+ * Represents the full descriptor of a DID, including verification methods
+ * and service endpoints.
+ *
+ * **Supported DID Methods:**
+ * - did:key - Self-contained, ephemeral identities
+ * - did:web - Domain-bound identities resolved via HTTPS
+ * - did:jwk - JWK-based identities
+ *
+ * **@context:**
+ * While the W3C spec requires @context, it's optional in this type to support
+ * simplified parsing. Implementations should include "https://www.w3.org/ns/did/v1"
+ * as the base context.
+ */
+export interface DidDocument {
+    /** JSON-LD context (typically "https://www.w3.org/ns/did/v1") */
+    '@context'?: string | string[] | Record<string, any>;
+    /** The DID this document describes (e.g., "did:key:z6Mk...") */
+    id: string;
+    /** Also known as - alternative identifiers for this DID */
+    alsoKnownAs?: string[];
+    /**
+     * Verification methods available for this DID
+     * Contains public key information for signature verification
+     */
+    verificationMethod?: VerificationMethod[];
+    /**
+     * Authentication verification relationship
+     * References to verification methods or embedded methods
+     * Used for authenticating as the DID subject
+     */
+    authentication?: (string | VerificationMethod)[];
+    /**
+     * Assertion method verification relationship
+     * References to verification methods or embedded methods
+     * Used for issuing verifiable credentials
+     */
+    assertionMethod?: (string | VerificationMethod)[];
+    /**
+     * Key agreement verification relationship
+     * References to verification methods or embedded methods
+     * Used for encryption and key agreement protocols
+     */
+    keyAgreement?: (string | VerificationMethod)[];
+    /**
+     * Capability invocation verification relationship
+     * References to verification methods or embedded methods
+     * Used for invoking capabilities
+     */
+    capabilityInvocation?: (string | VerificationMethod)[];
+    /**
+     * Capability delegation verification relationship
+     * References to verification methods or embedded methods
+     * Used for delegating capabilities
+     */
+    capabilityDelegation?: (string | VerificationMethod)[];
+    /** Service endpoints for the DID */
+    service?: DidService[];
+    /** Additional properties allowed for extensibility */
+    [key: string]: any;
+}
+/**
+ * DID Method
+ *
+ * String literal type for supported DID methods
+ */
+export type DidMethod = 'key' | 'web' | 'jwk' | 'ion' | 'ebsi';
+/**
+ * Helper type guards
+ */
+/**
+ * Type guard to check if a value is a VerificationMethod
+ */
+export declare function isVerificationMethod(value: any): value is VerificationMethod;
+/**
+ * Type guard to check if a value is a string reference to a verification method
+ */
+export declare function isVerificationMethodReference(value: any): value is string;
+/**
+ * Type guard to check if a DID Document is valid (basic structural check)
+ */
+export declare function isDidDocument(value: any): value is DidDocument;
+/**
+ * Extract DID method from a DID string
+ *
+ * @param did - The DID string (e.g., "did:key:z6Mk...")
+ * @returns The method name (e.g., "key") or null if invalid
+ */
+export declare function extractDidMethod(did: string): string | null;
+/**
+ * Extract key ID from a DID URL
+ *
+ * @param didUrl - A DID URL with fragment (e.g., "did:key:z6Mk...#key-1")
+ * @returns The fragment part (e.g., "key-1") or null if no fragment
+ */
+export declare function extractKeyId(didUrl: string): string | null;
+//# sourceMappingURL=types.d.ts.map