@kya-os/contracts 1.5.3-canary.16 → 1.5.3-canary.17

package/src/delegation/schemas.ts

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

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