Added token struct and switched to multibase

Author: jrabausch

README.md

@@ -30,10 +30,12 @@ Random::Secure.random_bytes(key)
 branca = Branca.new key
 
 token = branca.encode("Hello world!", 123206400)
-payload, timestamp = branca.decode(token)
+p token # e.g. 870S4BYxgHw0KnP3W9fgVUHEhT5g86vJ17etaC5Kh5uIraWHCI1psNQGv298ZmjPwoYbjDQ9chy2z
 
-p String.new(payload) == "Hello world!" # true
-p timestamp == 123206400 # true
+decoded = branca.decode(token)
+
+p String.new(decoded.payload) == "Hello world!" # true
+p decoded.timestamp == 123206400 # true
 ```
 
 Make sure you use a secure encryption key generated by `Random::Secure.random_bytes`

shard.yml

@@ -1,5 +1,5 @@
 name: branca
-version: 0.2.1
+version: 0.3.0
 
 authors:
   - Johannes Rabausch <mail@jrabausch.de>
@@ -8,8 +8,8 @@ dependencies:
   monocypher:
     github: konovod/monocypher.cr
     version: ~> 4.0.1
-  base62:
-    github: Sija/base62.cr
+  multibase:
+    github: radbas/multibase.cr
 
 development_dependencies:
   ameba:

spec/branca_spec.cr

@@ -59,51 +59,51 @@ describe Branca do
   describe "#decode" do
     it "decodes hello world with zero timestamp" do
       token = "870S4BYxgHw0KnP3W9fgVUHEhT5g86vJ17etaC5Kh5uIraWHCI1psNQGv298ZmjPwoYbjDQ9chy2z"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "48656c6c6f20776f726c6421"
-      timestamp.should eq 0
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "48656c6c6f20776f726c6421"
+      res.timestamp.should eq 0
     end
     it "decodes hello world with max timestamp" do
       token = "89i7YCwu5tWAJNHUDdmIqhzOi5hVHOd4afjZcGMcVmM4enl4yeLiDyYv41eMkNmTX6IwYEFErCSqr"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "48656c6c6f20776f726c6421"
-      timestamp.should eq 4294967295
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "48656c6c6f20776f726c6421"
+      res.timestamp.should eq 4294967295
     end
     it "decodes hello world with November 27 timestamp" do
       token = "875GH23U0Dr6nHFA63DhOyd9LkYudBkX8RsCTOMz5xoYAMw9sMd5QwcEqLDRnTDHPenOX7nP2trlT"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "48656c6c6f20776f726c6421"
-      timestamp.should eq 123206400
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "48656c6c6f20776f726c6421"
+      res.timestamp.should eq 123206400
     end
     it "decodes eight null bytes with zero timestamp" do
       token = "1jIBheHbDdkCDFQmtgw4RUZeQoOJgGwTFJSpwOAk3XYpJJr52DEpILLmmwYl4tjdSbbNqcF1"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "0000000000000000"
-      timestamp.should eq 0
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "0000000000000000"
+      res.timestamp.should eq 0
     end
     it "decodes eight null bytes with max timestamp" do
       token = "1jrx6DUu5q06oxykef2e2ZMyTcDRTQot9ZnwgifUtzAphGtjsxfbxXNhQyBEOGtpbkBgvIQx"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "0000000000000000"
-      timestamp.should eq 4294967295
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "0000000000000000"
+      res.timestamp.should eq 4294967295
     end
     it "decodes eight null bytes with November 27th timestamp" do
       token = "1jJDJOEjuwVb9Csz1Ypw1KBWSkr0YDpeBeJN6NzJWx1VgPLmcBhu2SbkpQ9JjZ3nfUf7Aytp"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "0000000000000000"
-      timestamp.should eq 123206400
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "0000000000000000"
+      res.timestamp.should eq 123206400
     end
     it "decodes empty payload" do
       token = "4sfD0vPFhIif8cy4nB3BQkHeJqkOkDvinI4zIhMjYX4YXZU5WIq9ycCVjGzB5"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq ""
-      timestamp.should eq 0
+      res = branca.decode(token)
+      res.payload.hexstring.should eq ""
+      res.timestamp.should eq 0
     end
     it "decodes non-UTF8 payload" do
       token = "K9u6d0zjXp8RXNUGDyXAsB9AtPo60CD3xxQ2ulL8aQoTzXbvockRff0y1eXoHm"
-      payload, timestamp = branca.decode(token)
-      payload.hexstring.should eq "80"
-      timestamp.should eq 123206400
+      res = branca.decode(token)
+      res.payload.hexstring.should eq "80"
+      res.timestamp.should eq 123206400
     end
     it "throws with wrong version 0xBB" do
       token = "89mvl3RkwXjpEj5WMxK7GUDEHEeeeZtwjMIOogTthvr44qBfYtQSIZH5MHOTC0GzoutDIeoPVZk3w"

spec/spec_helper.cr

@@ -5,6 +5,6 @@ require "../src/branca"
 #
 # This sets a user defined nonce for testing.
 # Do not do this in production.
-struct Branca
+class Branca
   @nonce = "beefbeefbeefbeefbeefbeefbeefbeefbeefbeefbeefbeef".hexbytes
 end

src/branca.cr

@@ -1,18 +1,29 @@
 require "monocypher"
-require "base62"
+require "multibase/base_62"
 
-struct Branca
-  VERSION = UInt8.new 0xBA
+class Branca
+  VERSION = 0xBA
 
   alias BigEndian = IO::ByteFormat::BigEndian
+  alias Base62 = Multibase::Base62
   alias Nonce = Crypto::Nonce
   alias Mac = Crypto::Header
 
+  struct Token
+    property :payload, :timestamp
+
+    def initialize(
+      @payload : Bytes = Bytes.empty,
+      @timestamp : UInt32 = Time.utc.to_unix.to_u32
+    )
+    end
+  end
+
   class ExpiredTokenError < Exception
-    getter :delta
+    getter :token
 
-    def initialize(@delta : UInt32)
-      super "token is expired by: #{@delta}s"
+    def initialize(@token : Token)
+      super "token is expired"
     end
   end
 
@@ -29,7 +40,7 @@ struct Branca
     @key = StaticArray(UInt8, 32).new { |i| key[i] }
   end
 
-  # Creates a XChaCha20-Poly1305 AEAD encrypted Branca token.
+  # Creates a XChaCha20-Poly1305 AEAD encrypted Branca Token.
   #
   # Returns a Base62 encoded String.
   def encode(payload : String | Bytes, timestamp : UInt32 = Time.utc.to_unix.to_u32) : String
@@ -40,7 +51,7 @@ struct Branca
 
     # Use custom nonce if set (only for testing).
     nonce = @nonce || Nonce.new.to_slice
-    header = Slice(UInt8).new(1, VERSION) + time + nonce
+    header = Slice(UInt8).new(1, VERSION.to_u8) + time + nonce
 
     ciphertext = Bytes.new(payload.size + Mac.size)
     LibMonocypher.aead_lock(
@@ -57,12 +68,15 @@ struct Branca
     Base62.encode(token)
   end
 
-  # Decodes a valid Branca token.
+  def encode(token : Token) : String
+    encode(token.payload, token.timestamp)
+  end
+
+  # Decodes a Base62 encoded Branca Token.
   #
   # If *ttl* is greater than 0 and the token is expired, an `ExpiredTokenError` is raised.
-  # Returns a {payload, timestamp} Tuple.
-  def decode(token : String, ttl : UInt32 = 0) : {Bytes, UInt32}
-    bytes = Base62.decode(token).to_s(16).hexbytes
+  def decode(str : String, ttl : UInt32 = 0) : Token
+    bytes = Base62.decode(str)
     header_size = 5 + Nonce.size
     raise "invalid token header size: got #{bytes.size}, expected #{header_size}" if bytes.size < header_size
 
@@ -87,11 +101,9 @@ struct Branca
     raise "decryption error occurred: #{res}" unless res == 0
 
     timestamp = BigEndian.decode(UInt32, header[1..4])
-    if ttl > 0
-      delta = Time.utc.to_unix - (timestamp + ttl)
-      raise ExpiredTokenError.new delta.to_u32 if delta > 0
-    end
+    token = Token.new(payload, timestamp)
 
-    {payload, timestamp}
+    raise ExpiredTokenError.new token if ttl > 0 && (timestamp + ttl) < Time.utc.to_unix
+    token
   end
 end