Secure Document Vault Operational Specification

1. Executive Summary

This document resolves five open operational questions that must be answered before the Secure Document Vault (SDV) subsystem can proceed to mainnet deployment. Each decision was evaluated across engineering, compliance, and product teams and is now binding for the SDV subsystem.

The five questions addressed are: (1) What are the maximum document size limits per account tier? (2) Which storage providers does SDV use and how are they layered? (3) How does key recovery work when a user loses access? (4) How are team vaults governed across multiple administrators? (5) What document retention policies are available and which regulatory minimums apply?

SDV handles the most sensitive data in the JIL ecosystem - legal documents, compliance records, KYC artifacts, and financial statements. The decisions here prioritize data integrity and recoverability above all else. Conservative defaults can be relaxed through governance as the system matures, but they cannot be weakened unilaterally.

2. Document Size Limits

Decision: Tiered limits by account level with client-side chunking.

Maximum document sizes are enforced at the API gateway layer by mobile-sdk-backend (port 9015), which handles chunked uploads. Limits scale with account tier to balance storage costs against institutional requirements.

Tier Limits

Chunked Upload Protocol

All uploads use client-side chunking with a fixed 5 MB chunk size regardless of tier. The chunk size is small enough to survive unstable mobile connections while large enough to avoid excessive round-trips. Upload progress is tracked per-chunk and displayed to the user in real time.

• Resume support - Each upload session receives a unique upload ID. If the connection drops, the client queries which chunks have been received and resumes from the last missing chunk. Sessions expire after 24 hours of inactivity.
• Retry policy - Failed chunks auto-retry 3 times with exponential backoff (1s, 2s, 4s). After 3 failures on the same chunk, the upload is paused and the user is notified to check their connection.
• Integrity - Each chunk includes a SHA-256 hash computed client-side. The server verifies the hash on receipt and rejects corrupted chunks immediately. After all chunks arrive, the server reassembles the document and verifies the full-file SHA-256 against the client-provided manifest hash.
• Parallel uploads - Higher tiers can upload multiple chunks simultaneously. Free tier uploads sequentially (1 chunk at a time) to limit server load from unpaid accounts.

3. Storage Provider Architecture

Decision: 3-tier storage with Hetzner S3 as primary, Arweave for permanence, and IPFS as optional backup.

The storage architecture was ratified in PR #359 when SDV migrated from IPFS-only to the current multi-provider model. Each tier serves a distinct purpose with clear trade-offs between cost, durability, and immutability.

3.1 Primary - Hetzner S3

All active documents are stored on Hetzner Object Storage (Helsinki/hel1). This is the production storage layer that handles all reads and writes during normal operation.

• Bucket: jil-sdv with object key prefix docs/{sha256}
• Encryption: AES-256-GCM at rest, client-side encryption before upload
• Addressing: Content-addressed via SHA-256 hash - identical documents share the same storage key, providing automatic deduplication
• Region: eu-central (Helsinki) - GDPR-compliant jurisdiction
• Cost: Approximately $0.0065/GB/month - orders of magnitude cheaper than on-chain storage

3.2 Archival - Arweave

Documents flagged for permanent storage are replicated to Arweave via bundled transactions. The arweave-integration service (port 8950) manages uploads and transaction monitoring.

• Use case: Legal agreements, compliance attestations, audit trails, and any document the user explicitly marks as permanent
• Permanence warning: Users see a confirmation dialog at upload time: "Arweave copies are permanent and cannot be deleted. This action is irreversible."
• Bundling: Small documents are bundled into Arweave transactions to reduce per-document cost. Bundle threshold is 256 KB - documents below this size are queued and bundled every 15 minutes.
• Transaction ID: The Arweave transaction ID is stored alongside the Hetzner S3 key in the document metadata, providing a secondary retrieval path

3.3 Backup - IPFS (Optional)

Pinata serves as an external backup pinning layer for high-availability documents. The ipfs-pinning service (port 8920) manages CID lifecycle including pinning, unpinning, and garbage collection.

• Scope: Only Premium and Institutional tier documents are eligible for IPFS backup
• CID tracking: IPFS CIDs are stored in the document metadata table and verified on a 24-hour cycle
• Fallback: If Hetzner S3 is unreachable during a read request, the system attempts IPFS retrieval via the stored CID before returning an error

Replication Policy

4. Key Recovery Mechanism

Decision: Guardian-based recovery with 2-of-3 quorum and 24-hour timelock.

The recovery-ceremony service (port 8130) orchestrates the full recovery flow. Recovery is designed to be secure against both key loss and social engineering attacks.

Guardian Setup

During vault initialization, the user designates exactly 3 guardians. Guardians can be any combination of the following types:

• Other JIL users - Identified by their on-chain wallet address. The guardian receives a notification and must explicitly accept the role.
• Hardware keys - A YubiKey or similar FIDO2 device registered as a guardian. The physical device must be present during recovery attestation.
• Institutional custodians - A qualified custodian (bank, trust company, or licensed custodian) registered as a guardian. Attestation requires the custodian's authorized signatory.

Recovery Flow

1. Initiation - Any guardian can initiate recovery by submitting a request to the recovery-ceremony service with their attestation.
2. Quorum - A second guardian must independently submit their attestation. The system requires 2-of-3 guardian attestations before proceeding. Attestations expire after 72 hours.
3. Timelock - After quorum is reached, a 24-hour timelock begins. During this window, the original wallet can cancel the recovery if the initiation was unauthorized (compromised guardian scenario).
4. Wallet generation - After the timelock expires without cancellation, a new MPC 2-of-3 wallet is generated for the user during the recovery ceremony.
5. Re-encryption - All documents in the vault are re-encrypted with the new wallet's keys. The hsm-key-management service (port 8935) handles the re-encryption via an HSM intermediate key that never leaves the secure enclave.
6. NFT transfer - DocumentNFT ownership is transferred from the old wallet to the new wallet on-chain, preserving the full document history and metadata.
7. Revocation - The old wallet's access is permanently revoked. All active sessions are terminated and the old key shards are marked as compromised in the MPC registry.

Emergency Recovery

When all 3 guardians are unreachable (deceased, lost access, or unresponsive for 180 consecutive days), the user can petition for emergency recovery via a 14-of-20 validator vote. This path requires:

• Legal identity verification (notarized documents or court order)
• Proof of prior vault ownership (signed messages from the old wallet, transaction history)
• 180-day mandatory waiting period after the petition is filed
• Public notice period (30 days) during which any party can contest the recovery

5. Team Vault Governance

Decision: Multi-admin voting model with timelock and veto rights.

Team vaults support up to 10 administrators. All document operations require majority approval with a 72-hour timelock that allows any single admin to veto. TeamVault.sol enforces voting and timelock mechanics on-chain.

Operation Approval Thresholds

Governance Mechanics

• Proposal lifecycle - Any admin can propose an operation. The proposal enters a voting phase where other admins approve or reject. Once the threshold is met, the 72-hour timelock begins. After the timelock expires without veto, the operation executes automatically.
• Veto power - During the 72-hour timelock window, any single admin can veto any pending operation. A veto immediately cancels the operation. The vetoing admin must provide a reason (stored on-chain). Vetoed proposals can be resubmitted but require fresh votes.
• Quorum requirement - At least 3 admins must be active (have signed a transaction within 90 days) for the vault to accept new proposals. If fewer than 3 admins are active, the vault enters read-only mode until activity resumes.
• Admin cap - Maximum 10 admins per vault. This limit is enforced by TeamVault.sol and cannot be increased without a contract upgrade through validator governance.

Emergency Access

When all admins become unreachable (no on-chain activity for 180 consecutive days), a 14-of-20 validator vote can grant emergency access. The petitioner must provide legal basis documentation (court order, corporate resolution, or equivalent) proving legitimate authority over the team vault's assets.

6. Document Retention Policies

Decision: 7 retention options with regulatory minimums enforced automatically.

Users select a retention policy at document upload time. The system enforces regulatory minimums based on document type classification - users can choose longer retention but cannot go below the regulatory floor.

Retention Options

Regulatory Minimums

The system classifies documents at upload time (based on metadata tags and content analysis) and enforces the following minimum retention periods. Users cannot select a retention option shorter than the applicable minimum.

• US tax documents - 7-year minimum (IRS requirement). Includes W-9s, 1099s, tax returns, and supporting schedules.
• Financial records - 5-year minimum. Includes balance sheets, income statements, audit reports, and bank statements.
• KYC documents - Duration of relationship plus 5 years. Retention clock starts when the customer relationship ends, not when the document is uploaded.

Deletion Process

• 30-day notice - Before any auto-deletion, the system sends a pre-deletion notice via email and push notification 30 days in advance. The notice includes the document name, upload date, retention policy, and scheduled deletion date.
• Extension - During the 30-day notice period, the user can extend the retention by selecting a longer option. Extensions take effect immediately and reset the deletion countdown.
• Execution - After the notice period expires without extension, the document is permanently deleted from Hetzner S3. IPFS pins (if any) are unpinned. The DocumentNFT metadata is updated to reflect the deletion, but the NFT itself remains as a historical record that the document once existed.
• Arweave exception - Documents stored on Arweave are permanent and cannot be deleted regardless of the retention setting selected for the Hetzner S3 copy. Users are warned about this at upload time.

7. Cross-Reference Matrix

This matrix maps each operational decision to the services, contracts, and governance mechanisms that enforce it.