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

package/src/delegation/schemas.ts

@@ -1,595 +0,0 @@
-/**
- * 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
- */
-
-import { z } from 'zod';
-import { DelegationConstraintsSchema, type DelegationConstraints } from './constraints.js';
-import {
-  VerifiableCredentialSchema,
-  ContextSchema,
-  IssuerSchema,
-  CredentialStatusSchema,
-  ProofSchema,
-  type VerifiableCredential,
-} from '../vc/schemas.js';
-
-/**
- * Delegation Status
- *
- * Lifecycle status of a delegation
- */
-export const DelegationStatusSchema = z.enum(['active', 'revoked', 'expired']);
-export type DelegationStatus = z.infer<typeof DelegationStatusSchema>;
-
-/**
- * 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)
- */
-export const DelegationRecordSchema = z.object({
-  /** Unique identifier for the delegation */
-  id: z.string().min(1),
-
-  /** DID of the delegator (issuer, e.g., merchant/user) */
-  issuerDid: z.string().min(1),
-
-  /** DID of the delegatee (subject, e.g., agent) */
-  subjectDid: z.string().min(1),
-
-  /** Optional controller (user account ID or DID) */
-  controller: z.string().optional(),
-
-  /** ID of the backing Verifiable Credential */
-  vcId: z.string().min(1),
-
-  /** Optional parent delegation ID for chain tracking */
-  parentId: z.string().optional(),
-
-  /** CRISP constraints on this delegation */
-  constraints: DelegationConstraintsSchema,
-
-  /** Detached JWS signature over canonical delegation document */
-  signature: z.string().min(1),
-
-  /** Current status of the delegation */
-  status: DelegationStatusSchema,
-
-  /** Timestamp when created (milliseconds since epoch) */
-  createdAt: z.number().int().positive().optional(),
-
-  /** Timestamp when revoked (if status is revoked) */
-  revokedAt: z.number().int().positive().optional(),
-
-  /** Optional reason for revocation */
-  revokedReason: z.string().optional(),
-
-  /** Optional metadata */
-  metadata: z.record(z.any()).optional(),
-}).passthrough(); // Allow extensibility
-
-export type DelegationRecord = z.infer<typeof DelegationRecordSchema>;
-
-/**
- * Delegation Chain Entry
- *
- * Represents a single link in a delegation chain
- */
-export const DelegationChainEntrySchema = z.object({
-  /** Delegation ID */
-  delegationId: z.string().min(1),
-
-  /** Issuer DID */
-  issuerDid: z.string().min(1),
-
-  /** Subject DID */
-  subjectDid: z.string().min(1),
-
-  /** VC ID */
-  vcId: z.string().min(1),
-
-  /** Depth in chain (0 = root) */
-  depth: z.number().int().nonnegative(),
-
-  /** Constraints */
-  constraints: DelegationConstraintsSchema,
-
-  /** Status */
-  status: DelegationStatusSchema,
-});
-
-export type DelegationChainEntry = z.infer<typeof DelegationChainEntrySchema>;
-
-/**
- * Delegation Chain
- *
- * Represents a complete delegation chain from root to leaf
- */
-export const DelegationChainSchema = z.object({
-  /** Root issuer DID */
-  rootIssuer: z.string().min(1),
-
-  /** Leaf subject DID */
-  leafSubject: z.string().min(1),
-
-  /** All delegations in the chain, ordered root to leaf */
-  chain: z.array(DelegationChainEntrySchema).min(1),
-
-  /** Total chain depth */
-  depth: z.number().int().nonnegative(),
-
-  /** Whether the entire chain is valid */
-  valid: z.boolean(),
-
-  /** Optional validation errors */
-  errors: z.array(z.string()).optional(),
-});
-
-export type DelegationChain = z.infer<typeof DelegationChainSchema>;
-
-/**
- * Delegation Creation Request
- *
- * Input for creating a new delegation
- */
-export const DelegationCreationRequestSchema = z.object({
-  /** Delegator DID */
-  issuerDid: z.string().min(1),
-
-  /** Delegatee DID */
-  subjectDid: z.string().min(1),
-
-  /** Optional controller */
-  controller: z.string().optional(),
-
-  /** Constraints */
-  constraints: DelegationConstraintsSchema,
-
-  /** Optional parent delegation ID */
-  parentId: z.string().optional(),
-
-  /** Optional VC ID (if not provided, will be created) */
-  vcId: z.string().optional(),
-});
-
-export type DelegationCreationRequest = z.infer<typeof DelegationCreationRequestSchema>;
-
-/**
- * Delegation Verification Result
- *
- * Result of delegation verification
- */
-export const DelegationVerificationResultSchema = z.object({
-  /** Whether delegation is valid */
-  valid: z.boolean(),
-
-  /** Delegation ID */
-  delegationId: z.string().min(1),
-
-  /** Status */
-  status: DelegationStatusSchema,
-
-  /** Optional reason for invalid status */
-  reason: z.string().optional(),
-
-  /** Whether backing VC is valid */
-  credentialValid: z.boolean().optional(),
-
-  /** Whether chain is valid (if part of chain) */
-  chainValid: z.boolean().optional(),
-
-  /** Timestamp of verification */
-  verifiedAt: z.number().int().positive(),
-
-  /** Optional verification details */
-  details: z.record(z.any()).optional(),
-});
-
-export type DelegationVerificationResult = z.infer<typeof DelegationVerificationResultSchema>;
-
-/**
- * Validation Helpers
- */
-
-/**
- * Validate a delegation record
- *
- * @param record - The delegation record to validate
- * @returns Validation result
- */
-export function validateDelegationRecord(record: unknown) {
-  return DelegationRecordSchema.safeParse(record);
-}
-
-/**
- * Validate a delegation chain
- *
- * @param chain - The delegation chain to validate
- * @returns Validation result
- */
-export function validateDelegationChain(chain: unknown) {
-  return DelegationChainSchema.safeParse(chain);
-}
-
-/**
- * Check if a delegation is expired based on constraints
- *
- * @param delegation - The delegation to check
- * @returns true if expired
- */
-export function isDelegationExpired(delegation: DelegationRecord): boolean {
-  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
- */
-export function isDelegationNotYetValid(delegation: DelegationRecord): boolean {
-  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
- */
-export function isDelegationCurrentlyValid(delegation: DelegationRecord): boolean {
-  if (delegation.status !== 'active') {
-    return false;
-  }
-
-  if (isDelegationExpired(delegation)) {
-    return false;
-  }
-
-  if (isDelegationNotYetValid(delegation)) {
-    return false;
-  }
-
-  return true;
-}
-
-/**
- * Constants
- */
-
-/**
- * Maximum reasonable delegation chain depth
- */
-export const MAX_DELEGATION_CHAIN_DEPTH = 10;
-
-/**
- * Default delegation status for new delegations
- */
-export const DEFAULT_DELEGATION_STATUS: DelegationStatus = 'active';
-
-/**
- * Supported delegation statuses
- */
-export const DELEGATION_STATUSES: DelegationStatus[] = ['active', 'revoked', 'expired'];
-
-// ============================================================================
-// W3C VC-BASED DELEGATION CREDENTIALS (Phase 3 Implementation)
-// ============================================================================
-
-/**
- * Delegation Credential Context
- *
- * Additional JSON-LD context for delegation credentials
- */
-export const DELEGATION_CREDENTIAL_CONTEXT =
-  'https://schemas.kya-os.ai/xmcp-i/credentials/delegation.v1.0.0.json' as const;
-
-/**
- * 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.
- */
-export const DelegationCredentialSubjectSchema = z.object({
-  /** Subject DID (delegatee) */
-  id: z.string().min(1),
-
-  /** The delegation information */
-  delegation: z.object({
-    /** Unique identifier for the delegation */
-    id: z.string().min(1),
-
-    /** DID of the delegator (issuer, e.g., merchant/user) */
-    issuerDid: z.string().min(1),
-
-    /** DID of the delegatee (subject, e.g., agent) */
-    subjectDid: z.string().min(1),
-
-    /** Optional controller (user account ID or DID) */
-    controller: z.string().optional(),
-
-    /** Optional parent delegation ID for chain tracking */
-    parentId: z.string().optional(),
-
-    /** CRISP constraints on this delegation */
-    constraints: DelegationConstraintsSchema,
-
-    /** Current status of the delegation */
-    status: DelegationStatusSchema.default('active'),
-
-    /** Timestamp when created (milliseconds since epoch) */
-    createdAt: z.number().int().positive().optional(),
-
-    /** Optional metadata */
-    metadata: z.record(z.any()).optional(),
-  }),
-});
-
-export type DelegationCredentialSubject = z.infer<
-  typeof DelegationCredentialSubjectSchema
->;
-
-/**
- * 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
- */
-export const DelegationCredentialSchema = VerifiableCredentialSchema.extend({
-  /** @context MUST include delegation context */
-  '@context': z
-    .array(z.union([z.string().url(), z.record(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: z
-    .array(z.string())
-    .refine(
-      (types) =>
-        types.includes('VerifiableCredential') &&
-        types.includes('DelegationCredential'),
-      {
-        message:
-          'type must include both "VerifiableCredential" and "DelegationCredential"',
-      }
-    ),
-
-  /** issuer is the delegator DID */
-  issuer: IssuerSchema,
-
-  /** issuanceDate maps to delegation creation time */
-  issuanceDate: z.string().datetime(),
-
-  /** expirationDate maps to delegation.constraints.notAfter */
-  expirationDate: z.string().datetime().optional(),
-
-  /** credentialSubject contains delegatee DID + delegation data */
-  credentialSubject: DelegationCredentialSubjectSchema,
-
-  /** credentialStatus for StatusList2021 revocation checking */
-  credentialStatus: CredentialStatusSchema.optional(),
-
-  /** proof is Ed25519Signature2020 */
-  proof: ProofSchema.optional(),
-});
-
-export type DelegationCredential = z.infer<typeof DelegationCredentialSchema>;
-
-/**
- * Validate a delegation credential
- *
- * @param credential - The delegation credential to validate
- * @returns Validation result
- */
-export function validateDelegationCredential(credential: unknown) {
-  return 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
- */
-export function extractDelegationFromVC(vc: DelegationCredential): DelegationRecord {
-  const delegation = vc.credentialSubject.delegation;
-
-  // Extract signature from proof (may be in different formats)
-  let signature = '';
-  if (vc.proof) {
-    const proof = vc.proof as any;
-    signature = proof.proofValue || proof.jws || proof.signatureValue || '';
-  }
-
-  return {
-    id: delegation.id,
-    issuerDid: delegation.issuerDid,
-    subjectDid: delegation.subjectDid,
-    controller: delegation.controller,
-    vcId: vc.id || `vc:${delegation.id}`, // VC id becomes vcId
-    parentId: delegation.parentId,
-    constraints: delegation.constraints,
-    signature,
-    status: delegation.status,
-    createdAt: delegation.createdAt,
-    revokedAt: undefined, // Revocation status comes from credentialStatus
-    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
- */
-export function wrapDelegationAsVC(
-  delegation: DelegationRecord,
-  options?: {
-    id?: string;
-    issuanceDate?: string;
-    expirationDate?: string;
-    credentialStatus?: z.infer<typeof CredentialStatusSchema>;
-  }
-): Omit<DelegationCredential, 'proof'> {
-  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();
-  }
-
-  return {
-    '@context': [
-      'https://www.w3.org/2018/credentials/v1',
-      DELEGATION_CREDENTIAL_CONTEXT,
-    ],
-    id: options?.id || delegation.vcId || `urn:uuid:${delegation.id}`,
-    type: ['VerifiableCredential', 'DelegationCredential'],
-    issuer: delegation.issuerDid,
-    issuanceDate,
-    expirationDate,
-    credentialSubject: {
-      id: delegation.subjectDid,
-      delegation: {
-        id: delegation.id,
-        issuerDid: delegation.issuerDid,
-        subjectDid: delegation.subjectDid,
-        controller: delegation.controller,
-        parentId: delegation.parentId,
-        constraints: delegation.constraints,
-        status: delegation.status,
-        createdAt: delegation.createdAt,
-        metadata: delegation.metadata,
-      },
-    },
-    credentialStatus: options?.credentialStatus,
-  };
-}
-
-/**
- * Check if a delegation credential is expired
- *
- * @param vc - The delegation credential
- * @returns true if expired
- */
-export function isDelegationCredentialExpired(vc: DelegationCredential): boolean {
-  // Check VC expiration
-  if (vc.expirationDate) {
-    const expirationDate = new Date(vc.expirationDate);
-    const now = new Date();
-    if (expirationDate < now) {
-      return true;
-    }
-  }
-
-  // Check delegation constraints notAfter
-  const delegation = vc.credentialSubject.delegation;
-  if (delegation.constraints.notAfter) {
-    const nowSec = Math.floor(Date.now() / 1000);
-    if (nowSec > delegation.constraints.notAfter) {
-      return true;
-    }
-  }
-
-  return false;
-}
-
-/**
- * Check if a delegation credential is not yet valid
- *
- * @param vc - The delegation credential
- * @returns true if not yet valid
- */
-export function isDelegationCredentialNotYetValid(vc: DelegationCredential): boolean {
-  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) {
-      return true;
-    }
-  }
-
-  return false;
-}

package/src/did/index.ts

@@ -1,9 +0,0 @@
-/**
- * DID Module Exports
- *
- * Types and contracts for W3C Decentralized Identifiers (DIDs)
- */
-
-export * from './types.js';
-export * from './resolve-contract.js';
-export * from './schemas.js';