Skip to content

ADR-015-sensitive-data-lineage.md

Latest commit

 

History

History
35 lines (24 loc) · 4.05 KB

ADR-015-sensitive-data-lineage.md

File metadata and controls

35 lines (24 loc) · 4.05 KB
Raw

ADR-015: Sensitive-data omission, use, and lineage

Status: Accepted; complete cross-projection privacy qualification pending. Current policy contracts are in src/KeyLoad.Abstractions/Contracts.cs, enforcement in src/KeyLoad.Core/MutationAuthorization.cs and src/KeyLoad.Core/DatabaseEngine.cs, and shared policy primitives in src/KeyLoad.Security/Features/Authorization/Execution/AuthorizationPolicy.cs; product source sections 14, 26, 29–30, and 44.

Context and decision

Sensitive data can flow through documents, events, message payloads/headers, graph attributes, text/vector/search projections, query aliases, diagnostics, backups, and replay. Classified fields carry versioned policy/lineage. Human-readable outputs omit protected fields by default. A computation requiring raw fields needs an explicit data-use grant; redacted replacement is not silently substituted when it would change business semantics. Derived projections inherit source classification and policy epoch, and every read/replay/export boundary rechecks current restrictions.

Rationale and consequences

Omission and lineage reduce accidental disclosure through search, logs, aliases, and replay. Reclassification/revocation may invalidate projections and cursors and may require rebuild. Historical raw bytes are not erased by response omission; retention, physical purge, backups, and crypto-erasure need separate verified lifecycle decisions. Hashes can themselves be sensitive.

Related requirements

Authorization REQ-AUTH-001..003 plus REQ-AUTH-004..009 and matching AC-AUTH-004..009, particularly field read/use/write, policy-epoch enforcement, protected processing inputs, and sensitive-data lineage/diagnostics. Search REQ-SR-002/005, DocumentStorage REQ-DSTORE-003, Messaging REQ-MSG-002/003, GraphTraversal REQ-GRAPH-002, and EventStreams REQ-EVENT-003/006 also apply. ADR-014 defines authority; ADR-029 expands event/message classification.

Implementation contract

  1. Freeze classification vocabulary, schema lineage, required-input behavior, omission rules, derived-provider metadata, and safe diagnostic format.
  2. Add canary tests across document, event/header, queue/DLQ, SQL alias/sort, graph edge, search/vector, export, trace, and replay; assert both allowed raw use and denied omission/failure.
  3. Target owners: src/KeyLoad.Security/Features/Authorization/, each canonical source slice, and the existing src/KeyLoad.Query/Features/Search/ projection slice; no generic endpoint may bypass source ownership or create a separate search technical root.
  4. Reclassification increments policy/schema epochs and invalidates stale derived generations before exposing output. Rollback cannot restore permissive reads without restoring authorized policy state; purge operations must report replica/archive boundaries.
  5. GitHub CI runs TUnit and real RF3 SDK/MCP privacy cases. Root joins Security, Search, Messaging, and backup owners; retain sanitized evidence only.

Dependencies: ADR-004, ADR-006, ADR-009, ADR-010, ADR-013, ADR-014, ADR-018, ADR-019, ADR-022, ADR-029, and ADR-030. Stop on missing lineage or unsafe replay; do not infer erasure from omission.

flowchart LR
    Source[Classified canonical field] --> Lineage[Versioned source lineage]
    Lineage --> Policy[Current policy and use grant]
    Policy -->|human read| Omit[Safe omission or masked projection]
    Policy -->|required processing| Raw[Explicit authorized raw use]
    Raw --> Derived[Versioned derived output with inherited lineage]
    Derived --> Recheck[Recheck policy before every disclosure]
Loading