devutils-mcp-server

Instructions

Implementation Reference

• src/tools/jwt.ts:67-142 (handler)

  Implementation of the jwt_validate tool handler, which performs structural validation on a JWT, including checking its format, Base64URL encoding, JSON validity, and expiration, without verifying the signature.

  server.tool(
    "jwt_validate",
    "Validate the structure of a JWT. Checks format, Base64URL encoding, JSON validity, and expiration status. Does NOT verify the cryptographic signature.",
    { token: z.string().describe("The JWT string to validate") },
    async ({ token }) => {
      const issues: string[] = [];
      const checks: Record<string, boolean> = {};
  
      const parts = token.split(".");
      checks["has_three_parts"] = parts.length === 3;
  
      if (parts.length !== 3) {
        issues.push(`Expected 3 parts, got ${parts.length}`);
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ valid: false, checks, issues }, null, 2),
            },
          ],
        };
      }
  
      const decodeBase64Url = (str: string): string => {
        const base64 = str.replace(/-/g, "+").replace(/_/g, "/");
        const padded = base64 + "=".repeat((4 - (base64.length % 4)) % 4);
        return Buffer.from(padded, "base64").toString("utf-8");
      };
  
      // Check header
      try {
        const header = JSON.parse(decodeBase64Url(parts[0]));
        checks["valid_header_json"] = true;
        checks["has_alg"] = "alg" in header;
        if (!("alg" in header)) issues.push("Header missing 'alg' field");
      } catch {
        checks["valid_header_json"] = false;
        issues.push("Header is not valid Base64URL-encoded JSON");
      }
  
      // Check payload
      try {
        const payload = JSON.parse(decodeBase64Url(parts[1]));
        checks["valid_payload_json"] = true;
  
        // Check expiration
        if (payload.exp) {
          const now = Math.floor(Date.now() / 1000);
          checks["not_expired"] = payload.exp > now;
          if (payload.exp <= now) {
            issues.push(
              `Token expired at ${new Date(payload.exp * 1000).toISOString()}`
            );
          }
        }
      } catch {
        checks["valid_payload_json"] = false;
        issues.push("Payload is not valid Base64URL-encoded JSON");
      }
  
      // Check signature exists
      checks["has_signature"] = parts[2].length > 0;
      if (parts[2].length === 0) issues.push("Signature is empty");
  
      const valid = issues.length === 0;
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({ valid, checks, issues }, null, 2),
          },
        ],
      };
    }
  );