@kya-os/contracts 1.5.3-canary.21 → 1.5.3-canary.23

package/src/did/resolve-contract.ts

@@ -1,255 +0,0 @@
-/**
- * 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 const 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',
-} as const;
-
-export type ResolutionErrorCode =
-  (typeof RESOLUTION_ERROR_CODES)[keyof typeof RESOLUTION_ERROR_CODES];

package/src/did/schemas.ts

@@ -1,190 +0,0 @@
-/**
- * DID Document Zod Schemas
- *
- * Runtime validation schemas for DID Documents conforming to W3C DID Core specification.
- * These schemas complement the TypeScript types in types.ts with runtime validation.
- *
- * Related Spec: MCP-I §2.1, §2.3, W3C DID Core 1.0
- */
-
-import { z } from 'zod';
-import type {
-  DidDocument,
-  VerificationMethod,
-  DidService,
-  VerificationMethodType,
-} from './types.js';
-
-/**
- * Standard W3C DID Core context
- */
-export const DID_CONTEXT = 'https://www.w3.org/ns/did/v1' as const;
-
-/**
- * DID Context Entry Schema
- *
- * A context entry can be:
- * - A URL string (most common)
- * - A context definition object
- */
-export const DidContextEntrySchema = z.union([
-  z.string().url(),
-  z.record(z.any()),
-]);
-
-/**
- * DID @context Schema
- *
- * The @context property in DID Documents can be:
- * - A single string (typically the base DID context)
- * - An array of strings/objects (base context + additional contexts)
- * - A context definition object (for custom contexts)
- *
- * Per W3C DID Core spec, the base DID context should be present,
- * but we allow flexibility for different DID methods and extensions.
- */
-export const DidContextSchema = z.union([
-  // Single string context (e.g., "https://www.w3.org/ns/did/v1")
-  z.string().url(),
-  // Array of contexts (strings or objects)
-  z.array(DidContextEntrySchema).nonempty(),
-  // Context definition object
-  z.record(z.any()),
-]);
-
-/**
- * Verification Method Type Schema
- */
-export const VerificationMethodTypeSchema = z.enum([
-  'Ed25519VerificationKey2020',
-  'JsonWebKey2020',
-  'EcdsaSecp256k1VerificationKey2019',
-]);
-
-/**
- * Public Key JWK Schema (RFC 7517)
- */
-export const PublicKeyJwkSchema = z
-  .object({
-    /** Key Type */
-    kty: z.string(),
-    /** Curve (for elliptic curve keys) */
-    crv: z.string(),
-    /** X coordinate */
-    x: z.string(),
-    /** Y coordinate (optional for some key types) */
-    y: z.string().optional(),
-  })
-  .passthrough(); // Allow additional JWK properties
-
-/**
- * Verification Method Schema
- */
-export const VerificationMethodSchema: z.ZodType<VerificationMethod> = z.object({
-  /** Verification method identifier */
-  id: z.string(),
-  /** Type of verification method */
-  type: VerificationMethodTypeSchema,
-  /** Controller DID */
-  controller: z.string(),
-  /** Multibase-encoded public key (for Ed25519VerificationKey2020) */
-  publicKeyMultibase: z.string().optional(),
-  /** JSON Web Key (for JsonWebKey2020) */
-  publicKeyJwk: PublicKeyJwkSchema.optional(),
-});
-
-/**
- * DID Service Schema
- */
-export const DidServiceSchema: z.ZodType<DidService> = z.object({
-  /** Service identifier */
-  id: z.string(),
-  /** Service type(s) */
-  type: z.union([z.string(), z.array(z.string())]),
-  /** Service endpoint(s) */
-  serviceEndpoint: z.union([
-    z.string(),
-    z.array(z.string()),
-    z.record(z.any()),
-  ]),
-});
-
-/**
- * Verification Relationship Entry Schema
- *
- * Can be either a string reference to a verification method
- * or an embedded verification method object.
- */
-export const VerificationRelationshipEntrySchema = z.union([
-  z.string(), // Reference to verification method
-  VerificationMethodSchema, // Embedded verification method
-]);
-
-/**
- * DID Document Schema
- *
- * Validates a DID Document structure per W3C DID Core specification.
- */
-export const DidDocumentSchema: z.ZodType<DidDocument> = z
-  .object({
-    /** JSON-LD context */
-    '@context': DidContextSchema.optional(),
-    /** The DID this document describes */
-    id: z.string().refine((val) => val.startsWith('did:'), {
-      message: 'DID must start with "did:"',
-    }),
-    /** Alternative identifiers */
-    alsoKnownAs: z.array(z.string()).optional(),
-    /** Verification methods */
-    verificationMethod: z.array(VerificationMethodSchema).optional(),
-    /** Authentication verification relationship */
-    authentication: z.array(VerificationRelationshipEntrySchema).optional(),
-    /** Assertion method verification relationship */
-    assertionMethod: z.array(VerificationRelationshipEntrySchema).optional(),
-    /** Key agreement verification relationship */
-    keyAgreement: z.array(VerificationRelationshipEntrySchema).optional(),
-    /** Capability invocation verification relationship */
-    capabilityInvocation: z
-      .array(VerificationRelationshipEntrySchema)
-      .optional(),
-    /** Capability delegation verification relationship */
-    capabilityDelegation: z
-      .array(VerificationRelationshipEntrySchema)
-      .optional(),
-    /** Service endpoints */
-    service: z.array(DidServiceSchema).optional(),
-  })
-  .passthrough(); // Allow additional properties for extensibility
-
-/**
- * DID Method Schema
- */
-export const DidMethodSchema = z.enum(['key', 'web', 'jwk', 'ion', 'ebsi']);
-
-/**
- * Helper function to validate a DID Document
- *
- * @param doc - The document to validate
- * @returns The validated document or throws ZodError
- */
-export function validateDidDocument(doc: unknown): DidDocument {
-  return DidDocumentSchema.parse(doc);
-}
-
-/**
- * Helper function to safely validate a DID Document
- *
- * @param doc - The document to validate
- * @returns Result object with success status and data/error
- */
-export function safeValidateDidDocument(doc: unknown): {
-  success: boolean;
-  data?: DidDocument;
-  error?: z.ZodError;
-} {
-  const result = DidDocumentSchema.safeParse(doc);
-  if (result.success) {
-    return { success: true, data: result.data };
-  }
-  return { success: false, error: result.error };
-}

package/src/did/types.ts

@@ -1,224 +0,0 @@
-/**
- * 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}#${kid}` where kid 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 function isVerificationMethod(
-  value: any
-): value is VerificationMethod {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    typeof value.id === 'string' &&
-    typeof value.type === 'string' &&
-    typeof value.controller === 'string'
-  );
-}
-
-/**
- * Type guard to check if a value is a string reference to a verification method
- */
-export function isVerificationMethodReference(value: any): value is string {
-  return typeof value === 'string';
-}
-
-/**
- * Type guard to check if a DID Document is valid (basic structural check)
- */
-export function isDidDocument(value: any): value is DidDocument {
-  return (
-    typeof value === 'object' &&
-    value !== null &&
-    typeof value.id === 'string' &&
-    value.id.startsWith('did:')
-  );
-}
-
-/**
- * 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 function extractDidMethod(did: string): string | null {
-  const parts = did.split(':');
-  if (parts.length < 3 || parts[0] !== 'did') {
-    return null;
-  }
-  return parts[1];
-}
-
-/**
- * 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 function extractKeyId(didUrl: string): string | null {
-  const hashIndex = didUrl.indexOf('#');
-  if (hashIndex === -1) {
-    return null;
-  }
-  return didUrl.substring(hashIndex + 1);
-}