@kya-os/mcp 1.2.0

package/dist/utils/did-helpers.js

@@ -0,0 +1,211 @@
+/**
+ * DID Validation and Helper Utilities
+ *
+ * Centralized utilities for DID validation, normalization, and handling.
+ * Promotes DRY principle and consistency across the codebase.
+ *
+ * @package @kya-os/mcp/utils
+ */
+import { base58Encode } from "./base58.js";
+/**
+ * Check if a string is a valid DID format
+ *
+ * @param did - String to validate
+ * @returns true if string starts with "did:"
+ *
+ * @example
+ * ```typescript
+ * isValidDid("did:key:z6Mk...") // true
+ * isValidDid("not-a-did") // false
+ * ```
+ */
+export function isValidDid(did) {
+    return typeof did === "string" && did.startsWith("did:");
+}
+/**
+ * Get the DID method from a DID string
+ *
+ * @param did - DID string
+ * @returns DID method (e.g., "key", "web") or null if invalid
+ *
+ * @example
+ * ```typescript
+ * getDidMethod("did:key:z6Mk...") // "key"
+ * getDidMethod("did:web:example.com") // "web"
+ * getDidMethod("invalid") // null
+ * ```
+ */
+export function getDidMethod(did) {
+    if (!isValidDid(did)) {
+        return null;
+    }
+    const match = did.match(/^did:([^:]+):/);
+    return match?.[1] ?? null;
+}
+/**
+ * Normalize a DID string (trim whitespace)
+ *
+ * @param did - DID string to normalize
+ * @returns Normalized DID string
+ *
+ * @example
+ * ```typescript
+ * normalizeDid("  did:key:z6Mk...  ") // "did:key:z6Mk..."
+ * ```
+ */
+export function normalizeDid(did) {
+    return did.trim();
+}
+/**
+ * Compare two DIDs for equality (case-sensitive)
+ *
+ * @param did1 - First DID
+ * @param did2 - Second DID
+ * @returns true if DIDs are equal (after normalization)
+ *
+ * @example
+ * ```typescript
+ * compareDids("did:key:z6Mk...", "did:key:z6Mk...") // true
+ * compareDids("did:key:z6Mk...", "did:web:example.com") // false
+ * ```
+ */
+export function compareDids(did1, did2) {
+    return normalizeDid(did1) === normalizeDid(did2);
+}
+/**
+ * Extract server DID from config (supports both old and new field names)
+ *
+ * Supports backward compatibility by reading both `serverDid` and deprecated `agentDid`.
+ * Prefers `serverDid` if both are present.
+ *
+ * @param config - Config object with identity field
+ * @returns Server DID string
+ * @throws Error if neither serverDid nor agentDid is configured
+ *
+ * @example
+ * ```typescript
+ * // New config
+ * getServerDid({ identity: { serverDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Old config (backward compatibility)
+ * getServerDid({ identity: { agentDid: "did:web:example.com" } }) // "did:web:example.com"
+ *
+ * // Prefers serverDid over agentDid
+ * getServerDid({ identity: { serverDid: "new", agentDid: "old" } }) // "new"
+ * ```
+ */
+export function getServerDid(config) {
+    const serverDid = config.identity.serverDid || config.identity.agentDid;
+    if (!serverDid) {
+        throw new Error("Server DID not configured");
+    }
+    return serverDid;
+}
+/**
+ * Extract agent ID from DID
+ *
+ * The agent ID is the last component of the DID.
+ *
+ * @param did - DID string
+ * @returns Agent ID (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentId("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentId("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * extractAgentId("did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK") // "z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK"
+ * ```
+ */
+export function extractAgentId(did) {
+    const parts = did.split(':');
+    // split() always returns at least one element
+    return parts[parts.length - 1] ?? did;
+}
+/**
+ * Extract agent slug from DID
+ *
+ * Agent slug is the same as agent ID - the last component of the DID.
+ * For DID format: did:web:example.com:agents:my-agent
+ * Returns: my-agent
+ *
+ * @param did - DID string
+ * @returns Agent slug (last component of DID)
+ *
+ * @example
+ * ```typescript
+ * extractAgentSlug("did:web:example.com:agents:my-agent") // "my-agent"
+ * extractAgentSlug("did:web:localhost:3000:agents:12912feb") // "12912feb"
+ * ```
+ */
+export function extractAgentSlug(did) {
+    return extractAgentId(did);
+}
+/**
+ * Ed25519 multicodec prefix for did:key encoding
+ * As per https://w3c-ccg.github.io/did-method-key/
+ */
+const ED25519_MULTICODEC_PREFIX = new Uint8Array([0xed, 0x01]);
+/**
+ * Generate a did:key from Ed25519 public key bytes
+ *
+ * Following spec: https://w3c-ccg.github.io/did-method-key/
+ * Format: did:key:z<multibase-base58btc(<multicodec-ed25519-pub><publicKey>)>
+ *
+ * @param publicKeyBytes - Ed25519 public key as Uint8Array (32 bytes)
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKey = new Uint8Array(32); // 32-byte Ed25519 public key
+ * const did = generateDidKeyFromBytes(publicKey);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export function generateDidKeyFromBytes(publicKeyBytes) {
+    // Combine multicodec prefix + public key
+    const multicodecKey = new Uint8Array(ED25519_MULTICODEC_PREFIX.length + publicKeyBytes.length);
+    multicodecKey.set(ED25519_MULTICODEC_PREFIX);
+    multicodecKey.set(publicKeyBytes, ED25519_MULTICODEC_PREFIX.length);
+    // Base58-btc encode and add multibase prefix 'z'
+    const base58Encoded = base58Encode(multicodecKey);
+    return `did:key:z${base58Encoded}`;
+}
+/**
+ * Generate a did:key from base64-encoded Ed25519 public key
+ *
+ * Convenience wrapper around generateDidKeyFromBytes for base64-encoded keys.
+ *
+ * @param publicKeyBase64 - Ed25519 public key as base64 string
+ * @returns did:key string
+ *
+ * @example
+ * ```typescript
+ * const publicKeyBase64 = "...base64 encoded key...";
+ * const did = generateDidKeyFromBase64(publicKeyBase64);
+ * // did = "did:key:z6Mk..."
+ * ```
+ */
+export function generateDidKeyFromBase64(publicKeyBase64) {
+    // Decode base64 to bytes
+    const publicKeyBytes = Uint8Array.from(atob(publicKeyBase64), (c) => c.charCodeAt(0));
+    return generateDidKeyFromBytes(publicKeyBytes);
+}
+/**
+ * Get the spec-compliant fragment identifier for a did:key DID.
+ *
+ * Per the did:key spec (W3C CCG), the fragment equals the multibase-encoded
+ * public key value (the DID-specific-id). For example:
+ *   did:key:z6MkABC... → z6MkABC...
+ *
+ * @see https://w3c-ccg.github.io/did-key-spec/#document-creation-algorithm
+ * @param did - A did:key DID string
+ * @returns The fragment identifier (multibase value), or 'keys-1' as fallback for non-did:key
+ */
+export function didKeyFragment(did) {
+    if (did.startsWith('did:key:')) {
+        return did.slice('did:key:'.length);
+    }
+    // Fallback for non-did:key methods
+    return 'keys-1';
+}
+//# sourceMappingURL=did-helpers.js.map

package/dist/utils/did-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"did-helpers.js","sourceRoot":"","sources":["../../src/utils/did-helpers.ts"],"names":[],"mappings":"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"}

package/dist/utils/ed25519-constants.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Ed25519 Key Format Constants
+ *
+ * DER-encoded headers for Ed25519 key formats per RFC 8410 and RFC 5958.
+ */
+/**
+ * DER-encoded PKCS#8 header for Ed25519 private keys (RFC 8410 §7, RFC 5958).
+ * Prepended to the 32-byte Ed25519 seed to form a valid PKCS#8 private key.
+ */
+export declare const ED25519_PKCS8_DER_HEADER: Uint8Array<ArrayBuffer>;
+/**
+ * DER-encoded SPKI header for Ed25519 public keys (RFC 8410 §4).
+ * The 32-byte public key follows after this header.
+ */
+export declare const ED25519_SPKI_DER_HEADER_LENGTH = 12;
+/** Ed25519 raw key size in bytes */
+export declare const ED25519_KEY_SIZE = 32;
+//# sourceMappingURL=ed25519-constants.d.ts.map

package/dist/utils/ed25519-constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519-constants.d.ts","sourceRoot":"","sources":["../../src/utils/ed25519-constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,eAAO,MAAM,wBAAwB,yBAGnC,CAAC;AAEH;;;GAGG;AACH,eAAO,MAAM,8BAA8B,KAAK,CAAC;AAEjD,oCAAoC;AACpC,eAAO,MAAM,gBAAgB,KAAK,CAAC"}

package/dist/utils/ed25519-constants.js

@@ -0,0 +1,21 @@
+/**
+ * Ed25519 Key Format Constants
+ *
+ * DER-encoded headers for Ed25519 key formats per RFC 8410 and RFC 5958.
+ */
+/**
+ * DER-encoded PKCS#8 header for Ed25519 private keys (RFC 8410 §7, RFC 5958).
+ * Prepended to the 32-byte Ed25519 seed to form a valid PKCS#8 private key.
+ */
+export const ED25519_PKCS8_DER_HEADER = new Uint8Array([
+    0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05,
+    0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]);
+/**
+ * DER-encoded SPKI header for Ed25519 public keys (RFC 8410 §4).
+ * The 32-byte public key follows after this header.
+ */
+export const ED25519_SPKI_DER_HEADER_LENGTH = 12;
+/** Ed25519 raw key size in bytes */
+export const ED25519_KEY_SIZE = 32;
+//# sourceMappingURL=ed25519-constants.js.map

package/dist/utils/ed25519-constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ed25519-constants.js","sourceRoot":"","sources":["../../src/utils/ed25519-constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,UAAU,CAAC;IACrD,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;IACxC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI;CACrD,CAAC,CAAC;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAAG,EAAE,CAAC;AAEjD,oCAAoC;AACpC,MAAM,CAAC,MAAM,gBAAgB,GAAG,EAAE,CAAC"}

package/dist/utils/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+export { ED25519_PKCS8_DER_HEADER, ED25519_SPKI_DER_HEADER_LENGTH, ED25519_KEY_SIZE, } from './ed25519-constants.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/dist/utils/index.js

@@ -0,0 +1,5 @@
+/**
+ * Utility exports
+ */
+export { ED25519_PKCS8_DER_HEADER, ED25519_SPKI_DER_HEADER_LENGTH, ED25519_KEY_SIZE, } from './ed25519-constants.js';
+//# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,wBAAwB,EACxB,8BAA8B,EAC9B,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}

package/package.json

@@ -0,0 +1,115 @@
+{
+  "name": "@kya-os/mcp",
+  "version": "1.2.0",
+  "description": "Core library for MCP-I \u2014 delegation, proof, and session primitives for Model Context Protocol Identity",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./delegation": {
+      "types": "./dist/delegation/index.d.ts",
+      "default": "./dist/delegation/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "default": "./dist/auth/index.js"
+    },
+    "./proof": {
+      "types": "./dist/proof/index.d.ts",
+      "default": "./dist/proof/index.js"
+    },
+    "./session": {
+      "types": "./dist/session/index.d.ts",
+      "default": "./dist/session/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers/index.d.ts",
+      "default": "./dist/providers/index.js"
+    },
+    "./logging": {
+      "types": "./dist/logging/index.d.ts",
+      "default": "./dist/logging/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/protocol.d.ts",
+      "default": "./dist/types/protocol.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "default": "./dist/middleware/index.js"
+    },
+    "./schemas/*.json": "./schemas/*.json",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build && npm run test",
+    "demo": "bash scripts/demo.sh",
+    "example:server": "npx tsx examples/node-server/server.ts",
+    "example:inspector": "npx @modelcontextprotocol/inspector npx tsx examples/node-server/server.ts --stdio"
+  },
+  "dependencies": {
+    "jose": "^5.6.3",
+    "json-canonicalize": "^2.0.0",
+    "zod": "^4.3.6"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@kya-os/consent": "^0.1.37",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "@types/express": "^5.0.6",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^8.57.0",
+    "@typescript-eslint/parser": "^8.57.0",
+    "@vitest/coverage-v8": "^2.0.0",
+    "commander": "^14.0.3",
+    "eslint": "^10.0.3",
+    "express": "^5.2.1",
+    "typescript": "^5.5.3",
+    "typescript-eslint": "^8.57.0",
+    "vitest": "^2.0.0"
+  },
+  "keywords": [
+    "mcp-i",
+    "mcp",
+    "delegation",
+    "verifiable-credentials",
+    "did",
+    "protocol",
+    "identity",
+    "dif"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/modelcontextprotocol-identity/mcp-i-core"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/schemas/README.md

@@ -0,0 +1,117 @@
+# MCP-I JSON Schemas
+
+This directory contains JSON Schema definitions for the core MCP-I (Model Context Protocol - Identity) protocol messages.
+
+## Schemas
+
+| Schema | Description |
+|--------|-------------|
+| [handshake-request.json](./handshake-request.json) | Client-initiated session establishment request |
+| [handshake-response.json](./handshake-response.json) | Server response with session context |
+| [delegation-credential.json](./delegation-credential.json) | W3C Verifiable Credential for delegations |
+| [detached-proof.json](./detached-proof.json) | Cryptographic proof for tool request/response |
+| [well-known-mcpi.json](./well-known-mcpi.json) | Service discovery document |
+
+## Usage
+
+### Validation with Node.js (Ajv)
+
+```javascript
+import Ajv from 'ajv';
+import addFormats from 'ajv-formats';
+import handshakeRequestSchema from './schemas/handshake-request.json';
+
+const ajv = new Ajv({ strict: true });
+addFormats(ajv);
+
+const validate = ajv.compile(handshakeRequestSchema);
+
+const request = {
+  nonce: 'k7Hy9mNpQrStUvWxYz01Aa',
+  audience: 'did:web:example.com',
+  timestamp: Math.floor(Date.now() / 1000),
+  agentDid: 'did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK'
+};
+
+if (validate(request)) {
+  console.log('Valid handshake request');
+} else {
+  console.error('Validation errors:', validate.errors);
+}
+```
+
+### Validation with Python (jsonschema)
+
+```python
+import json
+from jsonschema import validate, ValidationError
+
+with open('schemas/handshake-request.json') as f:
+    schema = json.load(f)
+
+request = {
+    "nonce": "k7Hy9mNpQrStUvWxYz01Aa",
+    "audience": "did:web:example.com",
+    "timestamp": 1710268800
+}
+
+try:
+    validate(instance=request, schema=schema)
+    print("Valid handshake request")
+except ValidationError as e:
+    print(f"Validation error: {e.message}")
+```
+
+### Schema References
+
+All schemas use JSON Schema draft 2020-12 and are published at:
+
+```
+https://schema.modelcontextprotocol-identity.io/xmcp-i/{category}/{schema-name}.v1.0.0.json
+```
+
+Schemas can reference each other using `$ref`. For example, the delegation credential schema references shared definitions for constraints and proof structures.
+
+## Protocol Flow
+
+```
+┌────────┐                          ┌────────┐
+│ Client │                          │ Server │
+└───┬────┘                          └───┬────┘
+    │                                   │
+    │  GET /.well-known/mcpi            │
+    │──────────────────────────────────>│
+    │  (well-known-mcpi.json)           │
+    │<──────────────────────────────────│
+    │                                   │
+    │  POST /handshake                  │
+    │  (handshake-request.json)         │
+    │──────────────────────────────────>│
+    │  (handshake-response.json)        │
+    │<──────────────────────────────────│
+    │                                   │
+    │  POST /tools/{method}             │
+    │  + X-Session-Id header            │
+    │──────────────────────────────────>│
+    │  Response + detached-proof.json   │
+    │<──────────────────────────────────│
+    │                                   │
+```
+
+## Specification Reference
+
+These schemas implement types defined in the [MCP-I Specification](../SPEC.md):
+
+- **Handshake**: SPEC.md §4.5–4.9
+- **Delegation Credentials**: SPEC.md §4.1–4.2
+- **Detached Proofs**: SPEC.md §5
+- **Discovery**: SPEC.md §14 (Transport Binding)
+
+## Contributing
+
+When modifying schemas:
+
+1. Ensure backward compatibility or increment the schema version
+2. Update the `examples` array with valid instances
+3. Run validation tests against the examples
+4. Update this README if adding new schemas