# Spreadsheet recovery format v1

CheckThisFile's Protect spreadsheet data tool prepares XLSX or CSV data in the browser and restores known whole-cell identifiers later. It uses no AI, uploads, account, hosted API operation or automatic storage. The application and its static resources must load first; offline use is not guaranteed.

The prepared copy and private recovery file are separate downloads. Keep the recovery file and password privately. Losing either prevents recovery. This is reversible pseudonymization; unselected data and combinations can still identify people. Review every sheet before sharing.

## Supported data and output

XLSX is rebuilt in a new, values-only ZIP container. Supported numeric and boolean values retain their types. Numeric processing uses IEEE 754 double precision; stored integer literals that cannot be represented without rounding are rejected. Text retains its exact case, accents and whitespace. Formulas become their stored results and are never evaluated; stored results can be stale. Formulas without usable stored results are rejected. All included sheets, rows and columns become visible, and sheets receive neutral names. Supported date, time and percentage formats use a small safe set of generated styles. Unsupported formats and workbook features may be rejected.

Original shared strings, comments, document properties, defined names, links, chart and pivot caches, embedded objects and other non-cell parts are not copied into the output. Full Excel formatting, graphs and formulas are not preserved. Digitally signed, encrypted, macro-enabled, protected, old binary and incompatible workbooks are rejected. This is a cell-data transformation, not an Excel fidelity editor.

CSV supports comma, semicolon and tab delimiters, quoted fields, escaped quotes, embedded line breaks, empty cells, UTF-8, UTF-16 LE/BE and explicitly selected Windows-1252. Fields are read as text. CSV keeps its source format by default; conversion to XLSX is an explicit choice and stores every CSV field as text, including amounts, so Excel calculations may treat those fields differently. The output is quoted UTF-8 with BOM and the input delimiter. Formula-like CSV strings receive a protective leading apostrophe, including restored originals; other systems may retain that apostrophe as data. Complete finite negative decimals (dot or comma) and scientific numeric literals keep their original spelling; negative expressions are escaped. Quoting does not stop Excel reinterpreting leading zeros, numbers or dates. Import those columns as Text or choose XLSX, which stores CSV fields as text.

## Matching and recovery

Rules propose whole cells. Email syntax, conservative phone rules, DNI/NIE check letters and a supported IBAN country length plus modulo 97 check are review aids; they do not establish that a contact, account or identity exists. Names, companies and references require an explicit column/range selection or exact dictionary. Unformatted nonnegative safe integer cells can be selected as Phone or Reference and are restored as numbers; automatic numeric proposals use conservative Spanish phone rules. Formatted numbers, dates, times, percentages, decimals and booleans remain unchanged. International phone proposals require a leading plus and 7 to 15 digits; national proposals use 9 digits starting with 6, 7, 8 or 9. Arbitrary regular expressions are not accepted.

Matching does not normalize case, spaces or accents. Equal exact values of the same type receive the same identifier within the project. An optional exact context column separates equal names. That context column is not automatically protected; select it separately when needed. Distinct variants receive distinct aliases, preserving their original spellings. Identifiers include a random project marker, for example `Person 1 [CTF-<32 lowercase hexadecimal characters>]`. Labels are chosen in English or Spanish when the project is created; opening it in another language preserves its existing labels. Projects have no shared or global mapping.

Restoration matches a complete known cell identifier, independent of row number, order or column position. Sorting, filtering, duplicating rows and adding columns are supported. Only matched cells are changed; external results and unrecognized values remain. Embedded identifiers are not replaced inside prose. Changed or foreign markers, unknown aliases and mappings absent from the file are review incidents. When a marker is completely deleted, its identity cannot be inferred; absence is reported at mapping level, not by guessing a row. New records without known identifiers stay unchanged. Review incidents before accepting a partial restoration. A file with no recognized project identifiers cannot establish project compatibility.

Replacement numbers are scoped to the project and type. Collisions with source identifiers are checked before use. The preparation review also reports selected original values still present in remaining cell data; excluded or unrelated sensitive values remain the user's responsibility.

## Encrypted file

The `.ctf-recovery` file contains a UTF-8 JSON envelope with exactly these fields:

- `kind`: `checkthisfile-spreadsheet-recovery`
- `version`: `1`
- `kdf`: `PBKDF2-SHA256`
- `iterations`: `600000`
- `cipher`: `AES-256-GCM`
- `salt`: canonical Base64 encoding of 16 random bytes
- `iv`: canonical Base64 encoding of 12 random bytes
- `data`: canonical Base64 ciphertext followed by its 128-bit authentication tag

The password is UTF-8 encoded exactly as entered, without trimming or normalization. Length is 12 to 1,024 UTF-16 code units. Incomplete Unicode surrogate characters are rejected before encoding. PBKDF2 derives a non-exportable 256-bit AES key. Each save creates a fresh salt and IV using Web Crypto's random generator.

AES-GCM additional authenticated data is the UTF-8 JSON serialization of the header fields in the order `kind`, `version`, `kdf`, `iterations`, `cipher`, `salt`, `iv`, without whitespace. Altering authenticated data or using an incorrect password prevents decryption. Unknown versions, fields, unsupported parameters, malformed Base64 and excessive sizes are rejected before key derivation. The decrypted structure is validated before use. This file is authenticated with its password; it is not a public signature, receipt or timestamp.

The decrypted JSON has exactly `version` (1), `id` (32 lowercase hexadecimal characters), `locale` (`en` or `es`) and `mappings` (array). Each mapping has exactly `alias`, `original`, `kind` and `context`. Types are `person`, `company`, `reference`, `email`, `phone`, `document` or `iban`. Original strings are exact; supported numeric identifiers retain a numeric original. Context is an exact encoded additional key or the empty string. Duplicate aliases and duplicate type/value/context identities are rejected. The private file contains sensitive originals and context values; never include it in the shared workbook.

To extend a project, explicitly open its recovery file with the password before preparing another file. Previous mappings and aliases remain, and the new download includes both old and new mappings. Keep the latest recovery file. The application does not persist a project or password between sessions.

## Resource limits

- Input: 10 MiB per XLSX or CSV.
- Output: 10 MiB per download; generated XLSX parts also remain within 40 MiB uncompressed.
- XLSX: 40 MiB total uncompressed data and 512 ZIP entries.
- Workbook: 20 sheets, 20,000 rows per sheet, 200 columns and 200,000 cells total, including bounded sparse sheet extents.
- Text: 8,000 characters per cell or context.
- Dictionaries: 5,000 entries, 8,000 characters per value and 1,000,000 combined characters. The list input field counts line breaks toward its character cap.
- Recovery: 8 MiB encrypted file, 50,000 mappings, 1,000,000 aggregate original/context characters.
- Processing: a 90-second worker deadline per operation. Cancel terminates the worker. Progress reports processed entries, cells or stages; encryption has a stage indicator rather than simulated percentages.

Processing, parsing, transformation, key derivation and encryption use dedicated browser workers. No formulas, macros, external connections or workbook scripts run. Documents, mappings, passwords and original names are not written to localStorage, cookies, analytics or logs. Reset or close the page to release the current working session. Browser and operating-system memory cannot be guaranteed to have been securely erased.

[Third-party notices](./spreadsheet-third-party-notices.txt) cover the spreadsheet worker dependencies.