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

package/src/registry.ts

@@ -1,146 +0,0 @@
-import { z } from "zod";
-
-/**
- * Registry integration schemas (Know-That-AI and MCP Registry)
- */
-
-export const RegistrationInputSchema = z.object({
-  agentDID: z.string().min(1),
-  agentURL: z.string().url(),
-  verificationEndpoint: z.string().url(),
-  conformanceCapabilities: z.array(
-    z.enum(["handshake", "signing", "verification"])
-  ),
-  metadata: z.record(z.any()).optional(),
-});
-
-export const RegistrationResultSchema = z.object({
-  agentDID: z.string().min(1),
-  agentURL: z.string().url(),
-  agentId: z.string().min(1),
-  agentSlug: z.string().min(1),
-  claimURL: z.string().url().optional(),
-  verificationEndpoint: z.string().url(),
-  conformanceCapabilities: z.tuple([
-    z.literal("handshake"),
-    z.literal("signing"),
-    z.literal("verification"),
-  ]),
-  mirrorStatus: z.enum(["pending", "success", "error"]),
-  mirrorLink: z.string().url().optional(),
-});
-
-export const ClaimTokenSchema = z.object({
-  token: z.string().min(1),
-  expiresAt: z.number().int().positive(),
-  ttlHours: z.number().int().positive().default(24),
-});
-
-export const MirrorStatusSchema = z.object({
-  status: z.enum(["pending", "success", "error"]),
-  lastUpdated: z.number().int().positive(),
-  errorMessage: z.string().optional(),
-  registryURL: z.string().url().optional(),
-});
-
-export const AgentStatusSchema = z.object({
-  did: z.string().min(1),
-  kid: z.string().min(1),
-  ktaURL: z.string().url(),
-  mirrorStatus: MirrorStatusSchema,
-  lastHandshake: z.number().int().positive().optional(),
-});
-
-/**
- * Delegation schemas for verifiable credentials
- */
-export const DelegationSchema = z.object({
-  issuer: z.string().min(1), // DID of the issuer
-  subject: z.string().min(1), // DID of the subject
-  scopes: z.array(z.string()),
-  nbf: z.number().int().positive(), // Not before (unix timestamp)
-  exp: z.number().int().positive(), // Expires (unix timestamp)
-  aud: z.string().optional(), // Audience (optional)
-  delegationRef: z.string().optional(), // Reference to parent delegation
-});
-
-export const DelegationRequestSchema = z.object({
-  subject: z.string().min(1),
-  scopes: z.array(z.string()),
-  duration: z.number().int().positive().optional(), // Duration in seconds
-  audience: z.string().optional(),
-});
-
-/**
- * Storage mode configuration for verifiable credentials and delegations
- */
-export const StorageModeSchema = z.enum([
-  "ktaEncrypted",
-  "hybridReceiptsOnly",
-  "selfHostedAuthoritative",
-]);
-
-/**
- * Receipt object returned by KTA for verifiable operations
- * Schema ID: https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json
- */
-export const ReceiptSchema = z.object({
-  $schema: z
-    .literal("https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json")
-    .optional(),
-  ref: z.string().min(1),
-  contentHash: z.string().regex(/^sha256:[a-f0-9]{64}$/),
-  action: z.enum(["issue", "revoke"]),
-  // Back-compat: accept ISO string (preferred) or legacy epoch number
-  ts: z.union([z.string().datetime(), z.number().int().positive()]),
-  logIndex: z.number().int().nonnegative(),
-  logRoot: z.string().min(1),
-  inclusionProof: z.array(z.string()),
-});
-
-export const DelegationResponseSchema = z.object({
-  delegation: DelegationSchema,
-  receipt: ReceiptSchema,
-  encryptedPayload: z.string().optional(), // For ktaEncrypted mode
-});
-
-/**
- * Storage configuration for different deployment modes
- */
-export const StorageConfigSchema = z.object({
-  mode: StorageModeSchema,
-  encryptionEnabled: z.boolean().default(false),
-  receiptVerificationEnabled: z.boolean().default(true),
-  ktaBaseURL: z.string().url().default("https://knowthat.ai"),
-});
-
-// Type exports
-export type RegistrationInput = z.infer<typeof RegistrationInputSchema>;
-export type RegistrationResult = z.infer<typeof RegistrationResultSchema>;
-export type ClaimToken = z.infer<typeof ClaimTokenSchema>;
-export type MirrorStatus = z.infer<typeof MirrorStatusSchema>;
-export type AgentStatus = z.infer<typeof AgentStatusSchema>;
-export type StorageMode = z.infer<typeof StorageModeSchema>;
-export type Receipt = z.infer<typeof ReceiptSchema>;
-export type StorageConfig = z.infer<typeof StorageConfigSchema>;
-export type Delegation = z.infer<typeof DelegationSchema>;
-export type DelegationRequest = z.infer<typeof DelegationRequestSchema>;
-export type DelegationResponse = z.infer<typeof DelegationResponseSchema>;
-
-// Constants
-export const MCP_I_CAPABILITIES = [
-  "handshake",
-  "signing",
-  "verification",
-] as const;
-export const CLAIM_TOKEN_TTL_HOURS = 24;
-export const KTA_BASE_URL = "https://knowthat.ai"; // Placeholder for docs/tests
-
-// Storage mode constants
-export const DEFAULT_STORAGE_MODE: StorageMode = "ktaEncrypted";
-export const STORAGE_MODE_ENV_VAR = "MCPI_STORAGE_MODE";
-
-// Receipt schema constants
-export const RECEIPT_SCHEMA_ID =
-  "https://schemas.kya-os.ai/mcpi/receipt/v1.0.0.json";
-export const CONTENT_HASH_REGEX = /^sha256:[a-f0-9]{64}$/;

package/src/runtime/errors.ts

@@ -1,153 +0,0 @@
-/**
- * Runtime Error Contracts
- *
- * Error types and schemas for runtime errors, especially authorization errors
- *
- * Related Spec: MCP-I §6
- * Python Reference: Core-Documentation.md
- */
-
-import { z } from 'zod';
-
-/**
- * Display hint types for authorization UI
- */
-export const DisplayHintSchema = z.enum(['link', 'qr', 'code']);
-export type DisplayHint = z.infer<typeof DisplayHintSchema>;
-
-/**
- * Display options for authorization flow
- */
-export const AuthorizationDisplaySchema = z.object({
-  /** Optional title for the authorization screen */
-  title: z.string().optional(),
-
-  /** Hints for how to display authorization (link, QR code, or code) */
-  hint: z.array(DisplayHintSchema).optional(),
-
-  /** Optional short authorization code */
-  authorizationCode: z.string().optional(),
-
-  /** Optional QR code URL */
-  qrUrl: z.string().url().optional(),
-}).passthrough();
-
-export type AuthorizationDisplay = z.infer<typeof AuthorizationDisplaySchema>;
-
-/**
- * NeedsAuthorizationError Schema
- *
- * Error returned when a request requires authorization.
- * Includes a resumeToken and authorizationUrl for the authorization flow.
- */
-export const NeedsAuthorizationErrorSchema = z.object({
-  /** Error code */
-  error: z.literal('needs_authorization'),
-
-  /** Human-readable error message */
-  message: z.string().min(1),
-
-  /** URL for the user to authorize (includes resume token) */
-  authorizationUrl: z.string().url(),
-
-  /** Short-lived resume token for continuing after authorization */
-  resumeToken: z.string().min(1),
-
-  /** Expiration timestamp for the resume token (milliseconds since epoch) */
-  expiresAt: z.number().int().positive(),
-
-  /** Required scopes for authorization */
-  scopes: z.array(z.string()),
-
-  /** Optional display configuration for authorization UI */
-  display: AuthorizationDisplaySchema.optional(),
-
-  /** Optional additional context */
-  context: z.record(z.any()).optional(),
-}).passthrough();
-
-export type NeedsAuthorizationError = z.infer<typeof NeedsAuthorizationErrorSchema>;
-
-/**
- * Generic Error Schema
- *
- * Standard error format for all runtime errors
- */
-export const RuntimeErrorSchema = z.object({
-  /** Error code */
-  error: z.string().min(1),
-
-  /** Human-readable error message */
-  message: z.string().min(1),
-
-  /** Optional error details */
-  details: z.record(z.any()).optional(),
-
-  /** HTTP status code (if applicable) */
-  httpStatus: z.number().int().min(400).max(599).optional(),
-});
-
-export type RuntimeError = z.infer<typeof RuntimeErrorSchema>;
-
-/**
- * Validation Helpers
- */
-
-/**
- * Validate a needs authorization error
- *
- * @param error - The error to validate
- * @returns Validation result
- */
-export function validateNeedsAuthorizationError(error: unknown) {
-  return NeedsAuthorizationErrorSchema.safeParse(error);
-}
-
-/**
- * Check if error is a needs authorization error
- *
- * @param error - The error to check
- * @returns true if it's a needs authorization error
- */
-export function isNeedsAuthorizationError(error: any): error is NeedsAuthorizationError {
-  return error && error.error === 'needs_authorization';
-}
-
-/**
- * Create a needs authorization error
- *
- * @param config - Configuration for the error
- * @returns NeedsAuthorizationError instance
- */
-export function createNeedsAuthorizationError(config: {
-  message: string;
-  authorizationUrl: string;
-  resumeToken: string;
-  expiresAt: number;
-  scopes: string[];
-  display?: AuthorizationDisplay;
-}): NeedsAuthorizationError {
-  return {
-    error: 'needs_authorization',
-    ...config,
-  };
-}
-
-/**
- * Constants
- */
-
-/**
- * Error codes
- */
-export const ERROR_CODES = Object.freeze({
-  NEEDS_AUTHORIZATION: 'needs_authorization',
-  INVALID_TOKEN: 'invalid_token',
-  TOKEN_EXPIRED: 'token_expired',
-  INSUFFICIENT_SCOPE: 'insufficient_scope',
-  INVALID_SIGNATURE: 'invalid_signature',
-  DELEGATION_REVOKED: 'delegation_revoked',
-  CREDENTIAL_REVOKED: 'credential_revoked',
-} as const);
-
-export type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];

package/src/runtime/headers.ts

@@ -1,136 +0,0 @@
-/**
- * Runtime Header Contracts
- *
- * Header contracts for downstream services
- *
- * Related Spec: MCP-I §6
- * Python Reference: Core-Documentation.md
- */
-
-/**
- * Downstream Headers Interface
- *
- * Headers passed to downstream services after verification
- */
-export interface DownstreamHeaders {
-  /** DID of the verified agent */
-  'X-Agent-DID': string;
-
-  /** Optional delegation ID */
-  'X-Delegation-Id'?: string;
-
-  /** Optional delegation chain (format: vc_id>del_id>...) */
-  'X-Delegation-Chain'?: string;
-
-  /** Proof ID for audit trail */
-  'X-MCPI-Proof-Id': string;
-
-  /** Optional CRISP spend info (JSON string: {unit, delta, remaining}) */
-  'X-CRISP-Spend'?: string;
-
-  /** Optional session ID */
-  'X-Session-Id'?: string;
-
-  /** Optional scopes */
-  'X-Scopes'?: string;
-}
-
-/**
- * Header names as constants for type safety
- */
-export const DOWNSTREAM_HEADER_NAMES = Object.freeze({
-  AGENT_DID: 'X-Agent-DID',
-  DELEGATION_ID: 'X-Delegation-Id',
-  DELEGATION_CHAIN: 'X-Delegation-Chain',
-  PROOF_ID: 'X-MCPI-Proof-Id',
-  CRISP_SPEND: 'X-CRISP-Spend',
-  SESSION_ID: 'X-Session-Id',
-  SCOPES: 'X-Scopes',
-} as const);
-
-/**
- * CRISP Spend Info
- *
- * Structure for X-CRISP-Spend header value
- */
-export interface CrispSpendInfo {
-  /** Unit of spending */
-  unit: 'USD' | 'ops' | 'points';
-
-  /** Amount spent in this request */
-  delta?: number;
-
-  /** Remaining budget */
-  remaining?: number;
-}
-
-/**
- * Helper to serialize CRISP spend info to header value
- *
- * @param info - CRISP spend info
- * @returns JSON string for header
- */
-export function serializeCrispSpend(info: CrispSpendInfo): string {
-  return JSON.stringify(info);
-}
-
-/**
- * Helper to parse CRISP spend info from header value
- *
- * @param headerValue - JSON string from header
- * @returns Parsed CRISP spend info or null if invalid
- */
-export function parseCrispSpend(headerValue: string): CrispSpendInfo | null {
-  try {
-    const parsed = JSON.parse(headerValue);
-    if (parsed && typeof parsed.unit === 'string') {
-      return parsed as CrispSpendInfo;
-    }
-    return null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Helper to create downstream headers
- *
- * @param config - Configuration for headers
- * @returns DownstreamHeaders object
- */
-export function createDownstreamHeaders(config: {
-  agentDid: string;
-  proofId: string;
-  delegationId?: string;
-  delegationChain?: string;
-  crispSpend?: CrispSpendInfo;
-  sessionId?: string;
-  scopes?: string[];
-}): DownstreamHeaders {
-  const headers: DownstreamHeaders = {
-    'X-Agent-DID': config.agentDid,
-    'X-MCPI-Proof-Id': config.proofId,
-  };
-
-  if (config.delegationId) {
-    headers['X-Delegation-Id'] = config.delegationId;
-  }
-
-  if (config.delegationChain) {
-    headers['X-Delegation-Chain'] = config.delegationChain;
-  }
-
-  if (config.crispSpend) {
-    headers['X-CRISP-Spend'] = serializeCrispSpend(config.crispSpend);
-  }
-
-  if (config.sessionId) {
-    headers['X-Session-Id'] = config.sessionId;
-  }
-
-  if (config.scopes && config.scopes.length > 0) {
-    headers['X-Scopes'] = config.scopes.join(',');
-  }
-
-  return headers;
-}

package/src/runtime/index.ts

@@ -1,6 +0,0 @@
-/**
- * Runtime Module Exports
- */
-
-export * from './errors.js';
-export * from './headers.js';

package/src/test.ts

@@ -1,143 +0,0 @@
-/**
- * Test infrastructure types and schemas for XMCP-I
- *
- * This module provides types and utilities for testing XMCP-I applications
- * without hitting external services like KTA.
- */
-
-import { z } from "zod";
-
-/**
- * Test environment configuration
- */
-export const TestEnvironmentSchema = z.object({
-  mode: z.literal("test"),
-  seed: z.string().optional(),
-  deterministicKeys: z.boolean().default(true),
-  skipKTACalls: z.boolean().default(true),
-});
-
-export type TestEnvironment = z.infer<typeof TestEnvironmentSchema>;
-
-/**
- * Mock identity configuration for testing
- */
-export const MockIdentitySchema = z.object({
-  did: z.string(),
-  kid: z.string(),
-  privateKey: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 private key (44 characters)"),
-  publicKey: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "Must be a valid base64-encoded Ed25519 public key (44 characters)"),
-  createdAt: z.string(),
-  lastRotated: z.string().optional(),
-});
-
-export type MockIdentity = z.infer<typeof MockIdentitySchema>;
-
-/**
- * Mock delegation status for testing
- */
-export const MockDelegationStatusSchema = z.enum([
-  "active",
-  "revoked",
-  "pending",
-]);
-export type MockDelegationStatus = z.infer<typeof MockDelegationStatusSchema>;
-
-/**
- * Mock KTA failure scenarios for testing
- */
-export const MockKTAFailureTypeSchema = z.enum([
-  "network",
-  "auth",
-  "invalid",
-  "timeout",
-]);
-export type MockKTAFailureType = z.infer<typeof MockKTAFailureTypeSchema>;
-
-/**
- * Mock identity provider configuration
- */
-export const MockIdentityProviderConfigSchema = z.object({
-  identities: z.record(z.string(), MockIdentitySchema),
-  delegations: z.record(z.string(), MockDelegationStatusSchema),
-  ktaFailures: z.array(MockKTAFailureTypeSchema).default([]),
-  deterministicSeed: z.string().optional(),
-});
-
-export type MockIdentityProviderConfig = z.infer<
-  typeof MockIdentityProviderConfigSchema
->;
-
-/**
- * Local verification result for offline testing
- */
-export const LocalVerificationResultSchema = z.object({
-  valid: z.boolean(),
-  did: z.string().optional(),
-  kid: z.string().optional(),
-  signature: z.object({
-    valid: z.boolean(),
-    algorithm: z.string(),
-    error: z.string().optional(),
-  }),
-  proof: z.object({
-    valid: z.boolean(),
-    structure: z.boolean(),
-    timestamps: z.boolean(),
-    hashes: z.boolean(),
-    error: z.string().optional(),
-  }),
-  session: z.object({
-    valid: z.boolean(),
-    expired: z.boolean(),
-    error: z.string().optional(),
-  }),
-  errors: z.array(z.string()).default([]),
-  warnings: z.array(z.string()).default([]),
-});
-
-export type LocalVerificationResult = z.infer<
-  typeof LocalVerificationResultSchema
->;
-
-/**
- * Test DID and Key ID constants
- */
-export const TEST_DIDS = {
-  AGENT_1: "did:test:agent-1",
-  AGENT_2: "did:test:agent-2",
-  VERIFIER_1: "did:test:verifier-1",
-} as const;
-
-export const TEST_KEY_IDS = {
-  KEY_TEST_1: "key-test-1",
-  KEY_TEST_2: "key-test-2",
-  KEY_VERIFIER_1: "key-verifier-1",
-} as const;
-
-/**
- * Test environment detection
- */
-export function isTestEnvironment(): boolean {
-  return process.env.XMCP_ENV === "test";
-}
-
-/**
- * Get test seed from environment or test name
- */
-export function getTestSeed(testName?: string): string {
-  return process.env.XMCP_TEST_SEED || testName || "default-test-seed";
-}
-
-/**
- * Error codes for test infrastructure
- */
-export const TEST_ERROR_CODES = {
-  MOCK_KTA_FAILURE: "XMCP_I_TEST_MOCK_KTA_FAILURE",
-  DETERMINISTIC_KEY_GENERATION_FAILED: "XMCP_I_TEST_DETERMINISTIC_KEY_FAILED",
-  LOCAL_VERIFICATION_FAILED: "XMCP_I_TEST_LOCAL_VERIFICATION_FAILED",
-  INVALID_TEST_CONFIGURATION: "XMCP_I_TEST_INVALID_CONFIG",
-} as const;
-
-export type TestErrorCode =
-  (typeof TEST_ERROR_CODES)[keyof typeof TEST_ERROR_CODES];

package/src/tlkrc/index.ts

@@ -1,5 +0,0 @@
-/**
- * TLKRC Module Exports
- */
-
-export * from './rotation.js';