bug_bunny 5.1.0 → 5.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 877e5f5961f53d587b2bc67e6a8c39d247b996e1272ddad076236633df65f267
-  data.tar.gz: 6928594ae30624f1dccd2841594bee4b0faed40ee0cd238a69387399559a757b
+  metadata.gz: dd173a6f940a79457235d63629891426cba1f94a8381c19a219e38f275fe96dd
+  data.tar.gz: 78f927d9ed2ef4d04bf5b3059a3b3d54b93974ee11a8d7235ade9ae82095a51b
 SHA512:
-  metadata.gz: fea6d7206396aae6ff2b35277e651ed944bee590f74200a392f2fb962af8757f56057b6d637434a91603d272b59b6215b459b330e98999d37f72d1c2ad6af763
-  data.tar.gz: b9d531b234ec094ab7127ea5921506d92a32e57961463904e6a62e158ce8a8e3020368ff1c6006cb30ae62a5beea942f3c004ce33e91362c910de2e87165aa6e
+  metadata.gz: 188ad45954c08cf19dda7625236fdc8da934676de77a6af7136547893f2fc8ae0ad782aa890782dbd59e16b39b90d8fa8dec3f9b1c9a5c3b4b4fd22db5c77f8f
+  data.tar.gz: 87bf5385a97fea06f86fccb396ade8ce2602ec831181e4a2ba7893711a784eccb4d922ca4303137f0e25f7a625d88d015e61858f4f48209fa89624ae02a92cea

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [5.1.1] - 2026-07-31
+
+### Correcciones
+- **`safe_log` redacta credenciales embebidas en el VALOR, no solo por nombre de clave (#61):** el filtro por-clave solo ve el NOMBRE, así que una credencial en texto libre pasaba entera al log. El caso canónico es el `message` de una excepción inesperada, que llega como `reason=`/`error_message=` —nombres no sensibles— y puede arrastrar `Authorization: "Bearer …"`. Se agrega `Observability.redact_value`, aplicada a todo valor no numérico que `safe_log` serializa, con tres reglas: esquemas de auth HTTP (`Bearer`/`Basic`), key sensible dentro del texto (conserva el nombre de la key y filtra solo el valor) y credenciales en URL (`user:pass@host`). Cubre las variantes con separador y camelCase (`access_token=`, `user_password=`, `accessToken=`), igual que el matching por substring de `sensitive_key?`. No-breaking: no cambia firmas ni el formato `k=v`, y un log sin credenciales sale idéntico. Riesgo asumido: sobre-redacción de contenido diagnóstico anclado a marcadores de credencial (un `token=missing` sale filtrado). — @gedera
+- **Un valor `Hash` sigue siendo JSON parseable después de redactar:** se agrega `Observability.redact_structure`, que redacta la estructura **antes** de serializar (recorre `Hash` anidado y `Array`) en vez de aplicar el regex sobre el JSON ya serializado, que colapsaba el par `"token": "abc"` y dejaba el campo sin parsear — el secreto desaparecía, pero quien consume el log perdía el objeto entero. De paso, las keys internas del `Hash` ahora también pasan por `sensitive_key?`. — @gedera
+
+### Documentación
+- La lista de claves sensibles **deja de replicarse**: el docblock de `Error#raw_response` y `docs/errors/` apuntan a `Observability::SENSITIVE_KEYS` como canónica, en vez de duplicarla. La copia venía desincronizada (incluía `pass` bare, que está excluido a propósito para no filtrar `passport_number`, y le faltaban `authorization`, `credential`, `private_key`, `csrf`, `session_id`). `docs/glossary/`, README y `skill/` describen ahora las dos capas de redacción. — @Pslp
+
 ## [5.1.0] - 2026-07-22
 
 ### Nuevas funcionalidades

data/README.md

@@ -365,7 +365,10 @@ BugBunny measures and emits durations automatically — **there is no need to wr
 | `consumer.message_processed` | `duration_s` | Message processing (router + controller + reply). |
 | `consumer.execution_error` | `duration_s` | Elapsed time until the error. |
 
-Sensitive keys (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) are automatically filtered to `[FILTERED]` across all log output.
+Credentials are redacted to `[FILTERED]` across all log output, in two layers:
+
+- **By key name** — sensitive keys (`password`, `token`, `secret`, `api_key`, `authorization`, etc.) are matched as substrings, so variants like `user_password` or `accessToken` are covered too.
+- **By value content** — a credential embedded in free text is redacted even when the key name is *not* sensitive. The canonical case: an unexpected exception whose `message` carries `Authorization: "Bearer …"` and reaches the log as `reason=`. Covers HTTP auth schemes, a sensitive key inside the text, and credentials in a URL. `Hash` values are redacted **before** being serialized, so the field stays valid JSON.
 
 ---
 
@@ -429,20 +432,31 @@ end
 
 Artefactos de detalle (modelo `dev-*`, RFC-001). El README indexa; no duplica.
 
+Anclado a `v5.1.1`.
+
 | Capa | Artefacto | Estado |
 |---|---|---|
-| Datos | — | n/a — gema sin DB (sin schema/models) |
 | Glosario | [docs/glossary/glossary.md](docs/glossary/glossary.md) | parcial, acreta por PR |
 | Comportamiento | [docs/behavior/behavior.md](docs/behavior/behavior.md) | completa — 6 flujos (backfill on-demand) |
-| Operaciones / Interfaz / Topología | — | F2 no implementado (dev-structure) — ver nota |
+| Configuración | [docs/config/configuracion.md](docs/config/configuracion.md) | §a-§e/§i estructura + §f/§g/§h enrich — completa |
+| Dependencias consumidas | [docs/consumed/rabbitmq.md](docs/consumed/rabbitmq.md) | §a/§b/§d estructura + §c/§e enrich |
+| Errores | [docs/errors/errors.md](docs/errors/errors.md) | §a/§b/§d completas; §c política inferida (verificación humana pendiente) |
+| Test | [docs/test/testing.md](docs/test/testing.md) | §a-§h — 16 unit / 7 integration |
+| Release | [docs/release/release.md](docs/release/release.md) | completa (régimen gema: build→publish; §e/f/g n/a) |
+| Datos | — | n/a — gema sin DB (sin schema/models) |
+| Eventos | — | n/a — la gema **es** el transporte; no declara catálogo de eventos de dominio propio |
+| Seguridad | — | n/a — sin authn/authz propias; el guard anti-RCE (403) se documenta en `docs/errors/` |
+| Operaciones / Interfaz / Topología | — | pendiente — ver nota |
 
-**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras la capa de detalle destino (operaciones/interfaz/topología) esté declarada pero **no implementada** (dev-structure F1, F2 del plan), permanecen embebidos/cruzados, bajo el interim normado:
+**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras las capas `docs/api/` (operaciones), `docs/interface/` y `docs/topology/` no estén generadas para este repo, el contrato que les correspondería permanece embebido:
 
-- **En este README:** el contrato (jerarquía de excepciones, API de configuración, modos de entrega).
+- **En este README:** la jerarquía de excepciones, la API de configuración y los modos de entrega.
 - **En `skill/SKILL.md`:** además el diagrama de arquitectura (flujo RPC).
 - **Guías how-to** (`skill/references/*.md`, pre-estándar): el README las enlaza pese a la regla "no referenciar `skill/` desde el README" — destino futuro `docs/howto/`.
 
-Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando F2 entregue, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando se generen, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+
+> **Nota de alcance (2026-07-31):** la justificación original de este interim era que el generador no implementaba esas capas. Ya las implementa, así que el pendiente es de **este repo**, no de tooling — en particular `docs/interface/` (RFC-004), que es donde correspondería registrar la API pública de la gema. Queda como trabajo propio, fuera del alcance de este release.
 
 How-to (pre-estándar):
 [Routing](skill/references/routing.md) ·

data/docs/errors/errors.md

@@ -1,10 +1,11 @@
 # Errores — bug_bunny
 
 > meta: artefacto errores · RFC-020 · generado `arch-structure` (§a/§b/§d) +
-> `arch-enrich` (§c) · anclado a `d0533bf`, `lib/bug_bunny/exception.rb`,
-> `remote_error.rb`, `middleware/raise_error.rb`, `controller.rb`, `consumer.rb`
-> · fecha 2026-06-30 · cobertura: §a/§b/§d completas (estructura); §c política
-> completa (enrich, **inferida** de HTTP/AMQP — verificación humana pendiente).
+> `arch-enrich` (§c) · anclado a `5697541`, `lib/bug_bunny/exception.rb`,
+> `remote_error.rb`, `middleware/raise_error.rb`, `controller.rb`, `consumer.rb`,
+> `observability.rb` · fecha 2026-07-31 · cobertura: §a/§b/§d completas
+> (estructura); §c política completa (enrich, **inferida** de HTTP/AMQP —
+> verificación humana pendiente).
 
 ## 1. Resumen
 
@@ -156,8 +157,13 @@ parsea el body, devuelve `parsed['errors']` por convención o el cuerpo completo
 
 > **Seguridad (cruza RFC-017):** `raw_response` puede contener datos sensibles en
 > `details`. La gema lo entrega crudo a propósito; **sanitizar antes de cualquier
-> sink** (Sentry/logs) filtrando `password|pass|passwd|secret|token|api_key|auth`
-> → `[FILTERED]` es responsabilidad del consumidor (`exception.rb:25-30`).
+> sink** (Sentry/logs) es responsabilidad del consumidor (`exception.rb:25-34`).
+> La lista canónica de claves sensibles es `Observability::SENSITIVE_KEYS`
+> (`observability.rb:13-16`) y **no se replica acá** — replicarla la desincroniza
+> (ojo: `pass` bare NO está en la lista, a propósito, para no filtrar
+> `passport_number`). Para sanear se reusa `Observability.sensitive_key?` (filtra
+> por NOMBRE de clave) y `Observability.redact_structure` (recorre la estructura
+> y además redacta credenciales embebidas en el VALOR → `[FILTERED]`).
 
 ## 3. Inferencias
 

data/docs/glossary/glossary.md

@@ -1,6 +1,6 @@
 # Glosario — bug_bunny
 
-> meta: artefacto `glosario` · RFC-009 (binding opcional, r: §2 materialización no-tabular) · generado dev-enrich (siembra) · anclado a `a5cdb10` · cobertura: parcial, acreta por PR
+> meta: artefacto `glosario` · RFC-009 (binding opcional, r: §2 materialización no-tabular) · generado dev-enrich (siembra) · anclado a `5697541` · fecha 2026-07-31 · cobertura: parcial, acreta por PR
 
 ## 1. Resumen
 
@@ -127,7 +127,7 @@ Cadena transversal que corre antes del dispatch al controller (tracing, auth, lo
 - `lib/bug_bunny/consumer_middleware.rb` — `BugBunny::ConsumerMiddleware`
 
 ## Observability
-Mixin de logging estructurado `key=value` que implementa OTel semantic conventions for messaging; `safe_log` nunca lanza; filtra claves sensibles a `[FILTERED]`.
+Mixin de logging estructurado `key=value` que implementa OTel semantic conventions for messaging; `safe_log` nunca lanza; redacta a `[FILTERED]` en dos capas — por **NOMBRE de clave** (`sensitive_key?`, substring sobre `SENSITIVE_KEYS`) y por **CONTENIDO del valor** (`redact_value`, para la credencial embebida en texto libre que la capa de clave no ve; `redact_structure` para un `Hash`, redactado antes de serializar para no romper el JSON).
 
 **Binding:**
 - `lib/bug_bunny/observability.rb` — `BugBunny::Observability`

data/docs/release/release.md

@@ -2,8 +2,9 @@
 
 > meta: artefacto release · RFC-014 (`accepted`) · generado por `arch-structure`
 > + `arch-enrich` (híbrido RFC-014 §2; nació como piloto manual #51, re-anclado
-> a la RFC vigente) · anclado a `.github/workflows/release.yml`, `*.gemspec`,
-> `lib/bug_bunny/version.rb`, `CHANGELOG.md`, git · fecha 2026-06-30 · cobertura:
+> a la RFC vigente) · anclado a `5697541`
+> (`.github/workflows/release.yml`, `*.gemspec`, `lib/bug_bunny/version.rb`,
+> `CHANGELOG.md`) · fecha 2026-07-31 · cobertura:
 > completa (régimen gema: build→publish, §e/f/g n/a).
 
 ## 1. Resumen
@@ -20,9 +21,9 @@ out-of-repo).
 
 ### a. Hecho verificable
 
-- **Convención de versión:** SemVer `vX.X.X`. Actual: **4.19.0**.
-- **Source of truth:** tag remoto (`v4.19.0`) + **triple mirror**
-  `lib/bug_bunny/version.rb` (`VERSION = '4.19.0'`) ← `bug_bunny.gemspec:7`
+- **Convención de versión:** SemVer `vX.X.X`. Actual: **5.1.1**.
+- **Source of truth:** tag remoto (`v5.1.1`) + **triple mirror**
+  `lib/bug_bunny/version.rb` (`VERSION = '5.1.1'`) ← `bug_bunny.gemspec:7`
   (`spec.version = BugBunny::VERSION`).
 - **Changelog canónico:** `CHANGELOG.md` único.
 - **Patrón de trigger:** `gema-tag` (patrón 1).
@@ -33,7 +34,7 @@ out-of-repo).
 
 - **Convención:** SemVer `vX.X.X` (**con `v`** — distinto al servicio).
 - **Source of truth:** tag remoto canónico (`git tag --sort=-v:refname` →
-  `v4.19.0`).
+  `v5.1.1`).
 - **Mirror:** `lib/bug_bunny/version.rb` (`VERSION`), leído por
   `bug_bunny.gemspec:7` (`spec.version = BugBunny::VERSION`).
   `required_ruby_version >= 2.6.0` (`bug_bunny.gemspec:17`).
@@ -58,8 +59,8 @@ out-of-repo).
   `on: push: tags: ['v*']` → `ruby/setup-ruby@v1` → `gem build *.gemspec` +
   `gem push *.gem` (auth `secrets.RUBYGEMS_API_KEY`). Auditable y versionado con
   el código; se ancla a `file:line`, no se referencia como caja negra.
-- **Consumo:** los servicios la pinnean por versión (`gem "bug_bunny", "~> 4.19.0"`)
-  desde RubyGems — **no** git-source.
+- **Consumo:** los servicios la pinnean por versión (`gem "bug_bunny", "~> X.Y.0"`,
+  hoy `~> 5.1.0`) desde RubyGems — **no** git-source.
 
 ### e. Deploy / publish
 
@@ -79,12 +80,19 @@ procedimiento per-repo porque no vive acá. Una versión yankeada se anotaría e
 
 ### h. Dependencias de deploy inter-servicio
 
-- **Consumidores** (cruza RFC-018): servicios del fleet la pinnean
-  `~> 4.19.0` (semántica minor-compatible). Un cambio de contrato del gem
-  (ej. el behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`)
-  obliga a los consumidores a migrar; el `CHANGELOG.md` lo documenta como
-  breaking note. **Orden de deploy:** los consumidores adoptan al hacer `bundle
-  update bug_bunny` — no hay deploy coordinado (cada servicio elige cuándo).
+- **Consumidores** (cruza RFC-018): servicios del fleet la pinnean con la forma
+  `~> X.Y.0` — **patch-compatible**, no minor: `~> 5.1.0` resuelve
+  `>= 5.1.0, < 5.2.0`, así que un minor **no entra** sin editar el `Gemfile`.
+  Consecuencia operativa: un fix publicado como **patch** lo toman con
+  `bundle update bug_bunny`; uno publicado como **minor** requiere tocar el pin
+  en cada consumidor. Estado hoy: `box_manager_service` y `box_radius_manager`
+  en `~> 5.1.0`; `box_acs_manager` y `box_cluster_manager` todavía en
+  `~> 4.19.0` (bumps pendientes). Un cambio de contrato del gem (ej. el
+  behavior-change de `4.18.0` — `Bunny::Exception` → `CommunicationError`, o la
+  eliminación de `BugBunny::SecurityError` en `5.0.0`) obliga a los consumidores
+  a migrar; el `CHANGELOG.md` lo documenta como breaking note. **Orden de
+  deploy:** los consumidores adoptan al hacer `bundle update bug_bunny` — no hay
+  deploy coordinado (cada servicio elige cuándo).
 
 ### i. Contrato con la skill productora
 

data/lib/bug_bunny/exception.rb

@@ -23,11 +23,15 @@ module BugBunny
     #   respuesta RPC (ej: {CommunicationError}, {ConfigurationError}).
     #
     # @note **No loguear ni enviar a sinks (Sentry/logs) sin sanitizar.** El
-    #   cuerpo crudo puede contener datos sensibles (p. ej. en `details`). Antes
-    #   de cualquier sink, filtrar las claves sensibles del fleet
-    #   (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]`. La
-    #   gema entrega el cuerpo crudo a propósito; sanitizarlo es responsabilidad
-    #   del consumidor.
+    #   cuerpo crudo puede contener datos sensibles (p. ej. en `details`). La
+    #   lista canónica de claves sensibles es
+    #   {BugBunny::Observability::SENSITIVE_KEYS} — no la repliques acá ni en el
+    #   consumidor: se desincroniza (ojo que `pass` bare NO está en la lista, a
+    #   propósito, para no filtrar `passport_number`). Para sanear, reusá
+    #   {BugBunny::Observability.sensitive_key?} (filtra por NOMBRE de clave) y
+    #   {BugBunny::Observability.redact_structure} (recorre la estructura y
+    #   además redacta credenciales embebidas en el VALOR). La gema entrega el
+    #   cuerpo crudo a propósito; sanitizarlo es responsabilidad del consumidor.
     attr_accessor :raw_response
 
     # @return [Integer, nil] El código de estado de la respuesta que originó el

data/lib/bug_bunny/observability.rb

@@ -27,6 +27,81 @@ module BugBunny
       SENSITIVE_KEYS.any? { |sensitive| key_str.include?(sensitive) }
     end
 
+    # Alternación de keys sensibles ordenada de más larga a más corta: en un regex
+    # la alternación matchea leftmost-first, así que sin este orden `auth` ganaría
+    # sobre `authorization` y el patrón dejaría de matchear (`orization=x` no sigue
+    # con `[:=]`).
+    SENSITIVE_KEYS_ALTERNATION = SENSITIVE_KEYS.sort_by { |k| -k.length }.join('|').freeze
+
+    # Reglas de VALOR sensible, como pares `[regex, reemplazo]`.
+    #
+    # {.sensitive_key?} solo ve el NOMBRE de la clave; no puede ver una credencial
+    # embebida en TEXTO LIBRE. El caso canónico es el `message` de una excepción
+    # inesperada (llega como `reason=` o `error_message=`, nombres no sensibles):
+    # un `NoMethodError` sobre un objeto de respuesta HTTP puede arrastrar
+    # `Authorization: "Bearer eyJ..."` en su mensaje y el filtro por-clave lo deja
+    # pasar entero al log.
+    #
+    # El reemplazo conserva el nombre de la clave cuando viaja dentro del texto
+    # (`token=[FILTERED]`, no `[FILTERED]`): saber QUÉ credencial apareció es
+    # diagnóstico útil; su valor no.
+    SENSITIVE_VALUE_RULES = [
+      # Esquemas de autenticación HTTP: "Bearer <jwt>", "Basic <base64>".
+      [/\b(?:bearer|basic)\s+[A-Za-z0-9\-._~+\/]{8,}={0,2}/i, '[FILTERED]'],
+      # La key viaja DENTRO del texto: `token=abc`, `password: 'x'`, `"api_key" => "y"`.
+      #
+      # El prefijo `\w*` va en lugar de un `\b`: `_` es word-char, así que un borde de
+      # palabra NO existe dentro de `access_token` ni de `accessToken` y esas variantes
+      # se colarían en claro — justo las que {.sensitive_key?} cubre a propósito con
+      # substring matching. Se captura el prefijo para conservar el nombre COMPLETO de la
+      # key en el log (`access_token=[FILTERED]`): saber qué credencial apareció es
+      # diagnóstico útil. No reintroduce el falso positivo de `passport_number` porque
+      # ninguna key de SENSITIVE_KEYS es substring suyo (por eso `pass` bare está excluida).
+      [/(\w*(?:#{SENSITIVE_KEYS_ALTERNATION}))["']?\s*(?:=>|[:=])\s*["']?[^\s,;"'}\])]+/i,
+       '\1=[FILTERED]'],
+      # Credenciales en una URL: `amqp://user:pass@host` → conserva el esquema y el host.
+      [%r{(://)[^\s/:@]+:[^\s/@]+@}, '\1[FILTERED]@']
+    ].freeze
+
+    # Redacta credenciales embebidas en un valor de texto libre.
+    #
+    # Complementa a {.sensitive_key?}: esa filtra por NOMBRE de clave, esta por
+    # CONTENIDO. Se aplica a todo valor no numérico que {#safe_log} serializa.
+    #
+    # @param value [Object] El valor a redactar (se serializa con `to_s`).
+    # @return [String] El valor con las credenciales reemplazadas por `[FILTERED]`.
+    def self.redact_value(value)
+      SENSITIVE_VALUE_RULES.reduce(value.to_s) do |acc, (pattern, replacement)|
+        acc.gsub(pattern, replacement)
+      end
+    end
+
+    # Redacta una estructura ANTES de serializarla, recorriendo keys y valores.
+    #
+    # Se usa para los valores `Hash` de {#safe_log}. Redactar el JSON ya serializado con
+    # {.redact_value} no sirve: la regla de key-dentro-del-texto normaliza el separador a
+    # `=` y se come la comilla de cierre de la key, dejando un objeto donde el par
+    # `"token": "abc"` quedó colapsado en `"token=[FILTERED]"` — el secreto desaparece,
+    # pero el campo deja de ser JSON parseable y quien consume el log pierde el objeto
+    # entero, no solo el valor redactado.
+    #
+    # Recorriendo la estructura, además, las keys internas SÍ pasan por {.sensitive_key?}
+    # (que solo veía las keys de primer nivel del metadata).
+    #
+    # @param obj [Object] Estructura a redactar (Hash/Array anidados incluidos).
+    # @return [Object] La misma forma, con los valores sensibles reemplazados.
+    def self.redact_structure(obj)
+      case obj
+      when Hash
+        obj.each_with_object({}) do |(k, v), acc|
+          acc[k] = sensitive_key?(k) ? '[FILTERED]' : redact_structure(v)
+        end
+      when Array then obj.map { |element| redact_structure(element) }
+      when Numeric, TrueClass, FalseClass, NilClass then obj
+      else redact_value(obj)
+      end
+    end
+
     private
 
     # Registra un evento estructurado. Nunca eleva excepciones.
@@ -43,12 +118,17 @@ module BugBunny
         val = BugBunny::Observability.sensitive_key?(k) ? '[FILTERED]' : v
         next if val.nil?
 
+        # La redacción por CONTENIDO se aplica a todo valor no numérico: el filtro
+        # por-clave de arriba no ve una credencial embebida en texto libre.
         formatted = case val
                     when Numeric then val
                     when Hash
-                      val.to_json
-                    when String then val.include?(' ') ? val.inspect : val
-                    else val.to_s.include?(' ') ? val.to_s.inspect : val
+                      # Se redacta la estructura y DESPUÉS se serializa: al revés el campo
+                      # queda con el secreto tapado pero el JSON roto (ver .redact_structure).
+                      BugBunny::Observability.redact_structure(val).to_json
+                    else
+                      redacted = BugBunny::Observability.redact_value(val)
+                      redacted.include?(' ') ? redacted.inspect : redacted
                     end
         "#{k}=#{formatted}"
       end.compact.join(' ')

data/lib/bug_bunny/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BugBunny
-  VERSION = '5.1.0'
+  VERSION = '5.1.1'
 end

data/skill/SKILL.md

@@ -19,7 +19,9 @@ Gema Ruby: capa de routing RESTful sobre AMQP/RabbitMQ. Microservicios se comuni
 
 ## Contrato resumido (piso mínimo)
 
-> Resume el contrato de **`bug_bunny` 4.18.0**. Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en [`../docs/behavior/behavior.md`](../docs/behavior/behavior.md) (6 flujos) y [`../docs/glossary/glossary.md`](../docs/glossary/glossary.md) (símbolos→significado). Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
+> Resume el contrato de **`bug_bunny` 5.1.1** (anclado a `v5.1.1`). Suficiente para el uso típico sin abrir el detalle; el detalle version-locked está en el **Índice de artefactos** de abajo. Antipatrones/API completa: más abajo (embebido interim, ver Cobertura y fronteras).
+>
+> **Si venís de 4.x, dos breaking a mirar antes de subir:** `5.0.0` eliminó la constante pública `BugBunny::SecurityError` (un `rescue BugBunny::SecurityError` que sobreviva revienta con `NameError` y **enmascara la excepción original**) y `4.18.0` cambió el wrapping `Bunny::Exception` → `CommunicationError`. Detalle en `CHANGELOG.md`.
 
 **Símbolos públicos clave**
 
@@ -58,14 +60,21 @@ client.publish('events', body: { type: 'x' })   # => { 'status' => 202 }
 
 ## Índice de artefactos (fuente de verdad)
 
-El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume**, no duplica. Links relativos = version-locked (mismo tag del release; `gemspec.files` incluye `docs/**`).
+El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume**, no duplica. Links relativos = version-locked (mismo tag del release, `v5.1.1`; `gemspec.files` incluye `docs/**`, así que estos archivos viajan dentro del `.gem` que ya tenés instalado).
 
 | Capa | Artefacto | Estado |
 |---|---|---|
 | Glosario de dominio | [docs/glossary/glossary.md](../docs/glossary/glossary.md) | parcial, acreta por PR |
 | Comportamiento (flujos) | [docs/behavior/behavior.md](../docs/behavior/behavior.md) | completa — 6 flujos |
+| Configuración | [docs/config/configuracion.md](../docs/config/configuracion.md) | §a-§e/§i estructura + §f/§g/§h enrich — completa |
+| Dependencias consumidas | [docs/consumed/rabbitmq.md](../docs/consumed/rabbitmq.md) | §a/§b/§d estructura + §c/§e enrich |
+| Errores | [docs/errors/errors.md](../docs/errors/errors.md) | §a/§b/§d completas; §c política inferida (verificación humana pendiente) |
+| Test | [docs/test/testing.md](../docs/test/testing.md) | §a-§h — 16 unit / 7 integration |
+| Release | [docs/release/release.md](../docs/release/release.md) | completa (régimen gema: build→publish; §e/f/g n/a) |
 | Datos | — | n/a — gema sin DB |
-| Operaciones / Interfaz / Topología | — | F2 no implementado — ver Cobertura y fronteras |
+| Eventos | — | n/a — la gema **es** el transporte; no declara catálogo de eventos de dominio propio |
+| Seguridad | — | n/a — sin authn/authz propias; el guard anti-RCE (403) está en `docs/errors/` |
+| Operaciones / Interfaz / Topología | — | pendiente — ver Cobertura y fronteras |
 
 > **Glosario:** migrado a [docs/glossary/glossary.md](../docs/glossary/glossary.md)
 > (RFC-008 §2 — el compuesto referencia, no copia). Términos AMQP base
@@ -74,13 +83,15 @@ El detalle vive en `docs/<capa>/` (modelo `dev-*`); esta skill **indexa y resume
 
 ## Cobertura y fronteras
 
-**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras la capa de detalle destino (operaciones/interfaz/topología) esté declarada pero **no implementada** (dev-structure F1, F2 del plan), permanecen embebidos bajo el interim normado:
+**Coexistencia transitoria con destino pendiente (RFC-008 §2 — interim de migración):** mientras las capas `docs/api/` (operaciones), `docs/interface/` y `docs/topology/` no estén generadas para este repo, el contrato que les correspondería permanece embebido bajo el interim normado:
 
 - **En esta skill (abajo):** el contrato detallado (jerarquía de excepciones, API de config, modos de entrega) **y** el diagrama de arquitectura (flujo RPC). El *Contrato resumido* de arriba es el piso mínimo (RFC-008 §2); lo de abajo es el detalle interim hasta que exista `docs/api|interface|topology`.
 - **En `README.md`:** el contrato (sin el diagrama de arquitectura).
 - **Guías how-to** (`references/*.md`, pre-estándar): destino futuro `docs/howto/`.
 
-Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando F2 entregue, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se duplica; migra cuando se generen, mismo PR. Estado transitorio declarado, no excepción permanente. Origen del gap (resuelto, normado): [sequre/ai_knowledge#95](https://github.com/sequre/ai_knowledge/issues/95).
+
+> **Nota de alcance (2026-07-31):** la justificación original de este interim era que el generador no implementaba esas capas. Ya las implementa, así que el pendiente es de **este repo**, no de tooling — en particular `docs/interface/` (RFC-004), donde correspondería registrar la API pública (incluidos `Observability.redact_value` y `.redact_structure`, agregados en `5.1.1`). Queda como trabajo propio, fuera del alcance de este release.
 
 ---
 
@@ -129,7 +140,7 @@ Por RFC-008 §2: no se fabrica la capa, no se borra contrato sin destino, no se
 | `BugBunny::Controller` | Base class tipo Rails. `before_action`, `around_action`, `after_action`, `rescue_from`, `render`. |
 | `BugBunny::Resource` | ORM sobre AMQP. `find`, `where`, `create`, `save`, `destroy`. ActiveModel validations y callbacks. |
 | `BugBunny::Routing::RouteSet` | DSL de rutas: `resources`, `namespace`, `member`, `collection`. |
-| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log` nunca lanza excepciones. Filtra keys sensibles. |
+| `BugBunny::Observability` | Mixin de logging estructurado. `safe_log` nunca lanza excepciones. Redacta credenciales en dos capas: por nombre de clave (`sensitive_key?`) y por contenido del valor (`redact_value` / `redact_structure`, para la credencial embebida en texto libre). |
 | `BugBunny::Middleware::Stack` | Builder de middlewares client-side (onion architecture tipo Faraday). |
 | BugBunny::Request | Value object del mensaje saliente con metadata AMQP completa. |
 | BugBunny::OTel | Helpers para emitir campos siguiendo las OTel semantic conventions for messaging. |

data/skill/references/errores.md

@@ -37,9 +37,13 @@ rescue BugBunny::Error => e
 end
 ```
 
-> ⚠️ **No loguear `raw_response` crudo.** Puede contener datos sensibles. Filtrar
-> claves (`password|pass|passwd|secret|token|api_key|auth`) → `[FILTERED]` antes
-> de Sentry/logs. La gema lo entrega a propósito; sanitizar es del consumidor.
+> ⚠️ **No loguear `raw_response` crudo.** Puede contener datos sensibles. Sanear
+> antes de Sentry/logs con `Observability.redact_structure` (recorre la
+> estructura: filtra por nombre de clave y también redacta la credencial
+> embebida en el valor). **No replicar la lista de claves** — la canónica es
+> `Observability::SENSITIVE_KEYS`; replicarla la desincroniza (y `pass` bare NO
+> está en ella, a propósito, para no filtrar `passport_number`). La gema entrega
+> el cuerpo crudo a propósito; sanitizar es del consumidor.
 
 Para consumir un envelope estructurado de dominio (ej. `{ error: { code,
 message, details } }`), parsealo en el boundary del servicio desde

data/spec/unit/observability_spec.rb

@@ -29,6 +29,164 @@ RSpec.describe BugBunny::Observability do
     log_output.string.split("\n").last.to_s.sub(/\A.*?:\s*/, '')
   end
 
+  describe '.redact_value (contenido sensible en texto libre)' do
+    # Complementa a .sensitive_key?: esa mira el NOMBRE de la clave, esta el
+    # CONTENIDO. El caso que motiva la feature es el `message` de una excepción.
+    it 'redacta un Bearer token' do
+      redacted = BugBunny::Observability.redact_value(
+        'undefined method for #<Faraday::Response headers={"Authorization"=>"Bearer eyJhbGciOiJIUzI1NiJ9.abc"}>'
+      )
+
+      expect(redacted).not_to include('eyJhbGciOiJIUzI1NiJ9.abc')
+      expect(redacted).to include('[FILTERED]')
+    end
+
+    it 'redacta un esquema Basic' do
+      redacted = BugBunny::Observability.redact_value('Authorization: Basic dXNlcjpwYXNzd29yZA==')
+
+      expect(redacted).not_to include('dXNlcjpwYXNzd29yZA')
+      expect(redacted).to include('[FILTERED]')
+    end
+
+    it 'redacta el valor cuando la key viaja DENTRO del texto, conservando el nombre' do
+      redacted = BugBunny::Observability.redact_value('connect failed (token=abc123, host=rabbit)')
+
+      expect(redacted).not_to include('abc123')
+      expect(redacted).to include('token=[FILTERED]')
+      # El resto del mensaje sobrevive: la redacción es quirúrgica, no destructiva.
+      expect(redacted).to include('host=rabbit')
+    end
+
+    it 'matchea la key más larga primero (authorization no se parte en auth)' do
+      redacted = BugBunny::Observability.redact_value('authorization: "Bearer-less-secret-value"')
+
+      expect(redacted).not_to include('Bearer-less-secret-value')
+      expect(redacted).to include('authorization=[FILTERED]')
+    end
+
+    it 'redacta credenciales de una URL conservando esquema y host' do
+      redacted = BugBunny::Observability.redact_value('amqp://guest:s3cr3t@rabbit:5672/vhost')
+
+      expect(redacted).not_to include('s3cr3t')
+      expect(redacted).to include('amqp://[FILTERED]@rabbit:5672/vhost')
+    end
+
+    it 'deja intacto un texto sin credenciales' do
+      expect(BugBunny::Observability.redact_value('timeout after 30s on queue acs.rpc'))
+        .to eq('timeout after 30s on queue acs.rpc')
+    end
+
+    it 'no confunde una key no sensible que contiene un substring parecido' do
+      expect(BugBunny::Observability.redact_value('passport_number=AB123'))
+        .to include('AB123')
+    end
+
+    # `_` es word-char: un `\b` antes de la key NO encuentra borde dentro de
+    # `access_token` ni de `accessToken`, y esas variantes se colaban en claro.
+    # Son exactamente las que sensitive_key? cubre a propósito con substring matching.
+    it 'redacta la variante con separador (access_token) conservando el nombre completo' do
+      redacted = BugBunny::Observability.redact_value('request failed access_token=eyJsecret.jwt')
+
+      expect(redacted).not_to include('eyJsecret.jwt')
+      expect(redacted).to include('access_token=[FILTERED]')
+    end
+
+    it 'redacta la variante con prefijo (user_password)' do
+      redacted = BugBunny::Observability.redact_value('invalid params user_password=hunter2')
+
+      expect(redacted).not_to include('hunter2')
+      expect(redacted).to include('user_password=[FILTERED]')
+    end
+
+    it 'redacta la variante camelCase (accessToken)' do
+      redacted = BugBunny::Observability.redact_value('boom accessToken=eyJsecret.jwt')
+
+      expect(redacted).not_to include('eyJsecret.jwt')
+      expect(redacted).to include('accessToken=[FILTERED]')
+    end
+
+    it 'no redacta una key no sensible con sufijo numérico (processing_session_count)' do
+      expect(BugBunny::Observability.redact_value('processing_session_count=5'))
+        .to eq('processing_session_count=5')
+    end
+  end
+
+  describe '.redact_structure (estructura antes de serializar)' do
+    it 'redacta por key interna y deja la forma intacta' do
+      redacted = BugBunny::Observability.redact_structure(
+        'token' => 'abc123', 'host' => 'rabbit'
+      )
+
+      expect(redacted).to eq('token' => '[FILTERED]', 'host' => 'rabbit')
+    end
+
+    it 'recorre Hash anidado y Array' do
+      redacted = BugBunny::Observability.redact_structure(
+        'nested' => { 'api_key' => 'xyz', 'n' => 1 },
+        'list' => ['token=abc123', 'clean']
+      )
+
+      expect(redacted).to eq(
+        'nested' => { 'api_key' => '[FILTERED]', 'n' => 1 },
+        'list' => ['token=[FILTERED]', 'clean']
+      )
+    end
+
+    it 'no altera numéricos ni booleanos ni nil' do
+      expect(BugBunny::Observability.redact_structure('n' => 1, 'ok' => true, 'x' => nil))
+        .to eq('n' => 1, 'ok' => true, 'x' => nil)
+    end
+  end
+
+  describe '#safe_log — redacción por contenido' do
+    # El caso real: el nombre de la clave NO es sensible (`reason`), así que el
+    # filtro por-clave lo deja pasar; la credencial va en el valor.
+    it 'filtra una credencial embebida en el valor de una key NO sensible' do
+      host.safe_log(:error, 'unhandled_exception',
+                    reason: 'NoMethodError on headers {"Authorization"=>"Bearer eyJsupersecret.jwt"}')
+
+      expect(last_log_line).not_to include('eyJsupersecret.jwt')
+      expect(last_log_line).to include('[FILTERED]')
+    end
+
+    it 'filtra dentro de un Hash serializado (las keys internas no pasan por sensitive_key?)' do
+      host.safe_log(:error, 'unhandled_exception', details: { 'token' => 'abc123xyz' })
+
+      expect(last_log_line).not_to include('abc123xyz')
+      expect(last_log_line).to include('[FILTERED]')
+    end
+
+    # La redacción no puede costar la estructura: quien consume el log parsea este campo
+    # como JSON, y un objeto roto le hace perder TODOS los pares, no solo el redactado.
+    it 'mantiene el campo Hash como JSON parseable después de redactar' do
+      host.safe_log(:error, 'unhandled_exception',
+                    details: { 'token' => 'abc123xyz', 'host' => 'rabbit',
+                               'nested' => { 'api_key' => 'xyz789', 'n' => 1 } })
+
+      field = last_log_line[/details=(\S+)/, 1]
+
+      expect { JSON.parse(field) }.not_to raise_error
+      expect(JSON.parse(field)).to eq(
+        'token' => '[FILTERED]', 'host' => 'rabbit',
+        'nested' => { 'api_key' => '[FILTERED]', 'n' => 1 }
+      )
+    end
+
+    it 'no altera un valor numérico' do
+      host.safe_log(:info, 'done', duration_s: 1.5, status: 200)
+
+      expect(last_log_line).to include('duration_s=1.5', 'status=200')
+    end
+
+    it 'preserva el resto de la línea (component, event y campos limpios)' do
+      host.safe_log(:error, 'request_error', kind: 'unavailable', reason: 'ACS down')
+
+      line = last_log_line
+      expect(line).to include('event=request_error', 'kind=unavailable')
+      expect(line).to include('reason="ACS down"')
+    end
+  end
+
   describe '.sensitive_key? (módulo público)' do
     subject(:sensitive?) { BugBunny::Observability.method(:sensitive_key?) }
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bug_bunny
 version: !ruby/object:Gem::Version
-  version: 5.1.0
+  version: 5.1.1
 platform: ruby
 authors:
 - gabix
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-22 00:00:00.000000000 Z
+date: 2026-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bunny
@@ -314,7 +314,7 @@ metadata:
   homepage_uri: https://github.com/gedera/bug_bunny
   source_code_uri: https://github.com/gedera/bug_bunny
   changelog_uri: https://github.com/gedera/bug_bunny/blob/main/CHANGELOG.md
-  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.1.0/skill
+  documentation_uri: https://github.com/gedera/bug_bunny/blob/v5.1.1/skill
 post_install_message:
 rdoc_options: []
 require_paths: