basecradle 0.10.0 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3acdf9b8dad4d29a40926030c480cc415b96ffff03c56a121838b4fdb42cd638
-  data.tar.gz: 2b88488a27cae407aa366cce9899da840b7ea1e74db86d21c511f0f2b1ac47d7
+  metadata.gz: 0a805499915d7672ddf23664f7a5147b41915446a488a122c018cb46ac65f076
+  data.tar.gz: 5739cfa3f912b9d9d29d03a9a083c58371175b0bd7dd75dbad1ee6209d426288
 SHA512:
-  metadata.gz: 7f753c98128c1935e0503dd1963917ac1918e171401b4a39f6c1b650cd716213f02c52b1dd538a54bb201de0ede89af19e7ab2ec9abfa79d2eba68d71faa5f57
-  data.tar.gz: 31772a4161d2e3563a835ffbd2c9ae5a2d9e285a157ca2772be3213037297b168f8e89b67e8290a7897a77a009add74b9769bf5e623ac5256ec19f26eece04d9
+  metadata.gz: 3836f2b3204ca798e3d2c4bd17dcc43f59faf0dc86c7097504f05e01519e5d91cc8c10f0889852899c64a816ef7c33da009cd3a2948f0f9cd8019ee279246870
+  data.tar.gz: 44894880f4119664ffdceff8d9550b8d69e715073a55ad31287bfbd507ba8a7758bc92003de5fb0f1e8b17919ddf3f0968ff4c6344c988c53f91360aca5c685d

data/CHANGELOG.md

@@ -9,6 +9,60 @@ 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.1] - 2026-09-30
+
+### Security
+
+- **A `Client` no longer serializes, and never emits its token**
+  ([#198](https://github.com/basecradle/basecradle-ruby/issues/198)). A client is a
+  connection, not a record, and it defined no `as_json`/`to_json` — so with ActiveSupport
+  loaded it fell through to `Object#as_json`, which is `instance_values`, walked
+  recursively. Its instance variables include the raw `bc_uat_` token, so
+  `render json: { conn: bc }` or `logger.info({ conn: bc }.to_json)` wrote the live
+  credential into a response body or a log line, and **a token in a log is a token to
+  rotate**. `bc.to_json` now raises `BaseCradle::NotSerializableError`, a
+  `BaseCradle::Error`, naming what to serialize instead. Long-standing and latent; no
+  token is known to have been emitted.
+- **`Client#inspect` and `#to_s` redact the token** — the same exposure through a
+  different door. Ruby's default `inspect` dumps every instance variable, so the
+  credential printed into every exception message, REPL transcript and `p` call that
+  touched a client. Both now read
+  `#<BaseCradle::Client base_url="https://basecradle.com" token=[REDACTED]>`, with `to_s`
+  the same string because interpolation is the door people reach for without thinking.
+
+### Fixed
+
+- **A collection resource no longer serializes either.** `bc.timelines`, `bc.messages`,
+  `timeline.tasks`, any `.filter(...)`, and the `Paginator` behind them are lazy queries,
+  not records. ActiveSupport's `Enumerable#as_json` calls `to_a`, so serializing one ran
+  a page-by-page GET loop over the whole resource from **inside a view render** and
+  emitted every record it fetched. It did *not* reach the token — `Enumerable#as_json`
+  shadows the `instance_values` walk above — but a client's instance variables are eight
+  collections, so serializing a client fired those loops on its way to the credential.
+  All of them now raise the same `NotSerializableError`, before any HTTP, pointing at
+  `.to_a` so how much you fetch is a visible act in your own code.
+  Without ActiveSupport these calls were useless rather than dangerous
+  (`"#<BaseCradle::MessagesResource:0x…>"`, the heap address 0.10.0 removed for models);
+  that is closed too.
+- **The collection resources' `inspect` is unchanged** and still shows Ruby's default
+  ivar dump — which renders the client through the redacting `Client#inspect` above, so
+  no token reaches it. Pinned by test so it stays that way.
+
+### Known limitation
+
+The refusals are on the SDK's own objects. An `Enumerator` built from a collection —
+`bc.messages.each`, `bc.messages.lazy` — is a plain Ruby object this SDK does not own,
+and ActiveSupport gives it an `as_json` that calls `to_a`, so
+`render json: { recent: bc.messages.lazy }` still pages the whole resource. No token is
+exposed; call `.first(n)` or `.to_a` before handing a query to a renderer.
+
+### Migrating
+
+Nothing to change unless you were serializing a `Client` or a collection, which never
+emitted anything useful and, for a client under ActiveSupport, emitted your token. If you
+were: serialize the record you meant (`bc.me`, a timeline, a message), or call `.to_a` /
+`.first(n)` on a collection first.
+
 ## [0.10.0] - 2026-09-30
 
 ### Fixed
@@ -396,6 +450,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.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
 [0.9.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.9.0
 [0.8.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.8.0

data/README.md

@@ -359,6 +359,57 @@ something Rails renders comes out right too. Three caveats worth knowing:
   pretty-prints. What an unknown option does is your `json` version's business — 3.x
   raises, the 2.x older Rubies ship ignores it.
 
+## 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:
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.new
+
+begin
+  bc.to_json                          # and render json: { conn: bc }
+rescue BaseCradle::NotSerializableError => e
+  puts e.message.include?("bc_uat_")  # => true
+end
+
+begin
+  bc.messages.to_json                 # a lazy query, not a record
+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
+```
+
+A **client** holds your `bc_uat_` token, and under ActiveSupport `Object#as_json` is
+`instance_values` — walked recursively. So `render json: { conn: bc }` or
+`logger.info({ conn: bc }.to_json)` used to write the raw credential into a response body
+or a log line, and a token in a log is a token to rotate.
+
+A **collection** (`bc.timelines`, `bc.messages`, `timeline.tasks`, any `.filter(...)`) is
+a lazy query. ActiveSupport's `Enumerable#as_json` calls `to_a`, so serializing one ran a
+page-by-page GET loop over the whole resource from inside the render and emitted every
+record it fetched. (It did *not* reach the token — `Enumerable#as_json` shadows the ivar
+walk — but a client's instance variables are eight collections, so serializing a *client*
+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
+`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.
+
+`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
+and REPL transcript that touched a client:
+
+```
+#<BaseCradle::Client base_url="https://basecradle.com" token=[REDACTED]>
+```
+
 ## Development
 
 ```bash

data/lib/basecradle/client.rb

@@ -7,6 +7,7 @@ require "uri"
 require_relative "dashboard"
 require_relative "errors"
 require_relative "items"
+require_relative "serialization"
 require_relative "sessions"
 require_relative "timelines"
 require_relative "user"
@@ -23,6 +24,10 @@ module BaseCradle
   # Every resource is built on +#request+, which is also the escape hatch for API
   # endpoints added before the SDK wraps them (the API is additive-only).
   class Client
+    # A client is a connection holding a live credential, never a record: serializing one
+    # raises rather than write the token into a response body or a log line.
+    include NotSerializable
+
     DEFAULT_BASE_URL = "https://basecradle.com"
     DEFAULT_TIMEOUT = 30
 
@@ -192,8 +197,20 @@ module BaseCradle
       handle(response)
     end
 
+    # Never the token. Ruby's default +inspect+ dumps every ivar, which would print the
+    # credential into every exception message, REPL transcript and +p+ call that touched
+    # a client — the same leak as serializing one, through a different door. The
+    # redaction marker is fixed text, so what it stands for cannot be guessed from its
+    # length. +to_s+ is the same string: string interpolation is the door people reach
+    # for without thinking about it.
     def inspect
-      "#<#{self.class} base_url=#{@base_url.inspect}>"
+      "#<#{self.class} base_url=#{@base_url.inspect} token=[REDACTED]>"
+    end
+
+    # Late-bound rather than `alias to_s inspect`, so a subclass that redacts more in
+    # inspect is not bypassed by interpolation.
+    def to_s
+      inspect
     end
 
     # The shared low-level send: returns the Net::HTTPResponse or raises APIConnectionError.
@@ -226,6 +243,16 @@ 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.
+    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."
+    end
+
     # Record what the mint response said about the credential just issued. Private: only
     # +.login+ calls it, on a client it has just built.
     def minted(body)

data/lib/basecradle/errors.rb

@@ -30,6 +30,12 @@ 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.
+  class NotSerializableError < Error; end
+
   # The request never got an API response (DNS failure, refused connection, timeout).
   # The underlying exception is preserved as +cause+.
   class APIConnectionError < Error; end

data/lib/basecradle/items.rb

@@ -5,6 +5,7 @@ require "time"
 
 require_relative "api_object"
 require_relative "pagination"
+require_relative "serialization"
 require_relative "user"
 
 module BaseCradle
@@ -93,6 +94,7 @@ module BaseCradle
   # PLURAL / SINGULAR / MODEL.
   class ItemsResource
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, filters: {})
       @client = client
@@ -163,6 +165,7 @@ module BaseCradle
   # One timeline's messages: create here, or iterate (newest first).
   class TimelineMessages
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, timeline_uuid)
       @client = client
@@ -190,6 +193,7 @@ module BaseCradle
   # One timeline's assets: upload here (multipart), or iterate (newest first).
   class TimelineAssets
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, timeline_uuid)
       @client = client
@@ -234,6 +238,7 @@ module BaseCradle
   # One timeline's tasks: create here, or iterate (newest first).
   class TimelineTasks
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, timeline_uuid)
       @client = client

data/lib/basecradle/pagination.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "serialization"
+
 module BaseCradle
   # The shared cursor-pagination engine. Every list endpoint paginates the same way:
   # newest first, up to 50 per page, +next_cursor+ in the response passed back as
@@ -10,6 +12,7 @@ module BaseCradle
   # and cursors never appear in calling code.
   class Paginator
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, path, envelope_key:, model:, params: nil)
       @client = client

data/lib/basecradle/serialization.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "errors"
+
+module BaseCradle
+  # Refuse to serialize an object that is a connection or a live query rather than a
+  # record, and say what to serialize instead.
+  #
+  # With ActiveSupport loaded, +Object#as_json+ is +instance_values+ — every instance
+  # variable, walked recursively. A Client's ivars include its raw +bc_uat_+ token, so
+  # <tt>render json: { conn: bc }</tt> or <tt>logger.info({ conn: bc }.to_json)</tt> put
+  # the credential in a response body or a log line, and **a token in a log is a token to
+  # rotate**. That same walk reaches the client's eight collection ivars, and
+  # ActiveSupport's +Enumerable#as_json+ calls +to_a+ — so serializing a client also fired
+  # a live, unbounded, page-by-page GET loop before it got to the token, and serializing a
+  # collection on its own fired one from inside the render for no stated reason.
+  #
+  # Without ActiveSupport the same calls were merely useless: +"#<BaseCradle::Client:0x…>"+,
+  # a heap address that differs every run.
+  #
+  # 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.
+  module NotSerializable
+    # ActiveSupport's serialization hook — what reaches this object when it is nested in
+    # something Rails renders (<tt>render json: { conn: bc }</tt>).
+    def as_json(*)
+      raise NotSerializableError, serialization_refusal
+    end
+
+    # +JSON.generate+, +Hash#to_json+, +Array#to_json+ and a bare
+    # <tt>render json: bc</tt> all arrive here.
+    def to_json(*)
+      raise NotSerializableError, serialization_refusal
+    end
+
+    private
+
+    def serialization_refusal
+      "#{self.class} is not a record and cannot be serialized."
+    end
+  end
+
+  # What every lazy collection resource mixes in — the auto-paginating resources
+  # (+bc.timelines+, +bc.messages+, +timeline.tasks+, any +.filter(...)+) and the
+  # Paginator behind them.
+  #
+  # It includes +Enumerable+ itself, and that is load-bearing rather than tidy:
+  # ActiveSupport defines +as_json+ and +to_json+ on +Enumerable+, so the refusal only
+  # takes effect while it sits *ahead* of Enumerable in the ancestor chain. Pulling
+  # Enumerable in here makes that true whichever order an including class writes its
+  # +include+ lines — a module already in the chain is not moved by a later include — so
+  # the guarantee is structural instead of a rule in a comment that a future resource can
+  # forget. The classes still write +include Enumerable+ explicitly, because being
+  # Enumerable is part of what they are.
+  module NotSerializableCollection
+    include Enumerable
+    include NotSerializable
+
+    private
+
+    # Deliberately does *not* claim a token leak. Measured on this tree: 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.
+    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."
+    end
+  end
+end

data/lib/basecradle/sessions.rb

@@ -2,6 +2,7 @@
 
 require_relative "api_object"
 require_relative "pagination"
+require_relative "serialization"
 
 module BaseCradle
   # One credential you hold — a web sign-in or a bc_uat_ API token.
@@ -39,6 +40,7 @@ module BaseCradle
   #   end
   class SessionsResource
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client)
       @client = client

data/lib/basecradle/timelines.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "pagination"
+require_relative "serialization"
 require_relative "timeline"
 
 module BaseCradle
@@ -10,6 +11,7 @@ module BaseCradle
   # method (+map+, +find+, +first+ — which stop early without fetching every page).
   class TimelinesResource
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client)
       @client = client

data/lib/basecradle/user.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "api_object"
+require_relative "serialization"
 
 module BaseCradle
   # The trust relationship between you and another user, from your point of view.
@@ -98,6 +99,7 @@ module BaseCradle
   #   bc.users.each { |user| puts [user.handle, user.kind, user.trust.mutual].inspect }
   class UsersResource
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client)
       @client = client

data/lib/basecradle/version.rb

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

data/lib/basecradle/webhooks.rb

@@ -2,6 +2,7 @@
 
 require_relative "api_object"
 require_relative "items"
+require_relative "serialization"
 require_relative "user"
 
 module BaseCradle
@@ -260,6 +261,7 @@ module BaseCradle
   # One timeline's webhook endpoints: create here, or iterate (newest first).
   class TimelineWebhookEndpoints
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, timeline_uuid)
       @client = client
@@ -287,6 +289,7 @@ module BaseCradle
   # One timeline's webhook events — read-only, so iterate is all there is.
   class TimelineWebhookEvents
     include Enumerable
+    include NotSerializableCollection
 
     def initialize(client, timeline_uuid)
       @client = client

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.10.0
+  version: 0.10.1
 platform: ruby
 authors:
 - Drawk Kwast
@@ -26,6 +26,7 @@ files:
 - lib/basecradle/errors.rb
 - lib/basecradle/items.rb
 - lib/basecradle/pagination.rb
+- lib/basecradle/serialization.rb
 - lib/basecradle/sessions.rb
 - lib/basecradle/timeline.rb
 - lib/basecradle/timelines.rb