Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
/**
* The TypeScript driver of the Rust vault sync engine: runs one operation by carrying out the engine's commands
* against the host. The per-operation wrappers that call this live in VaultSync.
*/
import { NetworkError } from '../api/errors/NetworkError';
import { RequestTimeoutError } from '../api/errors/RequestTimeoutError';
import { WebApiService } from '../api/WebApiService';
import { VaultKeyService } from '../auth/VaultKeyService';
import { StorageKeys } from '../constants/StorageKeys';
import { AppInfo } from '../platform/AppInfo';
import { getPlatform } from '../platform/ClientPlatform';
import { devLog, devWarn } from '../platform/Logger';
import { rustCore } from '../rust/RustCore';
import { base64ToBytes, bytesToBase64 } from '../utilities/Base64';
import { getDirtyScopes } from './VaultDirtyState';
import type { StorageKey } from '../platform/KeyValueStore';
import type { ISqliteDatabase, SqliteValue } from '../platform/SqliteEngine';
/** The operations the engine runs. */
/** The sharing operations, which take `VaultSyncSharingParams`. */
export type VaultSyncSharingOperation = 'createSharedManifest' | 'inviteToSharedManifest' | 'updateSharedManifest' | 'lookupAccountFingerprint' | 'acceptSharedManifestInvitation' | 'transferEmailClaim' | 'approveMobileLogin';
export type VaultSyncOperation = 'fullSync' | 'migrationStatus' | 'migrateManifest' | 'statusCheck' | 'resolveVaultKey' | VaultSyncSharingOperation | 'rotateAccountKeys';
/** What a key rotation works with (the Rust `KeyRotationParams`): the password proof and the new unlock method come from the host. */
export type VaultSyncKeyRotationParams = {
userId: string;
currentClientPublicEphemeral: string;
currentClientSessionProof: string;
accountKeyVersion: number;
manifestKeyVersion: number;
newUnlockKey: string;
newSalt: string;
newVerifier: string;
newEncryptionType: string;
newEncryptionSettings: string;
};
/** What a sharing operation acts on (the Rust `SharingParams`). */
export type VaultSyncSharingParams = {
groupId?: string;
manifestId?: string;
userId?: string;
name?: string;
invitationId?: string;
accountFingerprint?: string;
address?: string;
sourceManifestId?: string;
claimVersion?: number;
requestId?: string;
encryptedAccountKey?: string;
algorithm?: string;
};
/** Moving an email alias from `sourceManifestId` to `manifestId`, signed over the claim version the server reported. */
export type EmailClaimTransfer = Required<Pick<VaultSyncSharingParams, 'address' | 'sourceManifestId' | 'manifestId' | 'claimVersion'>>;
/** What the host hands the engine at session start (the Rust `SyncRequest`). */
export type VaultSyncEngineRequest = {
operation: VaultSyncOperation;
username: string;
encryptionKey?: string;
accountPublicKey?: string;
accountPrivateKey?: string;
accountKey?: string;
isDirty: boolean;
mutationSequence: number;
dirtyScopes: string[];
privateEmailDomains: string[];
forcePull: boolean;
minServerVersion: string;
isOfflineMode: boolean;
sharing?: VaultSyncSharingParams;
keyRotation?: VaultSyncKeyRotationParams;
};
/** The email domains the server serves; hidden private domains are also in the private list. */
export type VaultSyncEmailDomains = {
privateEmailDomainList: string[];
hiddenPrivateEmailDomainList: string[];
publicEmailDomainList: string[];
};
/** Why a sync ended the session (the Rust `LogoutReason`). */
export type LogoutReason = 'clientVersionNotSupported' | 'serverVersionNotSupported' | 'sessionExpired' | 'passwordChanged' | 'vaultVersionIncompatible';
/** What every engine result carries. */
export type VaultSyncEngineResultBase = {
vaultChanged: boolean;
};
/** Outcome of a full sync (the Rust `SyncResult`). */
export type VaultSyncEngineResult = VaultSyncEngineResultBase & {
success: boolean;
hasNewVault: boolean;
wasOffline: boolean;
sqliteBlobUpgradeRequired: boolean;
manifestMigrationRequired: boolean;
error?: string;
errorCode?: string;
apiErrorCode?: string;
logoutReason?: LogoutReason;
requiresLogout: boolean;
serverVersion?: string;
capabilities?: Record<string, string>;
pendingSharingInvitations?: number;
isOfflineMode: boolean;
pulledRevision?: number;
emailDomains?: VaultSyncEmailDomains;
};
/** Outcome of the migration classification. */
export type VaultSyncMigrationStatusResult = VaultSyncEngineResultBase & {
kind: 'none' | 'schemaRebuild' | 'storageFormatUpgrade';
};
/** Outcome of the manifest migration. */
export type VaultSyncMigrateManifestResult = VaultSyncEngineResultBase & {
success: boolean;
pushed: boolean;
error?: string;
errorCode?: string;
apiErrorCode?: string;
logoutReason?: LogoutReason;
requiresLogout: boolean;
};
/** Why a key rotation did not run (the Rust `KeyRotationRefusal`). */
export type VaultSyncKeyRotationRefusal = 'vaultOutOfDate' | 'serverStateChanged' | 'sharedVaultKeyUnavailable' | 'vaultUpgradeRequired';
/** Outcome of a key rotation (the Rust `KeyRotationResult`). */
export type VaultSyncKeyRotationResult = VaultSyncEngineResultBase & {
success: boolean;
accountKey?: string;
encryptionKey?: string;
refusal?: VaultSyncKeyRotationRefusal;
error?: string;
errorCode?: string;
apiErrorCode?: string;
logoutReason?: LogoutReason;
requiresLogout: boolean;
};
/** Outcome of a sharing operation (the Rust `SharingOperationResult`). */
export type VaultSyncSharingResult = VaultSyncEngineResultBase & {
success: boolean;
manifestId?: string;
username?: string;
alreadyMember: boolean;
apiErrorCode?: string;
vaultUpgradeRequired: boolean;
error?: string;
errorCode?: string;
logoutReason?: LogoutReason;
requiresLogout: boolean;
};
/** What the engine asks to persist as the at-rest vault blob. */
export type VaultSyncStoreRequest = {
encryptedBlob: string;
markDirty: boolean;
expectedMutationSeq?: number;
revision?: number;
};
/** Outcome of a store: refused when the expected mutation sequence no longer matched. */
export type VaultSyncStoreOutcome = {
success: boolean;
mutationSequence: number;
};
/** What a running sync is doing: downloading a newer server vault, or uploading local changes. */
export type VaultSyncPhase = 'pull' | 'push';
/**
* The engine's host interface.
*/
export interface IVaultSyncEngineHost {
/**
* The open local vault.
*/
localDatabase(): Promise<ISqliteDatabase>;
/**
* The at-rest vault blob, or null when none is stored.
*/
loadVault(): Promise<string | null>;
/**
* Persist the at-rest vault blob.
*/
storeVault(request: VaultSyncStoreRequest): Promise<VaultSyncStoreOutcome>;
/**
* Clear the dirty flag unless a local mutation happened since the given sequence.
*/
markClean(mutationSeqAtStart: number): Promise<boolean>;
/**
* Called when the run ends with changes written to the local database that no store persisted, so the host can
* drop its in-memory copy and reload the stored vault.
*/
discardLocalDatabase?(): void;
/**
* Called when the engine has decided what the sync is about to do.
*/
onPhase?(phase: VaultSyncPhase): void;
}
/** A JSON value as the engine exchanges it. */
type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
/** One parameterized statement of a `dbExec` command. */
type EngineSqlStatement = { sql: string; params?: JsonValue[] };
/** The engine's commands; see the Rust `Command` enum. */
type EngineCommand =
| { kind: 'http'; method: string; path: string; body?: string; auth: boolean; largeTransfer: boolean; binaryResponse?: boolean; binaryBody?: boolean }
| { kind: 'stateGet'; key: string }
| { kind: 'stateSet'; key: string; value: JsonValue }
| { kind: 'stateRemove'; key: string }
| { kind: 'dbQuery'; sql: string; params: JsonValue[] }
| { kind: 'dbExec'; statements: EngineSqlStatement[] }
| { kind: 'dbExport' }
| { kind: 'vaultStore'; encryptedBlob: string; markDirty: boolean; encryptionKey?: string; expectedMutationSeq?: number; revision?: number }
| { kind: 'vaultLoad' }
| { kind: 'markClean'; mutationSeqAtStart: number }
| { kind: 'log'; level: 'log' | 'warn' | 'phase'; message: string }
| { kind: 'done'; result: JsonValue };
/** The host's response to one command: the JSON, plus the raw bytes of a `dbExport` or a binary `http` response. */
type HostResponse = { json: JsonValue; bytes: Uint8Array | null };
/**
* A cell as the engine binds it: `{ __b64 }` binds a BLOB, booleans bind as integers, objects as their JSON.
* @param value - the JSON parameter
*/
function toBindValue(value: JsonValue | undefined): SqliteValue {
if (value === null || value === undefined) {
return null;
}
if (typeof value === 'string' || typeof value === 'number') {
return value;
}
if (typeof value === 'boolean') {
return value ? 1 : 0;
}
if (!Array.isArray(value) && typeof value.__b64 === 'string') {
return base64ToBytes(value.__b64);
}
return JSON.stringify(value);
}
/**
* A cell as the engine reads it: BLOB columns travel as `{ __b64 }`.
* @param value - the SQLite value
*/
function toJsonCell(value: SqliteValue): JsonValue {
return value instanceof Uint8Array ? { __b64: bytesToBase64(value) } : value;
}
/**
* Run statements inside one transaction, rolling back when any fails.
* @param db - the database
* @param statements - the statements
*/
function execInTransaction(db: ISqliteDatabase, statements: EngineSqlStatement[]): void {
db.exec('BEGIN');
try {
for (const statement of statements) {
db.run(statement.sql, (statement.params ?? []).map(toBindValue));
}
db.exec('COMMIT');
} catch (error) {
try {
db.exec('ROLLBACK');
} catch {
// The transaction is already gone; the original error is what matters.
}
throw error;
}
}
/**
* The storage key of an engine state key.
* @param key - the engine's key
*/
function stateKey(key: string): StorageKey {
if (key.includes(':')) {
throw new Error(`The sync engine addressed a prefixed state key: ${key}`);
}
return `local:${key}` as StorageKey;
}
/**
* Current time in milliseconds.
*/
function now(): number {
return typeof performance !== 'undefined' ? performance.now() : Date.now();
}
/**
* Carries out one engine run's commands.
*/
class EngineRun {
/** The open local vault. */
private local: ISqliteDatabase | null = null;
/** Whether the local database was written to since the last store. */
private localMutated = false;
/** Time spent in the host per command kind (for debugging). */
private readonly timings = new Map<string, { count: number; ms: number }>();
/**
* Create a run.
* @param host - the host
* @param webApi - the API the HTTP commands run on
*/
public constructor(private readonly host: IVaultSyncEngineHost, private readonly webApi: WebApiService) {}
/**
* Carry out one command and return the host's response.
* @param command - the command
* @param commandBytes - the raw bytes the engine attached to the command (the body of a binary `http` request)
*/
public async handle(command: Exclude<EngineCommand, { kind: 'done' }>, commandBytes: Uint8Array | null = null): Promise<HostResponse> {
const started = now();
try {
if (command.kind === 'http') {
return await this.http(command, commandBytes);
}
const response = await this.dispatch(command);
return response instanceof Uint8Array ? { json: {}, bytes: response } : { json: response, bytes: null };
} catch (error) {
return { json: { error: error instanceof Error ? error.message : String(error) }, bytes: null };
} finally {
const timing = this.timings.get(command.kind) ?? { count: 0, ms: 0 };
timing.count++;
timing.ms += now() - started;
this.timings.set(command.kind, timing);
}
}
/**
* One line of where the time went.
* @param operation - the operation that ran
* @param totalMs - the run's wall time
*/
public summarize(operation: string, totalMs: number): string {
let hostMs = 0;
const parts: string[] = [];
for (const [kind, timing] of [...this.timings.entries()].sort((a, b) => b[1].ms - a[1].ms)) {
hostMs += timing.ms;
parts.push(`${kind} ${timing.count}x ${timing.ms.toFixed(0)}ms`);
}
return `[VaultSyncEngine] ${operation} took ${totalMs.toFixed(0)}ms: engine ${(totalMs - hostMs).toFixed(0)}ms, host ${hostMs.toFixed(0)}ms (${parts.join(', ')})`;
}
/**
* End the run, discarding local changes no store persisted.
*/
public close(): void {
if (this.localMutated) {
this.host.discardLocalDatabase?.();
}
}
/**
* The command handlers. Raw bytes (a `dbExport`) go back to the engine outside the JSON.
* @param command - the command
*/
private async dispatch(command: Exclude<EngineCommand, { kind: 'done' | 'http' }>): Promise<JsonValue | Uint8Array> {
switch (command.kind) {
case 'stateGet':
return { value: await getPlatform().storage.get<JsonValue>(stateKey(command.key)) };
case 'stateSet':
await getPlatform().storage.set(stateKey(command.key), command.value);
return {};
case 'stateRemove':
await getPlatform().storage.remove(stateKey(command.key));
return {};
case 'dbQuery': {
const rows = (await this.database()).query(command.sql, command.params.map(toBindValue));
return { rows: rows.map(row => Object.fromEntries(Object.entries(row).map(([column, value]) => [column, toJsonCell(value)]))) };
}
case 'dbExec':
execInTransaction(await this.database(), command.statements);
this.localMutated = true;
return {};
case 'dbExport':
return (await this.database()).export();
case 'vaultStore':
return this.storeVault(command);
case 'vaultLoad':
return { encryptedBlob: await this.host.loadVault() };
case 'markClean':
return { cleared: await this.host.markClean(command.mutationSeqAtStart) };
case 'log':
this.log(command.level, command.message);
return {};
default:
throw new Error(`Unknown engine command ${(command as { kind: string }).kind}`);
}
}
/**
* An API request. On success a binary response returns its body as raw bytes instead of as `body` text in the JSON.
* @param command - the command
* @param commandBytes - the request body of a binary request
*/
private async http(command: Extract<EngineCommand, { kind: 'http' }>, commandBytes: Uint8Array | null): Promise<HostResponse> {
try {
const body = command.binaryBody ? commandBytes ?? new Uint8Array() : command.body;
const response = await this.webApi.engineRequest(command.method, command.path, body, command.auth, command.largeTransfer, command.binaryResponse);
return { json: { status: response.status, body: response.body }, bytes: response.bytes ?? null };
} catch (error) {
if (error instanceof NetworkError) {
return { json: { status: 0, transportError: error.message, timedOut: error instanceof RequestTimeoutError }, bytes: null };
}
throw error;
}
}
/**
* Persist the blob.
* @param command - the command
*/
private async storeVault(command: Extract<EngineCommand, { kind: 'vaultStore' }>): Promise<JsonValue> {
const outcome = await this.host.storeVault({
encryptedBlob: command.encryptedBlob,
markDirty: command.markDirty,
expectedMutationSeq: command.expectedMutationSeq,
revision: command.revision,
});
if (outcome.success) {
// The local database is now the vault just stored; the host serves it on the next request.
this.localMutated = false;
this.local = null;
}
return { success: outcome.success, mutationSequence: outcome.mutationSequence };
}
/**
* The local vault the `db*` commands address.
*/
private async database(): Promise<ISqliteDatabase> {
this.local ??= await this.host.localDatabase();
return this.local;
}
/**
* Route an engine log line.
* @param level - the level
* @param message - the message
*/
private log(level: string, message: string): void {
switch (level) {
case 'phase':
this.host.onPhase?.(message as VaultSyncPhase);
break;
case 'warn':
devWarn(message);
break;
default:
devLog(message);
}
}
}
/**
* Run one engine operation.
* Other platform implementations: VaultSyncEngine.swift (iOS), VaultSyncEngine.kt (Android).
* @param host - the host
* @param request - the request
* @param webApi - the API the HTTP commands run on
*/
export async function runVaultSyncEngine<T extends VaultSyncEngineResultBase>(host: IVaultSyncEngineHost, request: VaultSyncEngineRequest, webApi: WebApiService = new WebApiService()): Promise<T> {
const started = now();
const session = await rustCore().createVaultSyncSession(JSON.stringify(request));
const run = new EngineRun(host, webApi);
try {
for (;;) {
const command = JSON.parse(await session.nextCommand()) as EngineCommand;
if (command.kind === 'done') {
devLog(run.summarize(request.operation, now() - started));
return command.result as T;
}
const commandBytes = command.kind === 'http' && command.binaryBody ? await session.commandBytes() : null;
const response = await run.handle(command, commandBytes);
await session.resume(JSON.stringify(response.json), response.bytes);
}
} finally {
run.close();
session.free();
}
}
/** What a caller may ask of a full sync beyond what the revisions decide. */
export type VaultSyncOptions = {
forcePull?: boolean;
};
/**
* Build the engine request from the session state in the platform storage.
* @param operation - the operation
* @param options - what the caller asks beyond what the engine decides
*/
export async function buildVaultSyncRequest(operation: VaultSyncOperation, options: VaultSyncOptions = {}): Promise<VaultSyncEngineRequest> {
const storage = getPlatform().storage;
const [username, sessionKeys, accountPublicKey, isDirty, mutationSequence, privateEmailDomains, isOfflineMode] = await Promise.all([
storage.get<string>(StorageKeys.USERNAME),
VaultKeyService.getSessionKeys(),
storage.get<string>(StorageKeys.ACCOUNT_PUBLIC_KEY),
storage.get<boolean>(StorageKeys.IS_DIRTY),
storage.get<number>(StorageKeys.MUTATION_SEQUENCE),
storage.get<string[]>(StorageKeys.PRIVATE_EMAIL_DOMAINS),
storage.get<boolean>(StorageKeys.IS_OFFLINE_MODE),
]);
return {
operation,
username: username ?? '',
encryptionKey: sessionKeys?.vaultEncryptionKey,
accountPublicKey: accountPublicKey ?? undefined,
accountPrivateKey: sessionKeys?.accountPrivateKey ?? undefined,
accountKey: sessionKeys?.accountKey,
isDirty: isDirty ?? false,
mutationSequence: mutationSequence ?? 0,
dirtyScopes: isDirty ? await getDirtyScopes() : [],
privateEmailDomains: privateEmailDomains ?? [],
forcePull: options.forcePull === true,
minServerVersion: AppInfo.MIN_SERVER_VERSION,
isOfflineMode: isOfflineMode ?? false,
};
}