basecradle 0.10.1 → 0.10.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0a805499915d7672ddf23664f7a5147b41915446a488a122c018cb46ac65f076
-  data.tar.gz: 5739cfa3f912b9d9d29d03a9a083c58371175b0bd7dd75dbad1ee6209d426288
+  metadata.gz: b1fc584abdde2edfd9233ea937bf054ba6fb672708b6c815014d46a1dc4d59c2
+  data.tar.gz: bc53a3e49ad9eb40fd21e5fb2fe424d054738359a30eb2c137a26c8a5f634d27
 SHA512:
-  metadata.gz: 3836f2b3204ca798e3d2c4bd17dcc43f59faf0dc86c7097504f05e01519e5d91cc8c10f0889852899c64a816ef7c33da009cd3a2948f0f9cd8019ee279246870
-  data.tar.gz: 44894880f4119664ffdceff8d9550b8d69e715073a55ad31287bfbd507ba8a7758bc92003de5fb0f1e8b17919ddf3f0968ff4c6344c988c53f91360aca5c685d
+  metadata.gz: c603f01c320e465db82dc376ad78cfca4d52c63db107580be7366d2a2c3b79f99e1d5b3f356917bd1526b9f63bb294747cc218a1e7cf71e8fc22caa41ccc4b34
+  data.tar.gz: 401d5b9b58f5dc726fb3bc457180954b582e077b8b0aa224c0f92513a39c4122bac16ea56dfff4746e44e2b252cc88ab8a6cf12b178d989ee1eed5b2caf1d02a

data/CHANGELOG.md

@@ -9,6 +9,121 @@ 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
+
+- **`WebhookEventHeaders` no longer prints header values when inspected**
+  ([#206](https://github.com/basecradle/basecradle-ruby/issues/206)). An inbound
+  delivery's headers are the *sender's*, stored verbatim by the platform, so one of them
+  may be the sender's own credential — a POST authenticated to an ingest URL carries its
+  `Authorization` or `X-Api-Key` right there. `WebhookEventHeaders` is a `Hash`
+  descendant and inherited `Hash`'s render, which prints every pair, so
+  `logger.debug(event.content.headers)` wrote **another party's secret** into your logs.
+  `inspect`, `to_s` and `pp` now render the header names alone, sorted, matching the rule
+  every other object in this SDK already followed (`ApiObject#inspect` prints field
+  names, never values):
+
+  ```
+  #<BaseCradle::WebhookEventHeaders Authorization, Content-Type, X-Api-Key>
+  ```
+
+  **Only the human-facing render changed.** Every read is untouched and still wire-exact:
+  the case-folded lookup, `fetch`, `each`, `keys`, `to_h`, `to_json`, `==`. If you were
+  relying on `inspect` to see values, use `to_h` — which is what it was always for. No
+  credential of yours was exposed; the exposure was of whoever sent you the webhook, so
+  if you have logged inbound deliveries at debug level, treat those senders' headers as
+  disclosed.
+- **Two ways a header value still reaches a log, both by design.** `to_json`/`as_json`
+  emit the delivery verbatim — that is what a webhook record *is* — so
+  `render json: event` and `logger.info(event.to_json)` still write the sender's headers
+  in full. And converting away from the type gives up the redaction exactly as it gives up
+  the case-folding: `slice`, `except`, `select`, `transform_values` and `to_h` each hand
+  back a plain `Hash`, whose `inspect` prints pairs. Only `merge` and `dup` keep the type,
+  and so the redaction. Changing what a webhook record *serializes* as is a separate
+  decision and is not made here.
+
 ## [0.10.1] - 2026-09-30
 
 ### Security
@@ -450,6 +565,8 @@ 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
 [0.9.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.9.0

data/README.md

@@ -220,6 +220,19 @@ fallback-less `fetch` raise `KeyError` naming the headers that did arrive, while
 and the methods that reshape it (`slice`, `except`, `select`) work on those stored names,
 case-sensitively.
 
+What it does **not** show you is the values. `inspect`, `to_s` and `pp` print the header
+names alone — `#<BaseCradle::WebhookEventHeaders Authorization, Content-Type>` — because
+these headers are the **sender's**, and a sender that authenticates its POST to your
+ingest URL carries its credential in one of them. So `logger.debug(event.content.headers)`
+cannot write another party's secret into your logs. Every read is unaffected; `to_h` is
+how you look at values.
+
+Two things do still show them, deliberately. `to_json` emits the delivery verbatim — that
+is what the record is — so `render json: event` and `logger.info(event.to_json)` write the
+headers in full. And converting away from the type gives up the redaction exactly as it
+gives up the case-folding: `slice`, `except`, `select`, `transform_values` and `to_h` hand
+back a plain `Hash`, which prints pairs. `merge` and `dup` keep the type, and keep both.
+
 This holds however you reach the record. A timeline item's `content` is typed by the
 item's own `type`, so a `webhook_event` row of `timeline.items` is a `WebhookEventContent`
 just like one from `bc.webhook_events` — `item.content.headers["X-GitHub-Delivery"]` folds
@@ -362,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
 
@@ -381,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
 ```
 
@@ -397,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
@@ -426,6 +496,12 @@ CI additionally lints the workflow files with [actionlint](https://github.com/rh
 both and run `actionlint` from the repo root — CI pins actionlint by version and SHA256 in
 `.github/workflows/ci.yml`; match that version to see what CI sees.
 
+Bare `actionlint` covers slightly more than CI blocks on. It lints everything under
+`.github/workflows`, including `needs-human-alert.yml` and `dependabot-auto-merge.yml`,
+which are shared verbatim from the BaseCradle core repo and are not this repo's to edit;
+CI lints those two advisory-only, so a finding in them is reported upstream rather than
+failing the build. A finding in any other workflow does fail it.
+
 ## Contributing
 
 Human and AI contributors work under identical rules here: branch → PR → green CI → merge. See [`CLAUDE.md`](CLAUDE.md) for the project conventions and the issues for the roadmap.

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.1"
+  VERSION = "0.10.3"
 end

data/lib/basecradle/webhooks.rb

@@ -99,6 +99,14 @@ module BaseCradle
   # that already happened. Converting away from this type gives up the folding too
   # (+to_h+, <tt>{**headers}</tt>, and anything else that hands back a plain +Hash+);
   # +merge+ and +dup+ keep it.
+  #
+  # What it does *not* print is the values: +inspect+, +to_s+ and +pp+ render the header
+  # names alone, because these are the sender's headers and one of them may be the
+  # sender's credential. Every read is unaffected — and so is +to_json+, which still
+  # emits the delivery verbatim. Converting away from this type gives the redaction up
+  # exactly as it gives up the folding, and for the same reason: +slice+, +except+,
+  # +select+, +transform_values+ and +to_h+ hand back a plain +Hash+, whose +inspect+
+  # prints pairs.
   class WebhookEventHeaders < Hash
     # Hash's own exact-match membership, kept under a private name before the case-folding
     # +key?+ below takes the name: a caller who wrote the wire's own spelling is answered
@@ -167,6 +175,43 @@ module BaseCradle
       ->(name) { dig(name) }
     end
 
+    # The header *names* this delivery carried, and none of their values.
+    #
+    # +Hash+'s own +inspect+ prints every pair, and these headers are the *sender's*,
+    # stored verbatim by the platform: a sender that authenticates its POST to an ingest
+    # URL puts its credential in one of them, so +logger.debug(event.content.headers)+
+    # would write another party's secret into our logs. Every other renderable object in
+    # this SDK is already safe by one rule — +ApiObject#inspect+ prints field names, never
+    # values — and this is the one class that sat outside it, because +Hash+ brought its
+    # own render.
+    #
+    # Only the human-facing render changes. Every *read* is untouched and still
+    # wire-exact: lookups, +fetch+, +each+, +keys+, +to_h+, +to_json+, +==+.
+    #
+    # Names are sorted, as +ApiObject#inspect+ sorts its fields and as the +KeyError+ a
+    # missing header raises already lists the ones that did arrive.
+    def inspect
+      return "#<#{self.class}>" if empty?
+
+      "#<#{self.class} #{keys.sort_by(&:to_s).join(', ')}>"
+    end
+
+    # +Hash+ aliases +to_s+ to its *own* +inspect+ — one shared method entry — so
+    # overriding +inspect+ alone would leave <tt>"#{headers}"</tt> and +puts headers+
+    # printing every value. Late-bound rather than +alias to_s inspect+, so a subclass
+    # that redacts more is not bypassed by interpolation (as +Client#to_s+ is).
+    def to_s
+      inspect
+    end
+
+    # +pp+ reaches for +pretty_print+, and +Hash+ brings one that prints the pairs — the
+    # same leak through the one door +inspect+ does not cover. Delegating puts +pp+ back
+    # on the SDK-wide rule: +pp+ uses an object's own +inspect+ when it defines one, which
+    # is why every +ApiObject+ is already safe here and only a +Hash+ descendant was not.
+    def pretty_print(printer)
+      printer.text(inspect)
+    end
+
     private
 
     # The wire's own spelling of +name+, or nil if no casing of it was delivered. Anything

metadata

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