nebula-token 1.0.1 → 1.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e174bf87f7b2cca663e761f710c4d7caf75795d1fe2077e4bfd781f68ec064a6
-  data.tar.gz: e1285aa87c3bb87eafd5216204be69cf852b01cd450df9c5329dd9639521fda5
+  metadata.gz: 61d4afd2ad50c4081a6242d832a2fa4c6b9658c493671312857cc270acbde9aa
+  data.tar.gz: 7fb59167e1ac60a8e7c9c089d5421cc52b58ec57c0209014526baa4a37197cec
 SHA512:
-  metadata.gz: e450ff9a8351b508db17d31d251eb560ff73fed504b44746e4c7315d9900d34d7e2073b8119d4d42dc17722fb0685e5374103055bd1d4ec743cc860d396c1712
-  data.tar.gz: fe19f48e27733096ce103921b5fa20e21faa0aeab3a9d38d4ba5648718ff3b8a1e69c38bb83c21e9c749fccce2943f1f3c4b6cd54226b3831032ffa65d0beb24
+  metadata.gz: 246a1592aa4f314982053fa2e07dee50547bd961a56fbcdbf98f28b019ae1e445697e60e3a90c72c9df6b1cbcdb52d598c2cd44f64a117f14e322cfe08a5c21c
+  data.tar.gz: 06e23d009ba3686ea6367581103dba8c6dd6961fe7807c543bdb90a7f9bc6cfb791a31a1e3a3b869fb45f65e6306290dd72513c036b2ffb49bd1a5880a0095a9

data/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [1.0.2] - 2026-08-04
+
+### Fixed
+- The engine tested the compare-and-set return value directly, and in Ruby `0`
+  is truthy. A store reporting the affected-row count — which `docs/STORE.md`
+  told adapters to return — made a **lost** compare-and-set read as applied, so
+  two concurrent refreshes each minted a successor and the family forked into
+  two independently valid lineages with reuse detection off for it ([N-17],
+  [N-18], [N-34] step 5). Counts are normalised now and anything outside the
+  contract fails closed as "not applied".
+- A device identifier was decided on the String's encoding tag rather than on
+  its bytes, so bytes that every other port accepts were refused when tagged
+  `ASCII-8BIT` — from `String#b`, `File.binread` or a socket read. In `refresh`
+  that is a sender-binding failure, so the whole family was revoked where the
+  other nine rotate normally ([N-11], [N-32]). [N-12]'s treatment of invalid
+  Unicode is unchanged. Ruby is the only one of the ten where a string carries a
+  declared encoding distinct from its bytes, so it is the only port this could
+  affect; erratum E-1 records the clarification to [N-11], and the shared cases
+  `dh-08`/`dh-09` now pin it for every implementation.
+
 ## [1.0.1] - 2026-07-30
 
 Release automation only; no change to this package's behaviour, API or wire
@@ -24,5 +44,6 @@ workflow failed, and neither permits republishing a used version number.
   window, family revocation, sender (device) binding, dual expiry clocks,
   pepper rotation via `kid`.
 
+[1.0.2]: https://github.com/nebula-token/nebula-token/releases/tag/v1.0.2
 [1.0.1]: https://github.com/nebula-token/nebula-token/releases/tag/v1.0.1
-[1.0.0]: https://github.com/nebula-token/nebula-token/releases/tag/v1.0.0
+[1.0.0]: https://github.com/nebula-token/nebula-token/commit/cb66b3dd897dc968bff8b211f001b94de7531b09

data/README.md

@@ -1,6 +1,6 @@
 # nebula-token (Ruby)
 
-Ruby implementation of [NEBULA](../../SPECIFICATION.md) — opaque rotating refresh tokens (RFC 9700 model). Standard library only (`openssl`, `securerandom`), no gem dependencies, Ruby ≥ 3.3.
+Ruby implementation of [NEBULA](../../SPECIFICATION.md) — opaque rotating refresh tokens (RFC 9700 model). Standard library only (`openssl`, `securerandom`), no gem dependencies, Ruby ≥ 3.3. Implements `spec_version = 1`.
 
 ```
 gem install nebula-token

data/lib/nebula_token.rb

@@ -138,11 +138,26 @@ module NebulaToken
   # failure on the attacker-reachable path, a caller error at issue ([N-12]).
   # Deriving a hash from a replacement character instead would make the same
   # identifier hash differently across languages.
+  # A binary-tagged String is bytes, not text, and is decided on the BYTES for
+  # the same reason pepper_bytes is: the identical identifier reaches Ruby
+  # tagged UTF-8 from JSON and ASCII-8BIT from String#b, File.binread or a
+  # socket read, and ASCII-8BIT -> UTF-8 transcoding raises for every byte above
+  # 0x7F. Transcoding it would refuse an identifier the other nine ports accept
+  # — and in `refresh` that refusal is a sender-binding failure, so it would
+  # revoke the whole family where the other nine rotate normally. A String that
+  # carries a real text encoding still transcodes, so its UTF-8 encoding is the
+  # one [N-11] names.
   def utf8_bytes(value)
     return nil unless value.is_a?(String)
 
-    utf8 = value.encoding == Encoding::UTF_8 ? value : value.encode(Encoding::UTF_8)
-    utf8.valid_encoding? ? utf8.b : nil
+    utf8 =
+      if value.encoding == Encoding::UTF_8 || value.encoding == Encoding::BINARY
+        value
+      else
+        value.encode(Encoding::UTF_8)
+      end
+    bytes = utf8.b
+    bytes.dup.force_encoding(Encoding::UTF_8).valid_encoding? ? bytes : nil
   rescue EncodingError
     nil
   end
@@ -275,6 +290,30 @@ module NebulaToken
     STATUS_BY_NAME.fetch(value.to_s, STATUS_REVOKED)
   end
 
+  # Did a compare-and-set apply? ([N-17], [N-18])
+  #
+  # The store contract returns a boolean, but `docs/STORE.md` §4 also tells an
+  # adapter to derive it from the affected-row count its driver reports —
+  # `cmd_tuples` on a `PG::Result`, `affected_rows` on Mysql2 — and in Ruby `0`
+  # is truthy. A bare `unless @store.mark_rotated(...)` therefore reads a LOST
+  # compare-and-set as applied: two concurrent refreshes each mint a successor,
+  # the family forks into two independently valid lineages, and no later
+  # presentation of either is a replay. Reuse detection is not weakened for that
+  # family, it is switched off — which is the entire failure [N-17] exists to
+  # close. Ruby is the only one of the ten ports where a count can read as
+  # success, so this is a Ruby-side guard, not a change of contract.
+  #
+  # Anything outside the contract fails closed as "not applied": a spurious
+  # CONFLICT revokes nothing and is retryable ([N-35]), a spurious success is
+  # unrecoverable.
+  def cas_applied?(value)
+    case value
+    when true, false then value
+    when Integer then value.positive?
+    else false
+    end
+  end
+
   # ── Server-side record (§3) ────────────────────────────────────────────────
 
   # One row per issued token ([N-10]).
@@ -787,7 +826,7 @@ module NebulaToken
 
           # Compare-and-set: exactly one concurrent retry may consume the unused
           # successor. The loser rotates nothing and reports CONFLICT ([N-30] 2).
-          unless @store.revoke_if_active(successor.selector)
+          unless NebulaToken.cas_applied?(@store.revoke_if_active(successor.selector))
             return RefreshResult.failure(ErrorCode::CONFLICT, record)
           end
 
@@ -816,7 +855,8 @@ module NebulaToken
                               device_hash, record.family_expires_at, now)
       @store.insert(successor)
 
-      unless @store.mark_rotated(record.selector, from_status, rotated_at, successor.selector)
+      unless NebulaToken.cas_applied?(@store.mark_rotated(record.selector, from_status,
+                                                          rotated_at, successor.selector))
         # [N-34] step 5: a concurrent refresh won the compare-and-set. Clean up
         # the successor we inserted and report a retryable conflict — never a
         # token. Without the CAS both refreshes would mint a successor and the

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nebula-token
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.0.2
 platform: ruby
 authors:
 - Matteo Teodori