securevault-guidelines

SecureVault Implementation Guidelines

Introduction

These guidelines encapsulate vital information for using SecureVault in our application. SecureVault is our secure storage system built on GRDB with SQLCipher encryption, providing a layered security approach for sensitive data.

For general GRDB knowledge, refer to GRDB documentation. This guide covers DuckDuckGo-specific patterns and requirements.

Essential Knowledge

SecureVault Architecture Overview

SecureVault is a protocol-based system that provides:

• L0: Not encrypted (currently unused)
• L1: Secret key encrypted (usernames, domains, duck addresses)
• L2: User password encrypted with time-based access (user passwords)
• L3: User password required at request time (future: credit cards, sensitive data)

// Core SecureVault protocol pattern
public protocol SecureVault {
    associatedtype DatabaseProvider: SecureStorageDatabaseProvider
    init(providers: SecureStorageProviders<DatabaseProvider>)
}

// Example: AutofillSecureVault implementation
public protocol AutofillSecureVault: SecureVault {
    func storeWebsiteCredentials(_ credentials: SecureVaultModels.WebsiteCredentials) throws -> Int64
    func websiteCredentialsFor(domain: String) throws -> [SecureVaultModels.WebsiteCredentials]
    // ... other autofill-specific methods
}

Database Location and Setup

Choosing the Database Location

Important Note: If you need to share the Database through AppGroup, please refer to Sharing Database through AppGroup section below.

For typical single-app usage:

• Create a dedicated folder for the database file
• This helps separate it from other files and makes file coordination easier
• Makes future migration simpler if needed

// Example database location setup
let databaseDirectory = FileManager.default
    .urls(for: .applicationSupportDirectory, in: .userDomainMask)[0]
    .appendingPathComponent("SecureVault")

try FileManager.default.createDirectory(at: databaseDirectory, 
                                       withIntermediateDirectories: true)

let databaseURL = databaseDirectory.appendingPathComponent("vault.sqlite")