rbbcode 0.1.2 → 0.1.3

data/README

@@ -4,13 +4,13 @@ RbbCode validates and cleans input. It supports customizable schemas so you can
 
 Example usage:
 
-require 'rubygems'
-require 'rbbcode'
-
-bb_code = 'This is [b]bold[/b] text'
-parser = RbbCode::Parser.new
-html = parser.parse(bb_code)
-# => '<p>This is <strong>bold</strong> text</p>'
+  require 'rubygems'
+  require 'rbbcode'
+  
+  bb_code = 'This is [b]bold[/b] text'
+  parser = RbbCode::Parser.new
+  html = parser.parse(bb_code)
+  # => '<p>This is <strong>bold</strong> text</p>'
 
 Customizing
 ===========
@@ -20,9 +20,9 @@ You can customize RbbCode by subclassing HtmlMaker and/or by passing configurati
 HtmlMaker can be extended by adding methods like this:
 
 class MyHtmlMaker < RbbCode::HtmlMaker
-	def html_from_TAGNAME_tag(node)
-		# ...
-	end
+  def html_from_TAGNAME_tag(node)
+    # ...
+  end
 end
 
 ...where TAGNAME should be replaced with the name of the tag. The method should accept an RbbCode::TagNode and return HTML as a string. (See tree_maker.rb for the definition of RbbCode::TagNode.) Anytime the parser encounters the specified tag, it will call your method and insert the returned HTML into the output.
@@ -36,11 +36,77 @@ RbbCode removes invalid markup by comparing the input against a Schema object. T
 
 Normally, RbbCode instantiates Schema behind the scenes, but if you want to customize it, you'll have to instantiate it yourself and pass the instance to the Parser object:
 
-schema = RbbCode::Schema.new
-schema.tag('quote').may_not_be_nested # Or whatever other configuration methods you want to call
-parser = RbbCode::Parser.new(:schema => schema)
+  schema = RbbCode::Schema.new
+  schema.tag('quote').may_not_be_nested # Or whatever other configuration methods you want to call
+  parser = RbbCode::Parser.new(:schema => schema)
 
 Unicode Support
 ===============
 
-UTF-8 compatibility is a high priority for this project. RbbCode aims to be fully compatible with UTF-8, but not with other multibyte encodings. As of the most recent release, UTF-8 support has been tested to a limited extent. It is possible that there are some hidden gotchas. Please report any bugs you may find.
+UTF-8 compatibility is a high priority for this project. RbbCode aims to be fully compatible with UTF-8, but not with other multibyte encodings. As of the most recent release, UTF-8 support has been tested to a limited extent. It is possible that there are some hidden gotchas. Please report any bugs you may find.
+
+RbbCode does not use any Unicode-aware string classes or methods. Instead, it relies on the fact that BBCode control characters are all in the ASCII range (0x00-0x7F). Since bytes in that range are not allowed as part of multibyte characters, the parser should not mistake a single byte in a multibyte character for a control character. This approach does mean that multibyte characters will be temporarily split up in the RbbCode internals. But in theory, this should be of no consequence, because they should always be correctly reassembled in the output. Please submit a bug report if this is not the case.
+
+BBCode Syntax
+=================
+
+As of this writing, there is no official BBCode standard. There are reference implementations, but they differ quite substantially. Wikipedia seemed like the only source with any claim to being canonical, so I followed its examples. The Wikipedia article is at:
+
+http://en.wikipedia.org/wiki/BBCode
+
+From that, I extracted some rules for "common" BBCode syntax. Here are the rules.
+
+Text gets wrapped in <p> tags unless it's marked up as some other block-level element such as a list. A single line break becomes a <br/>. Two line breaks mark the end of a paragraph, thus a closing </p> and possibly an opening <p>.
+
+Tags must be in one of the following forms:
+
+  [tagname]Text[/tagname]
+  [tagname=value]Text[/tagname]
+
+As you can infer from the second example, RbbCode does not support attributes like in HTML and XML. Rather, a tag can have a single "value," which is similar to an anonymous attribute. This is how [url] and [img] tags work, for example.
+
+RbbCode does not support all the tags listed on Wikpedia out of the box, and probably never will. However, you can easily add support for as many tags as you want.
+
+XSS Prevention
+==============
+
+Preventing XSS is one of the top priorities for RbbCode. For tags, RbbCode uses a whitelist. However, URLs can contain JavaScript, and it is not possible to construct a URL whitelist. Therefore, when parsing tags like [url] and [img], RbbCode has to use a blacklist. If you find a vulnerability there, please submit a bug report immediately.
+
+RbbCode sanitizes its URLs in two ways. First, it prepends "http://" to any URL that doesn't have a well-formed protocol. "javascript:" is not a well-formed protocol, because it lacks the two slashes. "javascript://" should not execute. Second, RbbCode hex-encodes various permutations of the word "JavaScript." These two precautions will *hopefully* be enough to prevent browsers executing scripts in URLs, but I can't be sure, because there are a lot of browsers out there.
+
+Also, by enforcing valid XHTML, RbbCode should prevent users breaking your layouts with unclosed tags. Submit a bug report if it doesn't.
+
+Bug Reports
+===========
+
+This project is maintained, but bugs sometimes take a few weeks to get fixed. If you find a bug, please take the following steps. Doing so will save me effort and thus greatly increase the chance of the bug being fixed in a timely manner.
+
+1. Make sure it's a bug and not a feature request. See below for details.
+2. Write a failing spec. This project uses RSpec. If you don't know how to use it and don't care to learn, then just create a script that produces bad output. Be sure to make it clear what you think the correct output should be. (Don't just say "the output is wrong.") Provide the *shortest* possible input that demonstrates the bug. For example, "Foo bar" is better dummy text than "Mary had a little lamb whose fleece was white as snow." Don't include extra markup that isn't necessary to trigger the bug.
+3. Open an issue on Github and paste in your spec or sample script. This is preferred over sending a message.
+
+Feature Requests vs Bugs
+========================
+
+Examples of bugs:
+- Executable JavaScript appears in the output
+- The output is not a valid XHTML fragment
+- RbbCode fails to support common BBCode syntax, as exemplified in http://en.wikipedia.org/wiki/BBCode
+- UTF-8 messes up, or the output is otherwise mangled
+- Any of the specs fail
+
+Example of feature requests:
+- You want support for more tags. RbbCode lets you define your own tags. So the absence of, say, the "color" tag in the default parser is not a bug
+- You want to support uncommon BBCode syntax, i.e. something you wouldn't see on http://en.wikipedia.org/wiki/BBCode
+
+Do not open an issue for a feature request. Just send a message on Github.
+
+Installation
+============
+
+  gem install rbbcode
+
+If that doesn't work, it's probably because RbbCode is hosted on Gemcutter, and your computer doesn't know about Gemcutter yet. To fix that:
+
+  gem install gemcutter
+  gem tumble

data/spec/html_maker_spec.rb

@@ -36,12 +36,12 @@ describe RbbCode::HtmlMaker do
 
 		it 'should not allow JavaScript in URLs' do
 			urls = {
-				'javascript:alert("foo");' => 'http://javascript%3Aalert("foo");',
-				'j a v a script:alert("foo");' => 'http://j+a+v+a+script%3Aalert("foo");',
-				' javascript:alert("foo");' => 'http://+javascript%3Aalert("foo");',
-				'JavaScript:alert("foo");' => 'http://JavaScript%3Aalert("foo");' ,
-				"java\nscript:alert(\"foo\");" => 'http://java%0Ascript%3Aalert("foo");',
-				"java\rscript:alert(\"foo\");" => 'http://java%0Dscript%3Aalert("foo");'
+				'javascript:alert("1");' => 'http://%6A%61%76%61%73%63%72%69%70%74%3Aalert(%221%22);',
+				'j a v a script:alert("2");' => 'http://%6A%20%61%20%76%20%61%20%73%63%72%69%70%74%3Aalert(%222%22);',
+				' javascript:alert("3");' => 'http://%20%6A%61%76%61%73%63%72%69%70%74%3Aalert(%223%22);',
+				'JavaScript:alert("4");' => 'http://%4A%61%76%61%53%63%72%69%70%74%3Aalert(%224%22);',
+				"java\nscript:alert(\"5\");" => 'http://%6A%61%76%61%0A%73%63%72%69%70%74%3Aalert(%225%22);',
+				"java\rscript:alert(\"6\");" => 'http://%6A%61%76%61%0D%73%63%72%69%70%74%3Aalert(%226%22);'
 			}
 			
 			# url tag
@@ -66,5 +66,15 @@ describe RbbCode::HtmlMaker do
 				end
 			end
 		end
+		
+		it 'should hex-encode double-quotes in the URL' do
+			expect_html('<p><a href="http://example.com/foo%22bar">Foo</a></p>') do
+				tag('p') do
+					tag('url', 'http://example.com/foo"bar') do
+						text 'Foo'
+					end
+				end
+			end
+		end
 	end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rbbcode
 version: !ruby/object:Gem::Version 
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors: 
 - Jarrett Colby
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2009-12-09 00:00:00 -06:00
+date: 2009-12-31 00:00:00 -06:00
 default_executable: 
 dependencies: []