📦 Monica WebDAV Backup Format Specification

Abstract

This specification defines the archive structure, underlying data formats, and encryption protocols utilized by the Monica local vault during automated WebDAV backups and data transfers. This framework ensures robust cross-platform parsing capabilities alongside compromising-free privacy and security.

---

1. Overview

Monica's WebDAV backup mechanism bundles the user's core data into a standard ZIP archive (.zip when unencrypted, and .enc.zip when high-strength backup encryption is enabled).

Instead of traditional, redundant direct binary database exports, the backup archive adopts a loosely coupled architecture consisting of .json core data, .csv summaries, and media resources (Images). This ensures simplified data auditing and highly precise restoration workflows across platforms in the future.

---

2. Backup Archive Directory Structure

The tree structure of a standard backup ZIP archive upon extraction is detailed below:

/ (Root Directory)
├── passwords/                  # Password entries (highly cohesive separate storage)
│   ├── password_1_1700000.json
│   └── password_2_1700001.json
├── notes/                      # Secure notes data
│   └── note_5_1700002.json
├── images/                     # Image assets (e.g., encrypted physical ID photos, attachments)
│   └── image_20240101.jpg
├── trash/                      # Recycle Bin archives (supports soft-deleted data recovery)
│   ├── trash_passwords.json
│   └── trash_secure_items.json
├── categories.json             # Independent global category layout configurations
├── Monica_20240101_password.csv # Flattened password summary (for manual inspection & compatibility exports)
├── Monica_20240101_totp.csv     # TOTP two-factor authentication summary
├── common_account.json         # Common identities & autofill settings
├── webdav_config.json          # WebDAV current node connection config (supports seamless migration)
├── timeline_history.json       # Audit logs (operational timeline)
└── generated_history.json      # Strong password generator history logs

---

3. Detailed File Format Specifications

3.1 Password Entries (passwords/password_{id}_{timestamp}.json)

Each password item is encapsulated within its own independent JSON file to mitigate the risk of catastrophic vault corruption from a single faulty file.

Field	Type	Description
id	Long	Original database entry ID
title	String	Title of the password item (e.g., Google)
username	String	Account login / Username
password	String	Password string (plaintext or encrypted, depending on backup encryption status)
website	String	Associated URL / Domain
notes	String	Plaintext description/notes
isFavorite	Boolean	Whether the item is added to favorites
categoryId	Long?	Associated category ID (nullable)
categoryName	String?	Category name (used to automatically rebuild category trees during cross-device remote restorations)
authenticatorKey	String	Associated 2-factor authentication (TOTP) seed secret
loginType	String	Authentication architecture: PASSWORD (traditional) or SSO (Single Sign-On)
ssoRefEntryId	Long?	Associated parent password entry ID for SSO mappings

💡 Click to view a complete password entry JSON example

{
  "id": 1,
  "title": "Google",
  "username": "user@gmail.com",
  "password": "mySecurePassword123",
  "website": "[https://accounts.google.com](https://accounts.google.com)",
  "notes": "Primary personal account containing vital cloud assets.",
  "isFavorite": true,
  "categoryId": 2,
  "categoryName": "Social",
  "authenticatorKey": "NBSWY3DPEB3W64TBNQ======",
  "loginType": "PASSWORD",
  "ssoRefEntryId": null
}

3.2 Secure Notes (notes/note_{id}_{timestamp}.json)

Field	Type	Description
notes	String	Note content body (supports Markdown formatting or pure text)
imagePaths	String	File name list of associated image assets (comma , separated)

3.3 Configuration Summaries

categories.json

// Stores global category profiles and front-end UI sorting indices
[
  { "id": 1, "name": "Work", "sortOrder": 0 },
  { "id": 2, "name": "Social", "sortOrder": 1 }
]

common_account.json

// Stores identity configuration data used to facilitate quick autofill routines
{
  "email": "myemail@example.com",
  "phone": "13800138000",
  "autoFillEnabled": true
}

webdav_config.json

// Enables seamless device takeovers and configurations of custom WebDAV infrastructures
{
  "url": "[https://dav.jianguoyun.com/dav/](https://dav.jianguoyun.com/dav/)",
  "username": "monica_user@dav.com",
  "encryptedPassword": "U2FsdGVkX19..." // ⚠️ Secondarily encrypted locally utilizing the user's "Backup Password"
}

3.4 Recycle Bin Architectures (trash/)

• trash_passwords.json：Contains all password entries currently moved to the Recycle Bin. The underlying schema mirrors standard items but appends a high-precision deletedAt timestamp.
• trash_secure_items.json：Tracks soft-deleted secure notes, payment cards, secure tokens, and other auxiliary digital items.

3.5 Compatibility CSV Sheets (*.csv)

TIP

These CSV schemas (e.g., Monica_20240101_password.csv) are generated exclusively for manual inspection or import compatibility with alternative credential providers. Monica's complete native cross-device data recovery workflows do not rely on CSV streams, operating 100% via the JSON formats defined above.

---

4. Encryption Mechanics

When a user toggles "Backup Encryption" under Settings ➔ Backup Configurations, the data pipeline transitions into a hardened security defense layout:

[Raw Compressed Stream] ➔ [EncryptionHelper] ➔ [AES-256-GCM Encryption] ➔ Exported as .enc.zip

1. Binary Stream Encryption: The payload of the standard ZIP folder never hits local storage in plaintext; it is processed explicitly as raw binary blocks.
2. Algorithm Selection: Enforces the AES-256-GCM authenticated encryption scheme, providing data stealth alongside comprehensive integrity verification against malicious tampering.
3. Extension Labeling: The extensions of physical archive files compiled under encryption are strictly designated as .enc.zip.
4. Binary Header Design: The file header explicitly bundles a sequence of unique magic bytes:

• MONICA_ENC_V1 (Format generation version indicator)
• High-entropy random Salt
• Random Initialization Vector (IV)

---

5. Cross-Device Restoration & Conflict Mitigation Logic

During the data restoration phase, client runtimes strictly execute the following sequential pipeline lifecycle:

1. Decryption & Validation: Decode .enc.zip ➔ Validate header block integrity ➔ Decrypt stream via master-password-derived keys ➔ Unpack files into an isolated sandbox in memory.
2. ID Conflict Resolution:

• If an extracted JSON entry's id is discovered to already exist in the active device database, the engine rejects direct overwriting.
• Triggers a fallback route: Allocates a new physical unique Long ID for the incoming record and safely inserts it into the database.

3. Relational Graph Restructuring (ID Mapping Repairs):

• Run-time routines compile a transient map tracing Old ID ➔ New ID adjustments.
• Automatically patches ssoRefEntryId parameters, paired account indicators, and related TOTP bindings, preserving graph linkages without breakage.

4. Media Asset Relocation:

• Processes all binary records inside the images/ directory tree.
• Securely migrates snapshots and document attachments to the host app's isolated local filesystem space (context.filesDir), rewriting corresponding internal path bindings within the active note databases.