basecradle 0.10.2 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e662740bb7ecbde3769c3430a269cbe32a0c507a4244626688af1ca13ce3ce4
-  data.tar.gz: 64820f7409159b2cfd1b063a53c96858302bfc939e4ff2df17b6ffcaf3b494e5
+  metadata.gz: b1fc584abdde2edfd9233ea937bf054ba6fb672708b6c815014d46a1dc4d59c2
+  data.tar.gz: bc53a3e49ad9eb40fd21e5fb2fe424d054738359a30eb2c137a26c8a5f634d27
 SHA512:
-  metadata.gz: 6c7a007a0c7eef4fe1bb8d4d19fc108c361fc5e5d4a618d5d61600a0cdd55fbb6b97ecc5ea5c07ed8ac6488840b7cc33133c59a6160feab2a04222da73683eeb
-  data.tar.gz: 7059369ae648787b45a97afe3b12ba721474629078031ac036461732cc7dfc9d13e764b916f48a7e72fa96b248bac4c53c1ee3ed686f2abc98d13ed1c54a6c28
+  metadata.gz: c603f01c320e465db82dc376ad78cfca4d52c63db107580be7366d2a2c3b79f99e1d5b3f356917bd1526b9f63bb294747cc218a1e7cf71e8fc22caa41ccc4b34
+  data.tar.gz: 401d5b9b58f5dc726fb3bc457180954b582e077b8b0aa224c0f92513a39c4122bac16ea56dfff4746e44e2b252cc88ab8a6cf12b178d989ee1eed5b2caf1d02a

data/CHANGELOG.md

@@ -9,6 +9,87 @@ section**. The newest heading is always the version `lib/basecradle/version.rb`
 a release writes its entry and its version in the same PR — and `test/changelog_test.rb`
 fails CI if the two ever disagree.
 
+## [0.10.3] - 2026-09-30
+
+### Security
+
+- **`Marshal.dump` and `to_yaml` no longer emit a `Client`'s token**
+  ([#205](https://github.com/basecradle/basecradle-ruby/issues/205)). 0.10.1 shut the
+  JSON door on a client; `Marshal` and Psych walk instance variables directly, consult no
+  `as_json`, and need no ActiveSupport to do it — so both still wrote the raw `bc_uat_`
+  credential into their output. They are the worse pair, because they are what puts a
+  token *at rest*: ActiveSupport's cache stores marshal what you write, so
+  `Rails.cache.write("bc", bc)` landed it in Redis, memcached or a file store; a
+  Marshal-backed session landed it in the session; Delayed::Job YAMLs its handler into
+  the database. (Queue backends that serialize arguments as **JSON** — ActiveJob and
+  Sidekiq among them — go through `to_json`, and so were already closed in 0.10.1.)
+  `Marshal.dump(bc)`, `bc.to_yaml`,
+  `YAML.dump(conn: bc)` and the `Marshal.load(Marshal.dump(bc))` deep-copy idiom now all
+  raise `BaseCradle::NotSerializableError`, the same typed error with the same message
+  the JSON door already raised. Long-standing and latent; no token is known to have been
+  emitted.
+- **The collection door was the wider one, not the narrower one.** Through JSON, a
+  collection never reached the token — ActiveSupport's `Enumerable#as_json` shadows
+  `Object#as_json`, so `bc.messages.to_json` serialized fetched records, never the client
+  held in an ivar. `Marshal` and Psych have no such shadow, so
+  **`Marshal.dump(bc.messages)` reached the credential where `bc.messages.to_json` never
+  did** — and a query is the likelier of the two to be handed to a cache. Every lazy
+  collection (`bc.timelines`, `bc.messages`, `timeline.tasks`, any `.filter(...)`, the
+  `Paginator` behind them) now refuses through all four doors; the refusals are on the
+  shared `NotSerializable` mixin, so a resource added later is covered by construction.
+  **`.to_a` is only half the remedy for a dumper** — the array it hands back is full of
+  models that each hold the client, so `Marshal.dump(bc.messages.to_a)` lands back on the
+  same error. Dump `bc.messages.to_a.map(&:to_h)`, which the refusal now says.
+- **Anything holding a client refuses too — models included, and that is the fix.** Both
+  walkers recurse, so `Marshal.dump(message)` and `message.to_yaml` reached the client's
+  token where `message.to_json` (which serializes the wire record) never did. They now
+  raise, naming `BaseCradle::Client` as what was reached. **If you cache or enqueue
+  models, cache the record instead** — `message.to_h` is the wire `Hash`, holds no
+  client, and marshals exactly as it always did; rebuild with
+  `BaseCradle::Message.new(record, client: bc)` when you need the verbs back. Nothing
+  else changed: `to_json`, `as_json`, `to_h`, `inspect`, every field reader and
+  `dup`/`clone` (which do not go through `Marshal`) are untouched. This matches the
+  Python SDK, whose `__reduce__` refusal says the same thing — *“Nothing holding a client
+  can be serialized either … copy the record's data instead.”*
+
+### Known limitation
+
+- **YAML reaches the `Enumerator` escape that 0.10.1 documented for JSON, on plain
+  Ruby.** Every refusal here is on this SDK's own objects; an `Enumerator` you build from
+  a collection (`bc.messages.each`, `bc.messages.lazy`) is a plain Ruby object this SDK
+  does not own and may not patch. Psych iterates one to dump it — with **no
+  ActiveSupport required**, where the `to_json` version is inert without it — so
+  `bc.messages.each.to_yaml` fires the page-by-page GET loop and *then* raises
+  `NotSerializableError` on the first record, which holds the client: the requests are
+  spent and no document comes out. `Marshal` is the exception — Ruby itself refuses to
+  dump an `Enumerator` at all. No token is exposed through any of them. Call `.first(n)`
+  or `.to_a` before a renderer, and `.map(&:to_h)` too before a dumper.
+- **Four doors is every hook Ruby gives a library**, not every way bytes can be made. A
+  serializer that reads instance variables directly rather than through `as_json`,
+  `to_json`, `marshal_dump` or `encode_with` is outside what this SDK can intercept.
+  Keep a client out of one.
+
+### Migrating
+
+Nothing to change unless you `Marshal.dump` or `to_yaml` something that holds a client.
+If you do:
+
+- **Caching or enqueuing a model** — `Rails.cache.write(key, message)`,
+  `Rails.cache.fetch(key) { bc.messages.get(id) }` — now raises
+  `BaseCradle::NotSerializableError` where it used to write your token to the store.
+  Cache `message.to_h`, the wire `Hash`, and rebuild with
+  `BaseCradle::Message.new(record, client: bc)` if you need the verbs back.
+- **Caching or enqueuing a client or a collection** — serialize nothing; build a client
+  where you need one (`BaseCradle::Client.new(token)`), moving the token only through
+  whatever you already trust with secrets. For a collection, `.to_a` / `.first(n)` is
+  enough for JSON but **not** for a dumper — use `bc.messages.to_a.map(&:to_h)`, since
+  the models in that array each hold the client.
+- **Deep-copying with `Marshal.load(Marshal.dump(x))`** — refuses at the dump for the
+  same objects. `dup` and `clone` do not go through `Marshal` and are unchanged.
+
+If any of these ran in production against a real store, treat the token as disclosed and
+rotate it: `bc.sessions` lists your credentials and `session.revoke` retires one.
+
 ## [0.10.2] - 2026-09-30
 
 ### Security
@@ -484,6 +565,7 @@ the Python SDK's behavior in idiomatic Ruby. Zero runtime dependencies.
 - **Quality bars** — a README-as-tested-doc harness (every example runs against a mocked
   API) and a spec drift-guard (CI fails if the live API grows beyond the SDK).
 
+[0.10.3]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.3
 [0.10.2]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.2
 [0.10.1]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.1
 [0.10.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.0

data/README.md

@@ -375,10 +375,15 @@ something Rails renders comes out right too. Three caveats worth knowing:
 ## What does not serialize: clients and collections
 
 Two things in this SDK are *not* records, and serializing either raises
-`BaseCradle::NotSerializableError` rather than emitting something:
+`BaseCradle::NotSerializableError` rather than emitting something — and under `Marshal`
+and YAML, so does anything *holding* one, models included (see below). Four doors refuse:
+`to_json`, `as_json`, `Marshal.dump` and `to_yaml` — every hook Ruby gives a library to
+intercept. A serializer that reads instance variables directly instead of through those
+hooks is outside what any library can stop, so keep a client out of one.
 
 ```ruby
 require "basecradle"
+require "yaml"
 
 bc = BaseCradle::Client.new
 
@@ -394,6 +399,18 @@ rescue BaseCradle::NotSerializableError => e
   puts e.message.include?(".to_a")    # => true
 end
 
+begin
+  Marshal.dump(bc)                    # and Rails.cache.write("bc", bc), a job argument
+rescue BaseCradle::NotSerializableError => e
+  puts e.message.include?("bc_uat_")  # => true
+end
+
+begin
+  bc.messages.to_yaml                 # YAML walks the ivars, and reaches the client
+rescue BaseCradle::NotSerializableError => e
+  puts e.message.include?(".to_a")    # => true
+end
+
 puts bc.messages.first(20).to_json    # serialize the page you actually asked for
 ```
 
@@ -410,10 +427,50 @@ walk — but a client's instance variables are eight collections, so serializing
 ran those loops too, on its way to the credential.) Call `.to_a` or `.first(n)` yourself
 and serialize that, so how much you fetch is a visible act in your code.
 
-Both refusals happen before any HTTP — but they are on the SDK's own objects. An
+**`Marshal` and YAML are the same refusal for a different reason.** Both walk instance
+variables directly, so neither needed ActiveSupport to reach the token — and neither is
+shadowed the way `Enumerable#as_json` shadowed the ivar walk, so `Marshal.dump(bc.messages)`
+reached the credential where `bc.messages.to_json` never did. They are also where a leaked
+token stops being a log line and becomes a token *at rest*: ActiveSupport's cache stores
+marshal what you write, so `Rails.cache.write("bc", bc)` landed it in Redis, memcached or
+a file; a Marshal-backed session landed it in the session; Delayed::Job YAMLs its handler
+into the database. `Marshal.load(Marshal.dump(x))`, the deep-copy idiom, refuses at the
+dump. (Queue backends that serialize arguments as **JSON** — ActiveJob and Sidekiq among
+them — go through `to_json`, and so were already closed in 0.10.1.)
+
+**Anything *holding* a client refuses too, models included** — both walkers recurse, so
+`Marshal.dump(message)` reaches the client and raises naming `BaseCradle::Client`. That is
+the fix, not a limitation: before, it emitted the token. It is also why **`.to_a` is only
+half the remedy for a dumper**: the array it hands back is full of models that each hold
+the client, so `Marshal.dump(bc.messages.to_a)` lands straight back on the same error.
+Dump the wire records — which is what you wanted in a cache anyway:
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.new
+message = bc.messages.first
+
+record = message.to_h                                  # the wire Hash, no client in it
+puts Marshal.load(Marshal.dump(record)) == record      # => true
+
+page = bc.messages.first(20).map(&:to_h)               # a whole page, no client in it
+puts Marshal.load(Marshal.dump(page)) == page          # => true
+```
+
+Rebuild a model from a cached record with `BaseCradle::Message.new(record, client: bc)`
+when you need its verbs back.
+
+Every refusal happens before any HTTP — but they are on the SDK's own objects. An
 `Enumerator` you built from one is a plain Ruby object this SDK does not own, so
 `render json: { recent: bc.messages.lazy }` and `bc.messages.each.to_json` still page the
-whole resource. Call `.first(n)` or `.to_a` before handing a query to a renderer.
+whole resource. **YAML reaches that escape on plain Ruby**, where the `to_json` version
+needs ActiveSupport: Psych iterates an `Enumerator` to dump it, so
+`bc.messages.each.to_yaml` fires the page-by-page GET loop and *then* raises
+`NotSerializableError` on the first record (which holds the client) — the requests are
+spent, and no document comes out. (`Marshal` is the exception: Ruby itself refuses to
+dump an `Enumerator` at all.) No token is exposed through any of them. Call `.first(n)`
+or `.to_a` before handing a query to a renderer, and `.map(&:to_h)` too before a dumper.
 
 `bc.inspect` and `"#{bc}"` are redacted for the same reason — Ruby's default `inspect`
 dumps every instance variable, which would print the token into every exception message

data/lib/basecradle/client.rb

@@ -243,14 +243,28 @@ module BaseCradle
 
     private
 
-    # Why +to_json+ / +as_json+ refuse (see BaseCradle::NotSerializable). A client is not
-    # a record, and the thing it would emit is a live credential.
+    # Why every serializer refuses — +to_json+ / +as_json+, +Marshal.dump+, +to_yaml+
+    # (see BaseCradle::NotSerializable). A client is not a record, and the thing it would
+    # emit is a live credential.
+    #
+    # The last sentence is for the caller who never named a client: Marshal and Psych
+    # recurse, so dumping a model or a resource reaches the client it holds and lands
+    # here. Telling that caller only about clients would be telling them about an object
+    # they did not pass — the Python SDK's +__reduce__+ is worded for the same reason
+    # ("copying a resource or a record reaches this too — copy the record's data").
+    #
+    # And it has to name +to_h+, because the first remedy does not hold through those two
+    # doors: a model serializes as its record through JSON, but <tt>Marshal.dump(bc.me)</tt>
+    # walks to the client again. Advice that fails through the door the reader just used
+    # is worse than none.
     def serialization_refusal
       "#{self.class} is a connection holding your bc_uat_ token, not a record. " \
-      "Serializing it writes the raw credential into whatever you were rendering or " \
-      "logging, and a token in a log is a token to rotate. Serialize the record you " \
-      "meant instead (bc.me, a timeline, a message), or bc.base_url to name the " \
-      "connection itself."
+      "Serializing it writes the raw credential into whatever you were rendering, " \
+      "logging or storing, and a token in a log or a cache is a token to rotate. " \
+      "Serialize the record you meant instead (bc.me, a timeline, a message), or " \
+      "bc.base_url to name the connection itself. Marshal and YAML reach a client " \
+      "through anything holding one, models included, so dump the wire record rather " \
+      "than the object: model.to_h holds no client."
     end
 
     # Record what the mint response said about the credential just issued. Private: only

data/lib/basecradle/errors.rb

@@ -30,10 +30,15 @@ module BaseCradle
   # this response form). The SDK raises rather than return an ambiguous nil.
   class MissingFieldError < Error; end
 
-  # A Client or a collection resource was serialized (+to_json+ / +as_json+). Neither is
-  # a record: a Client holds your bearer token, and a collection is a lazy query whose
-  # serialization would page the whole API from inside your renderer. The SDK refuses
-  # loudly rather than emit a credential or a heap address — see BaseCradle::NotSerializable.
+  # A Client or a collection resource was serialized — +to_json+ / +as_json+,
+  # +Marshal.dump+, or +to_yaml+ / +YAML.dump+. Neither is a record: a Client holds your
+  # bearer token, and a collection is a lazy query that holds the client and would page
+  # the whole API from inside your renderer. The SDK refuses loudly rather than emit a
+  # credential or a heap address — see BaseCradle::NotSerializable.
+  #
+  # It is also how a caller who serialized *neither* gets here: +Marshal+ and Psych
+  # recurse, so dumping a model reaches the client it holds and raises this, naming
+  # BaseCradle::Client. Dump the record's own data, +model.to_h+, which holds no client.
   class NotSerializableError < Error; end
 
   # The request never got an API response (DNS failure, refused connection, timeout).

data/lib/basecradle/serialization.rb

@@ -18,6 +18,17 @@ module BaseCradle
   # Without ActiveSupport the same calls were merely useless: +"#<BaseCradle::Client:0x…>"+,
   # a heap address that differs every run.
   #
+  # +Marshal+ and Psych are that same act through two doors ActiveSupport never touched.
+  # Both walk instance variables directly and neither consults +as_json+, so closing the
+  # JSON door left them open, needing no ActiveSupport to be reachable. They are also the
+  # worse pair, because they are what puts a credential *at rest*: ActiveSupport's cache
+  # stores marshal what you write, so <tt>Rails.cache.write("bc", bc)</tt> landed the
+  # token in Redis, memcached or a file; a Marshal-backed session landed it in the
+  # session; Delayed::Job YAMLs its handler into the database. And nothing shadows the
+  # ivar walk the way +Enumerable#as_json+ shadows +Object#as_json+ — so
+  # <tt>Marshal.dump(bc.messages)</tt> reached the token where <tt>bc.messages.to_json</tt>
+  # never did. Both doors now raise, on the same mixin, so every includer is covered.
+  #
   # Includers supply +serialization_refusal+; the default below is the honest fallback
   # for one that does not, so the failure is still a rescuable BaseCradle::Error rather
   # than a NoMethodError out of a renderer.
@@ -34,6 +45,24 @@ module BaseCradle
       raise NotSerializableError, serialization_refusal
     end
 
+    # +Marshal.dump+, and so every store built on it: ActiveSupport's cache backends, a
+    # Marshal-backed session, and the <tt>Marshal.load(Marshal.dump(x))</tt> deep-copy
+    # idiom. Marshal reaches for this hook before it walks ivars, so defining it is what
+    # stops the walk.
+    #
+    # Deliberately unpaired with a +marshal_load+: the pair only matters to something
+    # being loaded, and nothing can be loaded because nothing is ever dumped.
+    def marshal_dump
+      raise NotSerializableError, serialization_refusal
+    end
+
+    # Psych's hook — +to_yaml+, +YAML.dump+, and anything either one nests. Psych prefers
+    # +encode_with+ over its own ivar walk for any object that defines it. The coder is
+    # unused: it is the thing we decline to fill.
+    def encode_with(_coder)
+      raise NotSerializableError, serialization_refusal
+    end
+
     private
 
     def serialization_refusal
@@ -59,16 +88,31 @@ module BaseCradle
 
     private
 
-    # Deliberately does *not* claim a token leak. Measured on this tree: ActiveSupport's
+    # One message, four doors — and it names both harms because which one you get depends
+    # on the door, measured on this tree. Through JSON, ActiveSupport's
     # +Enumerable#as_json+ shadows +Object#as_json+, so a collection serialized as its
-    # fetched records, never as its ivars — the client it holds was never walked. The
-    # harm is the unbounded fetch and the records that came out with it.
+    # fetched records and the client in its ivars was never walked: the harm is the
+    # unbounded fetch. +Marshal+ and Psych have no such shadow and walked the ivars
+    # instead, reaching the token and writing it wherever the dump went.
+    #
+    # Naming only the fetch would have told a +Rails.cache.write+ caller their credential
+    # was slow to write rather than at rest in Redis — a wrong diagnosis being worse than
+    # a missing one. Naming both keeps one refusal per resource, which is what stops the
+    # doors drifting apart.
+    #
+    # The remedy is two-part for the same reason. <tt>.to_a</tt> alone is enough for JSON,
+    # where a model serializes as its record — but the array it hands back is full of
+    # models that each hold the client, so <tt>Marshal.dump(bc.messages.to_a)</tt> lands
+    # straight back here. Measured, not assumed.
     def serialization_refusal
-      "#{self.class} is a lazy, auto-paginating query, not a record, so there is no one " \
-      "record to serialize. Serializing it runs a page-by-page GET loop over the whole " \
-      "resource from inside your renderer, and emits every record it fetched. Call " \
-      ".to_a (or .first(n), or .filter(...).to_a) and serialize that — then how much you " \
-      "fetch is a visible act in your own code."
+      "#{self.class} is a lazy, auto-paginating query holding your connection, not a " \
+      "record, so there is no one record to serialize. Serializing it either runs a " \
+      "page-by-page GET loop over the whole resource from inside your renderer and " \
+      "emits every record it fetched, or writes out the connection it holds — your " \
+      "bc_uat_ token with it. Call .to_a (or .first(n), or .filter(...).to_a) and " \
+      "serialize that — then how much you fetch is a visible act in your own code. " \
+      "Marshal and YAML reach the client through the records too, so dump the wire " \
+      "records rather than the models: .to_a.map(&:to_h)."
     end
   end
 end

data/lib/basecradle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BaseCradle
-  VERSION = "0.10.2"
+  VERSION = "0.10.3"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.10.2
+  version: 0.10.3
 platform: ruby
 authors:
 - Drawk Kwast