branca-ruby 1.0.4 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a18a64bfdd3003e06e8cf821c88851354edab732357676b3b86014a62fd6a172
-  data.tar.gz: 281778e2b9e47f9ba6d92a982c5b7e3adfae2cab7a0eee7e2e1610ea143677eb
+  metadata.gz: ca468058d67919573d667e3031f3d330ab5407afd95e7c01f4fa0a1f14221420
+  data.tar.gz: 4a55b87679fbd08a1cc364b245af0aecc7c5e1db1b87c2e7594e14ce15feef69
 SHA512:
-  metadata.gz: 8b80e5b4e5df1e1ffa41ac6cf95c2dd861c9db446cfbed290d84cdafebeea41370ccd819add02d4a5949a3de25c72c5e46179ac700ffefa866f50e8b7b8162eb
-  data.tar.gz: a37487ab60fe01d67e1ee7d49c4e57e64bb0afda1554a4e5708fcde5c09d450d15497022a9e0190dbab4e200e75037a7c193cd9e192c550e626f7f7a0ae73055
+  metadata.gz: 2b06a8122e6afc30cccbc41fd9292a31f2e27fba1714ed3e5e86b7a1d2581ef435ab33ee37f5e491b514ee1eb7d4d89085509267ddede8def3ff3ea709ebef88
+  data.tar.gz: 13ca319d1f6e3d3b2ed11db3c06fd63e78605cea934d332b5500d9ede6d3949f97513be686689d118ec0acaa0b6a8cfa1759b832ab116c937f5039b6e1b639ff

data/.github/workflows/ruby.yml

@@ -10,7 +10,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['2.5', '2.6', '2.7', '3.0']
+        ruby-version: ['3.0', '3.1']
 
     steps:
     - uses: actions/checkout@v3

data/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+## [1.0.5] - 2025-02-10
+
+### Changed
+
+- Replaced the `base_x` gem with a built-in `Branca::Base62` encoder/decoder.
+
+The `base_x` gem uses mathematical range-based padding, which prepends a leading `'0'` character
+to the encoded token when `62^len < 256^byte_count`. This is incompatible with the JavaScript
+[base-x](https://github.com/cryptocoinjs/base-x) library used by
+[branca-js](https://github.com/tuupola/branca-js) and all other Branca implementations.
+
+The JavaScript `base-x` library follows the Bitcoin-style convention where leading `'0'` characters
+in the encoded string map 1:1 to leading `\x00` bytes in the decoded binary. When it decodes a
+Ruby-generated token that starts with `'0'` (added as mathematical padding), it interprets that
+character as a `\x00` byte, corrupting the version byte from `0xBA` to `0x00` and causing an
+"Invalid token version" error.
+
+The new `Branca::Base62` module implements the same Bitcoin-style algorithm, ensuring full
+cross-language compatibility with every Branca implementation listed in the
+[branca-spec](https://github.com/thadeu/branca-spec).
+
+### Removed
+
+- Removed the `base_x` gem dependency.
+
+## [1.0.4] - 2026-02-10
+
+### Changed
+
+- First attempt to fix the leading `'0'` issue in Base62-encoded tokens by using a rearranged
+  alphabet (`BaseX.new('123456789ABCDEF...0')`) to avoid `'0'` as the first character. This
+  workaround shifted `'0'` to the end of the numeral set but did not address the root cause:
+  the `base_x` gem's mathematical padding algorithm is fundamentally incompatible with the
+  JavaScript `base-x` library used by all other Branca implementations.
+
+- Added a fallback in `base62_decode` that retries with the original `BaseX::Base62` alphabet
+  when the version byte does not match `0xBA`, providing partial backward compatibility.
+
+- Added comprehensive tests for Base62 encoding compliance and round-trip validation with
+  production-like payloads.
+
+> **Note:** This version was superseded by 1.0.5, which fully replaces the `base_x` gem with
+> a Bitcoin-style `Branca::Base62` implementation that is natively compatible with `branca-js`.

data/README.md

@@ -17,7 +17,7 @@ It is possible to use [Branca as an alternative to JWT](https://appelsiini.net/2
 Add this line to your application's Gemfile, Note that you also must have [libsodium](https://download.libsodium.org/doc/) installed.
 
 ```ruby
-gem 'branca-ruby', '~> 1.0.3'
+gem 'branca-ruby'
 ```
 
 ## Configure

data/branca-ruby.gemspec

@@ -22,7 +22,6 @@ Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.3.0'
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'base_x', '~> 0.8.1'
   spec.add_dependency 'rbnacl', '~> 7.0'
   spec.add_development_dependency 'bundler', '>= 1.14'
   spec.add_development_dependency 'rake', '~> 10.0'

data/lib/branca/base62.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Branca
+  # Bitcoin-style Base62 encoder/decoder compatible with the JavaScript
+  # `base-x` library (https://github.com/cryptocoinjs/base-x).
+  #
+  # Leading \x00 bytes in the input map 1:1 to leading '0' characters
+  # in the encoded output, and vice-versa on decode.
+  module Base62
+    ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+    BASE = ALPHABET.length
+
+    ALPHABET_MAP = ALPHABET.each_char.with_index.to_h.freeze
+
+    class << self
+      def encode(data)
+        data = data.b
+        return '' if data.empty?
+
+        leading_zeros = count_leading_bytes(data, 0x00)
+
+        int_val = bytes_to_integer(data, leading_zeros)
+
+        encoded = integer_to_base62(int_val)
+
+        (ALPHABET[0] * leading_zeros) + encoded
+      end
+
+      def decode(string)
+        return ''.b if string.empty?
+
+        leading_zeros = count_leading_chars(string, ALPHABET[0])
+
+        int_val = base62_to_integer(string, leading_zeros)
+
+        bytes = integer_to_bytes(int_val)
+
+        ("\x00".b * leading_zeros) + bytes
+      end
+
+      private
+
+      def count_leading_bytes(data, byte)
+        count = 0
+        data.each_byte { |b| b == byte ? (count += 1) : break }
+        count
+      end
+
+      def count_leading_chars(string, char)
+        count = 0
+        string.each_char { |c| c == char ? (count += 1) : break }
+        count
+      end
+
+      def bytes_to_integer(data, skip)
+        int_val = 0
+        data.bytes.drop(skip).each { |b| int_val = int_val * 256 + b }
+        int_val
+      end
+
+      def integer_to_base62(int_val)
+        return '' if int_val.zero?
+
+        result = ''.b
+        while int_val.positive?
+          int_val, remainder = int_val.divmod(BASE)
+          result << ALPHABET[remainder]
+        end
+        result.reverse
+      end
+
+      def base62_to_integer(string, skip)
+        int_val = 0
+        string[skip..].each_char do |c|
+          digit = ALPHABET_MAP[c]
+          raise ArgumentError, "invalid base62 character: #{c.inspect}" unless digit
+
+          int_val = int_val * BASE + digit
+        end
+        int_val
+      end
+
+      def integer_to_bytes(int_val)
+        return ''.b if int_val.zero?
+
+        bytes = []
+        while int_val.positive?
+          bytes.unshift(int_val & 0xFF)
+          int_val >>= 8
+        end
+        bytes.pack('C*')
+      end
+    end
+  end
+end

data/lib/branca/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Branca
-  VERSION = '1.0.4'
+  VERSION = '1.0.5'
 end

data/lib/branca.rb

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 require 'rbnacl'
-require 'base_x'
 
 require 'branca/version'
 require 'branca/exceptions'
 require 'branca/decoder'
+require 'branca/base62'
 
 module Branca
   class << self
@@ -21,7 +21,7 @@ module Branca
       ciphertext = cipher.encrypt(nonce, message, header)
       raw_token = header + ciphertext
 
-      base62_encode(raw_token)
+      Branca::Base62.encode(raw_token)
     end
 
     def decode(token, ttl: self.ttl, secret_key: self.secret_key)
@@ -58,28 +58,14 @@ module Branca
     end
 
     def token_explode(token)
-      raw = base62_decode(token)
-      bytes = raw.unpack('C C4 C24 C*')
+      raise DecodeError if token.nil? || token.empty?
+
+      bytes = Branca::Base62.decode(token).unpack('C C4 C24 C*')
       header = bytes.shift(1 + 4 + 24)
 
       [header, bytes]
     end
 
-    BASE62_NO_LEADING_ZERO = BaseX.new(
-      '123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0'
-    ).freeze
-
-    def base62_encode(raw_token)
-      BASE62_NO_LEADING_ZERO.encode(raw_token)
-    end
-
-    def base62_decode(token)
-      raw = BASE62_NO_LEADING_ZERO.decode(token)
-      return raw if raw.getbyte(0) == VERSION
-
-      BaseX::Base62.decode(token)
-    end
-
     def header_explode(header)
       version = header[0]
       nonce = header[5..header.size].pack('C*')

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: branca-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.4
+  version: 1.0.5
 platform: ruby
 authors:
 - Thadeu Esteves
@@ -9,20 +9,6 @@ bindir: bin
 cert_chain: []
 date: 2026-02-10 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: base_x
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.8.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.8.1
 - !ruby/object:Gem::Dependency
   name: rbnacl
   requirement: !ruby/object:Gem::Requirement
@@ -108,6 +94,7 @@ files:
 - ".rubocop.yml"
 - ".travis-libsodium.sh"
 - ".travis.yml"
+- CHANGELOG.md
 - Gemfile
 - LICENSE
 - README.md
@@ -116,6 +103,7 @@ files:
 - bin/setup
 - branca-ruby.gemspec
 - lib/branca.rb
+- lib/branca/base62.rb
 - lib/branca/decoder.rb
 - lib/branca/exceptions.rb
 - lib/branca/version.rb