Skip to content

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

Add shared importer logic (#2413)

Leendert de Borst77ca4954f442
diff --git a/core/client/src/transfer/export/AvexExportService.ts b/core/client/src/transfer/export/AvexExportService.ts
index 4c19659f4..9cd3a2ba4 100644
--- a/core/client/src/transfer/export/AvexExportService.ts
+++ b/core/client/src/transfer/export/AvexExportService.ts
@@ -3,7 +3,6 @@ import { EncryptionUtility } from '../../crypto/EncryptionUtility';
import { AppInfo } from '../../platform/AppInfo';
import { argon2DeriveKey } from '../../rust/RustCore';
import { base64ToBytes, bytesToBase64 } from '../../utilities/Base64';
-import { formatIsoDateTime } from '../shared/DateTimeUtils';
import { AvexConstants } from './AvexConstants';
@@ -39,7 +38,7 @@ export class AvexExportService {
version: AvexConstants.FormatVersion,
kdf: { type: DEFAULT_ENCRYPTION.type, salt: saltBase64, params: { ...ARGON2_KDF_PARAMS } },
encryption: { algorithm: 'AES-256-GCM', encryptedDataOffset: 0 },
- metadata: { exportedAt: formatIsoDateTime(new Date()), exportedBy: username, appVersion: AppInfo.VERSION },
+ metadata: { exportedAt: new Date().toISOString(), exportedBy: username, appVersion: AppInfo.VERSION },
};
const encoder = new TextEncoder();
diff --git a/core/client/src/transfer/export/AvuxExportService.ts b/core/client/src/transfer/export/AvuxExportService.ts
index 5a9ff180f..4c0f0d765 100644
--- a/core/client/src/transfer/export/AvuxExportService.ts
+++ b/core/client/src/transfer/export/AvuxExportService.ts
@@ -1,5 +1,4 @@
import { bytesToBase64 } from '../../utilities/Base64';
-import { formatIsoDateTime } from '../shared/DateTimeUtils';
import { createZipArchive, textToZipBytes } from '../shared/ZipArchive';
import type { AvuxAttachment, AvuxFieldDefinition, AvuxFieldValue, AvuxFolder, AvuxItem, AvuxItemTag, AvuxLogo, AvuxManifest, AvuxPasskey, AvuxTag, AvuxTotpCode } from './AvuxManifest';
@@ -46,7 +45,7 @@ export class AvuxExportService {
private static createManifest(items: ItemEntity[], folders: FolderEntity[], tags: TagEntity[], itemTags: ItemTagEntity[], fieldDefinitions: FieldDefinitionEntity[], logos: LogoEntity[], username: string): AvuxManifest {
return {
version: AVUX_FORMAT_VERSION,
- exportedAt: formatIsoDateTime(new Date()),
+ exportedAt: new Date().toISOString(),
exportedBy: username,
items: items.filter(i => !i.IsDeleted).map(AvuxExportService.mapItemToAvux),
folders: folders.filter(f => !f.IsDeleted).map(AvuxExportService.mapFolderToAvux),
@@ -67,8 +66,8 @@ export class AvuxExportService {
id: item.Id,
name: item.Name,
itemType: item.ItemType,
- createdAt: formatIsoDateTime(item.CreatedAt),
- updatedAt: formatIsoDateTime(item.UpdatedAt),
+ createdAt: item.CreatedAt.toISOString(),
+ updatedAt: item.UpdatedAt.toISOString(),
folderId: item.FolderId,
logoId: item.LogoId,
fieldValues: item.FieldValues.filter(fv => !fv.IsDeleted).map(AvuxExportService.mapFieldValueToAvux),
@@ -150,8 +149,8 @@ export class AvuxExportService {
name: folder.Name,
parentFolderId: folder.ParentFolderId,
weight: folder.Weight,
- createdAt: formatIsoDateTime(folder.CreatedAt),
- updatedAt: formatIsoDateTime(folder.UpdatedAt),
+ createdAt: folder.CreatedAt.toISOString(),
+ updatedAt: folder.UpdatedAt.toISOString(),
};
}
@@ -166,8 +165,8 @@ export class AvuxExportService {
name: tag.Name,
color: tag.Color,
displayOrder: tag.DisplayOrder,
- createdAt: formatIsoDateTime(tag.CreatedAt),
- updatedAt: formatIsoDateTime(tag.UpdatedAt),
+ createdAt: tag.CreatedAt.toISOString(),
+ updatedAt: tag.UpdatedAt.toISOString(),
};
}
@@ -212,7 +211,7 @@ export class AvuxExportService {
id: logo.Id,
source: logo.Source,
mimeType: logo.MimeType,
- fetchedAt: logo.FetchedAt ? formatIsoDateTime(logo.FetchedAt) : null,
+ fetchedAt: logo.FetchedAt ? logo.FetchedAt.toISOString() : null,
relativePath: AvuxExportService.logoPath(logo),
};
}
diff --git a/core/client/src/transfer/export/ItemCsvExportService.ts b/core/client/src/transfer/export/ItemCsvExportService.ts
index b9587d3ed..7dea6e9ac 100644
--- a/core/client/src/transfer/export/ItemCsvExportService.ts
+++ b/core/client/src/transfer/export/ItemCsvExportService.ts
@@ -1,11 +1,11 @@
-import { FieldKey, normalizeTotpAlgorithm, normalizeTotpDigits, normalizeTotpPeriod, TOTP_DEFAULT_ALGORITHM, TOTP_DEFAULT_DIGITS, TOTP_DEFAULT_PERIOD } from '@aliasvault/models/vault';
+import { FieldKey, getFieldValue, getFieldValues, normalizeTotpAlgorithm, normalizeTotpDigits, normalizeTotpPeriod, TOTP_DEFAULT_ALGORITHM, TOTP_DEFAULT_DIGITS, TOTP_DEFAULT_PERIOD } from '@aliasvault/models/vault';
-import { formatInvariantDateTime, parseDateExact } from '../shared/DateTimeUtils';
-import { buildFolderPath } from '../shared/FolderPaths';
+import { fromStandardFormat } from '../../utilities/DateFormatter';
+import { parseDateExact } from '../shared/DateTimeUtils';
import { writeCsv } from './CsvWriter';
-import type { FolderEntity, ItemEntity, TotpCodeEntity } from '../shared/VaultEntities';
+import type { Item, TotpCode } from '@aliasvault/models/vault';
/** The columns of the AliasVault CSV export. */
export const ITEM_CSV_COLUMNS = [
@@ -41,40 +41,45 @@ export class ItemCsvExportService {
/**
* Export items to CSV.
* @param items - The items to export
- * @param folders - The vault's folders, to resolve each item's folder path
+ * @param getTotpCodes - Reads an item's TOTP codes; the first one is exported
* @returns The CSV file as UTF-8 bytes
*/
- public static exportItemsToCsv(items: ItemEntity[], folders: FolderEntity[] = []): Uint8Array {
- const foldersById = new Map(folders.map(folder => [folder.Id, folder]));
-
+ public static exportItemsToCsv(items: Item[], getTotpCodes: (item: Item) => TotpCode[] = (): TotpCode[] => []): Uint8Array {
const rows = items.map((item): string[] => {
+ /**
+ *
+ */
+ /**
+ * A single field value, or the empty string when absent.
+ */
+ const field = (fieldKey: string): string => getFieldValue(item, fieldKey) ?? '';
const record: Record<ItemCsvColumn, string | Date | null> = {
ServiceName: item.Name ?? '',
- FolderPath: buildFolderPath(item.FolderId, foldersById),
- ServiceUrl: ItemCsvExportService.getJoinedFieldValues(item, FieldKey.LoginUrl),
- Username: ItemCsvExportService.getFieldValue(item, FieldKey.LoginUsername),
- CurrentPassword: ItemCsvExportService.getFieldValue(item, FieldKey.LoginPassword),
- AliasEmail: ItemCsvExportService.getFieldValue(item, FieldKey.LoginEmail),
- TwoFactorSecret: ItemCsvExportService.formatTwoFactorSecret(item.TotpCodes.find(t => !t.IsDeleted) ?? null),
- AliasGender: ItemCsvExportService.getFieldValue(item, FieldKey.AliasGender),
- AliasFirstName: ItemCsvExportService.getFieldValue(item, FieldKey.AliasFirstName),
- AliasLastName: ItemCsvExportService.getFieldValue(item, FieldKey.AliasLastName),
- AliasBirthDate: ItemCsvExportService.parseBirthDate(ItemCsvExportService.getFieldValue(item, FieldKey.AliasBirthdate)),
- Notes: ItemCsvExportService.getFieldValue(item, FieldKey.NotesContent),
- CardholderName: ItemCsvExportService.getFieldValue(item, FieldKey.CardCardholderName),
- CardNumber: ItemCsvExportService.getFieldValue(item, FieldKey.CardNumber),
- CardExpiryMonth: ItemCsvExportService.getFieldValue(item, FieldKey.CardExpiryMonth),
- CardExpiryYear: ItemCsvExportService.getFieldValue(item, FieldKey.CardExpiryYear),
- CardCvv: ItemCsvExportService.getFieldValue(item, FieldKey.CardCvv),
- CardPin: ItemCsvExportService.getFieldValue(item, FieldKey.CardPin),
- CreatedAt: item.CreatedAt,
- UpdatedAt: item.UpdatedAt,
+ FolderPath: item.FolderPath?.join('/') ?? '',
+ ServiceUrl: getFieldValues(item, FieldKey.LoginUrl).map(url => url.trim()).filter(url => url.length > 0).join(','),
+ Username: field(FieldKey.LoginUsername),
+ CurrentPassword: field(FieldKey.LoginPassword),
+ AliasEmail: field(FieldKey.LoginEmail),
+ TwoFactorSecret: ItemCsvExportService.formatTwoFactorSecret(getTotpCodes(item)[0] ?? null),
+ AliasGender: field(FieldKey.AliasGender),
+ AliasFirstName: field(FieldKey.AliasFirstName),
+ AliasLastName: field(FieldKey.AliasLastName),
+ AliasBirthDate: ItemCsvExportService.parseBirthDate(field(FieldKey.AliasBirthdate)),
+ Notes: field(FieldKey.NotesContent),
+ CardholderName: field(FieldKey.CardCardholderName),
+ CardNumber: field(FieldKey.CardNumber),
+ CardExpiryMonth: field(FieldKey.CardExpiryMonth),
+ CardExpiryYear: field(FieldKey.CardExpiryYear),
+ CardCvv: field(FieldKey.CardCvv),
+ CardPin: field(FieldKey.CardPin),
+ CreatedAt: fromStandardFormat(item.CreatedAt),
+ UpdatedAt: fromStandardFormat(item.UpdatedAt),
};
return ITEM_CSV_COLUMNS.map(header => {
const value = record[header];
if (value instanceof Date) {
- return formatInvariantDateTime(value);
+ return ItemCsvExportService.formatDateTime(value);
}
return value ?? '';
});
@@ -88,7 +93,7 @@ export class ItemCsvExportService {
* @param totpCode - The item's first live TOTP code, if any
* @returns The secret or an otpauth:// URI
*/
- private static formatTwoFactorSecret(totpCode: TotpCodeEntity | null): string {
+ private static formatTwoFactorSecret(totpCode: TotpCode | null): string {
if (!totpCode) {
return '';
}
@@ -101,32 +106,22 @@ export class ItemCsvExportService {
return totpCode.SecretKey;
}
- const label = encodeURIComponent(totpCode.Name.trim().length === 0 ? 'AliasVault' : totpCode.Name);
+ const name = totpCode.Name ?? '';
+ const label = encodeURIComponent(name.trim().length === 0 ? 'AliasVault' : name);
return `otpauth://totp/${label}?secret=${totpCode.SecretKey}&algorithm=${algorithm}&digits=${digits}&period=${period}`;
}
/**
- * A single field value of an item.
- * @param item - The item
- * @param fieldKey - The field key
- * @returns The value, or the empty string when absent
- */
- private static getFieldValue(item: ItemEntity, fieldKey: string): string {
- return item.FieldValues.find(fv => fv.FieldKey === fieldKey && !fv.IsDeleted)?.Value ?? '';
- }
-
- /**
- * All values of a multi-value field as one comma separated string, ordered by weight.
- * @param item - The item
- * @param fieldKey - The field key
- * @returns The joined values, or the empty string when there are none
+ * Format a date as "MM/dd/yyyy HH:mm:ss" (UTC), the date format of the CSV file.
+ * @param date - The date
+ * @returns The formatted date/time
*/
- private static getJoinedFieldValues(item: ItemEntity, fieldKey: string): string {
- return item.FieldValues
- .filter(fv => fv.FieldKey === fieldKey && !fv.IsDeleted && !!fv.Value && fv.Value.trim().length > 0)
- .sort((a, b) => a.Weight - b.Weight)
- .map(fv => fv.Value!.trim())
- .join(',');
+ private static formatDateTime(date: Date): string {
+ /**
+ * Two-digit zero-padded component.
+ */
+ const pad = (value: number): string => String(value).padStart(2, '0');
+ return `${pad(date.getUTCMonth() + 1)}/${pad(date.getUTCDate())}/${date.getUTCFullYear()} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())}`;
}
/**
diff --git a/core/client/src/transfer/import/importers/aliasvault/ItemCsvImportService.ts b/core/client/src/transfer/import/importers/aliasvault/ItemCsvImportService.ts
index dc2927abe..5a3d05eff 100644
--- a/core/client/src/transfer/import/importers/aliasvault/ItemCsvImportService.ts
+++ b/core/client/src/transfer/import/importers/aliasvault/ItemCsvImportService.ts
@@ -67,8 +67,6 @@ export class ItemCsvImportService {
FirstName: record.AliasFirstName,
LastName: record.AliasLastName,
BirthDate: record.AliasBirthDate,
- CreatedAt: record.CreatedAt,
- UpdatedAt: record.UpdatedAt,
},
TwoFactorSecret: record.TwoFactorSecret,
CreatedAt: record.CreatedAt,
diff --git a/core/client/src/transfer/import/importers/shared/ArchiveImport.ts b/core/client/src/transfer/import/importers/shared/ArchiveImport.ts
new file mode 100644
index 000000000..1f715ac58
--- /dev/null
+++ b/core/client/src/transfer/import/importers/shared/ArchiveImport.ts
@@ -0,0 +1,95 @@
+import { ZipArchive } from '../../../shared/ZipArchive';
+import { ImportException, ImportStage } from '../../models/ImportException';
+import { JsonException, parseJson } from '../../readers/JsonReader';
+
+import type { ImportedCredential } from '../../models/ImportedCredential';
+import type { ImportFailure } from '../../models/ImportFailure';
+import type { ImportFileResult } from '../../models/ImportFileResult';
+
+/**
+ * Open an uploaded ZIP archive.
+ * @param bytes - The archive bytes
+ * @returns The archive
+ * @throws {ImportException} when the bytes are not a valid ZIP archive.
+ */
+export function openArchive(bytes: Uint8Array): ZipArchive {
+ try {
+ return ZipArchive.open(bytes);
+ } catch (error) {
+ throw new ImportException(ImportStage.Archive, `File is not a valid ZIP archive or is corrupted: ${errorMessage(error)}`, error);
+ }
+}
+
+/**
+ * Read and parse a JSON file from the ZIP archive.
+ * @param archive - The ZIP archive
+ * @param path - The path of the JSON file
+ * @returns The parsed JSON value, never null
+ * @throws {ImportException} when the file is missing, empty or not valid JSON.
+ */
+export function readArchiveJson(archive: ZipArchive, path: string): unknown {
+ const text = archive.readText(path);
+ if (text === null) {
+ throw new ImportException(ImportStage.Parse, `'${path}' was not found in the archive`);
+ }
+
+ let result: unknown;
+ try {
+ result = parseJson(text);
+ } catch (error) {
+ throw new ImportException(ImportStage.Parse, `Failed to parse '${path}': ${errorMessage(error)}`, error);
+ }
+
+ if (result === null) {
+ throw new ImportException(ImportStage.Parse, `'${path}' is empty or deserialized to null`);
+ }
+ return result;
+}
+
+/**
+ * Convert raw items one by one, so a malformed item is reported as a failure instead of exiting the import.
+ * @param entries - The raw items, in export order
+ * @param convert - Converts one item; null skips it
+ * @param titleOf - Best-effort title of an item, read straight from the entry
+ * @returns The credentials and the per-item failures
+ */
+export function convertArchiveItems<T>(entries: T[], convert: (entry: T) => ImportedCredential | null, titleOf: (entry: T) => string | null): ImportFileResult {
+ const result: ImportFileResult = { Credentials: [], FailedItems: [] };
+ entries.forEach((entry, index) => {
+ try {
+ const credential = convert(entry);
+ if (credential) {
+ result.Credentials.push(credential);
+ }
+ } catch (error) {
+ result.FailedItems.push(buildItemFailure(index, titleOf(entry), error));
+ }
+ });
+ return result;
+}
+
+/**
+ * Build the failure entry of an item. Only JSON errors carry their message; any other error could hold item content,
+ * so it is reported by type only.
+ * @param index - Zero-based position of the item within the file
+ * @param title - Best-effort title of the item
+ * @param error - The error thrown while processing the item
+ * @returns A failure entry safe to surface in logs and the UI
+ */
+export function buildItemFailure(index: number, title: string | null, error: unknown): ImportFailure {
+ if (error instanceof JsonException) {
+ return { Index: index, ItemTitle: title, ExceptionType: 'JsonException', Message: `Failed to parse item: ${error.message}` };
+ }
+
+ const exceptionType = error instanceof Error ? error.name : 'Error';
+ return { Index: index, ItemTitle: title, ExceptionType: exceptionType, Message: `Item could not be processed (${exceptionType}): see item #${index} in the export.` };
+}
+
+/**
+ * The message of an unknown error.
+ * @param error - The error
+ * @returns The message
+ */
+function errorMessage(error: unknown): string {
+ return error instanceof Error ? error.message : String(error);
+}
diff --git a/core/client/src/transfer/import/importers/shared/CredentialHelpers.ts b/core/client/src/transfer/import/importers/shared/CredentialHelpers.ts
new file mode 100644
index 000000000..9113aa3e4
--- /dev/null
+++ b/core/client/src/transfer/import/importers/shared/CredentialHelpers.ts
@@ -0,0 +1,80 @@
+import { FieldTypes, ItemTypes, type FieldType, type ItemType } from '@aliasvault/models/vault';
+
+import { isBlank } from '../../../shared/StringUtils';
+
+import type { ImportedCredential } from '../../models/ImportedCredential';
+
+/**
+ * Split a URL column that may hold several comma separated URLs.
+ * @param url - The URL text
+ * @returns The URLs, or null when there are none
+ */
+export function parseUrls(url: string | null | undefined): string[] | null {
+ const urls = (url ?? '').split(',').map(u => u.trim()).filter(u => u.length > 0);
+ return urls.length > 0 ? urls : null;
+}
+
+/**
+ * Map a source's item type name to an item type.
+ * @param value - The source's type name
+ * @param types - Lower case type names to item types
+ * @returns The item type, Login for unknown names, or null when the name is empty
+ */
+export function mapItemType(value: string | null | undefined, types: Readonly<Record<string, ItemType>>): ItemType | null {
+ if (isBlank(value)) {
+ return null;
+ }
+ const key = value.toLowerCase();
+ return Object.hasOwn(types, key) ? types[key] : ItemTypes.Login;
+}
+
+/**
+ * Add a user-defined field to a credential; empty labels or values are skipped.
+ * @param credential - The credential
+ * @param label - The field label
+ * @param value - The field value
+ * @param fieldType - The field type, Text by default
+ */
+export function addCustomField(credential: ImportedCredential, label: string | null | undefined, value: string | null | undefined, fieldType: FieldType = FieldTypes.Text): void {
+ if (isBlank(label) || isBlank(value)) {
+ return;
+ }
+
+ credential.CustomFieldValues ??= [];
+ credential.CustomFieldValues.push({
+ DefinitionId: crypto.randomUUID(),
+ Label: label,
+ Value: value,
+ FieldType: fieldType,
+ IsMultiValue: false,
+ IsHidden: fieldType === FieldTypes.Hidden || fieldType === FieldTypes.Password,
+ EnableHistory: false,
+ Weight: 0,
+ ValueWeight: 0,
+ ApplicableToTypes: null,
+ });
+}
+
+/**
+ * Add an attachment to a credential.
+ * @param credential - The credential
+ * @param filename - The file name
+ * @param data - The file data
+ */
+export function addAttachment(credential: ImportedCredential, filename: string, data: Uint8Array): void {
+ credential.Attachments ??= [];
+ credential.Attachments.push({ Filename: filename, Blob: data });
+}
+
+/**
+ * Append a block of text to a credential's notes, separated by an empty line.
+ * @param credential - The credential
+ * @param lines - The lines to append.
+ */
+export function appendNotes(credential: ImportedCredential, lines: string[]): void {
+ if (lines.length === 0) {
+ return;
+ }
+ const block = lines.join('\n');
+ credential.Notes = isBlank(credential.Notes) ? block : `${credential.Notes}\n\n${block}`;
+}
diff --git a/core/client/src/transfer/import/models/ImportFailure.ts b/core/client/src/transfer/import/models/ImportFailure.ts
new file mode 100644
index 000000000..e5800ddd7
--- /dev/null
+++ b/core/client/src/transfer/import/models/ImportFailure.ts
@@ -0,0 +1,14 @@
+/**
+ * A single item that failed to be parsed during an import, kept alongside the successfully imported items
+ * so the user can see which entries were skipped.
+ */
+export type ImportFailure = {
+ /** Zero-based index of the item within the source file. */
+ Index: number;
+ /** Title of the failing item, if it could be read. */
+ ItemTitle?: string | null;
+ /** The error type name (e.g. "JsonException"). */
+ ExceptionType: string;
+ /** The error message describing what went wrong. */
+ Message: string;
+};
diff --git a/core/client/src/transfer/import/models/ImportFileResult.ts b/core/client/src/transfer/import/models/ImportFileResult.ts
new file mode 100644
index 000000000..ae2088377
--- /dev/null
+++ b/core/client/src/transfer/import/models/ImportFileResult.ts
@@ -0,0 +1,10 @@
+import type { ImportedCredential } from './ImportedCredential';
+import type { ImportFailure } from './ImportFailure';
+
+/**
+ * Result of an import file processor: the credentials that were parsed plus the per-item failures that were skipped.
+ */
+export type ImportFileResult = {
+ Credentials: ImportedCredential[];
+ FailedItems: ImportFailure[];
+};
diff --git a/core/client/src/transfer/import/readers/JsonReader.ts b/core/client/src/transfer/import/readers/JsonReader.ts
new file mode 100644
index 000000000..3efaf394d
--- /dev/null
+++ b/core/client/src/transfer/import/readers/JsonReader.ts
@@ -0,0 +1,226 @@
+/*
+ * JSON reader utility.
+ */
+
+/**
+ * A JSON object.
+ */
+export type JsonObject = Record<string, unknown>;
+
+/**
+ * Raised when JSON text cannot be parsed or a value does not have the expected type.
+ */
+export class JsonException extends Error {
+ /**
+ * Create the exception.
+ * @param message - What went wrong
+ */
+ public constructor(message: string) {
+ super(message);
+ this.name = 'JsonException';
+ Object.setPrototypeOf(this, JsonException.prototype);
+ }
+}
+
+/**
+ * Parse JSON text.
+ * @param text - The JSON text
+ * @returns The parsed value
+ * @throws {JsonException} When the text is not valid JSON.
+ */
+export function parseJson(text: string): unknown {
+ try {
+ return JSON.parse(text);
+ } catch (error) {
+ throw new JsonException(error instanceof Error ? error.message : String(error));
+ }
+}
+
+/**
+ * Whether a value is a JSON object (not null, not an array).
+ * @param value - The value
+ * @returns True for an object
+ */
+export function isJsonObject(value: unknown): value is JsonObject {
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Look up a property by name.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The value, or undefined when absent
+ */
+export function getProperty(obj: JsonObject, name: string): unknown {
+ if (name in obj) {
+ return obj[name];
+ }
+ const lower = name.toLowerCase();
+ const key = Object.keys(obj).find(k => k.toLowerCase() === lower);
+ return key === undefined ? undefined : obj[key];
+}
+
+/**
+ * Follow a path of property names and return the string at its end, without throwing.
+ * @param value - The value to start from
+ * @param path - The property names to follow
+ * @returns The string, or null when the path does not lead to a string
+ */
+export function readStringAtPath(value: unknown, ...path: string[]): string | null {
+ let current = value;
+ for (const name of path) {
+ if (!isJsonObject(current)) {
+ return null;
+ }
+ current = getProperty(current, name);
+ }
+ return typeof current === 'string' ? current : null;
+}
+
+/**
+ * Read a string property.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The string, or null when absent or null
+ * @throws {JsonException} When the value is not a string.
+ */
+export function readString(obj: JsonObject, name: string): string | null {
+ const value = getProperty(obj, name);
+ if (value === undefined || value === null) {
+ return null;
+ }
+ if (typeof value !== 'string') {
+ throw new JsonException(`Property '${name}' is not a string`);
+ }
+ return value;
+}
+
+/**
+ * Read a number property.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The number, or null when absent or null
+ * @throws {JsonException} When the value is not a number.
+ */
+export function readNumber(obj: JsonObject, name: string): number | null {
+ const value = getProperty(obj, name);
+ if (value === undefined || value === null) {
+ return null;
+ }
+ if (typeof value !== 'number') {
+ throw new JsonException(`Property '${name}' is not a number`);
+ }
+ return value;
+}
+
+/**
+ * Read a boolean property.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The boolean, or null when absent or null
+ * @throws {JsonException} When the value is not a boolean.
+ */
+export function readBoolean(obj: JsonObject, name: string): boolean | null {
+ const value = getProperty(obj, name);
+ if (value === undefined || value === null) {
+ return null;
+ }
+ if (typeof value !== 'boolean') {
+ throw new JsonException(`Property '${name}' is not a boolean`);
+ }
+ return value;
+}
+
+/**
+ * Read an object property.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The object, or null when absent or null
+ * @throws {JsonException} When the value is not an object.
+ */
+export function readObject(obj: JsonObject, name: string): JsonObject | null {
+ const value = getProperty(obj, name);
+ if (value === undefined || value === null) {
+ return null;
+ }
+ if (!isJsonObject(value)) {
+ throw new JsonException(`Property '${name}' is not an object`);
+ }
+ return value;
+}
+
+/**
+ * Read an array property.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The array, or null when absent or null
+ * @throws {JsonException} When the value is not an array.
+ */
+export function readArray(obj: JsonObject, name: string): unknown[] | null {
+ const value = getProperty(obj, name);
+ if (value === undefined || value === null) {
+ return null;
+ }
+ if (!Array.isArray(value)) {
+ throw new JsonException(`Property '${name}' is not an array`);
+ }
+ return value;
+}
+
+/**
+ * Read an array of objects, mapping each element.
+ * @param obj - The object
+ * @param name - The property name
+ * @param map - Maps one element
+ * @returns The mapped elements, or null when the property is absent or null
+ * @throws {JsonException} When an element is not an object.
+ */
+export function readObjectArray<T>(obj: JsonObject, name: string, map: (element: JsonObject) => T): T[] | null {
+ const array = readArray(obj, name);
+ if (array === null) {
+ return null;
+ }
+ return array.map((element, index) => {
+ if (!isJsonObject(element)) {
+ throw new JsonException(`Element ${index} of '${name}' is not an object`);
+ }
+ return map(element);
+ });
+}
+
+/**
+ * Read an array of strings; null elements are kept as null.
+ * @param obj - The object
+ * @param name - The property name
+ * @returns The strings, or null when the property is absent or null
+ * @throws {JsonException} When an element is neither a string nor null.
+ */
+export function readStringArray(obj: JsonObject, name: string): (string | null)[] | null {
+ const array = readArray(obj, name);
+ if (array === null) {
+ return null;
+ }
+ return array.map((element, index) => {
+ if (element === null) {
+ return null;
+ }
+ if (typeof element !== 'string') {
+ throw new JsonException(`Element ${index} of '${name}' is not a string`);
+ }
+ return element;
+ });
+}
+
+/**
+ * Require an object, for the root of a document or an array element.
+ * @param value - The value
+ * @param what - What the value is, for the error message
+ * @returns The object
+ * @throws {JsonException} When the value is not an object.
+ */
+export function requireObject(value: unknown, what: string): JsonObject {
+ if (!isJsonObject(value)) {
+ throw new JsonException(`${what} is not a JSON object`);
+ }
+ return value;
+}
diff --git a/core/client/src/transfer/import/writers/ImportDuplicateDetection.ts b/core/client/src/transfer/import/writers/ImportDuplicateDetection.ts
new file mode 100644
index 000000000..8c6429d32
--- /dev/null
+++ b/core/client/src/transfer/import/writers/ImportDuplicateDetection.ts
@@ -0,0 +1,138 @@
+import { FieldKey, getFieldValue, type Item } from '@aliasvault/models/vault';
+
+import { parseFolderPath } from '../../shared/FolderPaths';
+
+import type { ImportedCredential } from '../models/ImportedCredential';
+
+/**
+ * What the import preview learned about a parsed file, once duplicates of credentials already in the vault are dropped.
+ */
+export type ImportPreview = {
+ credentials: ImportedCredential[];
+ duplicateCount: number;
+ folderPaths: string[];
+ attachmentCount: number;
+ attachmentsTotalSize: number;
+};
+
+/**
+ * Drop the credentials the vault already contains based on a duplicate check.
+ * @param existingItems - The items already in the vault
+ * @param credentials - The parsed credentials
+ * @returns The preview
+ */
+export function detectAndRemoveDuplicates(existingItems: Item[], credentials: ImportedCredential[]): ImportPreview {
+ const duplicates = new Set(credentials.filter(imported => existingItems.some(existing => isDuplicateItem(existing, imported))));
+ const remaining = credentials.filter(credential => !duplicates.has(credential));
+
+ let attachmentCount = 0;
+ let attachmentsTotalSize = 0;
+ for (const credential of remaining) {
+ for (const attachment of credential.Attachments ?? []) {
+ attachmentCount++;
+ attachmentsTotalSize += attachment.Blob?.length ?? 0;
+ }
+ }
+
+ return {
+ credentials: remaining,
+ duplicateCount: duplicates.size,
+ folderPaths: collectHierarchicalFolderPaths(remaining),
+ attachmentCount,
+ attachmentsTotalSize,
+ };
+}
+
+/**
+ * Every unique folder path of the credentials including the ones that would be created: "Root/Business/Banking" and
+ * "Root/Personal" give ["Root", "Root/Business", "Root/Business/Banking", "Root/Personal"], parents first.
+ * @param credentials - The credentials
+ * @returns The folder paths in creation order
+ */
+export function collectHierarchicalFolderPaths(credentials: ImportedCredential[]): string[] {
+ const seen = new Set<string>();
+ const pathsWithDepth: { path: string; depth: number }[] = [];
+
+ for (const credential of credentials) {
+ const parts = parseFolderPath(credential.FolderPath);
+ for (let i = 0; i < parts.length; i++) {
+ const path = parts.slice(0, i + 1).join('/');
+ const key = path.toLowerCase();
+ if (!seen.has(key)) {
+ seen.add(key);
+ pathsWithDepth.push({ path, depth: i });
+ }
+ }
+ }
+
+ // Parents before children, then alphabetically.
+ return pathsWithDepth
+ .sort((a, b) => a.depth - b.depth || a.path.toLowerCase().localeCompare(b.path.toLowerCase()))
+ .map(entry => entry.path);
+}
+
+/**
+ * Whether an imported credential duplicates an item already in the vault.
+ * @param existing - The vault item
+ * @param imported - The imported credential
+ * @returns True when title, folder path, username, password and notes all match
+ */
+export function isDuplicateItem(existing: Item, imported: ImportedCredential): boolean {
+ if (!existing.Name || existing.Name.toLowerCase() !== (imported.ServiceName ?? '').toLowerCase()) {
+ return false;
+ }
+
+ const existingFolderPath = existing.FolderPath?.join('/') ?? '';
+ const importedFolderPath = imported.FolderPath ?? '';
+ if (existingFolderPath.toLowerCase() !== importedFolderPath.toLowerCase()) {
+ return false;
+ }
+
+ if (!fieldValuesMatch(getFieldValue(existing, FieldKey.LoginUsername), imported.Username)) {
+ return false;
+ }
+
+ if (!fieldValuesMatch(getFieldValue(existing, FieldKey.LoginPassword), imported.Password)) {
+ return false;
+ }
+
+ return notesFieldsMatch(getFieldValue(existing, FieldKey.NotesContent), imported.Notes);
+}
+
+/**
+ * Compare two field values.
+ * @param existingValue - The vault value
+ * @param importedValue - The imported value
+ * @returns True when they match
+ */
+function fieldValuesMatch(existingValue: string | null | undefined, importedValue: string | null | undefined): boolean {
+ const existingHasValue = !!existingValue;
+ const importedHasValue = !!importedValue;
+
+ if (existingHasValue && importedHasValue) {
+ return existingValue.toLowerCase() === importedValue.toLowerCase();
+ }
+
+ return !existingHasValue && !importedHasValue;
+}
+
+/**
+ * Compare two notes.
+ * @param existingNotes - The vault notes
+ * @param importedNotes - The imported notes
+ * @returns True when they match
+ */
+function notesFieldsMatch(existingNotes: string | null | undefined, importedNotes: string | null | undefined): boolean {
+ const existingHasValue = !!existingNotes;
+ const importedHasValue = !!importedNotes;
+
+ if (!existingHasValue && !importedHasValue) {
+ return true;
+ }
+
+ if (existingHasValue !== importedHasValue) {
+ return false;
+ }
+
+ return existingNotes!.toLowerCase().includes(importedNotes!.toLowerCase());
+}
diff --git a/core/client/src/transfer/import/writers/ItemConverter.ts b/core/client/src/transfer/import/writers/ItemConverter.ts
new file mode 100644
index 000000000..45329eff7
--- /dev/null
+++ b/core/client/src/transfer/import/writers/ItemConverter.ts
@@ -0,0 +1,160 @@
+import { FieldKey, ItemTypes, type ItemType } from '@aliasvault/models/vault';
+
+import { logExpected } from '../../../utilities/Diagnostics';
+import { formatDateOnly } from '../../shared/DateTimeUtils';
+import { isBlank } from '../../shared/StringUtils';
+
+import { sanitizeTotpSecretKey } from './TotpHelper';
+
+import type { FieldDefinitionEntity, ItemEntity, TotpCodeEntity } from '../../shared/VaultEntities';
+import type { ImportedCredential } from '../models/ImportedCredential';
+
+/**
+ * Convert imported credentials to vault items.
+ * @param credentials - The imported credentials
+ * @param folderPathToId - Folder paths to folder ids, or null
+ * @returns The items
+ */
+export function convertToItems(credentials: ImportedCredential[], folderPathToId?: Map<string, string> | null): ItemEntity[] {
+ return credentials.map(credential => convertToItem(credential, folderPathToId ?? null));
+}
+
+/**
+ * Convert one imported credential to a vault item with all its child fields.
+ * @param credential - The imported credential
+ * @param folderPathToId - Folder paths to folder ids, or null
+ * @returns The item
+ */
+function convertToItem(credential: ImportedCredential, folderPathToId: Map<string, string> | null): ItemEntity {
+ const now = new Date();
+ const itemId = crypto.randomUUID();
+ const itemType = determineItemType(credential);
+ const row = { CreatedAt: credential.CreatedAt ?? now, UpdatedAt: credential.UpdatedAt ?? now, IsDeleted: false };
+
+ const item: ItemEntity = {
+ Id: itemId,
+ Name: credential.ServiceName ?? '',
+ ItemType: itemType,
+ FolderId: folderPathToId && !isBlank(credential.FolderPath) ? folderPathToId.get(credential.FolderPath) ?? null : null,
+ LogoId: null,
+ ...row,
+ FieldValues: [],
+ Attachments: (credential.Attachments ?? []).map(attachment => ({ Id: crypto.randomUUID(), ItemId: itemId, Filename: attachment.Filename, Blob: attachment.Blob, ...row })),
+ TotpCodes: [],
+ Passkeys: (credential.Passkeys ?? []).map(passkey => ({
+ Id: passkey.Id ?? crypto.randomUUID(),
+ ItemId: itemId,
+ RpId: passkey.RpId,
+ UserHandle: passkey.UserHandle ?? new Uint8Array(0),
+ PublicKey: passkey.PublicKey,
+ PrivateKey: passkey.PrivateKey,
+ PrfKey: passkey.PrfKey ?? null,
+ DisplayName: passkey.DisplayName,
+ ...row,
+ })),
+ };
+
+ /**
+ * Add a system field value when the value is not empty.
+ */
+ const addField = (fieldKey: string, value: string | null | undefined, weight: number = 0): void => {
+ if (value) {
+ item.FieldValues.push({ Id: crypto.randomUUID(), ItemId: itemId, FieldKey: fieldKey, FieldDefinitionId: null, Value: value, Weight: weight, ...row });
+ }
+ };
+
+ if (itemType === ItemTypes.CreditCard) {
+ const card = credential.Creditcard;
+ addField(FieldKey.CardCardholderName, card?.CardholderName);
+ addField(FieldKey.CardNumber, card?.Number);
+ addField(FieldKey.CardCvv, card?.Cvv);
+ addField(FieldKey.CardPin, card?.Pin);
+ addField(FieldKey.CardExpiryMonth, card?.ExpiryMonth);
+ addField(FieldKey.CardExpiryYear, card?.ExpiryYear);
+ } else {
+ credential.ServiceUrls?.filter(url => !!url).forEach((url, index) => addField(FieldKey.LoginUrl, url, index));
+ addField(FieldKey.LoginUsername, credential.Username);
+ addField(FieldKey.LoginPassword, credential.Password);
+ addField(FieldKey.LoginEmail, credential.Email);
+ }
+
+ addField(FieldKey.NotesContent, credential.Notes);
+
+ const alias = credential.Alias;
+ if (alias) {
+ addField(FieldKey.AliasFirstName, alias.FirstName);
+ addField(FieldKey.AliasLastName, alias.LastName);
+ addField(FieldKey.AliasGender, alias.Gender);
+ addField(FieldKey.AliasBirthdate, alias.BirthDate ? formatDateOnly(alias.BirthDate) : null);
+ }
+
+ const totpCode = credential.TwoFactorSecret ? buildTotpCode(credential.TwoFactorSecret, itemId, row) : null;
+ if (totpCode) {
+ item.TotpCodes.push(totpCode);
+ }
+
+ // Values of the same source definition share one definition.
+ const definitionsBySourceId = new Map<string, FieldDefinitionEntity>();
+ for (const customField of credential.CustomFieldValues ?? []) {
+ if (isBlank(customField.Value)) {
+ continue;
+ }
+
+ let definition = definitionsBySourceId.get(customField.DefinitionId);
+ if (!definition) {
+ definition = {
+ Id: crypto.randomUUID(),
+ Label: customField.Label,
+ FieldType: customField.FieldType,
+ IsMultiValue: customField.IsMultiValue,
+ IsHidden: customField.IsHidden,
+ EnableHistory: customField.EnableHistory,
+ Weight: customField.Weight,
+ ApplicableToTypes: customField.ApplicableToTypes ?? null,
+ ...row,
+ };
+ definitionsBySourceId.set(customField.DefinitionId, definition);
+ }
+
+ item.FieldValues.push({ Id: crypto.randomUUID(), ItemId: itemId, FieldDefinition: definition, FieldDefinitionId: definition.Id, FieldKey: null, Value: customField.Value, Weight: customField.ValueWeight, ...row });
+ }
+
+ return item;
+}
+
+/**
+ * Build the TOTP code of an imported 2FA secret. An invalid secret is logged and skipped so the item itself still imports.
+ * @param secret - The bare secret or otpauth:// URI
+ * @param itemId - The item id
+ * @param row - The row timestamps
+ * @returns The TOTP code, or null when the secret is invalid
+ */
+function buildTotpCode(secret: string, itemId: string, row: Pick<TotpCodeEntity, 'CreatedAt' | 'UpdatedAt' | 'IsDeleted'>): TotpCodeEntity | null {
+ try {
+ const sanitized = sanitizeTotpSecretKey(secret);
+ return { Id: crypto.randomUUID(), ItemId: itemId, Name: sanitized.name ?? '', SecretKey: sanitized.secretKey, Algorithm: sanitized.algorithm, Digits: sanitized.digits, Period: sanitized.period, ...row };
+ } catch (error) {
+ logExpected('Error importing TOTP code', error);
+ return null;
+ }
+}
+
+/**
+ * Determine the item type: what the importer set, else Login; a Login that carries alias data becomes an Alias.
+ * @param credential - The credential
+ * @returns The item type
+ */
+function determineItemType(credential: ImportedCredential): ItemType {
+ const itemType = credential.ItemType ?? ItemTypes.Login;
+ return itemType === ItemTypes.Login && hasAliasData(credential) ? ItemTypes.Alias : itemType;
+}
+
+/**
+ * Whether the credential carries alias data.
+ * @param credential - The credential
+ * @returns True when any alias field is set
+ */
+function hasAliasData(credential: ImportedCredential): boolean {
+ const alias = credential.Alias;
+ return !!alias && (!!alias.FirstName || !!alias.LastName || !!alias.Gender || !!alias.BirthDate);
+}
diff --git a/core/client/src/transfer/import/writers/TotpHelper.ts b/core/client/src/transfer/import/writers/TotpHelper.ts
new file mode 100644
index 000000000..737c2497f
--- /dev/null
+++ b/core/client/src/transfer/import/writers/TotpHelper.ts
@@ -0,0 +1,75 @@
+import { normalizeTotpAlgorithm, normalizeTotpDigits, normalizeTotpPeriod, TOTP_DEFAULT_ALGORITHM, TOTP_DEFAULT_DIGITS, TOTP_DEFAULT_PERIOD } from '@aliasvault/models/vault';
+import * as OTPAuth from 'otpauth';
+
+/**
+ * A TOTP secret with the name and the RFC 6238 parameters it was imported with.
+ */
+export type SanitizedTotpSecret = {
+ secretKey: string;
+ name: string | null;
+ algorithm: string;
+ digits: number;
+ period: number;
+};
+
+/**
+ * Sanitize a TOTP secret that may be given as an otpauth:// URI.
+ * @param secretKey - The bare Base32 secret or an otpauth://totp/ URI
+ * @param name - The name to use; derived from the URI's label and issuer when not provided
+ * @returns The secret, name and parameters
+ * @throws {Error} When the URI is malformed or the secret cannot generate a code.
+ */
+export function sanitizeTotpSecretKey(secretKey: string, name?: string | null): SanitizedTotpSecret {
+ let secret = secretKey;
+ let algorithm = TOTP_DEFAULT_ALGORITHM;
+ let digits = TOTP_DEFAULT_DIGITS;
+ let period = TOTP_DEFAULT_PERIOD;
+ let resolvedName = name ?? null;
+
+ if (secret.startsWith('otpauth://totp/')) {
+ try {
+ const rest = secret.substring('otpauth://totp/'.length);
+ const queryIndex = rest.indexOf('?');
+ const labelEncoded = queryIndex >= 0 ? rest.substring(0, queryIndex) : rest;
+ const params = new URLSearchParams(queryIndex >= 0 ? rest.substring(queryIndex + 1) : '');
+
+ const secretParam = params.get('secret');
+ if (!secretParam) {
+ throw new Error('Secret not found in URI');
+ }
+ secret = secretParam;
+
+ algorithm = normalizeTotpAlgorithm(params.get('algorithm'));
+ digits = normalizeTotpDigits(params.get('digits'));
+ period = normalizeTotpPeriod(params.get('period'));
+
+ if (!resolvedName || resolvedName.trim().length === 0) {
+ // The label is everything after 'totp/' and before '?'.
+ const label = decodeURIComponent(labelEncoded.replace(/\+/g, ' '));
+ const issuer = params.get('issuer');
+
+ // A label "issuer:account" is split only when the query carries no issuer, so account names with colons survive.
+ if (label.includes(':') && (!issuer || issuer.trim().length === 0)) {
+ resolvedName = label.substring(label.indexOf(':') + 1);
+ } else {
+ resolvedName = label;
+ }
+
+ if (issuer && issuer.trim().length > 0) {
+ resolvedName = `${issuer}: ${resolvedName}`;
+ }
+ }
+ } catch {
+ throw new Error('Invalid TOTP URI format. Please check and try again.');
+ }
+ }
+
+ // The secret must be valid, check by trying to generate a code.
+ try {
+ new OTPAuth.TOTP({ secret: OTPAuth.Secret.fromBase32(secret), algorithm, digits, period }).generate();
+ } catch {
+ throw new Error('Invalid secret key. Please check and try again.');
+ }
+
+ return { secretKey: secret, name: resolvedName, algorithm, digits, period };
+}
diff --git a/core/client/src/transfer/import/writers/VaultImportWriter.ts b/core/client/src/transfer/import/writers/VaultImportWriter.ts
new file mode 100644
index 000000000..9f6426d19
--- /dev/null
+++ b/core/client/src/transfer/import/writers/VaultImportWriter.ts
@@ -0,0 +1,143 @@
+import { FieldKey } from '@aliasvault/models/vault';
+
+import { selectFaviconTarget } from '../../../rust/RustCore';
+import { buildFolderPath } from '../../shared/FolderPaths';
+import { ImportException, ImportStage } from '../models/ImportException';
+
+import { convertToItems } from './ItemConverter';
+
+import type { SqliteClient } from '../../../database/SqliteClient';
+import type { ItemEntity } from '../../shared/VaultEntities';
+import type { ImportedCredential } from '../models/ImportedCredential';
+
+/**
+ * How an import is written.
+ */
+export type VaultImportOptions = {
+ /** Folder paths to the folder ids they were created as; null when folders are not imported. */
+ folderNameToId?: Map<string, string> | null;
+ /** Whether attachments are written; false strips them before conversion. */
+ importAttachments: boolean;
+ /** Favicons fetched for the import, keyed by their Logos.Source (domain). */
+ extractedFavicons: Map<string, Uint8Array>;
+ /** Progress callback with the number of items saved so far and the total. */
+ onProgress?: (saved: number, total: number) => Promise<void> | void;
+};
+
+/**
+ * Writes imported credentials into the vault: creates the folders, resolves each item's logo and inserts the item
+ * and its fields.
+ */
+export class VaultImportWriter {
+ /**
+ * Create the folders an import needs, reusing the ones that already exist by full path, and
+ * map every path to its folder id. Parents come before children.
+ * @param sqliteClient - The vault
+ * @param folderPaths - The hierarchical folder paths, parents first (see collectHierarchicalFolderPaths)
+ * @returns Folder paths to folder ids
+ */
+ public static async createOrGetFolders(sqliteClient: SqliteClient, folderPaths: string[]): Promise<Map<string, string>> {
+ const folderPathToId = new Map<string, string>();
+ const idsByLowerPath = new Map<string, string>();
+
+ // Imported items land in the personal manifest, so only its folders can hold them.
+ const manifestId = sqliteClient.getPersonalManifestId();
+ if (!manifestId) {
+ throw new Error('VaultImportWriter: this client has no personal manifest recorded yet; sync once before importing.');
+ }
+
+ const existingFolders = sqliteClient.folders.getAll().filter(folder => folder.ManifestId === manifestId);
+ const foldersById = new Map(existingFolders.map(folder => [folder.Id, folder]));
+ for (const folder of existingFolders) {
+ idsByLowerPath.set(buildFolderPath(folder.Id, foldersById).toLowerCase(), folder.Id);
+ }
+
+ for (const folderPath of folderPaths) {
+ const existingId = idsByLowerPath.get(folderPath.toLowerCase());
+ if (existingId) {
+ folderPathToId.set(folderPath, existingId);
+ continue;
+ }
+
+ const lastSlashIndex = folderPath.lastIndexOf('/');
+ const folderName = lastSlashIndex >= 0 ? folderPath.substring(lastSlashIndex + 1) : folderPath;
+ const parentPath = lastSlashIndex >= 0 ? folderPath.substring(0, lastSlashIndex) : null;
+ const parentFolderId = parentPath !== null ? folderPathToId.get(parentPath) ?? idsByLowerPath.get(parentPath.toLowerCase()) ?? null : null;
+
+ const newFolderId = await sqliteClient.folders.create(folderName, parentFolderId ? { Id: parentFolderId, ManifestId: manifestId } : null);
+ folderPathToId.set(folderPath, newFolderId);
+ idsByLowerPath.set(folderPath.toLowerCase(), newFolderId);
+ }
+
+ return folderPathToId;
+ }
+
+ /**
+ * Convert the credentials to items and write them into the vault, one transaction per item.
+ * @param sqliteClient - The vault
+ * @param credentials - The credentials to import
+ * @param options - Folder mapping, attachments and favicons
+ * @returns The number of items written
+ * @throws {ImportException} With stage Save when an item cannot be written.
+ */
+ public static async importCredentialsToVault(sqliteClient: SqliteClient, credentials: ImportedCredential[], options: VaultImportOptions): Promise<number> {
+ // Stripping the attachments before conversion keeps them out of the resulting items.
+ if (!options.importAttachments) {
+ for (const credential of credentials) {
+ credential.Attachments = null;
+ }
+ }
+
+ const items = convertToItems(credentials, options.folderNameToId);
+
+ // One logo row per source per import session.
+ const sessionLogoIds = new Map<string, string | null>();
+
+ for (let index = 0; index < items.length; index++) {
+ const item = items[index];
+ try {
+ await VaultImportWriter.processSingleItem(sqliteClient, item, credentials, options.extractedFavicons, sessionLogoIds);
+ } catch (error) {
+ // Re-thrown with item context so the UI can show the credential that failed.
+ throw new ImportException(ImportStage.Save, `Failed to save item #${index + 1} of ${items.length} ("${item.Name ?? ''}"): ${error instanceof Error ? error.message : String(error)}`, error);
+ }
+
+ await options.onProgress?.(index + 1, items.length);
+ }
+
+ return items.length;
+ }
+
+ /**
+ * Resolve an item's logo and insert it.
+ * @param sqliteClient - The vault
+ * @param item - The item
+ * @param credentials - The credentials the item came from, for embedded logo bytes
+ * @param extractedFavicons - Favicons fetched for the import, by source
+ * @param sessionLogoIds - Logo ids already resolved in this import, by source
+ */
+ private static async processSingleItem(sqliteClient: SqliteClient, item: ItemEntity, credentials: ImportedCredential[], extractedFavicons: Map<string, Uint8Array>, sessionLogoIds: Map<string, string | null>): Promise<void> {
+ const importedCredential = credentials.find(c => c.ServiceName === item.Name);
+ const urls = item.FieldValues.filter(fv => fv.FieldKey === FieldKey.LoginUrl && !!fv.Value).map(fv => fv.Value!);
+ const target = await selectFaviconTarget(urls);
+
+ if (target) {
+ // Bytes embedded in the import file take precedence; otherwise what was fetched for this source.
+ const faviconBytes = importedCredential?.FaviconBytes ?? extractedFavicons.get(target.source) ?? null;
+ try {
+ if (sessionLogoIds.has(target.source)) {
+ item.LogoId = sessionLogoIds.get(target.source) ?? null;
+ } else {
+ item.LogoId = await sqliteClient.importExport.resolveImportLogo(target.source, faviconBytes);
+ sessionLogoIds.set(target.source, item.LogoId);
+ }
+ } catch (error) {
+ // A favicon is not critical: log and import the credential without one.
+ console.warn(`Failed to process favicon for item ${item.Name ?? ''}:`, error);
+ item.LogoId = null;
+ }
+ }
+
+ await sqliteClient.importExport.insertImportedItem(item);
+ }
+}
diff --git a/core/client/src/transfer/shared/DateTimeUtils.ts b/core/client/src/transfer/shared/DateTimeUtils.ts
new file mode 100644
index 000000000..0d4b578ae
--- /dev/null
+++ b/core/client/src/transfer/shared/DateTimeUtils.ts
@@ -0,0 +1,101 @@
+/*
+ * Date parsing for the import formats. Every date is UTC: a value without a timezone designator (an .avux manifest,
+ * a CSV column) is read as UTC, never as local time.
+ */
+
+/**
+ * Parse a date/time in any of the formats the import files carry: ISO 8601 (with or without timezone), the
+ * vault's "yyyy-MM-dd HH:mm:ss(.fff)", the US style "MM/dd/yyyy HH:mm:ss" and a bare "yyyy-MM-dd".
+ * @param value - The text
+ * @returns The date, or null when empty or unparseable
+ */
+export function parseDateTime(value: string | null | undefined): Date | null {
+ if (!value) {
+ return null;
+ }
+ const text = value.trim();
+ if (text.length === 0) {
+ return null;
+ }
+
+ // ISO 8601 and the vault format: yyyy-MM-dd[( |T)HH:mm[:ss[.fff]]][Z|+hh:mm]
+ const iso = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2})(?:\.(\d{1,7}))?)?)?(Z|[+-]\d{2}:?\d{2})?$/.exec(text);
+ if (iso) {
+ const [, year, month, day, hour, minute, second, fraction, zone] = iso;
+ const millis = fraction ? Number(fraction.substring(0, 3).padEnd(3, '0')) : 0;
+ const date = new Date(Date.UTC(Number(year), Number(month) - 1, Number(day), Number(hour ?? 0), Number(minute ?? 0), Number(second ?? 0), millis));
+ if (zone && zone !== 'Z') {
+ const sign = zone.startsWith('-') ? -1 : 1;
+ const digits = zone.substring(1).replace(':', '');
+ const offsetMinutes = sign * (Number(digits.substring(0, 2)) * 60 + Number(digits.substring(2, 4)));
+ date.setTime(date.getTime() - offsetMinutes * 60000);
+ }
+ return isNaN(date.getTime()) ? null : date;
+ }
+
+ // US style: MM/dd/yyyy[ HH:mm:ss], also with dashes.
+ const us = /^(\d{1,2})[/-](\d{1,2})[/-](\d{4})(?: (\d{1,2}):(\d{2})(?::(\d{2}))?)?$/.exec(text);
+ if (us) {
+ const [, month, day, year, hour, minute, second] = us;
+ return utcDate(Number(year), Number(month), Number(day), Number(hour ?? 0), Number(minute ?? 0), Number(second ?? 0));
+ }
+
+ const parsed = new Date(text);
+ return isNaN(parsed.getTime()) ? null : parsed;
+}
+
+/**
+ * Parse a date in one explicit day/month order, for sources whose birth dates are written the European way.
+ * @param value - The text
+ * @param format - "dd-MM-yyyy", "MM-dd-yyyy", "dd/MM/yyyy" or "MM/dd/yyyy"
+ * @returns The date, or null when the text does not match
+ */
+export function parseDateExact(value: string, format: 'dd-MM-yyyy' | 'MM-dd-yyyy' | 'dd/MM/yyyy' | 'MM/dd/yyyy'): Date | null {
+ const separator = format.includes('/') ? '/' : '-';
+ const parts = value.trim().split(separator);
+ if (parts.length !== 3 || parts.some(part => !/^\d+$/.test(part))) {
+ return null;
+ }
+ const [first, second, third] = parts.map(Number);
+ const dayFirst = format.startsWith('dd');
+ return utcDate(third, dayFirst ? second : first, dayFirst ? first : second, 0, 0, 0);
+}
+
+/**
+ * Build a UTC date, rejecting values that do not denote a real calendar date.
+ * @param year - Four-digit year
+ * @param month - 1-based month
+ * @param day - Day of month
+ * @param hour - Hour
+ * @param minute - Minute
+ * @param second - Second
+ * @returns The date, or null when out of range
+ */
+function utcDate(year: number, month: number, day: number, hour: number, minute: number, second: number): Date | null {
+ const date = new Date(Date.UTC(year, month - 1, day, hour, minute, second));
+ const valid = date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day && hour < 24 && minute < 60 && second < 60;
+ return valid ? date : null;
+}
+
+/**
+ * Convert a Unix timestamp in seconds to a date, or null when it falls outside years 1 to 9999 (e.g. a value in milliseconds).
+ * @param seconds - Seconds since the epoch
+ * @returns The date, or null
+ */
+export function fromUnixTimeSeconds(seconds: number | null | undefined): Date | null {
+ if (typeof seconds !== 'number') {
+ return null;
+ }
+ const date = new Date(Math.trunc(seconds) * 1000);
+ const year = date.getUTCFullYear();
+ return year >= 1 && year <= 9999 ? date : null;
+}
+
+/**
+ * Format a date as "yyyy-MM-dd" (UTC).
+ * @param date - The date
+ * @returns The formatted date
+ */
+export function formatDateOnly(date: Date): string {
+ return date.toISOString().substring(0, 10);
+}
diff --git a/core/client/src/transfer/shared/FolderPaths.ts b/core/client/src/transfer/shared/FolderPaths.ts
new file mode 100644
index 000000000..641f60f7d
--- /dev/null
+++ b/core/client/src/transfer/shared/FolderPaths.ts
@@ -0,0 +1,46 @@
+import { isBlank } from './StringUtils';
+
+/** The deepest folder level an import creates (matches AliasVault's UI limit). */
+const MAX_FOLDER_DEPTH = 5;
+
+/**
+ * The fields of a folder that make up its path.
+ */
+export type FolderNode = {
+ Name: string | null;
+ ParentFolderId: string | null | undefined;
+};
+
+/**
+ * The full path of a folder, walking up its parents: "Work/Projects/Active".
+ * @param folderId - The folder id
+ * @param foldersById - Every folder by id
+ * @returns The path, or the empty string when the folder is unknown
+ */
+export function buildFolderPath(folderId: string | null | undefined, foldersById: ReadonlyMap<string, FolderNode>): string {
+ const parts: string[] = [];
+ const visited = new Set<string>();
+ let id = folderId;
+ while (id && !visited.has(id)) {
+ const folder = foldersById.get(id);
+ if (!folder) {
+ break;
+ }
+ visited.add(id);
+ parts.unshift(folder.Name ?? '');
+ id = folder.ParentFolderId;
+ }
+ return parts.join('/');
+}
+
+/**
+ * Split a folder path into its folder names, at most five levels deep: "Root/Business/Banking" results in ["Root", "Business", "Banking"].
+ * @param folderPath - The folder path, with "/" or "\" separators
+ * @returns The folder names in order, empty when there are none
+ */
+export function parseFolderPath(folderPath: string | null | undefined): string[] {
+ if (isBlank(folderPath)) {
+ return [];
+ }
+ return folderPath.split(/[/\\]/).map(part => part.trim()).filter(part => part.length > 0).slice(0, MAX_FOLDER_DEPTH);
+}
diff --git a/core/client/src/transfer/shared/StringUtils.ts b/core/client/src/transfer/shared/StringUtils.ts
new file mode 100644
index 000000000..006db22db
--- /dev/null
+++ b/core/client/src/transfer/shared/StringUtils.ts
@@ -0,0 +1,26 @@
+/**
+ * Whether a value is null, undefined, empty or whitespace only.
+ * @param value - The value
+ * @returns True when there is no text
+ */
+export function isBlank(value: string | null | undefined): value is null | undefined | '' {
+ return !value || value.trim().length === 0;
+}
+
+/**
+ * The value, or null when it is blank.
+ * @param value - The value
+ * @returns The value, or null
+ */
+export function nullIfBlank(value: string | null | undefined): string | null {
+ return isBlank(value) ? null : value;
+}
+
+/**
+ * The non-blank values of a list.
+ * @param values - The values
+ * @returns The values that hold text
+ */
+export function nonBlank(values: readonly (string | null | undefined)[]): string[] {
+ return values.filter((value): value is string => !isBlank(value));
+}
diff --git a/core/client/src/transfer/shared/VaultEntities.ts b/core/client/src/transfer/shared/VaultEntities.ts
new file mode 100644
index 000000000..41b577e02
--- /dev/null
+++ b/core/client/src/transfer/shared/VaultEntities.ts
@@ -0,0 +1,146 @@
+import type { ItemType } from '@aliasvault/models/vault';
+
+/**
+ * An item with its child fields, as the export reads it and as the import produces it.
+ */
+export type ItemEntity = {
+ Id: string;
+ Name: string | null;
+ ItemType: ItemType;
+ FolderId: string | null;
+ LogoId: string | null;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+ FieldValues: FieldValueEntity[];
+ Attachments: AttachmentEntity[];
+ TotpCodes: TotpCodeEntity[];
+ Passkeys: PasskeyEntity[];
+};
+
+/**
+ * A field value: a system field (FieldKey set) or a custom field (FieldDefinitionId set).
+ */
+export type FieldValueEntity = {
+ Id: string;
+ ItemId: string;
+ FieldKey: string | null;
+ FieldDefinitionId: string | null;
+ /** The definition of a custom field, carried along so the import can recreate it. */
+ FieldDefinition?: FieldDefinitionEntity | null;
+ Value: string | null;
+ Weight: number;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * A custom field definition.
+ */
+export type FieldDefinitionEntity = {
+ Id: string;
+ FieldType: string;
+ Label: string;
+ IsMultiValue: boolean;
+ IsHidden: boolean;
+ EnableHistory: boolean;
+ Weight: number;
+ ApplicableToTypes: string | null;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * A TOTP code.
+ */
+export type TotpCodeEntity = {
+ Id: string;
+ ItemId: string;
+ Name: string;
+ SecretKey: string;
+ Algorithm: string;
+ Digits: number;
+ Period: number;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * A passkey.
+ */
+export type PasskeyEntity = {
+ Id: string;
+ ItemId: string;
+ RpId: string;
+ UserHandle: Uint8Array | null;
+ PublicKey: string;
+ PrivateKey: string;
+ PrfKey: Uint8Array | null;
+ DisplayName: string;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * An attachment.
+ */
+export type AttachmentEntity = {
+ Id: string;
+ ItemId: string;
+ Filename: string;
+ Blob: Uint8Array;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * A folder.
+ */
+export type FolderEntity = {
+ Id: string;
+ Name: string;
+ ParentFolderId: string | null;
+ Weight: number;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * A tag.
+ */
+export type TagEntity = {
+ Id: string;
+ Name: string;
+ Color: string | null;
+ DisplayOrder: number;
+ CreatedAt: Date;
+ UpdatedAt: Date;
+ IsDeleted: boolean;
+};
+
+/**
+ * An item-tag association.
+ */
+export type ItemTagEntity = {
+ ItemId: string;
+ TagId: string;
+ IsDeleted: boolean;
+};
+
+/**
+ * A logo (favicon, built-in or uploaded image).
+ */
+export type LogoEntity = {
+ Id: string;
+ Source: string;
+ FileData: Uint8Array | null;
+ MimeType: string | null;
+ FetchedAt: Date | null;
+ IsDeleted: boolean;
+};
diff --git a/core/client/src/transfer/shared/ZipArchive.ts b/core/client/src/transfer/shared/ZipArchive.ts
new file mode 100644
index 000000000..a63e2d1e5
--- /dev/null
+++ b/core/client/src/transfer/shared/ZipArchive.ts
@@ -0,0 +1,73 @@
+import { strFromU8, strToU8, unzipSync, zipSync } from 'fflate';
+
+/**
+ * A read-only ZIP archive held in memory.
+ */
+export class ZipArchive {
+ /**
+ * Wrap the extracted files.
+ * @param files - File paths to file data
+ */
+ private constructor(private readonly files: Map<string, Uint8Array>) {}
+
+ /**
+ * Open a ZIP archive.
+ * @param bytes - The archive bytes
+ * @returns The archive
+ * @throws When the bytes are not a valid ZIP archive.
+ */
+ public static open(bytes: Uint8Array): ZipArchive {
+ return new ZipArchive(new Map(Object.entries(unzipSync(bytes)).filter(([path]) => !path.endsWith('/'))));
+ }
+
+ /**
+ * Whether the archive holds a file.
+ * @param path - The path inside the archive
+ * @returns True when present
+ */
+ public has(path: string): boolean {
+ return this.files.has(path);
+ }
+
+ /**
+ * Read a file as UTF-8 text without a byte order mark.
+ * @param path - The path inside the archive
+ * @returns The text, or null when the archive has no such file
+ */
+ public readText(path: string): string | null {
+ const data = this.files.get(path);
+ if (!data) {
+ return null;
+ }
+ const text = strFromU8(data);
+ return text.charCodeAt(0) === 0xFEFF ? text.substring(1) : text;
+ }
+
+ /**
+ * Every file whose path starts with the prefix, compared case-insensitively.
+ * @param prefix - The path prefix (e.g. "attachments/")
+ * @returns File paths to file data
+ */
+ public filesUnder(prefix: string): Map<string, Uint8Array> {
+ const lowerPrefix = prefix.toLowerCase();
+ return new Map([...this.files].filter(([path]) => path.toLowerCase().startsWith(lowerPrefix)));
+ }
+}
+
+/**
+ * Build a ZIP archive from files keyed by path.
+ * @param files - The files to include
+ * @returns The archive bytes
+ */
+export function createZipArchive(files: Record<string, Uint8Array>): Uint8Array {
+ return zipSync(files);
+}
+
+/**
+ * Encode text as UTF-8 bytes for a ZIP entry.
+ * @param text - The text
+ * @returns The bytes
+ */
+export function textToZipBytes(text: string): Uint8Array {
+ return strToU8(text);
+}
diff --git a/core/client/src/utilities/DateFormatter.ts b/core/client/src/utilities/DateFormatter.ts
index 0d256a610..8bf911e47 100644
--- a/core/client/src/utilities/DateFormatter.ts
+++ b/core/client/src/utilities/DateFormatter.ts
@@ -29,13 +29,31 @@ export function now(): string {
return toStandardFormat(new Date());
}
+/**
+ * Parses a stored date-time string as UTC; a value without a timezone designator is read as UTC, not local time.
+ * @param value - The date-time string, in the standard format or ISO 8601
+ * @returns The date, or the epoch when the value cannot be read
+ */
+export function fromStandardFormat(value: string | null | undefined): Date {
+ const date = parseUtc(value ?? '');
+ return isNaN(date.getTime()) ? new Date(0) : date;
+}
+
/**
* Formats a date-time returned by the API (UTC by default) for display in the user's own locale and timezone.
* @param value - The date-time string as returned by the API
* @returns The date-time formatted for the current locale, or the raw value when it cannot be parsed
*/
export function toLocalDisplayFormat(value: string): string {
- const normalized = /^\d{4}-\d{2}-\d{2}[T ][\d:.]+$/.test(value) ? `${value.replace(' ', 'T')}Z` : value;
- const date = new Date(normalized);
+ const date = parseUtc(value);
return isNaN(date.getTime()) ? value : date.toLocaleString();
}
+
+/**
+ * Parses a date-time string, reading one without a timezone designator as UTC.
+ * @param value - The date-time string
+ * @returns The date, invalid when the value cannot be read
+ */
+function parseUtc(value: string): Date {
+ return new Date(/^\d{4}-\d{2}-\d{2}[T ][\d:.]+$/.test(value) ? `${value.replace(' ', 'T')}Z` : value);
+}