@kya-os/contracts 1.5.3-canary.2 → 1.5.3-canary.20

package/src/vc/schemas.ts

@@ -0,0 +1,277 @@
+/**
+ * Verifiable Credentials (W3C 1.1) Schemas
+ *
+ * Zod schemas and TypeScript types for W3C Verifiable Credentials Data Model 1.1.
+ * These schemas provide runtime validation and can emit JSON Schemas for interoperability.
+ *
+ * Related Spec: MCP-I §3, W3C VC Data Model 1.1
+ * Python Reference: Credential-Documentation.md, Credential-Service.md
+ */
+
+import { z } from 'zod';
+
+/**
+ * Standard W3C Verifiable Credentials context
+ */
+export const VC_CONTEXT = ['https://www.w3.org/2018/credentials/v1'] as const;
+
+/**
+ * Additional context for StatusList2021
+ */
+export const STATUS_LIST_CONTEXT =
+  'https://w3id.org/vc/status-list/2021/v1' as const;
+
+/**
+ * Context Entry Schema
+ *
+ * Supports both string URLs and context objects
+ */
+export const ContextEntrySchema = z.union([
+  z.string().url(),
+  z.record(z.any()),
+]);
+
+/**
+ * @context Schema
+ *
+ * The @context property establishes the semantic context of the credential.
+ * MUST include the base VC context and MAY include additional contexts.
+ */
+export const ContextSchema = z
+  .array(ContextEntrySchema)
+  .nonempty()
+  .refine(
+    (contexts) => {
+      // First context must be the base VC context
+      const firstContext = contexts[0];
+      return (
+        typeof firstContext === 'string' &&
+        firstContext === VC_CONTEXT[0]
+      );
+    },
+    {
+      message:
+        'First @context must be "https://www.w3.org/2018/credentials/v1"',
+    }
+  );
+
+/**
+ * Issuer Schema
+ *
+ * The issuer can be a DID string or an object with an id field
+ */
+export const IssuerSchema = z.union([
+  z.string().min(1),
+  z.object({
+    id: z.string().min(1),
+  }).passthrough(), // Allow additional properties
+]);
+
+/**
+ * Credential Subject Schema
+ *
+ * The subject of the credential. Can be a single object or array of objects.
+ * MUST have an id property that is a DID or URI.
+ */
+export const CredentialSubjectSchema = z.union([
+  z.record(z.any()),
+  z.array(z.record(z.any())),
+]);
+
+/**
+ * Credential Status Schema (StatusList2021Entry)
+ *
+ * References a position in a StatusList2021 credential for revocation/suspension checking.
+ */
+export const CredentialStatusSchema = z.object({
+  /** URI of this status entry */
+  id: z.string().url(),
+
+  /** Type MUST be StatusList2021Entry */
+  type: z.literal('StatusList2021Entry'),
+
+  /** Purpose of the status list (revocation or suspension) */
+  statusPurpose: z.enum(['revocation', 'suspension']),
+
+  /** Index of this credential in the status list (as string per spec) */
+  statusListIndex: z.string().regex(/^\d+$/, 'Must be a numeric string'),
+
+  /** URL of the StatusList2021Credential */
+  statusListCredential: z.string().url(),
+});
+
+/**
+ * Proof Schema
+ *
+ * Cryptographic proof for the credential.
+ * This is a flexible schema as proof formats vary.
+ */
+export const ProofSchema = z
+  .object({
+    type: z.string().min(1),
+    created: z.string().optional(),
+    verificationMethod: z.string().optional(),
+    proofPurpose: z.string().optional(),
+  })
+  .passthrough(); // Allow additional proof-specific fields
+
+/**
+ * Verifiable Credential Schema (W3C 1.1)
+ *
+ * Core schema for W3C Verifiable Credentials.
+ * Supports all required and common optional fields.
+ */
+export const VerifiableCredentialSchema = z.object({
+  /** JSON-LD context */
+  '@context': ContextSchema,
+
+  /** Unique identifier for the credential (optional per spec) */
+  id: z.string().url().optional(),
+
+  /** Type of the credential, MUST include "VerifiableCredential" */
+  type: z
+    .array(z.string())
+    .min(1)
+    .refine((types) => types.includes('VerifiableCredential'), {
+      message: 'type must include "VerifiableCredential"',
+    }),
+
+  /** Issuer of the credential (DID or issuer object) */
+  issuer: IssuerSchema,
+
+  /** Issuance date in ISO 8601 format */
+  issuanceDate: z.string().datetime(),
+
+  /** Expiration date in ISO 8601 format (optional) */
+  expirationDate: z.string().datetime().optional(),
+
+  /** The subject(s) of the credential */
+  credentialSubject: CredentialSubjectSchema,
+
+  /** Status information for revocation/suspension (optional) */
+  credentialStatus: CredentialStatusSchema.optional(),
+
+  /** Cryptographic proof (optional, may be added as external proof) */
+  proof: ProofSchema.optional(),
+
+  /** Allow additional properties for extensibility */
+}).passthrough();
+
+/**
+ * Type exports
+ */
+export type ContextEntry = z.infer<typeof ContextEntrySchema>;
+export type Context = z.infer<typeof ContextSchema>;
+export type Issuer = z.infer<typeof IssuerSchema>;
+export type CredentialSubject = z.infer<typeof CredentialSubjectSchema>;
+export type CredentialStatus = z.infer<typeof CredentialStatusSchema>;
+export type Proof = z.infer<typeof ProofSchema>;
+
+/**
+ * Verifiable Credential Type
+ *
+ * Use this type for type-safe credential handling.
+ */
+export type VerifiableCredential = z.infer<typeof VerifiableCredentialSchema>;
+
+/**
+ * Verifiable Presentation Schema
+ *
+ * Schema for presenting one or more credentials.
+ */
+export const VerifiablePresentationSchema = z.object({
+  '@context': ContextSchema,
+  id: z.string().url().optional(),
+  type: z
+    .array(z.string())
+    .min(1)
+    .refine((types) => types.includes('VerifiablePresentation'), {
+      message: 'type must include "VerifiablePresentation"',
+    }),
+  holder: z.string().min(1).optional(),
+  verifiableCredential: z
+    .union([
+      VerifiableCredentialSchema,
+      z.array(VerifiableCredentialSchema),
+    ])
+    .optional(),
+  proof: ProofSchema.optional(),
+}).passthrough();
+
+export type VerifiablePresentation = z.infer<
+  typeof VerifiablePresentationSchema
+>;
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate a verifiable credential
+ *
+ * @param credential - The credential to validate
+ * @returns Validation result with parsed credential or errors
+ */
+export function validateVerifiableCredential(credential: unknown) {
+  return VerifiableCredentialSchema.safeParse(credential);
+}
+
+/**
+ * Validate a verifiable presentation
+ *
+ * @param presentation - The presentation to validate
+ * @returns Validation result with parsed presentation or errors
+ */
+export function validateVerifiablePresentation(presentation: unknown) {
+  return VerifiablePresentationSchema.safeParse(presentation);
+}
+
+/**
+ * Check if a credential is expired
+ *
+ * @param credential - The credential to check
+ * @returns true if expired, false otherwise
+ */
+export function isCredentialExpired(credential: VerifiableCredential): boolean {
+  if (!credential.expirationDate) {
+    return false;
+  }
+
+  try {
+    const expirationDate = new Date(credential.expirationDate);
+    const now = new Date();
+    return expirationDate < now;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Extract issuer DID from credential
+ *
+ * @param credential - The credential
+ * @returns The issuer DID string
+ */
+export function getIssuerDid(credential: VerifiableCredential): string {
+  const issuer = credential.issuer as string | { id: string };
+  if (typeof issuer === 'string') {
+    return issuer;
+  }
+  return issuer.id;
+}
+
+/**
+ * Extract credential subject DID (if present)
+ *
+ * @param credential - The credential
+ * @returns The subject DID or null if not present
+ */
+export function getSubjectDid(
+  credential: VerifiableCredential
+): string | null {
+  const subject = Array.isArray(credential.credentialSubject)
+    ? credential.credentialSubject[0]
+    : credential.credentialSubject;
+
+  return (subject?.id as string) || null;
+}

package/src/vc/statuslist.ts

@@ -0,0 +1,279 @@
+/**
+ * StatusList2021 Types and Schemas
+ *
+ * Implementation of the W3C StatusList2021 specification for credential status.
+ * Provides types for status list credentials and helpers for bitstring operations.
+ *
+ * Related Spec: W3C StatusList2021
+ * Python Reference: Credential-Documentation.md (StatusList2021 section)
+ */
+
+import { z } from 'zod';
+import { ContextSchema, IssuerSchema, ProofSchema } from './schemas.js';
+
+/**
+ * Status Purpose
+ *
+ * Indicates the purpose of the status list
+ */
+export type StatusPurpose = 'revocation' | 'suspension';
+
+/**
+ * Status List Credential Subject Schema
+ *
+ * The credential subject of a StatusList2021Credential
+ */
+export const StatusList2021CredentialSubjectSchema = z.object({
+  /** Optional identifier for the status list */
+  id: z.string().optional(),
+
+  /** Type MUST be StatusList2021 */
+  type: z.literal('StatusList2021'),
+
+  /** Purpose of the status list */
+  statusPurpose: z.enum(['revocation', 'suspension']),
+
+  /**
+   * Encoded bitstring
+   *
+   * Base64url-encoded and GZIP-compressed bitstring.
+   * Each bit represents the status of a credential:
+   * - 0: Not revoked/suspended
+   * - 1: Revoked/suspended
+   */
+  encodedList: z.string().regex(/^[A-Za-z0-9_-]+$/, {
+    message: 'encodedList must be base64url encoded',
+  }),
+});
+
+/**
+ * StatusList2021 Credential Schema
+ *
+ * A credential that contains a status list for checking revocation/suspension
+ * of other credentials.
+ */
+export const StatusList2021CredentialSchema = z.object({
+  /** JSON-LD context */
+  '@context': ContextSchema.refine(
+    (contexts) => {
+      // Must include both base VC context and StatusList context
+      return (
+        contexts.length >= 2 &&
+        typeof contexts[0] === 'string' &&
+        contexts[0] === 'https://www.w3.org/2018/credentials/v1' &&
+        (contexts.includes('https://w3id.org/vc/status-list/2021/v1') ||
+          (contexts as any[]).some(
+            (ctx) =>
+              typeof ctx === 'object' &&
+              ctx['StatusList2021Credential'] !== undefined
+          ))
+      );
+    },
+    {
+      message:
+        '@context must include VC context and StatusList2021 context',
+    }
+  ),
+
+  /** Unique identifier for the status list credential */
+  id: z.string().url(),
+
+  /** Type MUST include VerifiableCredential and StatusList2021Credential */
+  type: z
+    .tuple([z.literal('VerifiableCredential'), z.literal('StatusList2021Credential')])
+    .or(
+      z.array(z.string()).refine(
+        (types) =>
+          types.includes('VerifiableCredential') &&
+          types.includes('StatusList2021Credential'),
+        {
+          message:
+            'type must include "VerifiableCredential" and "StatusList2021Credential"',
+        }
+      )
+    ),
+
+  /** Issuer of the status list credential */
+  issuer: IssuerSchema,
+
+  /** Issuance date in ISO 8601 format */
+  issuanceDate: z.string().datetime(),
+
+  /** The status list credential subject */
+  credentialSubject: StatusList2021CredentialSubjectSchema,
+
+  /** Cryptographic proof (optional) */
+  proof: ProofSchema.optional(),
+}).passthrough();
+
+/**
+ * Type exports
+ */
+export type StatusList2021CredentialSubject = z.infer<
+  typeof StatusList2021CredentialSubjectSchema
+>;
+export type StatusList2021Credential = z.infer<
+  typeof StatusList2021CredentialSchema
+>;
+
+/**
+ * StatusList2021 Credential Type (traditional TypeScript interface)
+ *
+ * For use when not using Zod validation
+ */
+export interface StatusList2021CredentialInterface {
+  '@context': (string | Record<string, any>)[];
+  id: string;
+  type: ['VerifiableCredential', 'StatusList2021Credential'];
+  issuer: string | { id: string };
+  issuanceDate: string;
+  credentialSubject: {
+    id?: string;
+    type: 'StatusList2021';
+    statusPurpose: 'revocation' | 'suspension';
+    encodedList: string;
+  };
+  proof?: Record<string, any>;
+}
+
+/**
+ * Validation Helpers
+ */
+
+/**
+ * Validate a StatusList2021 credential
+ *
+ * @param credential - The credential to validate
+ * @returns Validation result with parsed credential or errors
+ */
+export function validateStatusList2021Credential(credential: unknown) {
+  return StatusList2021CredentialSchema.safeParse(credential);
+}
+
+/**
+ * Helper Types for Bitstring Operations
+ *
+ * These types define the interface for bitstring encode/decode operations.
+ * Actual implementation would be in a separate utility module.
+ */
+
+/**
+ * Bitstring encoding options
+ */
+export interface BitStringEncodeOptions {
+  /** Total size of the bitstring (number of bits) */
+  size: number;
+
+  /** Positions to set to 1 (revoked/suspended) */
+  setBits?: number[];
+}
+
+/**
+ * Bitstring decoding result
+ */
+export interface BitStringDecodeResult {
+  /** Total size of the bitstring */
+  size: number;
+
+  /** Positions that are set to 1 */
+  setBits: number[];
+
+  /** Check if a specific index is set */
+  isSet: (index: number) => boolean;
+}
+
+/**
+ * Cache entry for StatusList2021 credentials
+ *
+ * Used for efficient caching of status list credentials with ETag support
+ */
+export interface StatusListCacheEntry {
+  /** The cached status list credential */
+  credential: StatusList2021Credential;
+
+  /** ETag from the HTTP response (if applicable) */
+  etag?: string;
+
+  /** Timestamp when cached (milliseconds since epoch) */
+  cachedAt: number;
+
+  /** TTL in seconds */
+  ttlSec: number;
+
+  /** Expires at timestamp (milliseconds since epoch) */
+  expiresAt: number;
+}
+
+/**
+ * Status checking result
+ */
+export interface StatusCheckResult {
+  /** Whether the credential is valid (not revoked/suspended) */
+  valid: boolean;
+
+  /** The status (active, revoked, suspended) */
+  status: 'active' | 'revoked' | 'suspended';
+
+  /** Optional reason for status */
+  reason?: string;
+
+  /** Timestamp when checked */
+  checkedAt: number;
+
+  /** Whether result came from cache */
+  fromCache?: boolean;
+}
+
+/**
+ * Helper to create a minimal status list credential structure
+ *
+ * This is a type-safe helper, actual credential creation requires
+ * proper signing and encoding implementation.
+ *
+ * @param config - Configuration for the status list credential
+ * @returns Partial credential structure (needs proof to be complete)
+ */
+export function createStatusListCredentialStructure(config: {
+  id: string;
+  issuer: string | { id: string };
+  statusPurpose: StatusPurpose;
+  encodedList: string;
+}): Omit<StatusList2021Credential, 'proof'> {
+  return {
+    '@context': [
+      'https://www.w3.org/2018/credentials/v1',
+      'https://w3id.org/vc/status-list/2021/v1',
+    ],
+    id: config.id,
+    type: ['VerifiableCredential', 'StatusList2021Credential'],
+    issuer: config.issuer,
+    issuanceDate: new Date().toISOString(),
+    credentialSubject: {
+      type: 'StatusList2021',
+      statusPurpose: config.statusPurpose,
+      encodedList: config.encodedList,
+    },
+  };
+}
+
+/**
+ * Constants
+ */
+
+/**
+ * Default cache TTL for status list credentials (in seconds)
+ * As per spec recommendation
+ */
+export const DEFAULT_STATUSLIST_CACHE_TTL_SEC = 60;
+
+/**
+ * Maximum reasonable bitstring size
+ * Used for validation to prevent memory exhaustion
+ */
+export const MAX_STATUSLIST_SIZE = 1000000; // 1 million entries
+
+/**
+ * StatusList2021 context URL
+ */
+export const STATUSLIST_2021_CONTEXT =
+  'https://w3id.org/vc/status-list/2021/v1';

package/src/verifier/index.ts

@@ -0,0 +1,2 @@
+// Re-export everything from the main verifier file
+export * from "../verifier";

package/src/verifier.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+/**
+ * Verifier middleware schemas and headers
+ */
+
+export const AgentContextSchema = z.object({
+  did: z.string().min(1),
+  kid: z.string().min(1),
+  subject: z.string().optional(),
+  scopes: z.array(z.string()).default([]),
+  session: z.string().min(1),
+  confidence: z.literal("verified"),
+  delegationRef: z.string().optional(),
+  registry: z.string().url(),
+  verifiedAt: z.number().int().positive(),
+});
+
+export const VerifierResultSchema = z.object({
+  success: z.boolean(),
+  headers: z.record(z.string()).optional(),
+  agentContext: AgentContextSchema.optional(),
+  error: z
+    .object({
+      code: z.string(),
+      message: z.string(),
+      details: z.any().optional(),
+      httpStatus: z.number().int().min(400).max(599),
+    })
+    .optional(),
+});
+
+export const StructuredErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  httpStatus: z.number().int().min(400).max(599),
+  details: z
+    .object({
+      reason: z.string().optional(),
+      expected: z.any().optional(),
+      received: z.any().optional(),
+      remediation: z.string().optional(),
+    })
+    .optional(),
+});
+
+// Type exports
+export type AgentContext = z.infer<typeof AgentContextSchema>;
+export type VerifierResult = z.infer<typeof VerifierResultSchema>;
+export type StructuredError = z.infer<typeof StructuredErrorSchema>;
+
+// Header constants (frozen names)
+export const AGENT_HEADERS = {
+  DID: "X-Agent-DID",
+  KEY_ID: "X-Agent-KeyId",
+  SUBJECT: "X-Agent-Subject",
+  SCOPES: "X-Agent-Scopes",
+  SESSION: "X-Agent-Session",
+  CONFIDENCE: "X-Agent-Confidence",
+  DELEGATION_REF: "X-Agent-Delegation-Ref",
+  REGISTRY: "X-Agent-Registry",
+  VERIFIED_AT: "X-Agent-Verified-At",
+} as const;
+
+// Verifier-specific error codes
+export const VERIFIER_ERROR_CODES = {
+  PROOF_INVALID_TS: "XMCP_I_PROOF_INVALID_TS",
+  PROOF_FUTURE_TS: "XMCP_I_PROOF_FUTURE_TS",
+  PROOF_TOO_OLD: "XMCP_I_PROOF_TOO_OLD",
+  PROOF_SKEW_EXCEEDED: "XMCP_I_PROOF_SKEW_EXCEEDED",
+  SESSION_IDLE_EXPIRED: "XMCP_I_SESSION_IDLE_EXPIRED",
+  SERVER_TIME_INVALID: "XMCP_I_SERVER_TIME_INVALID",
+} as const;
+
+// HTTP status mappings
+export const ERROR_HTTP_STATUS = {
+  XMCP_I_EBADPROOF: 403,
+  XMCP_I_ENOIDENTITY: 500,
+  XMCP_I_EMIRRORPENDING: 200,
+  XMCP_I_EHANDSHAKE: 401,
+  XMCP_I_ESESSION: 401,
+  XMCP_I_ECLAIM: 400,
+  XMCP_I_ECONFIG: 500,
+  XMCP_I_ERUNTIME: 500,
+  // Verifier-specific codes
+  [VERIFIER_ERROR_CODES.PROOF_INVALID_TS]: 403,
+  [VERIFIER_ERROR_CODES.PROOF_FUTURE_TS]: 403,
+  [VERIFIER_ERROR_CODES.PROOF_TOO_OLD]: 403,
+  [VERIFIER_ERROR_CODES.PROOF_SKEW_EXCEEDED]: 401,
+  [VERIFIER_ERROR_CODES.SESSION_IDLE_EXPIRED]: 401,
+  [VERIFIER_ERROR_CODES.SERVER_TIME_INVALID]: 500,
+} as const;