HiveAuth MCP Server

Instructions

Implementation Reference

• src/tools/refreshCredential.ts:9-221 (handler)

  Main handler function executing the refresh_credential tool. Validates input, calls HiveAuth refresh API, compares old/new credentials, generates comprehensive markdown summary with validity analysis, security info, and JSON output.

  export async function refreshCredential(args: any): Promise<CallToolResult> {
    // Validate and sanitize input
    const validation = validateAndSanitizeInput(RefreshCredentialInputSchema, args, 'refresh_credential');
    
    if (!validation.success) {
      return createValidationErrorResult(validation.error!);
    }
  
    const data = validation.data!;
    const { credentialId, refreshService } = data;
  
    const HIVEAUTH_API_BASE_URL = process.env.HIVEAUTH_API_BASE_URL || 'http://localhost:3000';
    const REFRESH_ENDPOINT = `${HIVEAUTH_API_BASE_URL}/api/refresh`;
  
    try {
      console.log(`[RefreshCredential] Starting credential refresh for: ${credentialId}`);
  
      const payload = {
        credentialId,
        ...(refreshService && { refreshService })
      };
  
      const response = await fetch(REFRESH_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 refresh credential: ${errorData.message}`);
      }
  
      const result = await response.json();
  
      // Analyze the refresh operation
      const oldCredential = result.originalCredential;
      const newCredential = result.refreshedCredential;
      const refreshInfo = result.refreshInfo || {};
  
      const summary = [
        `🔄 **Credential Refresh Results**`,
        ``,
        `• Original Credential ID: ${credentialId}`,
        `• New Credential ID: ${newCredential?.id || 'Generated automatically'}`,
        `• Refresh Method: ${refreshInfo.method || 'W3C Credential Refresh'}`,
        `• Refresh Service: ${refreshInfo.serviceEndpoint || refreshService || 'Auto-discovered'}`,
        `• Refresh Status: ${result.success ? '✅ Successful' : '❌ Failed'}`,
        ``
      ];
  
      if (result.success && oldCredential && newCredential) {
        // Compare expiration dates
        const oldExpiry = oldCredential.expirationDate || oldCredential.validUntil;
        const newExpiry = newCredential.expirationDate || newCredential.validUntil;
        
        summary.push(`**📅 Validity Period Comparison:**`);
        if (oldExpiry) {
          summary.push(`• Original Expiry: ${oldExpiry}`);
          const wasExpired = new Date(oldExpiry) < new Date();
          summary.push(`• Original Status: ${wasExpired ? '❌ Expired' : '⚠️ Expiring soon'}`);
        } else {
          summary.push(`• Original Expiry: No expiration date set`);
        }
        
        if (newExpiry) {
          summary.push(`• New Expiry: ${newExpiry}`);
          const timeUntilExpiry = new Date(newExpiry).getTime() - new Date().getTime();
          const daysUntilExpiry = Math.ceil(timeUntilExpiry / (1000 * 60 * 60 * 24));
          summary.push(`• New Status: ✅ Valid for ${daysUntilExpiry} more days`);
        } else {
          summary.push(`• New Expiry: No expiration date (indefinite validity)`);
        }
        summary.push(``);
  
        // Compare credential content
        summary.push(`**🔍 Content Comparison:**`);
        const contentChanges = compareCredentialContent(oldCredential, newCredential);
        if (contentChanges.length === 0) {
          summary.push(`• Content: ✅ Unchanged (only validity period updated)`);
        } else {
          summary.push(`• Content: ⚠️ ${contentChanges.length} changes detected`);
          contentChanges.forEach((change, index) => {
            summary.push(`  ${index + 1}. ${change}`);
          });
        }
        summary.push(``);
  
        // Issuer and signature information
        summary.push(`**🔐 Security Information:**`);
        summary.push(`• Original Issuer: ${getIssuerInfo(oldCredential)}`);
        summary.push(`• New Issuer: ${getIssuerInfo(newCredential)}`);
        summary.push(`• Issuer Consistency: ${getIssuerInfo(oldCredential) === getIssuerInfo(newCredential) ? '✅ Same issuer' : '⚠️ Different issuer'}`);
        
        if (newCredential.proof) {
          summary.push(`• New Signature: ✅ Fresh cryptographic signature`);
          summary.push(`• Proof Type: ${newCredential.proof.type || 'Unknown'}`);
        }
        summary.push(``);
  
        // Refresh service information
        if (refreshInfo.serviceDiscovered) {
          summary.push(`**🔎 Service Discovery:**`);
          summary.push(`• Service Discovery: ✅ Automatic discovery successful`);
          summary.push(`• Discovered Endpoint: ${refreshInfo.serviceEndpoint}`);
          summary.push(`• Discovery Method: ${refreshInfo.discoveryMethod || 'DID Document'}`);
          summary.push(``);
        }
  
        // Chain of trust
        if (result.trustChain) {
          summary.push(`**🔗 Trust Chain:**`);
          summary.push(`• Original credential linked: ✅ Cryptographic reference maintained`);
          summary.push(`• Chain integrity: ${result.trustChain.valid ? '✅ Valid' : '❌ Broken'}`);
          summary.push(`• Refresh authorization: ${result.trustChain.authorized ? '✅ Authorized' : '❌ Unauthorized'}`);
          summary.push(``);
        }
      } else if (!result.success) {
        summary.push(`**❌ Refresh Failed:**`);
        summary.push(`• Reason: ${result.error || 'Unknown error'}`);
        if (result.retryable) {
          summary.push(`• Retry Possible: ✅ Yes, try again later`);
          summary.push(`• Suggested Retry: ${result.retryAfter || 'No specific time suggested'}`);
        } else {
          summary.push(`• Retry Possible: ❌ No, manual intervention required`);
        }
        summary.push(``);
      }
  
      // Usage recommendations
      summary.push(`**💡 Next Steps:**`);
      if (result.success) {
        summary.push(`• Replace the original credential with the refreshed version`);
        summary.push(`• Update any stored references to use the new credential ID`);
        summary.push(`• Verify the refreshed credential independently`);
        summary.push(`• Set up monitoring for the new expiration date`);
        if (result.originalCredential) {
          summary.push(`• Consider revoking the original credential if policy requires it`);
        }
      } else {
        summary.push(`• Check credential refresh service availability`);
        summary.push(`• Verify the credential is eligible for refresh`);
        summary.push(`• Contact the issuer if automatic refresh fails`);
        summary.push(`• Consider manual credential renewal process`);
      }
  
      return {
        content: [
          {
            type: 'text',
            text: summary.join('\n')
          },
          {
            type: 'text',
            text: `\`\`\`json\n${JSON.stringify({
              refreshSummary: {
                credentialId,
                success: result.success,
                refreshMethod: refreshInfo.method,
                serviceEndpoint: refreshInfo.serviceEndpoint,
                originalExpiry: oldCredential?.expirationDate || oldCredential?.validUntil,
                newExpiry: newCredential?.expirationDate || newCredential?.validUntil,
                contentChanges: result.success ? compareCredentialContent(oldCredential, newCredential).length : 0
              },
              refreshedCredential: result.success ? newCredential : null,
              refreshInfo: refreshInfo
            }, 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 Refresh (Simulation Mode)**\n\n` +
                    `Since the HiveAuth API is not available, here's what the credential refresh would accomplish:\n\n` +
                    `**Input Analysis:**\n` +
                    `• Credential ID: ${credentialId}\n` +
                    `• Refresh Service: ${refreshService || 'Auto-discovery from credential'}\n\n` +
                    `**Expected Refresh Process:**\n` +
                    `• Locate credential by ID in the system\n` +
                    `• Check expiration status and refresh eligibility\n` +
                    `• Discover or use specified refresh service endpoint\n` +
                    `• Request new credential with extended validity period\n` +
                    `• Maintain credential content while updating temporal properties\n` +
                    `• Generate fresh cryptographic signatures\n\n` +
                    `**W3C Credential Refresh Benefits:**\n` +
                    `• Automated credential lifecycle management\n` +
                    `• Seamless validity period extension\n` +
                    `• Maintains trust chain and cryptographic integrity\n` +
                    `• Reduces manual intervention for routine renewals\n\n` +
                    `**To enable full refresh:** Ensure HiveAuth API is running at ${HIVEAUTH_API_BASE_URL}`
            }
          ]
        };
      }
  
      return {
        content: [
          {
            type: 'text',
            text: `Failed to refresh credential: ${error.message}`
          }
        ],
        isError: true
      };
    }
  }

• src/schemas/toolSchemas.ts:146-149 (schema)

  Zod schema defining the input parameters for the refresh_credential tool: credentialId (required string) and optional refreshService URL.

  export const RefreshCredentialInputSchema = z.object({
    credentialId: z.string().min(1, 'Credential ID is required'),
    refreshService: z.string().url('Refresh service URL must be valid').optional()
  });

• src/utils/schemaConverter.ts:62-64 (registration)

  Tool registration in TOOL_DEFINITIONS array, converted to MCP Tool via createMCPTools() for listing available tools.

  name: 'refresh_credential',
  description: 'Refresh expiring or expired credentials using W3C Credential Refresh specification. Supports automatic service discovery and credential lifecycle management.',
  inputSchema: TOOL_SCHEMAS.refresh_credential

• src/index.ts:110-111 (registration)

  Dispatch registration in the MCP server request handler switch statement, mapping tool name to handler execution.

  case 'refresh_credential':
    return await refreshCredential(args);

• src/schemas/toolSchemas.ts:187-187 (schema)

  Schema registration in TOOL_SCHEMAS lookup object used by schemaConverter.ts.

  refresh_credential: RefreshCredentialInputSchema,