Skip to content

Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.

Add import CSV format helpers (#2413)

Leendert de Borst50a3bd1f89ae
diff --git a/core/client/src/importexport/csv/CsvImport.ts b/core/client/src/importexport/csv/CsvImport.ts
new file mode 100644
index 000000000..de7a4e81c
--- /dev/null
+++ b/core/client/src/importexport/csv/CsvImport.ts
@@ -0,0 +1,45 @@
+import { readCsvRecords, type CsvColumns, type CsvRecord } from './CsvRecordMapper';
+
+/**
+ * Decode uploaded file bytes into text.
+ * @param fileBytes - The raw bytes of the uploaded file
+ * @returns The decoded file content
+ */
+export function decodeFileContent(fileBytes: Uint8Array): string {
+ if (fileBytes[0] === 0xFF && fileBytes[1] === 0xFE) {
+ return new TextDecoder('utf-16le').decode(fileBytes);
+ }
+ if (fileBytes[0] === 0xFE && fileBytes[1] === 0xFF) {
+ return new TextDecoder('utf-16be').decode(fileBytes);
+ }
+ return new TextDecoder('utf-8').decode(fileBytes);
+}
+
+/**
+ * Read the records of a password manager's CSV export. Headers match ignoring case and spaces, and every
+ * non-empty text field is passed through the optional field decoder.
+ * @param fileContent - The CSV file content
+ * @param columns - The columns to read
+ * @param decodeField - Decodes one text field, for exports with their own escaping on top of CSV
+ * @returns The records
+ * @throws {Error} When the file holds no records.
+ */
+export function readImportCsv<C extends CsvColumns>(fileContent: string, columns: C, decodeField?: (value: string) => string): CsvRecord<C>[] {
+ const records = readCsvRecords(fileContent, columns, header => header.toLowerCase().trim().replace(/ /g, ''));
+ if (records.length === 0) {
+ throw new Error('No records found in the CSV file.');
+ }
+ if (!decodeField) {
+ return records;
+ }
+
+ for (const record of records) {
+ const fields = record as Record<string, unknown>;
+ for (const [key, value] of Object.entries(fields)) {
+ if (typeof value === 'string' && value.length > 0) {
+ fields[key] = decodeField(value);
+ }
+ }
+ }
+ return records;
+}
diff --git a/core/client/src/importexport/csv/CsvParser.ts b/core/client/src/importexport/csv/CsvParser.ts
new file mode 100644
index 000000000..d841eff72
--- /dev/null
+++ b/core/client/src/importexport/csv/CsvParser.ts
@@ -0,0 +1,58 @@
+/*
+ * CSV parser utility.
+ */
+
+/**
+ * Split CSV text into rows of fields. Blank lines are skipped, a byte order mark is ignored.
+ * @param content - The CSV text
+ * @returns The rows, each an array of field values
+ */
+export function parseCsvRows(content: string): string[][] {
+ const text = content.charCodeAt(0) === 0xFEFF ? content.substring(1) : content;
+ const rows: string[][] = [];
+ let row: string[] = [];
+ let field = '';
+ let i = 0;
+
+ while (i < text.length) {
+ const c = text[i];
+ if (c === '"' && field === '') {
+ i++;
+ while (i < text.length && !(text[i] === '"' && isFieldEnd(text, i + 1))) {
+ field += text[i];
+ i += text[i] === '"' && text[i + 1] === '"' ? 2 : 1;
+ }
+ i++;
+ } else if (c === ',') {
+ row.push(field);
+ field = '';
+ i++;
+ } else if (c === '\r' || c === '\n') {
+ i += c === '\r' && text[i + 1] === '\n' ? 2 : 1;
+ if (row.length > 0 || field !== '') {
+ row.push(field);
+ rows.push(row);
+ }
+ row = [];
+ field = '';
+ } else {
+ field += c;
+ i++;
+ }
+ }
+ if (row.length > 0 || field !== '') {
+ row.push(field);
+ rows.push(row);
+ }
+ return rows;
+}
+
+/**
+ * Whether the field ends at `i`: a delimiter, a line break or the end of the text.
+ * @param text - The CSV text
+ * @param i - The index to check
+ * @returns True when a field ends there
+ */
+function isFieldEnd(text: string, i: number): boolean {
+ return i >= text.length || text[i] === ',' || text[i] === '\r' || text[i] === '\n';
+}
diff --git a/core/client/src/importexport/csv/CsvRecordMapper.ts b/core/client/src/importexport/csv/CsvRecordMapper.ts
new file mode 100644
index 000000000..28c817934
--- /dev/null
+++ b/core/client/src/importexport/csv/CsvRecordMapper.ts
@@ -0,0 +1,71 @@
+import { parseDateTime } from '../utils/DateTimeUtils';
+
+import { parseCsvRows } from './CsvParser';
+
+/**
+ * Reads one column's text into a value; the text is undefined when the file lacks the column.
+ */
+export type CsvColumn<T> = (raw: string | undefined) => T;
+
+/**
+ * The columns of a record, keyed by their header.
+ */
+export type CsvColumns = Record<string, CsvColumn<unknown>>;
+
+/**
+ * The record type the columns read into.
+ */
+export type CsvRecord<C extends CsvColumns> = { [K in keyof C]: ReturnType<C[K]> };
+
+/**
+ * A text column; the empty string when the file lacks it.
+ * @param raw - The column text
+ * @returns The text
+ */
+export const text: CsvColumn<string> = (raw: string | undefined): string => raw ?? '';
+
+/**
+ * A text column; null when the file lacks it.
+ * @param raw - The column text
+ * @returns The text, or null
+ */
+export const optionalText: CsvColumn<string | null> = (raw: string | undefined): string | null => raw ?? null;
+
+/**
+ * A date/time column; null when absent, blank or unparseable.
+ * @param raw - The column text
+ * @returns The date, or null
+ */
+export const dateTime: CsvColumn<Date | null> = (raw: string | undefined): Date | null => parseDateTime(raw);
+
+/**
+ * Read typed records from CSV text with a header row. Each column is found by its key; columns the file lacks read
+ * as undefined, extra columns are ignored and the first of two columns with the same header wins.
+ * @param content - The CSV text
+ * @param columns - The columns to read, keyed by header
+ * @param normalizeHeader - Applied to both sides before headers are matched; exact matching by default
+ * @returns The records, one per data row
+ */
+export function readCsvRecords<C extends CsvColumns>(content: string, columns: C, normalizeHeader: (header: string) => string = (header): string => header): CsvRecord<C>[] {
+ const [headerRow, ...dataRows] = parseCsvRows(content);
+ if (!headerRow) {
+ return [];
+ }
+
+ const headerIndexes = new Map<string, number>();
+ headerRow.forEach((header, index) => {
+ const key = normalizeHeader(header);
+ if (!headerIndexes.has(key)) {
+ headerIndexes.set(key, index);
+ }
+ });
+
+ const indexedColumns = Object.entries(columns).map(([key, read]) => ({ key, read, index: headerIndexes.get(normalizeHeader(key)) }));
+ return dataRows.map(row => {
+ const record: Record<string, unknown> = {};
+ for (const { key, read, index } of indexedColumns) {
+ record[key] = read(index === undefined ? undefined : row[index]);
+ }
+ return record as CsvRecord<C>;
+ });
+}
diff --git a/core/client/src/importexport/csv/CsvWriter.ts b/core/client/src/importexport/csv/CsvWriter.ts
new file mode 100644
index 000000000..4a920c81f
--- /dev/null
+++ b/core/client/src/importexport/csv/CsvWriter.ts
@@ -0,0 +1,21 @@
+/**
+ * Quote a field when needed: it contains a quote, the delimiter or a line break, or starts or ends with
+ * a space.
+ * @param value - The field value
+ * @returns The field as it appears in the file
+ */
+export function escapeCsvField(value: string): string {
+ const needsQuotes = value.includes('"') || value.includes(',') || value.includes('\r') || value.includes('\n') || value.startsWith(' ') || value.endsWith(' ');
+ return needsQuotes ? `"${value.replace(/"/g, '""')}"` : value;
+}
+
+/**
+ * Write rows as CSV text with CRLF line endings.
+ * @param headers - The header row
+ * @param rows - The data rows, each in header order
+ * @returns The CSV text
+ */
+export function writeCsv(headers: string[], rows: string[][]): string {
+ const lines = [headers, ...rows].map(row => row.map(escapeCsvField).join(','));
+ return `${lines.join('\r\n')}\r\n`;
+}