Improve error handling for timestamps that are out of bound, and update spec accordingly.

Author: alizain

README.md

@@ -92,7 +92,7 @@ From the community!
 
 Below is the current specification of ULID as implemented in this repository.
 
-*Note: the binary format has not been implemented.*
+*Note: the binary format has not been implemented in JavaScript as of yet.*
 
 ```
  01AN4Z07BY      79KA1307SR9X4MV3
@@ -117,14 +117,30 @@ Below is the current specification of ULID as implemented in this repository.
 
 The left-most character must be sorted first, and the right-most character sorted last (lexical order). The default ASCII character set must be used. Within the same millisecond, sort order is not guaranteed
 
-### Encoding
+### Canonical String Representation
+
+```
+ttttttttttrrrrrrrrrrrrrrrr
+
+where
+t is Timestamp (10 characters)
+r is Randomness (16 characters)
+```
+
+#### Encoding
 
 Crockford's Base32 is used as shown. This alphabet excludes the letters I, L, O, and U to avoid confusion and abuse.
 
 ```
 0123456789ABCDEFGHJKMNPQRSTVWXYZ
 ```
 
+#### Overflow Errors when Parsing Base32 Strings
+
+Technically, a 26 character Base32 encoded string can contain 130 bits of information, whereas a ULID must only contain 128 bits. Therefore, the largest valid ULID encoded in Base32 is `7ZZZZZZZZZZZZZZZZZZZZZZZZZ`, which corresponds to an epoch time of `281474976710655`.
+
+Any attempt to decode or encode a ULID larger than this should be rejected by all implementations, to prevent overflow bugs.
+
 ### Binary Layout and Byte Order
 
 The components are encoded as 16 octets. Each component is encoded with the Most Significant Byte first (network byte order).
@@ -143,16 +159,6 @@ The components are encoded as 16 octets. Each component is encoded with the Most
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 ```
 
-### String Representation
-
-```
-ttttttttttrrrrrrrrrrrrrrrr
-
-where
-t is Timestamp
-r is Randomness
-```
-
 ## Prior Art
 
 Partly inspired by:

index.js

@@ -42,6 +42,9 @@ function factory(prng) {
   }
 
   function decodeTime(id) {
+    if (id.length !== TIME_LEN + RANDOM_LEN) {
+      throw new Error("malformed ulid")
+    }
     var binStr = ''
     for (var i = 0; i < 10; i++) {
       var dec = ENCODING.indexOf(id[i])
@@ -52,7 +55,11 @@ function factory(prng) {
       }
       binStr += bin
     }
-    return parseInt(binStr, 2)
+    var time = parseInt(binStr, 2)
+    if (time > TIME_MAX) {
+      throw new Error("malformed ulid, timestamp too large")
+    }
+    return time
   }
 
   function ulid(seedTime) {

test.js

@@ -59,7 +59,7 @@ describe('ulid', function() {
     })
 
   })
-  
+
   describe('decodeTime', function() {
 
     it('should return correct timestamp', function() {
@@ -68,6 +68,22 @@ describe('ulid', function() {
       assert.strictEqual(timestamp, ulid.decodeTime(id))
     })
 
+    it('should accept the maximum allowed timestamp', function() {
+      assert.strictEqual(281474976710655, ulid.decodeTime('7ZZZZZZZZZZZZZZZZZZZZZZZZZ'))
+    })
+
+    describe('should reject', function() {
+
+      it('malformed strings of incorrect length', function() {
+        assert.throws(() => ulid.decodeTime('FFFF'), Error)
+      })
+
+      it('strings with timestamps that are too high', function() {
+        assert.throws(() => ulid.decodeTime('80000000000000000000000000'), Error)
+      })
+
+    })
+
   })
 
   describe('ulid', function() {