# BAT-017 Design: Import provenance and sensitive-data policy

- Status: draft
- Created At (KST): 2026-07-08 11:33 KST
- Included REQ: REQ-021

## Design Direction

Introduce a narrow provenance/sanitization layer used by import services and response adapters rather than scattering per-source masking rules across UI/MCP code.

## Proposed Components

- `provenance` helper functions under application/import boundary or a small shared module:
  - `mask_source_filename(path_or_name)`
  - `build_source_identity(source, file_path, source_hash, parser_name, parser_version)`
  - `minimize_raw_payload(source, payload)`
  - `sanitize_provenance_for_exposure(payload, level)`
- Source-specific allowlists:
  - KB Bank PDF: date/time, amount, direction, masked account hint, page/row reference, validation keys.
  - Toss Bank PDF: action category, normalized counterparty, masked account hint, page/row reference, validation keys.
  - Toss Securities PDF: section/action/code, normalized security/counterparty summary, numeric audit fields when required.
  - SeoulPay XLSX: sheet name, row reference, payment kind/category summary, minimized merchant/transaction reference.
  - CSV: explicit preview/import allowlist and sensitive-column suppression.

## Storage Policy

- Do not persist full local source paths.
- Store masked basename and source hash for operator correlation.
- Keep `source_hash` stable for dedupe/audit.
- `raw_payload` stores only minimized allowlisted fields; forbidden fields are removed/masked.
- Existing rows are not destructively rewritten by this batch.

## Interface Policy

- Default MCP responses use `minimal` exposure.
- Operator summary may include masked filename, parser identity, row/page/sheet reference, validation summary.
- Debug diagnostics require explicit gate and still exclude passwords/tokens/secrets/full path/raw document dump.

## Test Strategy

- Use synthetic fixtures only.
- Include negative assertions for forbidden keys and full path patterns.
- Verify duplicate/rollback metadata remains usable after minimization.

## Open Design Checks Before Implementation

- Decide whether provenance helpers live in `application/imports_service.py` initially or a new module.
- Confirm whether schema version bump is required or policy can be implemented through current columns plus memo JSON shape.
- Confirm MCP contract change is additive and does not break existing consumers.