## Status

Draft

## Story

**As a** security/compliance owner,
**I want** clearly documented redaction guarantees with automated validation,
**so that** sensitive data (e.g., credentials/PII) is provably removed from emitted logs before they reach sinks.

## Acceptance Criteria

1. A "Redaction Guarantees" section is authored that states, at minimum:
   - Scrub URL credentials of the form `scheme://user:pass@host...` in any string field (when `url_credentials` redactor is enabled).
   - Scrub explicitly configured field paths (dot-notation), including inside `context` and `diagnostics` (when `field_mask` redactor is enabled).
   - Optionally scrub paths matching configured regex rules; documented as configuration-dependent.
   - Redactors must be non-throwing; failures are reported to diagnostics with an indicator that redaction could not be completed.
2. A deterministic redaction order is defined and enforced (default: `regex-mask` → `url-credentials`).
3. Guardrails (max depth, max keys scanned) are documented and exposed via settings; exceeding limits results in best-effort redaction and a diagnostics entry. Defaults map to `core.settings.CoreSettings.redaction_max_depth` and `redaction_max_keys_scanned`.
4. Unit and property-based tests demonstrate guarantees across:
   - URL forms (http(s), postgres, amqp, etc.), with/without credentials.
   - Nested structures and lists for explicit path masking.
   - Regex path matching (positive/negative cases).
5. Redaction runs in the centralized pipeline prior to serialization so all sinks receive already-redacted envelopes.
6. Provide example configuration showing explicit paths and regex masks; include a test fixture that proves those settings are applied.

## Tasks / Subtasks

- [ ] Policy and docs (AC: 1, 2, 3)
  - [ ] Add `docs/redaction-guarantees.md` summarizing guarantees, limits, order of operations, and guardrails.
  - [ ] Confirm defaults and document how to change `redactors_order`, `redaction_max_depth`, and `redaction_max_keys_scanned`.
- [ ] Enforce deterministic order (AC: 2, 5)
  - [ ] Ensure default order in `Settings.core.redactors_order` is respected in `__init__.py` wiring and `core.logger._flush_batch()` path.
  - [ ] Failures never bubble; emit `core.diagnostics.warn` with redactor name and reason.
- [ ] Centralize redaction before envelope serialization (AC: 5)
  - [ ] Keep enrichers → redactors → envelope serialization → sinks order in `core.logger._flush_batch`.
  - [ ] Add guardrail usage inside redactors (depth/scan caps) reading from settings when available.
- [ ] Tests (AC: 4, 6)
  - [ ] URL scrub tests across common schemes.
  - [ ] Explicit path masking tests over nested dict/list structures.
  - [ ] Regex path tests (match/miss; performance guardrails).
  - [ ] Property-based tests generating nested payloads with seeded secrets.
  - [ ] Fixture-driven tests loading example config to validate behavior end-to-end.
- [ ] Examples (AC: 6)
  - [ ] Minimal config snippet showing explicit and regex path masks.
  - [ ] Example log before/after redaction in docs.

## Dev Notes

- Current pipeline already wires enrichers → redactors → sinks in `src/fapilog/core/logger.py` and sets default order in `src/fapilog/__init__.py` via `Settings.core.redactors_order`.
- URL credentials redactor exists at `src/fapilog/plugins/redactors/url_credentials.py` and observes guardrails internally; ensure these tie into settings defaults.
- `regex-mask` redactor is at `src/fapilog/plugins/redactors/regex_mask.py`; confirm pattern defaults and configurability via settings or constructor.
- Redactors should use `metrics.plugin_timer` when available, and record diagnostics failures via `core.diagnostics.warn`.
- Redaction must precede envelope serialization introduced in Story 1.17 so sinks never perform redaction.

### Testing

- Locations:
  - Unit: `tests/unit/redaction/`
  - Integration: `tests/integration/redaction/`
- Use `pytest` + `pytest-asyncio`; `hypothesis` for generative payloads.
- Include performance bounds tests tied to guardrails to prevent regressions.

## Change Log

| Date       | Version | Description                                              | Author    |
| ---------- | ------- | -------------------------------------------------------- | --------- |
| 2025-08-15 | 0.2     | Clarified order, guardrails, settings mapping, test plan | Architect |

## Dev Agent Record

### Agent Model Used

{{agent_model_name_version}}

### Debug Log References

### Completion Notes List

### File List

## QA Results


