CapaKraken/docs/import-hardening.md

Import Hardening

Date: 2026-03-30 Purpose: Define the safe parser boundary for untrusted spreadsheet imports.

Decision

• Untrusted workbook imports no longer accept legacy .xls.
• Server-side dispo imports accept only .xlsx files.
• Browser-side ad hoc imports accept .xlsx and .csv.
• Workbook import and export generation now use exceljs instead of direct runtime xlsx usage.

Server Boundary

The dispo-import reader in read-workbook.ts now enforces:

• normalized filesystem paths before reading
• regular-file checks
• non-empty file checks
• a hard size limit of 15 MiB
• a worksheet row limit of 10,000
• a worksheet column limit of 256
• .xlsx-only parsing through exceljs behind a hardened server-side parser boundary

The API entry points in dispo.ts reject non-.xlsx workbook paths before staging or validation begins.

Browser Boundary

The browser import helpers in excel.ts and skillMatrixParser.ts now enforce:

• a hard client-side file size limit of 10 MiB
• explicit rejection of legacy .xls
• a tabular row limit of 5,000 data rows plus the header row
• a tabular column limit of 200
• header validation that rejects blank and duplicate column names
• .xlsx parsing through exceljs
• .csv parsing through a local parser for simple tabular imports

Affected upload flows:

• resource CSV/XLSX import
• estimate scope spreadsheet import
• single skill-matrix import
• batch skill-matrix import

Rationale

• .xls support keeps the old binary workbook format in the untrusted path without enough payoff.
• the server path keeps compatibility-first .xlsx parsing for the current dispo workbooks, but only behind explicit file validation, size limits, and exceljs
• the browser path moves away from blanket spreadsheet parsing to a narrower parser boundary
• export generation follows the same maintained workbook stack as import parsing
• CSV remains useful for lightweight business imports and is small enough to parse with a narrow local parser.