jarca-ledger-mcp/docs/batches/bat-017_20260708_import-provenance-sensitive-data-policy/design.md

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.