foam-otel 1.2.1 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e10efb9aaacdda1498a19efaa4af8338afbb98d89880cc6f662aa99205aab59
-  data.tar.gz: 436060cbcfc7ed33c171ab230a60d4f8b62a882ce46be22bcd81e9c497edbc84
+  metadata.gz: 82f1791c9e7d9929a655760c4e2f67295bb70f55dee75a2738bfcae33f5658f6
+  data.tar.gz: 16917b6e7a4e1dc1f0c6160f7026d4fe90c6213a16fa0664807e459359c5ea92
 SHA512:
-  metadata.gz: 528f57356698e39e691b08bcc0b6f00bc409ad133afca0ac0bdeeb2d0caffbc052a7a19d7fe63b0285230eb16cd26117ede4bc0824c7c0f31377a4a983ad7458
-  data.tar.gz: 9e445e3ce3924ff924afd66e98c35b58fe536ae2d546a0f151d3d870f9359974b3bbfd781871fd39fef67d3d509573cab7c2ce573531067eedf3623943967f32
+  metadata.gz: 38df8e89604a42d3db4698f5f12934f2bf3e25e288124caf10694a0e698e50f3a732fdd9f1dd2455fb52af90777cba00a3e825f23b967817d6fbda25b567fbdf
+  data.tar.gz: 5034a35f4d3a7c9d1f18fb0e7adc6691e75aacf0130eb74312ce14ad0ab902e787a25b75af45d6f618cd70a13df12b8323fc172d1cb0abee2950991bb839db6d

data/GOTCHAS.md

@@ -240,34 +240,48 @@ anthropic 1.59.0, gemini-ai 4.3.0, ruby_llm 1.16.0).
   `@attributes = validated_attributes(@attributes).freeze` then sets `@ended`
   (opentelemetry-sdk `trace/span.rb:277,280`); `to_span_data` returns the frozen
   `@attributes` by reference (`trace/span.rb:296-307`).
-- **Opt-in redaction (holistic redesign, 2026-07-26)**: foam does NO redaction by
-  default — with no `redact_keys`/`redact_pii_keys` every value is captured RAW
-  (no secret floor, no value-pattern masking). When keys ARE configured, foam
-  applies the key pass at the EXPORTER boundary — a `RedactingSpanExporter`/
-  `RedactingLogRecordExporter` that rebuilds the mutable `SpanData`/
-  `LogRecordData` Structs with masked attributes/events/body before
-  serialization. With no keys configured the exporter is a true pass-through.
-- **Divergence (NARROWED)**: when keys are configured foam's HELPERS apply the
-  key pass AT CAPTURE (`api.rb` `stringify`/`set_attribute`/`log`; `metrics.rb`
-  always did), so a tenant `additional_*` instance receives foam-helper data
+- **Redaction posture (holistic redesign 2026-07-26, amended same day by the
+  credential-floor ruling)**: foam does NO customer redaction by default — with
+  no `redact_keys`/`redact_pii_keys` every value is captured RAW (no
+  value-pattern masking) EXCEPT the ALWAYS-ON CREDENTIAL FLOOR: the frozen
+  header/key name list of `contract/credential-denylist.json` masks to
+  `[REDACTED]` unconditionally, with no off switch (README "The default
+  credential denylist"; design doc `docs/decisions/credential-denylist-design.md`).
+  The floor + any configured keys run at the EXPORTER boundary — a
+  `RedactingSpanExporter`/`RedactingLogRecordExporter` that rebuilds the
+  mutable `SpanData`/`LogRecordData` Structs with masked
+  attributes/events/body before serialization. The pass runs unconditionally
+  (the floor has no off state); values under unmatched names ride through raw.
+- **Divergence (CLOSED in 1.3.0)**: foam's HELPERS apply the floor + key pass
+  AT CAPTURE (`api.rb` `stringify`/`set_attribute`/`log`; `metrics.rb` always
+  did), so a tenant `additional_*` instance receives foam-helper data
   ALREADY-MASKED (rule 18 C.3) — the pass is idempotent, so the wire value is
-  unchanged. The residual divergence is THIRD-PARTY INSTRUMENTATION attributes
-  only: those freeze at finish before any processor runs, so a tenant span
-  processor sees them as foam captured them and foam can only apply the key pass
-  at the exporter boundary. Ruby offers no safe pre-freeze hook — the
-  `on_finishing` hook runs inside the span mutex, so a processor calling
-  `set_attribute` there would deadlock. Foam's own export applies the configured
-  key pass, and the exporters FAIL CLOSED once a pass has begun: a struct whose
-  rebuild raises is DROPPED with a loud warning (`Redaction.mask_*` return nil on
-  hard failure), never exported half-masked.
-- **Mitigation**: capture-time key pass in `lib/foam/otel/api.rb` +
+  unchanged. THIRD-PARTY INSTRUMENTATION attributes freeze at finish before
+  any processor runs (no safe pre-freeze hook — `on_finishing` runs inside
+  the span mutex, so a processor calling `set_attribute` there would
+  deadlock), so they CANNOT be masked in place — instead the guarded tenant
+  wrappers (`pipelines.rb` `GuardedSpanProcessor#on_finish` /
+  `GuardedLogRecordProcessor#on_emit`) hand tenants a READ-ONLY MASKED VIEW
+  (`MaskedSpanView`/`MaskedLogRecordView`, served through the same
+  `Redaction.mask_span_data`/`mask_attributes`/`mask_body` pass foam's export
+  applies) — a tenant never sees a raw floor (or configured-key) value, and a
+  span whose masked view cannot be built is WITHHELD loudly, never handed
+  over raw. Foam's own export applies the same pass, and the exporters FAIL
+  CLOSED once the pass has begun: a struct whose rebuild raises is DROPPED
+  with a loud warning (`Redaction.mask_*` return nil on hard failure), never
+  exported half-masked.
+- **Mitigation**: capture-time pass in `lib/foam/otel/api.rb` + the masked
+  tenant view in `lib/foam/otel/pipelines.rb` +
   `lib/foam/otel/redacting_exporter.rb` + `lib/foam/otel/redaction.rb`.
-- **Test**: `spec/tenant_seam_spec.rb` (tenant processors receive helper-set
-  LISTED keys ALREADY-MASKED, free-text bodies RAW, the byte-identical
-  with/without-tenant proofs for spans, logs, AND metrics),
-  `spec/redacting_exporter_spec.rb` (opt-in masking on the wire; "a POISONED
-  SpanData (dup raises) is DROPPED — never exported raw"), `spec/redaction_spec.rb`
-  (default zero-redaction + the two opt-in key lists; capture+exporter idempotence).
+- **Test**: `spec/credential_floor_spec.rb` + `spec/credential_floor_wire_spec.rb`
+  (the floor per signal/door; the tenant masked-view regression gate — a
+  third-party-set `authorization` attribute never reaches a tenant raw),
+  `spec/tenant_seam_spec.rb` (tenant processors receive helper-set LISTED keys
+  ALREADY-MASKED, free-text bodies RAW, the byte-identical with/without-tenant
+  proofs for spans, logs, AND metrics), `spec/redacting_exporter_spec.rb`
+  (masking on the wire; "a POISONED SpanData (dup raises) is DROPPED — never
+  exported raw"), `spec/redaction_spec.rb` (raw-above-the-floor defaults + the
+  two opt-in key lists; capture+exporter idempotence).
 
 ## F2: OTEL_SDK_DISABLED and OTEL_PROPAGATORS are only honored by SDK.configure
 
@@ -623,8 +637,10 @@ anthropic 1.59.0, gemini-ai 4.3.0, ruby_llm 1.16.0).
   mitigation (foam never rewrites or drops metric dimensions — rule 4/26);
   the mitigation is the README metrics warning with the classic bad example —
   *Documented* (README "Metrics" section). *Test*: `spec/metrics_spec.rb`
-  ("captures a metric attribute RAW by default; masks it only when the key is in
-  redact_keys" — pins that unlisted attributes pass through VERBATIM).
+  ("captures a NON-floor metric attribute RAW by default; masks it only when
+  the key is in redact_keys" — pins that unlisted, non-floor attributes pass
+  through VERBATIM; the credential floor's frozen names are the one always-on
+  exception, `spec/credential_floor_wire_spec.rb`).
 - **G8 — never-ended spans leak memory**: a span started and never ended holds
   memory and context forever (and never exports — the batch processor only
   sees FINISHED spans, `on_finish`). `Foam::Otel.span {}` always ends the span

data/README.md

@@ -4,9 +4,12 @@ Foam's OpenTelemetry core for Ruby services. A thin, safe wrapper over the
 official OpenTelemetry libraries: foam owns the pipeline (providers, batch
 processors, OTLP export to the foam fleet endpoint), turns on automatic
 tier-1/2 instrumentation, and hands you a small set of never-throw helpers —
-and nothing else. **Redaction is fully opt-in: by default foam captures every
-value RAW** (no secret floor, no value-pattern masking); you enumerate the
-fields to mask via `redact_keys`/`redact_pii_keys`.
+and nothing else. **Redaction is fully opt-in above one always-on exception:
+by default foam captures every value RAW** (no value-pattern masking, no PII
+preset) **except the credential floor** — a fixed list of credential/secret
+header and field NAMES that is always masked to `[REDACTED]` (see "The
+default credential denylist" below); you enumerate any further fields to mask
+via `redact_keys`/`redact_pii_keys`.
 
 Built to `docs/BASE_PACKAGE_SPEC.md`. This README is the manual you integrate
 from.
@@ -75,10 +78,12 @@ drop-in upstream metrics gem, so foam ships its own collector),
 **session stitching** (inbound `baggage: session.id` from the foam browser
 package is stamped onto every span and log record), and the **LLM shims**
 (below). Every inbound request, DB call, HTTP call, job, log line, and model
-call now flows to foam. **Redaction is opt-in: by default every value —
-attributes, URLs/query strings, DB statement text, log bodies, LLM content —
-is captured RAW.** Pass `redact_keys`/`redact_pii_keys` to mask or erase
-specific fields (see below).
+call now flows to foam. **Redaction is opt-in above the credential floor: by
+default every value — attributes, URLs/query strings, DB statement text, log
+bodies, LLM content — is captured RAW, except values whose NAME is on the
+always-on credential denylist (masked `[REDACTED]`; see "The default
+credential denylist" below).** Pass `redact_keys`/`redact_pii_keys` to mask
+or erase further specific fields (see below).
 
 > **Sidekiq trace shape** (GOTCHAS G16): the bundled instrumentation keeps
 > its upstream default `propagation_style: :link` — a performed job runs as
@@ -134,8 +139,8 @@ API):** the allowlist must include BOTH headers —
 | `enabled:` | Boolean | yes | — | The config switch. `false` = fully inert (no SDK, no providers, no network, helpers no-op). `true` = export, in EVERY environment. No default — you write the logic. |
 | `token:` | String | when enabled | — | `Authorization: Bearer` for export. Required (and validated) only when `enabled: true`; wired explicitly from your secret source — never an env fallback read by the gem. **Fleet convention: read it from the `FOAM_OTEL_TOKEN` env var.** Blank while enabled → raises at boot. |
 | `version:` | String | no | nil | `service.version`, verbatim (git SHA recommended). Missing → warns and continues. Never detected at runtime. |
-| `redact_keys:` | Array<String> | no | `[]` | The ONLY field names tail-masked (shape-preserving, e.g. `********f456`). Opt-in — empty (the default) means NO masking. Matches by case-insensitive substring, including keys nested in structured values and query-string keys. |
-| `redact_pii_keys:` | Array<String> | no | `[]` | Field names fully erased to `[REDACTED]` (no tail). Opt-in — empty (the default) means NO erasure. Foam ships no preset; this is your enumeration. |
+| `redact_keys:` | Array<String> | no | `[]` | The ONLY field names tail-masked (shape-preserving, e.g. `********f456`). Opt-in and ADDITIVE on top of the always-on credential floor — empty (the default) means no masking beyond the floor. Matches by case-insensitive substring, including keys nested in structured values and query-string keys. A key that is also on the floor stays fully `[REDACTED]` (the floor wins; it is never downgraded to a tail). |
+| `redact_pii_keys:` | Array<String> | no | `[]` | Field names fully erased to `[REDACTED]` (no tail). Opt-in and additive above the floor — empty (the default) means no erasure beyond the floor. Foam ships no PII preset; this is your enumeration. |
 | `additional_span_processors:` | Array | no | `[]` | Tenant seam: constructed SpanProcessor instances added to foam's pipeline (additive; never replace foam's export). See coexistence. |
 | `additional_log_record_processors:` | Array | no | `[]` | Tenant seam, logs. |
 | `additional_metric_readers:` | Array | no | `[]` | Tenant seam, metrics. |
@@ -193,6 +198,86 @@ override is the operator-level `OTEL_EXPORTER_OTLP_ENDPOINT` env var (below).
 
 ---
 
+## The default credential denylist (the always-on floor)
+
+**Fleet ruling 2026-07-26** (binding design:
+`docs/decisions/credential-denylist-design.md`; frozen fixture:
+`contract/credential-denylist.json`). This is the ONE exception to foam's
+raw-by-default capture, and it has **no off switch** — no init option, no env
+var, and no door-2 parameter can disable, shrink, or re-spell it.
+
+**What is masked.** The VALUE of every header/attribute/field whose NAME is on
+the frozen list, in every signal (spans — events and links included — logs,
+metrics), on door 1, on all three door-2 ingest taps, and in the view handed
+to tenant `additional_*` processors:
+
+- **(a) the seven credential headers**, matched as header names wherever
+  headers are captured — including the semconv
+  `http.request.header.<name>` / `http.response.header.<name>` span-attribute
+  forms: `authorization`, `proxy-authorization`, `cookie`, `set-cookie`,
+  `x-api-key`, `x-auth-token`, `www-authenticate`;
+- **(b) the frozen 52-entry key list** of
+  `contract/credential-denylist.json` (the deduplicated union of those seven,
+  sentry-python's default denylists, and foam's documented reference roots —
+  `password`, `token`, `secret`, `api_key`, `ssn`, `jwt`, `private_key`,
+  `connect.sid`, `phpsessid`, …), matched as attribute/field names at every
+  depth the engine walks, and per-key in URL query strings
+  (`?token=x&user=bob` → `token=[REDACTED]&user=bob`).
+
+**The matching rule.** Case-insensitive, dash/underscore-normalized **EXACT
+name-equality — never substring**: `authorization` masks the header/field
+`authorization` (any casing, `-`≡`_`) and nothing else — `authorization_url`,
+`x_api_key_id`, `secretary`, and `session_count` all ride RAW. Dotted entries
+match verbatim and whole (`connect.sid` masks; `user.session` does not). This
+is deliberately STRICTER matching than your own `redact_keys` lists, which
+keep their documented substring behavior.
+
+**The mask.** The full literal `[REDACTED]` — no tail, no length
+preservation. These are credentials, not debug aids. Semconv header
+attributes (string arrays) mask per element, preserving arity.
+
+**Precedence.** The floor runs unconditionally BEFORE your
+`redact_keys`/`redact_pii_keys`, which stay purely additive on top. Listing a
+floor name in `redact_keys` does NOT downgrade it to a tail mask — the floor
+is terminal. `enabled: false` stays fully inert exactly as before (nothing
+exports at all — the floor masks data that leaves; inert mode has none).
+
+**Everything else stays RAW.** The floor matches NAMES only — it never scans
+values: bodies, query values, SQL text, LLM content, and PII under unlisted
+names export byte-identical raw, exactly as documented everywhere else in
+this README.
+
+**Why.** Coverage-over-masking remains the mission, but raw `Authorization`
+headers, cookies, and API keys on the wire are a breach in waiting for every
+customer at once — the fleet ruling carves out exactly this list (and only
+this list) as non-negotiable. The list is byte-identical in every foam core
+and gate-checked in CI against the fleet fixture
+(`spec/credential_floor_spec.rb`).
+
+**Fleet param-name canon** (the customer options above the floor, identical
+concept in every core — the floor itself has NO init surface anywhere):
+
+| Concept | js/otel | js/browser | python | ruby | java |
+|---|---|---|---|---|---|
+| secret keys (tail-mask) | `redactKeys` | `redactKeys` | `redact_keys` | `redact_keys:` | `.redactKeys(String…)` |
+| PII keys (full `[REDACTED]`) | `redactPiiKeys` | `redactPiiKeys` | `redact_pii_keys` | `redact_pii_keys:` | `.redactPiiKeys(String…)` |
+
+> **Migration note — 1.3.0 (minor): always-on credential masking.** As of
+> this version foam masks, by default and in every signal, the VALUES of a
+> fixed list of credential/secret header and field NAMES (`authorization`,
+> `cookie`, `set-cookie`, `proxy-authorization`, `x-api-key`, `x-auth-token`,
+> `www-authenticate`, and the 52-name key list in
+> `contract/credential-denylist.json` — Sentry-parity plus foam's documented
+> roots) to the literal `[REDACTED]`. Matching is exact name-equality,
+> case-insensitive, dash/underscore-insensitive — never substring:
+> `authorization_url` is untouched. Everything else still exports RAW exactly
+> as before; `redact_keys`/`redact_pii_keys` are unchanged and additive.
+> There is no off switch — if a dashboard keyed off a raw credential value
+> (it should not have), it will now see `[REDACTED]`. Customers who
+> previously received these header/field values raw stop receiving them.
+
+---
+
 ## The helpers
 
 All helpers never raise, and no-op silently before `init` and when disabled.
@@ -288,10 +373,13 @@ Foam::Otel.init(name: "checkout-api", environment: env, enabled: true, token: FO
 > Ruby note: when you configure `redact_keys`/`redact_pii_keys`, foam's HELPERS
 > apply the key pass at capture, so a tenant processor receives foam-helper data
 > (span/log helper attributes, log bodies, metric labels) ALREADY masked.
-> Because the Ruby SDK freezes span attributes at finish, a tenant
-> processor sees third-party instrumentation attributes UNMASKED (for those,
-> foam's key pass runs at the exporter boundary — GOTCHAS F1). With no keys
-> configured (the default) nothing is masked on either path.
+> The Ruby SDK freezes span attributes at finish, so historically a tenant
+> processor saw third-party instrumentation attributes UNMASKED — as of 1.3.0
+> that gap is closed: tenant span/log processors are handed a READ-ONLY MASKED
+> VIEW (the credential floor plus your configured keys, the same pass foam's
+> own export applies — GOTCHAS F1). A tenant never sees a raw floor value.
+> With no keys configured (the default) only the credential floor is masked
+> on either path.
 >
 > Loop-guard note: `ignored_outbound_hosts` suppresses spans for tenant/agent
 > egress made through **Net::HTTP or Excon**. A tenant exporter using
@@ -329,9 +417,10 @@ end
 
 **Outcome**: their pipeline keeps working exactly as before — their data,
 their resource, their export, byte-identical — and foam ALSO receives the
-signal, carrying THEIR resource identity plus foam's export-time stamp and
-any per-tap `redact_keys`/`redact_pii_keys` you set (opt-in — none by default;
-details in the Door 2 section).
+signal, carrying THEIR resource identity plus foam's export-time stamp, the
+always-on credential floor applied to foam's copy, and any per-tap
+`redact_keys`/`redact_pii_keys` you set (opt-in — none by default; details in
+the Door 2 section).
 
 **Unhappy paths**:
 
@@ -431,8 +520,10 @@ readers only: they never mutate their data, their resource, or their export.
 ### The three entries
 
 All three share one signature (`token:` and `environment:` required; the
-redaction kwargs are the ONLY keys that tap redacts — opt-in, none by default,
-scoped to that tap; `diagnostics:` is tap-scoped narration). Construction
+redaction kwargs are the only CUSTOMER keys that tap redacts — opt-in, none by
+default, scoped to that tap, additive above the always-on credential floor,
+which every tap applies with zero configuration; `diagnostics:` is tap-scoped
+narration). Construction
 validates loudly at boot and NEVER
 throws afterwards — a failure inside a tap can never break their pipeline.
 Fleet canon mapping (pinned by `spec/export_surface_spec.rb`):
@@ -453,9 +544,10 @@ their_tracer_provider.add_span_processor(processor)
 # raises ArgumentError at construction for a blank token/environment
 ```
 
-**Logs** — a LogRecordProcessor for THEIR LoggerProvider. The tap's
-`redact_keys`/`redact_pii_keys` (if any) match over record attributes and keys
-nested in structured bodies; free-text bodies ride RAW (no value-pattern pass):
+**Logs** — a LogRecordProcessor for THEIR LoggerProvider. The credential
+floor and the tap's `redact_keys`/`redact_pii_keys` (if any) match over
+record attributes and keys nested in structured bodies; free-text bodies ride
+RAW (no value-pattern pass):
 
 ```ruby
 provider = OpenTelemetry::SDK::Logs::LoggerProvider.new(resource: their_resource)
@@ -499,7 +591,7 @@ in THEIR pipeline. Three layers keep it closed:
 | | their pipeline | foam's copy |
 | --- | --- | --- |
 | `service.name` / `service.version` / `service.instance.id` | theirs | theirs, untouched (the data carries THEIR identity) |
-| all attributes / events / bodies | raw, byte-identical | your per-tap `redact_keys`/`redact_pii_keys` applied (default: none → identical to theirs) |
+| all attributes / events / bodies | raw, byte-identical | the credential floor + your per-tap `redact_keys`/`redact_pii_keys` applied (default: floor only — everything off the frozen list identical to theirs) |
 | `deployment.environment.name` | theirs (if any) | the tap's `environment:` argument (stamped at export time) |
 | `foam.ingest.tier` | absent | `"external"` (the wire-contract marker) |
 | `telemetry.distro.name` / `telemetry.distro.version` | absent | `"foam"` / the gem version (support reads the tap's presence and version from telemetry alone) |

data/RESEARCH.md

@@ -144,8 +144,11 @@ statement posture is **captured RAW, never suppressed** (2026-07-26 ruling —
 coverage is the mission), and the upstream `-pg`/`-mysql2`/`-redis`/`-mongo`
 gems all DEFAULT to `db_statement: :obfuscate` — a sanitizer — so foam
 explicitly activates them with `db_statement: :include` (GOTCHAS F9; pinned
-by `spec/floor_spec.rb`). Redaction stays fully opt-in, applied only for keys
-the customer lists in `redact_keys`/`redact_pii_keys`. An FDE can still clamp
+by `spec/floor_spec.rb`). Redaction stays fully opt-in above the always-on
+credential floor (the frozen NAME list of
+`contract/credential-denylist.json` — statement TEXT is never scanned),
+applied only for keys the customer lists in
+`redact_keys`/`redact_pii_keys`. An FDE can still clamp
 `db_statement: :omit`/`:obfuscate` per customer via the standard
 `OTEL_RUBY_INSTRUMENTATION_<NAME>_CONFIG_OPTS` env var when a compliance
 context calls for it — per-customer tightening (rule 18 / Area 4), not the
@@ -210,7 +213,8 @@ foam ships the logs pipeline + `log()` helper (trace-correlated) — the mechani
 rule 20 requires. The stdlib **Logger bridge is LANDED as foam's own code**
 (`lib/foam/otel/logger_bridge.rb`, console-logs ruling 2026-07-26): one
 prepend on `Logger#add` turns every message a host logger accepts into a
-trace-correlated OTel log record — body RAW (opt-in key-masking only),
+trace-correlated OTel log record — body RAW (name-keyed masking only: the
+always-on credential floor plus any customer keys; free text never scanned),
 severity mapped, loop-guarded (the OTel SDK's internal logger is skipped by
 identity + a thread-local re-entrancy flag), gated on foam owning the logs
 slot, and never able to break the host's log call (GOTCHAS F10; tests
@@ -226,7 +230,8 @@ The official contrib `opentelemetry-instrumentation-logger 0.4.0` bridges the
 same `Logger#add` seam and is deliberately NOT bundled — census disposition
 EXCLUDED/superseded (§3): foam's bridge additionally holds the lazy-block
 contract, the OTel-internal-logger identity guard, the re-entrancy flag, the
-logs-slot gate, and the opt-in redaction path, and shipping/sweeping both
+logs-slot gate, and the redaction path (credential floor + opt-in keys), and
+shipping/sweeping both
 would double-export every host log line (rule 12). init's sweep pins the
 contrib gem disabled even when an FDE bundles it (`spec/floor_spec.rb`).
 
@@ -289,38 +294,59 @@ https://opentelemetry.io/docs/specs/semconv/gen-ai/aws-bedrock/ ; traceloop Ruby
 
 ## 6. Redaction design record (rule 14, as amended 2026-07-26)
 
-**Redaction is FULLY OPT-IN — the default is ZERO redaction** (owner ruling
-2026-07-26, holistic-redesign decision log; `lib/foam/otel/redaction.rb`).
-With neither `redact_keys` nor `redact_pii_keys` set (or both empty) every
-value is captured RAW — attributes, headers, bodies, URL query params,
-`db.statement`, log bodies — including secrets and PII. There is NO always-on
-secrets floor and NO value-pattern auto-masking; the package auto-masks
-nothing and ships no preset. The customer owns the privacy/legal posture; the
-FDE reactive clamp is the per-customer valve.
-
-**The retired floor**: earlier revisions shipped an always-on researched
-secrets floor in `constants.rb` (roots + value-pattern pass, sourced from the
-OSS-scrubber consensus — raven-ruby, sentry, Elastic APM, Rails
-filter_parameters, gitleaks et al. — modeled on the Node core). It was
-REMOVED by the 2026-07-26 ruling; the provenance record lives in this file's
-git history and the decision log. Do not reintroduce it without a new ruling.
-
-**The current engine** (`redaction.rb`): redaction runs ONLY over the keys
-the customer enumerates. `redact_keys` matches → tail mask, shape-preserving
-(`********` + last 4 when ≥ 12 chars; the fixed 8-char body never reveals
-length; non-scalars redact in full); `redact_pii_keys` matches → full
-`[REDACTED]`, no tail. Matching is SUBSTRING, case-insensitive, over the
-lowercased key — the customer's lists, nothing inferred. The pass runs at the
-exporter boundary (`redacting_exporter.rb` — the Ruby SDK freezes span
-attributes at finish before any `on_finish` processor runs, so the exporter
-boundary is the seam; see GOTCHAS) and is a true pass-through when no keys
-are configured. The explicit `redact(value)` helper always masks (calling it
-is the opt-in). Fail-closed for listed keys (mask on any error, cycle + depth
-guarded).
-
-Proven by `spec/redaction_spec.rb` (opt-in defaults — nothing masked with no
-keys; both mask shapes; fail-closed) and `spec/redacting_exporter_spec.rb` +
-the conformance app (default-path RAW capture on the wire).
+**Redaction is FULLY OPT-IN above the CREDENTIAL FLOOR** (owner ruling
+2026-07-26, holistic-redesign decision log, AMENDED the same day by the
+credential-floor fleet ruling — `docs/decisions/credential-denylist-design.md`;
+`lib/foam/otel/redaction.rb`). With neither `redact_keys` nor
+`redact_pii_keys` set (or both empty) every value is captured RAW —
+attributes, bodies, URL query params, `db.statement`, log bodies — including
+PII, EXCEPT the one always-on exception: the CREDENTIAL FLOOR masks the
+values of the frozen credential/secret header + key NAME list
+(`contract/credential-denylist.json`: the seven headers + 52 keys, constants
+`CREDENTIAL_HEADER_DENYLIST`/`CREDENTIAL_KEY_DENYLIST` in `constants.rb`) to
+the literal `[REDACTED]`, in every signal, on every door, with NO off switch.
+There is still NO value-pattern auto-masking and NO PII preset; above the
+floor the customer owns the privacy/legal posture; the FDE reactive clamp is
+the per-customer valve.
+
+**The retired floor vs the credential floor**: earlier revisions shipped an
+always-on researched secrets floor in `constants.rb` (roots + value-pattern
+pass, sourced from the OSS-scrubber consensus — raven-ruby, sentry, Elastic
+APM, Rails filter_parameters, gitleaks et al. — modeled on the Node core). It
+was REMOVED by the 2026-07-26 zero-default ruling; the provenance record
+lives in this file's git history and the decision log. The SAME-DAY
+credential-floor ruling is the new fleet ruling that reintroduces exactly ONE
+always-on list — the frozen credential denylist (name-match only, never
+value patterns; rule-14 reference roots absorbed as entries). Its content
+changes only by a new fleet ruling and is CI-gated bit-for-bit against the
+fleet fixture (`spec/credential_floor_spec.rb`).
+
+**The current engine** (`redaction.rb`): the floor predicate
+(`floor_kind`/`floor_match?`) runs FIRST and is TERMINAL — canon-exact
+matching (trim, ASCII-lowercase, `-`→`_` fold; NEVER substring:
+`authorization` never masks `authorization_url`), including the semconv
+`http.{request,response}.header.<name>` prefix peel. Customer redaction then
+runs ONLY over the keys the customer enumerates. `redact_keys` matches → tail
+mask, shape-preserving (`********` + last 4 when ≥ 12 chars; the fixed 8-char
+body never reveals length; non-scalars redact in full); `redact_pii_keys`
+matches → full `[REDACTED]`, no tail. CUSTOMER matching is SUBSTRING,
+case-insensitive, over the lowercased key — the customer's lists, nothing
+inferred (the FLOOR deliberately does NOT ride the substring matcher — it
+would over-match). The pass runs at the exporter boundary
+(`redacting_exporter.rb` — the Ruby SDK freezes span attributes at finish
+before any `on_finish` processor runs, so the exporter boundary is the seam;
+see GOTCHAS) and runs UNCONDITIONALLY (the floor has no off state); values
+under unmatched names ride through raw, and tenant `additional_*` processors
+receive the masked VIEW (`pipelines.rb`, GOTCHAS F1). The explicit
+`redact(value)` helper always masks (calling it is the opt-in). Fail-closed
+for floor + listed keys (mask on any error, cycle + depth guarded).
+
+Proven by `spec/credential_floor_spec.rb` + `spec/credential_floor_wire_spec.rb`
+(the floor: list identity gate, matcher, every signal, doors 1+2, tenant
+view, negative controls), `spec/redaction_spec.rb` (raw-above-the-floor
+defaults — nothing else masked with no keys; both mask shapes; fail-closed)
+and `spec/redacting_exporter_spec.rb` + the conformance app (default-path RAW
+capture on the wire, floor names excepted).
 
 ---
 

data/lib/foam/otel/api.rb

@@ -105,13 +105,14 @@ module Foam
         span = OpenTelemetry::Trace.current_span
         return false unless span.respond_to?(:recording?) && span.recording?
 
-        # Capture-time key pass (rule 18 C.3): when the customer configured
-        # redact_keys/redact_pii_keys the value lands ALREADY-MASKED, so tenant
-        # processors and inert-mode providers only ever see the redacted view of
-        # helper-set data. The exporter pass re-applies (idempotent). With no
-        # keys configured this is a pass-through — the value is captured RAW.
-        # scrub_utf8 is encoding hygiene, not masking: an invalid-UTF-8 value
-        # would make the upstream OTLP encoder drop the WHOLE batch (rule 15).
+        # Capture-time pass (rule 18 C.3): the always-on credential floor plus
+        # any configured redact_keys/redact_pii_keys, so the value lands
+        # ALREADY-MASKED — tenant processors and inert-mode providers only ever
+        # see the redacted view of helper-set data. The exporter pass
+        # re-applies (idempotent). Values under unmatched names are captured
+        # RAW. scrub_utf8 is encoding hygiene, not masking: an invalid-UTF-8
+        # value would make the upstream OTLP encoder drop the WHOLE batch
+        # (rule 15).
         span.set_attribute(key.to_s, Redaction.mask_one(key.to_s, Redaction.scrub_utf8(value), active_config))
         true
       rescue StandardError, SystemStackError
@@ -260,14 +261,14 @@ module Foam
         LEVEL_TEXT[severity.to_s.downcase.to_sym]
       end
 
-      # Stringify keys, then apply the customer's key lists AT CAPTURE (rule 18
-      # C.3): when redact_keys/redact_pii_keys are configured, helper-set
-      # attributes are ALREADY-MASKED when they reach the span/log record, so a
-      # tenant processor (or a foreign provider in inert mode) only ever sees the
-      # redacted view of foam-helper data. The exporter-boundary pass re-applies
-      # — masking is idempotent. With no keys configured this is a pass-through
-      # (raw capture). NEVER throws (rule 9): non-enumerable garbage degrades to
-      # nil (attributes dropped, telemetry still flows).
+      # Stringify keys, then apply the credential floor + the customer's key
+      # lists AT CAPTURE (rule 18 C.3): helper-set attributes are
+      # ALREADY-MASKED when they reach the span/log record, so a tenant
+      # processor (or a foreign provider in inert mode) only ever sees the
+      # redacted view of foam-helper data. The exporter-boundary pass
+      # re-applies — masking is idempotent. Values under unmatched names ride
+      # RAW. NEVER throws (rule 9): non-enumerable garbage degrades to nil
+      # (attributes dropped, telemetry still flows).
       def stringify(attributes)
         return nil if attributes.nil?
 
@@ -279,10 +280,11 @@ module Foam
         nil
       end
 
-      # The customer key pass over a log BODY at capture (same rationale as
-      # stringify). When keys are configured mask_body is fail-closed and
-      # depth-guarded, so a cyclic structure is bounded before it can reach any
-      # encoder; with no keys configured the body is captured RAW.
+      # The floor + customer key pass over a log BODY at capture (same
+      # rationale as stringify). mask_body is fail-closed and depth-guarded,
+      # so a cyclic structure is bounded before it can reach any encoder; a
+      # free-text body (and every structured field under an unmatched name)
+      # is captured RAW.
       def mask_log_body(body)
         return body if body.nil?
 

data/lib/foam/otel/config.rb

@@ -42,8 +42,10 @@ module Foam
           environment: environment,
           version: version,
           enabled: enabled,
-          # Opt-in redaction (holistic redesign): the ONLY keys ever redacted.
-          # Empty (the default) → zero redaction, raw capture. Stored lowercased
+          # Opt-in CUSTOMER redaction (holistic redesign), additive above the
+          # always-on credential floor (which is a module constant, NOT config
+          # state — no config shape can alter it). Empty (the default) → no
+          # customer redaction, raw capture above the floor. Stored lowercased
           # for the engine's case-insensitive substring match.
           redact_keys: downcase_list(redact_keys),
           redact_pii_keys: downcase_list(redact_pii_keys),

data/lib/foam/otel/constants.rb

@@ -13,24 +13,117 @@ module Foam
     DISTRO_NAME = "foam"
 
     # Deep-redaction depth guard (rule 14). Beyond this, a value redacts in
-    # full rather than recursing further.
-    MAX_REDACT_DEPTH = 12
+    # full rather than recursing further. Pinned at 10 fleet-wide (contract
+    # SPEC §4; credential-denylist-design §4 cross-core table) — every core
+    # walks to the same depth so the floor's coverage is byte-identical.
+    MAX_REDACT_DEPTH = 10
 
     # deployment.environment.name values that do NOT warn (section 0: the
     # value is exported verbatim regardless; anything outside this set warns
     # but is never rewritten).
     KNOWN_ENVIRONMENTS = %w[production staging development test].freeze
 
-    # ---- Redaction is FULLY OPT-IN (holistic redesign, 2026-07-26) ----------
-    # The package does NO redaction by default: with neither redact_keys nor
-    # redact_pii_keys set (or both empty) every value is captured RAW,
-    # including secrets / PII / PHI. There is NO always-on secret floor and NO
-    # value-pattern auto-masking — the package auto-masks NOTHING. Redaction
-    # happens ONLY for the exact keys the customer enumerates:
+    # ---- Redaction is FULLY OPT-IN above the CREDENTIAL FLOOR ---------------
+    # (holistic redesign 2026-07-26, amended the same day by the
+    # credential-floor fleet ruling.) The package does NO redaction by default
+    # — with neither redact_keys nor redact_pii_keys set every value is
+    # captured RAW, including PII / PHI — EXCEPT the one always-on exception:
+    # the CREDENTIAL FLOOR below, which masks the values of the frozen
+    # credential/secret NAMES to the literal [REDACTED] in every signal, on
+    # every export path, with NO off switch. Everything not on the frozen list
+    # still exports RAW (no value-pattern auto-masking, no PII preset).
+    # Customer redaction happens ONLY for the exact keys the customer
+    # enumerates, ADDITIVE on top of the floor:
     #   * redact_keys     → tail-mask the value (shape-preserving; see below)
     #   * redact_pii_keys → erase the value ([REDACTED])
-    # (See docs/decisions/holistic-redesign-decision-log.md — "Redaction is
-    # FULLY OPT-IN".) The customer owns the privacy/legal posture.
+    # (See docs/decisions/holistic-redesign-decision-log.md and
+    # docs/decisions/credential-denylist-design.md.) Above the floor, the
+    # customer owns the privacy/legal posture.
+
+    # ---- THE CREDENTIAL FLOOR (fleet ruling 2026-07-26) ---------------------
+    # Frozen fleet constants, byte-identical in every core and gate-checked
+    # bit-for-bit against contract/credential-denylist.json (order included) by
+    # spec/credential_floor_spec.rb. They change ONLY by a new fleet ruling —
+    # never ship a subset, a superset, or a re-spelling. The floor is matched
+    # by Redaction.floor_kind: case-insensitive, dash/underscore-normalized
+    # EXACT name-equality — never substring ("authorization" never masks
+    # "authorization_url"; "secret" never masks "secretary"). It is deliberately
+    # NOT part of Config: no init option, env var, or door-2 parameter can
+    # build a floor-less engine (design §4 — safety is not configurable away).
+
+    # (a) The seven credential HEADERS, stored in wire-canonical dash form —
+    # matched as header names wherever headers are captured, including the
+    # semconv http.{request,response}.header.<name> span-attribute forms.
+    CREDENTIAL_HEADER_DENYLIST = %w[
+      authorization
+      proxy-authorization
+      cookie
+      set-cookie
+      x-api-key
+      x-auth-token
+      www-authenticate
+    ].freeze
+
+    # (b) The 52-entry KEY denylist, stored in canonical (lowercase,
+    # underscore) form, ASCII byte order — the deduplicated union of the seven
+    # headers, sentry-python's DEFAULT_DENYLIST + DEFAULT_PII_DENYLIST, and
+    # BASE_PACKAGE_SPEC rule 14's reference roots (design doc §1.2). Matched as
+    # attribute/field names at every depth the central engine walks. Every
+    # header above is also an entry here (subset invariant, design §1.1).
+    CREDENTIAL_KEY_DENYLIST = %w[
+      _csrf
+      _csrf_token
+      _session
+      _xsrf
+      aiohttp_session
+      api_key
+      apikey
+      auth
+      authorization
+      bearer
+      card
+      connect.sid
+      cookie
+      credential
+      credentials
+      csrf
+      csrf_token
+      csrftoken
+      cvc
+      cvv
+      ip_address
+      jwt
+      mfa
+      mysql_pwd
+      otp
+      passphrase
+      passwd
+      password
+      phpsessid
+      private_key
+      privatekey
+      proxy_authorization
+      pwd
+      remote_addr
+      secret
+      session
+      sessionid
+      set_cookie
+      sid
+      signature
+      ssn
+      symfony
+      token
+      user_session
+      www_authenticate
+      x_api_key
+      x_auth_token
+      x_csrftoken
+      x_forwarded_for
+      x_real_ip
+      xsrf
+      xsrf_token
+    ].freeze
 
     # The two mask shapes. A redact_keys match on a scalar keeps a debug tail;
     # a redact_pii_keys match (and any non-scalar value under a redact_keys

data/lib/foam/otel/pipelines.rb

@@ -4,6 +4,8 @@
 # export path, after it has lazily required the OTel SDK + exporters. A
 # provider is built and registered ONLY for a signal the classifier proved
 # FREE (BASE_PACKAGE_SPEC rule 18): foam never registers into a claimed slot.
+require "delegate"
+
 require_relative "redacting_exporter"
 require_relative "session_stitching"
 
@@ -58,7 +60,7 @@ module Foam
         # on_finish). Foam's batch export stays FIRST (pinned invariant).
         provider.add_span_processor(SessionStitching::SpanProcessor.new)
         Array(extra_processors).each do |processor|
-          provider.add_span_processor(GuardedSpanProcessor.new(processor))
+          provider.add_span_processor(GuardedSpanProcessor.new(processor, config))
         rescue StandardError => e
           Diagnostics.warn("additional span processor skipped: #{e.class}: #{e.message}")
         end
@@ -96,7 +98,7 @@ module Foam
         # batch export stays FIRST (pinned invariant).
         provider.add_log_record_processor(SessionStitching::LogRecordProcessor.new)
         Array(extra_processors).each do |processor|
-          provider.add_log_record_processor(GuardedLogRecordProcessor.new(processor))
+          provider.add_log_record_processor(GuardedLogRecordProcessor.new(processor, config))
         rescue StandardError => e
           Diagnostics.warn("additional log processor skipped: #{e.class}: #{e.message}")
         end
@@ -130,14 +132,14 @@ module Foam
         inner = OpenTelemetry::Exporter::OTLP::Metrics::MetricsExporter.new(
           endpoint: "#{endpoint}/v1/metrics", headers: headers
         )
-        # The exporter-boundary key pass, same as traces and logs above. A
-        # pass-through unless the customer configured redact_keys/redact_pii_keys.
+        # The exporter-boundary pass (credential floor + customer keys), same
+        # as traces and logs above — always on, raw for unmatched names.
         # get_meter is public passthrough surface: instruments created through it
         # (including observable-gauge callbacks) and contrib instrumentation
         # emitting metrics record attributes that pass NEITHER Metrics.stringify
-        # (four foam helpers only) NOR the capture-time pass — so when keys ARE
-        # configured this wrapper is what applies them on foam's own door-1
-        # metrics pipeline. The wrapper forwards `reset` for after_fork, so
+        # (four foam helpers only) NOR the capture-time pass — so this wrapper
+        # is what applies the floor (and any configured keys) on foam's own
+        # door-1 metrics pipeline. The wrapper forwards `reset` for after_fork, so
         # PeriodicMetricReader's fork recovery is unaffected (GOTCHAS R1/R7).
         exporter = RedactingMetricsExporter.new(inner, config)
         reader = OpenTelemetry::SDK::Metrics::Export::PeriodicMetricReader.new(exporter: exporter)
@@ -166,14 +168,85 @@ module Foam
       end
     end
 
+    # The tenant-seam MASKED VIEW (credential-floor design §5.4 / rule 18 C):
+    # the Ruby SDK freezes span attributes at finish BEFORE any on_finish
+    # processor runs (GOTCHAS F1), so foam cannot rewrite the span a tenant
+    # sees — instead the guarded wrappers below hand tenants a READ-ONLY
+    # delegator whose attributes/events/links/to_span_data are served from the
+    # SAME Redaction.mask_span_data pass foam's exporter applies (the
+    # credential floor + the customer's init-time key lists). Tenants only
+    # ever see the masked view — a raw floor value never crosses the seam,
+    # third-party instrumentation attributes included. Everything else
+    # (name, kind, context, status, resource, scope…) delegates to the real
+    # span untouched.
+    class MaskedSpanView < SimpleDelegator
+      def initialize(span, masked_span_data)
+        super(span)
+        @masked = masked_span_data
+      end
+
+      def attributes = @masked.attributes
+      def events = @masked.events
+      def links = @masked.links
+      def to_span_data = @masked
+    end
+
+    # The logs twin: on_emit receives the LIVE record, so the view masks
+    # attributes and body lazily through the same engine (floor + customer
+    # keys), fail-closed — a read that cannot be masked degrades to the mask,
+    # never the raw value. Reads happen AFTER foam's earlier processors
+    # (export buffer, session stitching) ran, so the tenant misses nothing.
+    class MaskedLogRecordView < SimpleDelegator
+      def initialize(record, config)
+        super(record)
+        @config = config
+      end
+
+      def attributes
+        @attributes ||= begin
+          Foam::Otel::Redaction.mask_attributes(__getobj__.attributes, @config)
+        rescue StandardError, SystemStackError
+          {} # fail closed: never the raw attributes
+        end
+      end
+
+      def body
+        @body ||= begin
+          Foam::Otel::Redaction.mask_body(__getobj__.body, @config)
+        rescue StandardError, SystemStackError
+          Foam::Otel::REDACTED # fail closed: never the raw body
+        end
+      end
+    end
+
     # A tenant span/log processor supplied via additional_* — wrapped so a
     # throwing tenant instance is skipped with a loud warning and breaks
     # neither the app nor foam's export (rule 18 C / rule 9). Never-throw is
-    # foam's guarantee for foam-invoked calls; the wrapper enforces it.
+    # foam's guarantee for foam-invoked calls; the wrapper enforces it. The
+    # wrapper is ALSO the tenant seam's masking point: on_finish/on_emit hand
+    # the tenant the masked view above, never the raw item (credential floor,
+    # capture-time clause — tenants only ever see the masked view).
     class GuardedSpanProcessor
-      def initialize(inner) = @inner = inner
+      def initialize(inner, config = nil)
+        @inner = inner
+        @config = config
+      end
+
       def on_start(span, context) = guarded { @inner.on_start(span, context) }
-      def on_finish(span) = guarded { @inner.on_finish(span) }
+
+      def on_finish(span)
+        guarded do
+          masked = Foam::Otel::Redaction.mask_span_data(span.to_span_data, @config)
+          if masked.nil?
+            # Fail closed, loudly (rule 15): a span whose masked view cannot be
+            # built is WITHHELD from the tenant, never handed over raw.
+            Foam::Otel::Diagnostics.warn("tenant span view masking failed — span withheld from " \
+                                         "additional span processor (fail-closed, rule 14)")
+          else
+            @inner.on_finish(MaskedSpanView.new(span, masked))
+          end
+        end
+      end
       def force_flush(timeout: nil) = guarded { @inner.force_flush(timeout: timeout) } || OpenTelemetry::SDK::Trace::Export::SUCCESS
       def shutdown(timeout: nil) = guarded { @inner.shutdown(timeout: timeout) } || OpenTelemetry::SDK::Trace::Export::SUCCESS
 
@@ -188,8 +261,12 @@ module Foam
     end
 
     class GuardedLogRecordProcessor
-      def initialize(inner) = @inner = inner
-      def on_emit(log_record, context) = guarded { @inner.on_emit(log_record, context) }
+      def initialize(inner, config = nil)
+        @inner = inner
+        @config = config
+      end
+
+      def on_emit(log_record, context) = guarded { @inner.on_emit(MaskedLogRecordView.new(log_record, @config), context) }
       def force_flush(timeout: nil) = guarded { @inner.force_flush(timeout: timeout) } || OpenTelemetry::SDK::Logs::Export::SUCCESS
       def shutdown(timeout: nil) = guarded { @inner.shutdown(timeout: timeout) } || OpenTelemetry::SDK::Logs::Export::SUCCESS
 

data/lib/foam/otel/redacting_exporter.rb

@@ -5,16 +5,19 @@ require_relative "diagnostics"
 
 module Foam
   module Otel
-    # The customer's opt-in key pass (redact_keys / redact_pii_keys) runs HERE,
-    # at the exporter boundary. Why not a SpanProcessor: the Ruby SDK freezes a
-    # span's attributes at finish, BEFORE any on_finish processor runs
-    # (opentelemetry-sdk span.rb — GOTCHAS entry), so no processor can mask them.
-    # SpanData / LogRecordData / Event are mutable Structs the exporter can
-    # rebuild, so masking happens on the copy foam serializes. With NO keys
-    # configured (the default) this is a pass-through — every value ships RAW.
-    # (Foam's own HELPERS additionally apply the same key pass at capture —
-    # api.rb stringify / set_attribute — so the tenant seam sees helper-set data
-    # already masked when keys are configured.)
+    # The central enforcement point: the ALWAYS-ON CREDENTIAL FLOOR
+    # (constants.rb / redaction.rb — fleet ruling 2026-07-26) plus the
+    # customer's opt-in key pass (redact_keys / redact_pii_keys) run HERE, at
+    # the exporter boundary, on door 1 AND door 2. Why not a SpanProcessor:
+    # the Ruby SDK freezes a span's attributes at finish, BEFORE any on_finish
+    # processor runs (opentelemetry-sdk span.rb — GOTCHAS entry), so no
+    # processor can mask them. SpanData / LogRecordData / Event are mutable
+    # Structs the exporter can rebuild, so masking happens on the copy foam
+    # serializes. The pass runs UNCONDITIONALLY — the floor has no off switch;
+    # values under unmatched names ship RAW. (Foam's own HELPERS additionally
+    # apply the same pass at capture — api.rb stringify / set_attribute — and
+    # the tenant seam hands additional_* processors a masked VIEW —
+    # pipelines.rb — so tenants only ever see masked data.)
     #
     # These wrap (never subclass) the real OTLP exporter by composition, so
     # they are robust across exporter versions — they only rely on the
@@ -27,12 +30,12 @@ module Foam
     # rescued explicitly (it is not a StandardError): a poisoned payload must
     # kill neither the batch thread nor the caller (rule 9 / rule 15).
     #
-    # Documented Ruby divergence (RESEARCH.md / GOTCHAS F1): because attributes
-    # freeze at finish, a tenant additional_span_processor sees THIRD-PARTY
-    # INSTRUMENTATION attributes unmasked — the "tenant sees already masked"
-    # guarantee (rule 18 C) holds for foam-captured/helper-set data and the
-    # redact() helper, but foam cannot mask third-party instrumentation
-    # attributes before the tenant processor in Ruby.
+    # The F1 tenant divergence is CLOSED (1.3.0, credential-floor design §5.4):
+    # attributes still freeze at finish, so they cannot be masked IN PLACE
+    # before a tenant additional_* processor — instead the guarded tenant
+    # wrappers (pipelines.rb) hand tenants a read-only MASKED VIEW built
+    # through the same Redaction pass these exporters apply, third-party
+    # instrumentation attributes included.
     class RedactingSpanExporter
       def initialize(inner, config)
         @inner = inner

data/lib/foam/otel/redaction.rb

@@ -1,23 +1,44 @@
 # frozen_string_literal: true
 
 require "json"
+require "set"
 require "uri"
 
 require_relative "constants"
+require_relative "diagnostics"
 
 module Foam
   module Otel
-    # Opt-in, key-list redaction (holistic redesign, 2026-07-26). The package
-    # does NO redaction by default: with neither redact_keys nor redact_pii_keys
-    # set (or both empty) every value is captured RAW — there is NO always-on
-    # secret floor and NO value-pattern auto-masking. Redaction runs ONLY over
-    # the keys the customer enumerates:
+    # The central redaction engine: the always-on CREDENTIAL FLOOR plus the
+    # customer's opt-in key lists (holistic redesign 2026-07-26, amended the
+    # same day by the credential-floor fleet ruling —
+    # docs/decisions/credential-denylist-design.md).
+    #
+    # THE FLOOR (unconditional, no off switch): every attribute/field whose
+    # NAME is on the frozen CREDENTIAL_KEY_DENYLIST (constants.rb) — including
+    # the semconv http.{request,response}.header.<name> forms of the
+    # CREDENTIAL_HEADER_DENYLIST — masks in FULL to the literal [REDACTED], in
+    # every signal, at every depth this engine walks, before the customer's
+    # lists run. Matching is canon-exact (lowercase + dash→underscore fold,
+    # design §1.0/§2.1): NEVER substring — "authorization" does not mask
+    # "authorization_url"; "secret" does not mask "secretary". The floor
+    # consults the module-level frozen constant directly (never Config), so no
+    # configuration path can disable, shrink, or re-spell it.
+    #
+    # ABOVE the floor, redaction stays fully opt-in: with neither redact_keys
+    # nor redact_pii_keys set (or both empty) every OTHER value is captured RAW
+    # — no value-pattern auto-masking. Customer redaction runs ONLY over the
+    # keys the customer enumerates, ADDITIVE on top of the floor:
     #
     #   * redact_keys     — tail-mask matching scalar values (shape-preserving,
     #                       e.g. ********f456); non-scalars redact in full.
     #   * redact_pii_keys — erase matching values in full ([REDACTED]).
     #
-    # Matching is SUBSTRING, case-insensitive, over the lowercased key.
+    # CUSTOMER matching is SUBSTRING, case-insensitive, over the lowercased key
+    # (documented Ruby behavior, unchanged). The FLOOR deliberately does NOT
+    # ride that matcher (design §2.4 — substring would over-match): it uses its
+    # own canon-exact predicate, floor_kind, below. A floor match is TERMINAL:
+    # listing a floor name in redact_keys never downgrades it to a tail mask.
     #
     # Two entry points:
     #   * redact(value)            — the public helper: mask a value the caller
@@ -27,9 +48,12 @@ module Foam
     #                                calling it.
     #   * mask_span_data / mask_log_record_data / mask_metric_data — the
     #                                exporter-boundary pass that applies the
-    #                                customer's key lists, run by the redacting
-    #                                exporters (redacting_exporter.rb). A true
-    #                                pass-through when no keys are configured.
+    #                                floor plus the customer's key lists, run by
+    #                                the redacting exporters
+    #                                (redacting_exporter.rb) on door 1 AND all
+    #                                three door-2 taps. Runs UNCONDITIONALLY —
+    #                                the floor has no off switch; values under
+    #                                unlisted names pass through raw.
     #
     # Ruby SDK constraint (see GOTCHAS.md): a Span freezes its attributes at
     # finish (opentelemetry-sdk span.rb) BEFORE any SpanProcessor#on_finish
@@ -94,8 +118,10 @@ module Foam
         "#{MASK_BODY}#{s[-4..]}"
       end
 
-      # True when the customer enumerated at least one key to redact. With
-      # neither list set the package does ZERO redaction (raw capture).
+      # True when the customer enumerated at least one key to redact — the
+      # CUSTOMER lists only. The credential floor runs regardless: this
+      # predicate gates only customer-list behavior (e.g. the exemplar-drop
+      # posture below), never the floor.
       def redaction_configured?(config)
         return false if config.nil?
 
@@ -106,25 +132,89 @@ module Foam
         false
       end
 
-      # ---- the customer key pass over exported attributes ------------------
-      # Returns a NEW attributes hash with the customer's key lists applied, or
-      # the same hash untouched when no keys are configured. Never raises; a key
-      # that fails to mask redacts in full rather than leaking.
+      # ---- the credential-floor predicate (design §2, self-contained) -------
+      # canon(name): trim ASCII whitespace → ASCII-lowercase → fold '-' to '_'
+      # (design §1.0). Applied to BOTH sides of every floor comparison; the
+      # stored CREDENTIAL_KEY_DENYLIST entries are already canonical.
+      def canon(name)
+        name.to_s.strip.downcase(:ascii).tr("-", "_")
+      end
+
+      # The two semconv header-attribute prefixes — the ONLY prefixes the floor
+      # peels (design §2.2). Canonical (lowercase, no dashes), so matching the
+      # canon'd name covers any case variant of the prefix too.
+      FLOOR_HEADER_PREFIXES = ["http.request.header.", "http.response.header."].freeze
+
+      # O(1) lookup set for the frozen key list (the array stays the shipped,
+      # fixture-gated constant; this is a derived view, same object identity of
+      # entries).
+      FLOOR_KEY_SET = CREDENTIAL_KEY_DENYLIST.to_set.freeze
+
+      # Classify a name against the FLOOR ONLY (never the customer lists):
+      #   :header — a semconv header attribute (http.{request,response}
+      #             .header.<name>) whose peeled suffix canon-matches the key
+      #             list (which contains all seven headers — subset invariant,
+      #             design §1.1; the peel checks the FULL 52-entry list, §2.2,
+      #             so e.g. http.request.header.x_forwarded_for masks too);
+      #   :key    — the full name itself canon-matches a key-list entry
+      #             (full-name equality: "user.session" does NOT match
+      #             "session"; "connect.sid" matches its own verbatim entry);
+      #   nil     — no floor match (customer lists may still apply).
+      def floor_kind(name)
+        c = canon(name)
+        FLOOR_HEADER_PREFIXES.each do |prefix|
+          next unless c.start_with?(prefix)
+
+          return FLOOR_KEY_SET.include?(c[prefix.length..]) ? :header : nil
+        end
+        FLOOR_KEY_SET.include?(c) ? :key : nil
+      end
+
+      def floor_match?(name)
+        !floor_kind(name).nil?
+      end
+
+      # The floor mask (design §3): a semconv header attribute is a string
+      # array (one element per header instance) — mask PER ELEMENT, preserving
+      # arity and the string-array type (OTel's own sanitize_header_values
+      # shape). Everything else replaces the ENTIRE value with the single
+      # literal [REDACTED] — scalar, object, array, number, binary. Never a
+      # tail, never length-preserving: these are credentials, not debug aids.
+      def floor_mask(kind, value)
+        return value.map { REDACTED } if kind == :header && value.is_a?(Array)
+
+        REDACTED
+      end
+
+      # ---- the floor + customer key pass over exported attributes -----------
+      # Returns a NEW attributes hash with the credential floor and the
+      # customer's key lists applied. Runs UNCONDITIONALLY (the floor has no
+      # off switch); values under unmatched names pass through raw (same
+      # objects). Never raises; a key that fails to mask redacts in full
+      # rather than leaking.
       def mask_attributes(attributes, config)
         return attributes unless attributes.is_a?(Hash)
-        return attributes unless redaction_configured?(config)
 
         attributes.each_with_object({}) do |(key, value), out|
           out[key] = mask_one(key.to_s, value, config)
         rescue StandardError
+          # Fail closed at the VALUE level, loudly (rule 15): the key name only
+          # — never the value — reaches the diagnostics channel. The warning is
+          # itself guarded: a poisoned key (#to_s raises) must still redact.
+          begin
+            Diagnostics.warn("masking failed for attribute #{key.to_s.inspect} — value redacted in full " \
+                             "(fail-closed, rule 14)")
+          rescue StandardError, SystemStackError
+            Diagnostics.warn("masking failed for an attribute (unprintable key) — value redacted in full " \
+                             "(fail-closed, rule 14)")
+          end
           out[key] = REDACTED
         end
       end
 
       def mask_one(key, value, config)
-        return value unless redaction_configured?(config)
-
         case classify_key(key, config)
+        when :floor then floor_mask(floor_kind(key), value)
         when :erase then REDACTED
         when :mask  then value.is_a?(Array) ? value.map { REDACTED } : scalar_or_full(value)
         else
@@ -146,10 +236,10 @@ module Foam
       end
 
       # Unmatched key: the value itself is captured RAW (no value-pattern
-      # auto-masking). Structured values still DESCEND so a redact_keys/
-      # redact_pii_keys key NESTED under an innocent key is honored — bounded to
-      # MAX_REDACT_DEPTH so an adversarial/cyclic structure can never drive a
-      # downstream encoder into SystemStackError (rule 9).
+      # auto-masking). Structured values still DESCEND so a floor-listed or
+      # redact_keys/redact_pii_keys key NESTED under an innocent key is honored
+      # — bounded to MAX_REDACT_DEPTH so an adversarial/cyclic structure can
+      # never drive a downstream encoder into SystemStackError (rule 9).
       def descend(value, config = nil, depth = 0)
         case value
         when Hash, Array then deep_mask(value, config || Foam::Otel.active_config, depth)
@@ -158,9 +248,17 @@ module Foam
       end
 
       # ---- key classification ----------------------------------------------
-      # redact_keys (:mask) wins over redact_pii_keys (:erase) when both claim a
-      # key. Substring, case-insensitive.
+      # The credential floor is checked FIRST and is TERMINAL (design §4): a
+      # floor-matched name is [REDACTED] in full even when the customer also
+      # lists it in redact_keys — the tail pass must never see a floor value (a
+      # tail mask over the [REDACTED] literal would emit ******** and destroy
+      # the contract literal). Below the floor: redact_keys (:mask) wins over
+      # redact_pii_keys (:erase) when both claim a key. Customer matching is
+      # substring, case-insensitive (unchanged).
       def classify_key(key, config)
+        return :floor if floor_match?(key)
+        return nil if config.nil?
+
         lower = key.downcase
         return :mask if match_any_substring?(lower, config.redact_keys)
         return :erase if match_any_substring?(lower, config.redact_pii_keys)
@@ -176,9 +274,11 @@ module Foam
 
       # ---- URL / query redaction -------------------------------------------
       # The instrumentation-set URL attributes (rack, http clients). Redact the
-      # query PER KEY so non-secret pairs survive: with redact_keys=["token"],
-      # `?token=x&user=bob` exports as `token=[REDACTED]&user=bob`. Only keys the
-      # customer listed are ever touched.
+      # query PER KEY so non-secret pairs survive: `?token=x&user=bob` exports
+      # as `token=[REDACTED]&user=bob`. A pair is touched only when its key is
+      # on the credential floor (canon-exact — the floor's `signature` entry
+      # covers OTel's own PARAMS_TO_REDACT `Signature` case-insensitively) or
+      # on one of the customer's lists.
       URL_ATTRIBUTES = %w[http.target url.query url.full http.url uri.query].freeze
 
       def url_attribute?(key)
@@ -214,8 +314,9 @@ module Foam
           rescue StandardError
             raw_key.downcase
           end
-          if match_any_substring?(decoded, config.redact_keys) ||
-             match_any_substring?(decoded, config.redact_pii_keys)
+          if floor_match?(decoded) ||
+             match_any_substring?(decoded, config&.redact_keys) ||
+             match_any_substring?(decoded, config&.redact_pii_keys)
             "#{raw_key}=#{REDACTED}"
           else
             pair
@@ -225,18 +326,16 @@ module Foam
         ""
       end
 
-      # ---- exporter-boundary key pass (SpanData / LogRecordData) ------------
-      # Rebuild the mutable Struct with the customer's key lists applied. A dup
-      # keeps foam's export copy independent of the span the tenant seam saw.
-      # With no keys configured this is a true PASS-THROUGH: the original struct
-      # is returned untouched (ZERO redaction — raw capture).
+      # ---- exporter-boundary pass (SpanData / LogRecordData) ----------------
+      # Rebuild the mutable Struct with the credential floor and the customer's
+      # key lists applied. A dup keeps foam's export copy independent of the
+      # span the tenant seam saw. Runs UNCONDITIONALLY (the floor has no off
+      # switch); values under unmatched names are carried through raw.
       #
       # FAIL CLOSED: on a hard failure these return NIL — never the raw payload
-      # once a key pass has begun. The redacting exporters drop a nil entry
+      # once the pass has begun. The redacting exporters drop a nil entry
       # (with a loud [foam] warning) rather than export a half-masked record.
       def mask_span_data(span_data, config)
-        return span_data unless redaction_configured?(config)
-
         masked = span_data.dup
         masked.attributes = mask_attributes(span_data.attributes, config) if span_data.attributes
         # Link attributes ride the key pass too: links are reachable on BOTH
@@ -263,8 +362,6 @@ module Foam
       end
 
       def mask_log_record_data(record, config)
-        return record unless redaction_configured?(config)
-
         masked = record.dup
         masked.attributes = mask_attributes(record.attributes, config) if record.attributes
         masked.body = mask_body(record.body, config) if record.body
@@ -275,27 +372,21 @@ module Foam
 
       # Door 1 masks metric attributes at capture; foreign (door-2) instrument
       # data never passes those helpers, so the ingest metric path applies the
-      # key lists here. Rebuilds every data point as a COPY (the collected
-      # points' attributes hash is the LIVE aggregation key upstream — masking
-      # in place would corrupt the customer's aggregation state). A true
-      # pass-through when no keys are configured.
+      # floor + key lists here. Rebuilds every data point as a COPY (the
+      # collected points' attributes hash is the LIVE aggregation key upstream —
+      # masking in place would corrupt the customer's aggregation state). Runs
+      # UNCONDITIONALLY (the floor has no off switch).
       #
       # FAIL CLOSED: returns NIL on a hard failure — the caller drops the metric
       # loudly rather than exporting a half-masked point.
       def mask_metric_data(metric_data, config)
-        return metric_data unless redaction_configured?(config)
-
         masked = metric_data.dup
         points = metric_data.data_points
         if points
           masked.data_points = points.map do |point|
             copy = point.dup
             copy.attributes = mask_attributes(point.attributes || {}, config)
-            # Exemplars carry filtered_attributes the OTLP exporter encodes RAW,
-            # one field over from the point attributes the key pass just masked.
-            # Once redaction is configured, drop them: fail-closed, no
-            # observability cost for foam's own use.
-            copy.exemplars = nil if copy.respond_to?(:exemplars=)
+            mask_exemplars!(copy, config)
             copy
           end
         end
@@ -304,13 +395,42 @@ module Foam
         nil
       end
 
+      # Exemplars carry filtered_attributes the OTLP exporter encodes RAW, one
+      # field over from the point attributes just masked — the floor must reach
+      # them too (design §2.3). Two postures, both fail-closed:
+      #   * customer keys configured → DROP exemplars entirely (the documented
+      #     pre-floor behavior for configured redaction, unchanged);
+      #   * floor only (the default path) → keep the exemplars but run their
+      #     filtered_attributes through the same engine pass, so floor-listed
+      #     names are [REDACTED] and everything else stays raw (§9: the only
+      #     default-path wire delta is floor values becoming [REDACTED]). An
+      #     exemplar whose rebuild fails is dropped, never exported raw.
+      def mask_exemplars!(point, config)
+        return unless point.respond_to?(:exemplars=)
+
+        if redaction_configured?(config)
+          point.exemplars = nil
+          return
+        end
+        exemplars = point.respond_to?(:exemplars) ? point.exemplars : nil
+        return if exemplars.nil?
+
+        point.exemplars = exemplars.filter_map do |exemplar|
+          copy = exemplar.dup
+          copy.filtered_attributes = mask_attributes(exemplar.filtered_attributes || {}, config)
+          copy
+        rescue StandardError
+          nil # fail closed: a poisoned exemplar drops, never ships raw
+        end
+      rescue StandardError
+        point.exemplars = nil # fail closed at the list level too
+      end
+
       # A log body is AnyValue: a free-text string is captured RAW (no
-      # value-pattern masking), a structured map/array DESCENDS so a listed key
-      # nested inside is honored (depth-guarded). Pass-through when no keys are
-      # configured.
+      # value-pattern masking — the floor matches NAMES, never scans content), a
+      # structured map/array DESCENDS so a floor-listed or customer-listed key
+      # nested inside is honored (depth-guarded). Runs unconditionally.
       def mask_body(body, config)
-        return body unless redaction_configured?(config)
-
         deep_mask(body, config, 0)
       rescue StandardError
         REDACTED
@@ -323,6 +443,7 @@ module Foam
         when Hash
           value.each_with_object({}) do |(key, val), out|
             case classify_key(key.to_s, config)
+            when :floor then out[key] = floor_mask(floor_kind(key.to_s), val)
             when :erase then out[key] = REDACTED
             when :mask  then out[key] = scalar_or_full(val)
             else out[key] = deep_mask(val, config, depth + 1)

data/lib/foam/otel/version.rb

@@ -17,6 +17,19 @@ module Foam
     #   -logger pinned disabled in the sweep (foam's LoggerBridge supersedes
     #   it — rule 12 double-bridge guard). Sidekiq + Faraday floor entries
     #   wire-proven (rule 8b); Sidekiq :link posture documented (GOTCHAS G16).
-    VERSION = "1.2.1"
+    # 1.3.0: ALWAYS-ON CREDENTIAL FLOOR (fleet ruling 2026-07-26; MINOR per the
+    #   ruling — security-motivated wire change, no API/config change,
+    #   docs/decisions/credential-denylist-design.md §9). Foam now masks, by
+    #   default and in every signal, the VALUES of the fixed credential/secret
+    #   header + field NAME list in contract/credential-denylist.json (seven
+    #   headers + 52 keys) to the literal [REDACTED]. Exact name-equality,
+    #   case-insensitive, dash/underscore-insensitive — never substring:
+    #   authorization_url is untouched. Everything else still exports RAW;
+    #   redact_keys/redact_pii_keys unchanged and additive; NO off switch.
+    #   Tenant additional_* processors now receive a MASKED read-only view
+    #   (closes the GOTCHAS F1 third-party-attribute divergence). If a
+    #   dashboard keyed off a raw credential value (it should not have), it
+    #   will now see [REDACTED].
+    VERSION = "1.3.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: foam-otel
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.3.0
 platform: ruby
 authors:
 - Foam