@kya-os/mcp-i 1.12.2 → 1.12.4

package/dist/runtime/identity.d.ts

@@ -75,8 +75,34 @@ export declare class IdentityManager {
     /**
      * Generate new development identity
      * Requirements: 4.1, 4.4
+     *
+     * @param preserveDid - use this DID instead of minting a fresh
+     *   did:web:localhost:... one. Added for `rotateDevIdentity()`'s benefit
+     *   (a rotation keeps the agent's DID stable by default); every existing
+     *   caller passes no argument and is unaffected.
      */
     private generateDevIdentity;
+    /**
+     * Force-generate a fresh Ed25519 keypair and persist it to
+     * `devIdentityPath`, unconditionally overwriting whatever identity (if
+     * any) is already there. Unlike `ensureIdentity()`, which loads an
+     * existing valid identity rather than replacing it, this always mints a
+     * new one -- the primitive `mcpi keys rotate` needs.
+     *
+     * Deliberately reuses this same jose-based, 32-byte-raw-key generation
+     * path (rather than a second, independent key generator) so a rotated
+     * identity file is always in the one format every other identity path in
+     * this codebase already produces and consumes -- `CLIIdentityFileSchema`
+     * (`packages/contracts/src/cli.ts`) requires exactly 44 base64 characters
+     * (a raw 32-byte key), which the CLI's own `node:crypto`-based DER
+     * keypair (PKCS8/SPKI, `utils/identity-manager.ts`'s `generateKeyPair`)
+     * does not produce -- confirmed by direct inspection, not assumed.
+     *
+     * @param preserveDid - reuse this DID instead of minting a fresh one,
+     *   mirroring `mcpi keys rotate`'s own default of keeping the DID stable
+     *   across a rotation unless `--new-did` is passed.
+     */
+    rotateDevIdentity(preserveDid?: string): Promise<AgentIdentity>;
     /**
      * Generate multibase-encoded key identifier (z-prefix base58btc)
      */

package/dist/runtime/identity.js

@@ -120,8 +120,13 @@ class IdentityManager {
     /**
      * Generate new development identity
      * Requirements: 4.1, 4.4
+     *
+     * @param preserveDid - use this DID instead of minting a fresh
+     *   did:web:localhost:... one. Added for `rotateDevIdentity()`'s benefit
+     *   (a rotation keeps the agent's DID stable by default); every existing
+     *   caller passes no argument and is unaffected.
      */
-    async generateDevIdentity() {
+    async generateDevIdentity(preserveDid) {
         // Generate Ed25519 keypair
         const keyPair = await (0, jose_1.generateKeyPair)("EdDSA", { crv: "Ed25519" });
         // Export keys to JWK format
@@ -133,10 +138,11 @@ class IdentityManager {
         const publicKey = Buffer.from(privateKeyJwk.x, "base64url").toString("base64");
         // Generate multibase-encoded key ID
         const kid = this.generateMultibaseKid(publicKey);
-        // Generate DID (for dev, use localhost)
-        // Extract a short identifier for the DID path (first 8 chars of hash for readability)
+        // Generate DID (for dev, use localhost), unless the caller wants to
+        // keep an existing one. Extract a short identifier for the DID path
+        // (first 8 chars of hash for readability).
         const shortId = (0, crypto_1.createHash)("sha256").update(publicKey).digest("hex").substring(0, 8);
-        const did = `did:web:localhost:3000:agents:${shortId}`;
+        const did = preserveDid ?? `did:web:localhost:3000:agents:${shortId}`;
         const now = new Date().toISOString();
         const identity = {
             did,
@@ -149,6 +155,33 @@ class IdentityManager {
         await this.saveDevIdentity(identity);
         return identity;
     }
+    /**
+     * Force-generate a fresh Ed25519 keypair and persist it to
+     * `devIdentityPath`, unconditionally overwriting whatever identity (if
+     * any) is already there. Unlike `ensureIdentity()`, which loads an
+     * existing valid identity rather than replacing it, this always mints a
+     * new one -- the primitive `mcpi keys rotate` needs.
+     *
+     * Deliberately reuses this same jose-based, 32-byte-raw-key generation
+     * path (rather than a second, independent key generator) so a rotated
+     * identity file is always in the one format every other identity path in
+     * this codebase already produces and consumes -- `CLIIdentityFileSchema`
+     * (`packages/contracts/src/cli.ts`) requires exactly 44 base64 characters
+     * (a raw 32-byte key), which the CLI's own `node:crypto`-based DER
+     * keypair (PKCS8/SPKI, `utils/identity-manager.ts`'s `generateKeyPair`)
+     * does not produce -- confirmed by direct inspection, not assumed.
+     *
+     * @param preserveDid - reuse this DID instead of minting a fresh one,
+     *   mirroring `mcpi keys rotate`'s own default of keeping the DID stable
+     *   across a rotation unless `--new-did` is passed.
+     */
+    async rotateDevIdentity(preserveDid) {
+        const identity = await this.generateDevIdentity(preserveDid);
+        const rotated = { ...identity, lastRotated: identity.createdAt };
+        await this.saveDevIdentity(rotated);
+        this.cachedIdentity = rotated;
+        return rotated;
+    }
     /**
      * Generate multibase-encoded key identifier (z-prefix base58btc)
      */

package/dist/runtime/mcpi-runtime-wrapper.js

@@ -14,6 +14,7 @@ exports.createMCPIRuntime = createMCPIRuntime;
 const mcp_i_runtime_1 = require("@kya-os/mcp-i-runtime");
 const node_providers_1 = require("../providers/node-providers");
 const path_1 = __importDefault(require("path"));
+const config_1 = require("@kya-os/contracts/config");
 /**
  * Convert legacy config to provider-based config
  */
@@ -67,8 +68,9 @@ class MCPINodeRuntimeWrapper extends mcp_i_runtime_1.MCPIRuntimeBase {
             timestampSkewSeconds: coreConfig.session?.timestampSkewSeconds || 120,
         });
         // Instantiate AccessControlApiService if API key is available
-        const apiKey = process.env.AGENTSHIELD_API_KEY;
-        const apiUrl = process.env.AGENTSHIELD_API_URL || "https://kya.vouched.id";
+        const checkpoint = (0, config_1.withCheckpointNames)(process.env);
+        const apiKey = checkpoint.CHECKPOINT_API_KEY;
+        const apiUrl = checkpoint.CHECKPOINT_API_URL || "https://kya.vouched.id";
         if (apiKey) {
             this.accessControlService = new mcp_i_runtime_1.AccessControlApiService({
                 baseUrl: apiUrl,

package/dist/runtime/mcpi-runtime.d.ts

@@ -47,7 +47,7 @@ export interface MCPIRuntimeConfig {
         enabled?: boolean;
         /** Proof batch queue configuration */
         batchQueue?: {
-            /** Proof submission destinations (AgentShield, KTA, etc.) */
+            /** Proof submission destinations (Checkpoint, KTA, etc.) */
             destinations?: Array<{
                 /** Destination type */
                 type: "agentshield" | "kta";
@@ -101,7 +101,7 @@ export interface MCPIRuntimeConfig {
         toolProtections?: ToolProtectionMap;
         /** Local tool protection file path (default: tool-protections.json) */
         toolProtectionsFile?: string | false;
-        /** AgentShield API configuration for fetching tool protections */
+        /** Checkpoint API configuration for fetching tool protections */
         agentShield?: {
             apiUrl: string;
             apiKey?: string;

package/dist/runtime/mcpi-runtime.js

@@ -66,7 +66,7 @@ class MCPIRuntime {
             this.delegationVerifier = (0, delegation_verifier_1.createDelegationVerifier)(config.delegation.verifier);
         }
         // NOTE: Tool protection resolver is created in initialize()
-        // after identity is loaded, because AgentShield API needs the agent DID
+        // after identity is loaded, because Checkpoint API needs the agent DID
     }
     /**
      * Initialize the runtime (async setup)
@@ -176,69 +176,70 @@ class MCPIRuntime {
         if (!this.cachedIdentity) {
             throw new Error("Runtime not initialized - call initialize() first");
         }
-        // PHASE 1 INTERCEPTOR: Check delegation BEFORE executing tool
-        if (this.config.delegation?.enabled && options.requiresDelegation) {
-            if (!this.delegationVerifier) {
-                throw new Error("Delegation verifier not configured");
-            }
-            if (!options.agentDid) {
-                throw new Error("agentDid required when requiresDelegation=true");
-            }
-            const requiredScopes = options.requiredScopes || [];
-            // Build auth handshake config
-            const authConfig = {
-                delegationVerifier: this.delegationVerifier,
-                resumeTokenStore: this.resumeTokenStore,
-                kta: this.config.delegation.authorization?.kta,
-                bouncer: {
-                    authorizationUrl: this.config.delegation.authorization?.authorizationUrl ||
-                        "https://agentshield.example.com/consent",
-                    resumeTokenTtl: this.config.delegation.authorization?.resumeTokenTtl,
-                    minReputationScore: this.config.delegation.authorization?.minReputationScore,
-                    requireAuthForUnknown: this.config.delegation.authorization?.requireAuthForUnknown,
-                },
-                debug: this.config.identity?.environment === "development",
-            };
-            // Verify delegation or return authorization hints
-            const verifyResult = await (0, auth_handshake_1.verifyOrHints)(options.agentDid, requiredScopes, authConfig);
-            // If not authorized, return needs_authorization error
-            if (!verifyResult.authorized) {
-                if (!verifyResult.authError) {
-                    throw new Error('Authorization failed but no authError was provided');
-                }
-                return verifyResult.authError;
-            }
-            // If authorized, capture delegation metadata for outbound header propagation
-            if (verifyResult.delegation) {
-                options.delegationRef = verifyResult.delegation.id;
-                options.delegationChain = (0, mcp_i_core_1.buildChainString)(verifyResult.delegation);
-                options.delegationScopes = options.requiredScopes ?? [];
-                const identity = await this.identityManager.ensureIdentity();
-                (0, request_context_1.setDelegationContextFromIdentity)({
-                    delegationId: options.delegationRef,
-                    delegationChain: options.delegationChain,
-                    delegationScopes: options.delegationScopes,
-                    // JWS-compact DelegationCredential VC from the verified result —
-                    // emitted on KYA-OS-Delegation-Credential when the verifier
-                    // returned a presentable credential.
-                    delegationCredential: verifyResult.credential?.credential_jwt,
-                    identity,
-                });
-            }
-        }
-        const auditInvocation = this.config.auditTrail
-            ? await (0, mcp_i_runtime_1.beginRuntimeToolAudit)(this.config.auditTrail, {
-                toolName: request.method,
-                args: request.params,
-                session: {
-                    ...session,
-                    id: session.sessionId,
-                },
-            })
-            : undefined;
-        // Capture before async boundary — TS narrowing doesn't survive across async callbacks
+        // Isolate verification and delegation setup before either can change a caller's
+        // context. The tool and proof generation then share this call's own store.
         const cachedIdentity = this.cachedIdentity;
         return (0, request_context_1.runWithContext)({ session: session ?? undefined }, async () => {
+            // PHASE 1 INTERCEPTOR: Check delegation BEFORE executing tool
+            if (this.config.delegation?.enabled && options.requiresDelegation) {
+                if (!this.delegationVerifier) {
+                    throw new Error("Delegation verifier not configured");
+                }
+                if (!options.agentDid) {
+                    throw new Error("agentDid required when requiresDelegation=true");
+                }
+                const requiredScopes = options.requiredScopes || [];
+                // Build auth handshake config
+                const authConfig = {
+                    delegationVerifier: this.delegationVerifier,
+                    resumeTokenStore: this.resumeTokenStore,
+                    kta: this.config.delegation.authorization?.kta,
+                    bouncer: {
+                        authorizationUrl: this.config.delegation.authorization?.authorizationUrl ||
+                            "https://agentshield.example.com/consent",
+                        resumeTokenTtl: this.config.delegation.authorization?.resumeTokenTtl,
+                        minReputationScore: this.config.delegation.authorization?.minReputationScore,
+                        requireAuthForUnknown: this.config.delegation.authorization?.requireAuthForUnknown,
+                    },
+                    debug: this.config.identity?.environment === "development",
+                };
+                // Verify delegation or return authorization hints
+                const verifyResult = await (0, auth_handshake_1.verifyOrHints)(options.agentDid, requiredScopes, authConfig);
+                // If not authorized, return needs_authorization error
+                if (!verifyResult.authorized) {
+                    if (!verifyResult.authError) {
+                        throw new Error('Authorization failed but no authError was provided');
+                    }
+                    return verifyResult.authError;
+                }
+                // If authorized, capture delegation metadata for outbound header propagation
+                if (verifyResult.delegation) {
+                    options.delegationRef = verifyResult.delegation.id;
+                    options.delegationChain = (0, mcp_i_core_1.buildChainString)(verifyResult.delegation);
+                    options.delegationScopes = options.requiredScopes ?? [];
+                    const identity = await this.identityManager.ensureIdentity();
+                    (0, request_context_1.setDelegationContextFromIdentity)({
+                        delegationId: options.delegationRef,
+                        delegationChain: options.delegationChain,
+                        delegationScopes: options.delegationScopes,
+                        // JWS-compact DelegationCredential VC from the verified result —
+                        // emitted on KYA-OS-Delegation-Credential when the verifier
+                        // returned a presentable credential.
+                        delegationCredential: verifyResult.credential?.credential_jwt,
+                        identity,
+                    });
+                }
+            }
+            const auditInvocation = this.config.auditTrail
+                ? await (0, mcp_i_runtime_1.beginRuntimeToolAudit)(this.config.auditTrail, {
+                    toolName: request.method,
+                    args: request.params,
+                    session: {
+                        ...session,
+                        id: session.sessionId,
+                    },
+                })
+                : undefined;
             try {
                 // Execute the tool (only if delegation check passed)
                 let data = await toolHandler(request);

package/dist/runtime/proof-batch-queue.d.ts

@@ -1,7 +1,7 @@
 /**
  * Proof Batch Queue
  *
- * Collects proofs in memory and submits them in batches to KTA and AgentShield.
+ * Collects proofs in memory and submits them in batches to KTA and Checkpoint.
  * This prevents blocking tool execution while ensuring proofs are eventually submitted.
  *
  * Performance:
@@ -74,9 +74,9 @@ export declare class KTAProofDestination implements ProofDestination {
     private submitOne;
 }
 /**
- * AgentShield proof submission destination
+ * Checkpoint proof submission destination
  *
- * Submits proofs to AgentShield's /api/v1/bouncer/proofs endpoint
+ * Submits proofs to Checkpoint's /api/v1/bouncer/proofs endpoint
  * with proper authentication and session grouping.
  */
 export declare class AgentShieldProofDestination implements ProofDestination {

package/dist/runtime/proof-batch-queue.js

@@ -2,7 +2,7 @@
 /**
  * Proof Batch Queue
  *
- * Collects proofs in memory and submits them in batches to KTA and AgentShield.
+ * Collects proofs in memory and submits them in batches to KTA and Checkpoint.
  * This prevents blocking tool execution while ensuring proofs are eventually submitted.
  *
  * Performance:
@@ -121,13 +121,13 @@ class KTAProofDestination {
 }
 exports.KTAProofDestination = KTAProofDestination;
 /**
- * AgentShield proof submission destination
+ * Checkpoint proof submission destination
  *
- * Submits proofs to AgentShield's /api/v1/bouncer/proofs endpoint
+ * Submits proofs to Checkpoint's /api/v1/bouncer/proofs endpoint
  * with proper authentication and session grouping.
  */
 class AgentShieldProofDestination {
-    name = "AgentShield";
+    name = "Checkpoint";
     apiUrl;
     apiKey;
     constructor(apiUrl, apiKey) {
@@ -139,13 +139,13 @@ class AgentShieldProofDestination {
             return;
         }
         const proofs = submissions.map((submission) => submission.proof);
-        // Extract session_id from first proof for AgentShield session grouping
-        // AgentShield uses this for analytics and detection monitoring
+        // Extract session_id from first proof for Checkpoint session grouping
+        // Checkpoint uses this for analytics and detection monitoring
         const sessionId = proofs[0]?.meta?.sessionId || "unknown";
-        // AgentShield API format requires delegation_id and session_id wrapper
+        // Checkpoint API format requires delegation_id and session_id wrapper
         const requestBody = {
             delegation_id: null, // null for proofs without delegation context
-            session_id: sessionId, // AgentShield session grouping (same as meta.sessionId)
+            session_id: sessionId, // Checkpoint session grouping (same as meta.sessionId)
             proofs: proofs,
         };
         const response = await fetch(`${this.apiUrl}/api/v1/bouncer/proofs`, {
@@ -161,7 +161,7 @@ class AgentShieldProofDestination {
             const errorBody = await response
                 .text()
                 .catch(() => "Unable to read error body");
-            throw new Error(`AgentShield proof submission failed: ${response.status} ${response.statusText}\n${errorBody}`);
+            throw new Error(`Checkpoint proof submission failed: ${response.status} ${response.statusText}\n${errorBody}`);
         }
     }
 }