branca-ruby 1.0.3 → 1.0.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb38a9b375ff1f3510d4f8be5d535210fa926b1852402900bfaffa78bc86954a
-  data.tar.gz: eb611a373fb87ac2c44c7ad98ebcfb64cf4a94d53128bb78e86d38c6553bdff8
+  metadata.gz: ca468058d67919573d667e3031f3d330ab5407afd95e7c01f4fa0a1f14221420
+  data.tar.gz: 4a55b87679fbd08a1cc364b245af0aecc7c5e1db1b87c2e7594e14ce15feef69
 SHA512:
-  metadata.gz: 845eb83b9b1fdaa2fea3957cf7b930607af154e3440265fcebade68b2db40dcd0177270d7f5d5016e8d3e4446df2115448b4e8e35964f0facc85e6012cf15334
-  data.tar.gz: 13f6b3408237cb98b24c4489d37d5b9a9386ed8ddeb5f9cef3473ff951eb9a811b6403c0f6cf005f9d3f8667dc54bb065db95ddaf76ad6f8f04dbe9b062c8098
+  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/.gitpod.yml

@@ -0,0 +1,8 @@
+# This configuration file was automatically generated by Gitpod.
+# Please adjust to your needs (see https://www.gitpod.io/docs/config-gitpod-file)
+# and commit this file to your remote git repository to share the goodness with others.
+
+tasks:
+  - init: bin/setup
+
+

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/Gemfile

@@ -7,4 +7,4 @@ gemspec
 
 ruby '>= 2.5.8'
 
-gem "byebug", "~> 10.0", :group => :test
+gem "byebug", :group => :test

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.2'
+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.3'
+  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
 
-      BaseX::Base62.encode(raw_token)
+      Branca::Base62.encode(raw_token)
     end
 
     def decode(token, ttl: self.ttl, secret_key: self.secret_key)
@@ -58,7 +58,9 @@ module Branca
     end
 
     def token_explode(token)
-      bytes = BaseX::Base62.decode(token).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]

metadata

@@ -1,29 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: branca-ruby
 version: !ruby/object:Gem::Version
-  version: 1.0.3
+  version: 1.0.5
 platform: ruby
 authors:
 - Thadeu Esteves
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-08-12 00:00:00.000000000 Z
+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
@@ -104,10 +89,12 @@ files:
 - ".github/FUNDING.yml"
 - ".github/workflows/ruby.yml"
 - ".gitignore"
+- ".gitpod.yml"
 - ".rspec"
 - ".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
@@ -123,7 +111,6 @@ homepage: https://github.com/thadeu/branca-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -138,8 +125,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Authenticated and encrypted API tokens using modern crypto
 test_files: []