HiveAuth MCP Server

Instructions

Implementation Reference

• src/tools/deriveCredential.ts:9-187 (handler)

  Core handler implementation for 'derive_credential' tool. Validates input using DeriveCredentialInputSchema, calls HiveAuth API (/api/derive) with originalCredential and frame for selective disclosure derivation, performs field analysis for privacy summary, generates detailed markdown+JSON output, and falls back to simulation mode if API unavailable.
  export async function deriveCredential(args: any): Promise<CallToolResult> { // Validate and sanitize input const validation = validateAndSanitizeInput(DeriveCredentialInputSchema, args, 'derive_credential'); if (!validation.success) { return createValidationErrorResult(validation.error!); } const data = validation.data!; const { originalCredential, frame, nonce } = data; const HIVEAUTH_API_BASE_URL = process.env.HIVEAUTH_API_BASE_URL || 'http://localhost:3000'; const DERIVE_ENDPOINT = `${HIVEAUTH_API_BASE_URL}/api/derive`; try { console.log(`[DeriveCredential] Starting credential derivation for credential: ${originalCredential.id}`); const payload = { credential: originalCredential, frame, ...(nonce && { nonce }) }; const response = await fetch(DERIVE_ENDPOINT, { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify(payload), }); if (!response.ok) { const errorData = await response.json().catch(() => ({ message: response.statusText })); throw new Error(`Failed to derive credential: ${errorData.message}`); } const result = await response.json(); // Analyze the derivation const originalFields = extractCredentialFields(originalCredential); const derivedFields = extractCredentialFields(result.derivedCredential); const hiddenFields = originalFields.filter(field => !derivedFields.includes(field)); const revealedFields = derivedFields; const summary = [ `🔄 **Credential Derivation Results**`, ``, `• Original Credential ID: ${originalCredential.id || 'Not specified'}`, `• Derived Credential ID: ${result.derivedCredential?.id || 'Generated automatically'}`, `• Derivation Method: ${result.derivationMethod || 'JSON-LD Frame'}`, `• Selective Disclosure: ${hiddenFields.length > 0 ? 'Yes' : 'No'}`, ``, `**📊 Field Analysis:**`, `• Original Fields: ${originalFields.length}`, `• Revealed Fields: ${revealedFields.length}`, `• Hidden Fields: ${hiddenFields.length}`, `• Privacy Level: ${Math.round((hiddenFields.length / originalFields.length) * 100)}% fields hidden`, `` ]; if (revealedFields.length > 0) { summary.push(`**✅ Revealed Fields (${revealedFields.length}):**`); revealedFields.forEach((field, index) => { summary.push(`${index + 1}. ${field}`); }); summary.push(``); } if (hiddenFields.length > 0) { summary.push(`**🔒 Hidden Fields (${hiddenFields.length}):**`); hiddenFields.forEach((field, index) => { summary.push(`${index + 1}. ${field} (protected by selective disclosure)`); }); summary.push(``); } // Proof information if (result.derivedCredential?.proof) { const proof = result.derivedCredential.proof; summary.push(`**🔐 Derived Proof Information:**`); summary.push(`• Proof Type: ${proof.type || 'Unknown'}`); summary.push(`• Verification Method: ${proof.verificationMethod || 'Not specified'}`); summary.push(`• Created: ${proof.created || 'Not specified'}`); summary.push(`• Purpose: ${proof.proofPurpose || 'assertionMethod'}`); if (nonce) { summary.push(`• Nonce: ${nonce} (replay protection enabled)`); } summary.push(``); } // Derivation integrity checks summary.push(`**🛡️ Integrity Verification:**`); summary.push(`• Original signature preserved: ${result.signaturePreserved ? '✅ Yes' : '❌ No'}`); summary.push(`• Derivation proof valid: ${result.derivationValid ? '✅ Yes' : '❌ No'}`); summary.push(`• JSON-LD frame applied: ${result.frameApplied ? '✅ Yes' : '❌ No'}`); if (result.chainedCredential) { summary.push(`• Credential chaining: ✅ Derived credential properly chained`); } // Usage recommendations summary.push(``); summary.push(`**💡 Usage Recommendations:**`); if (hiddenFields.length > 0) { summary.push(`• Use this derived credential for privacy-sensitive scenarios`); summary.push(`• Original credential remains unchanged and can be used separately`); } if (nonce) { summary.push(`• Nonce provides replay protection - credential is single-use`); } summary.push(`• Verify derived credential independently before accepting`); summary.push(`• Consider the revealed fields sufficient for your use case`); return { content: [ { type: 'text', text: summary.join('\n') }, { type: 'text', text: `\`\`\`json\n${JSON.stringify({ derivationSummary: { originalCredentialId: originalCredential.id, derivedCredentialId: result.derivedCredential?.id, originalFields: originalFields.length, revealedFields: revealedFields.length, hiddenFields: hiddenFields.length, privacyLevel: Math.round((hiddenFields.length / originalFields.length) * 100), frameApplied: result.frameApplied, signaturePreserved: result.signaturePreserved }, derivedCredential: result.derivedCredential, derivationProof: result.derivationProof }, null, 2)}\n\`\`\`` } ] }; } catch (error: any) { // Check if it's a network error (HiveAuth API not available) if (error.message.includes('fetch failed') || error.message.includes('ECONNREFUSED')) { return { content: [ { type: 'text', text: `🔄 **Credential Derivation (Simulation Mode)**\n\n` + `Since the HiveAuth API is not available, here's what the credential derivation would accomplish:\n\n` + `**Input Analysis:**\n` + `• Original Credential ID: ${originalCredential.id || 'Not specified'}\n` + `• Original Credential Type: ${originalCredential.type?.join(', ') || 'Unknown'}\n` + `• Derivation Frame: ${Object.keys(frame).length} frame properties specified\n` + `• Nonce: ${nonce ? 'Provided (replay protection)' : 'Not provided'}\n\n` + `**Expected Derivation Results:**\n` + `• New credential with selective disclosure applied\n` + `• Original signature preserved in derived proof\n` + `• Only specified fields revealed according to frame\n` + `• Cryptographic link to original credential maintained\n\n` + `**Privacy Benefits:**\n` + `• Sensitive fields hidden while maintaining verifiability\n` + `• Zero-knowledge proof of credential possession\n` + `• Granular control over revealed information\n\n` + `**To enable full derivation:** Ensure HiveAuth API is running at ${HIVEAUTH_API_BASE_URL}` } ] }; } return { content: [ { type: 'text', text: `Failed to derive credential: ${error.message}` } ], isError: true }; } }
• src/schemas/toolSchemas.ts:140-144 (schema)

  Zod schema defining the input structure for derive_credential: requires originalCredential (CredentialSchema), frame (JSON-LD object), optional nonce (string for replay protection).
  export const DeriveCredentialInputSchema = z.object({ originalCredential: CredentialSchema, frame: z.object({}).passthrough().describe('JSON-LD frame for selective disclosure'), nonce: z.string().optional().describe('Nonce for derived proof') });
• src/utils/schemaConverter.ts:56-60 (registration)

  MCP tool registration definition, mapping 'derive_credential' name to its description and input schema (converted to JSON Schema via zodToJsonSchema for MCP protocol compliance).
  { name: 'derive_credential', description: 'Derive credentials with selective disclosure using JSON-LD frames. Supports credential chaining and zero-knowledge proofs for privacy-preserving presentations.', inputSchema: TOOL_SCHEMAS.derive_credential },
• src/index.ts:107-108 (registration)

  Runtime tool dispatch in main server switch statement, routing 'derive_credential' calls to the deriveCredential handler function.
  case 'derive_credential': return await deriveCredential(args);
• src/tools/deriveCredential.ts:192-214 (helper)

  Utility helper to recursively extract claim field paths from a credential (excluding metadata like @context, id, type, proof) for deriving revealed/hidden fields in derivation analysis.
  function extractCredentialFields(credential: any): string[] { const fields: string[] = []; function extractFromObject(obj: any, prefix = ''): void { if (!obj || typeof obj !== 'object') return; for (const [key, value] of Object.entries(obj)) { const fieldPath = prefix ? `${prefix}.${key}` : key; // Skip metadata fields if (['@context', 'id', 'type', 'proof'].includes(key)) continue; if (value && typeof value === 'object' && !Array.isArray(value)) { extractFromObject(value, fieldPath); } else { fields.push(fieldPath); } } } extractFromObject(credential); return fields; }