Repository Public
1// Client engine: all cryptography and sync logic of a device. Used by the web app and by the integration tests2// (with a memory store and a software authenticator). The server only ever sees what this file sends.3import * as P from "../../../../packages/protocol/src/index.ts";45export class ApiError extends Error { constructor(public status: number, public code: string, message?: string, public body?: any) { super(message ?? code); } }6export interface Transport { request(method: string, path: string, body?: unknown, opts?: { headers?: Record<string, string>; binary?: Uint8Array; raw?: boolean }): Promise<any> }7export interface Store { get<T>(key: string): Promise<T | undefined>; set(key: string, value: unknown): Promise<void>; clear(): Promise<void> }8export interface Passkeys { create(options: any): Promise<any>; get(options: any): Promise<any> }910export class MemoryStore implements Store {11 m = new Map<string, unknown>();12 async get<T>(k: string) { return this.m.get(k) as T | undefined; }13 async set(k: string, v: unknown) { this.m.set(k, v); }14 async clear() { this.m.clear(); }15}1617interface Identity { accountId: string; handle: string; deviceId: string; createdAt: string; keys: P.DeviceKeys; arkEnvelope?: string }18interface StoredRecord { id: string; type: P.RecordType; rev: number; envelope: P.Envelope; deleted: boolean; seq: number; updatedAt?: string; deviceId?: string | null; attachments?: string[] }19interface StoredVault { vaultId: string; epoch: number; role: P.Role; ownerId: string; cursor: number; grants: P.VaultGrant[]; members: Member[]; records: Record<string, StoredRecord> }20interface OutboxEntry { key: string; vaultId: string; recordId: string; type: P.RecordType; baseRev: number; envelope: P.Envelope; deleted: boolean; attachments: string[] }21interface Persisted { vaults: Record<string, StoredVault>; outbox: OutboxEntry[]; maxRev: Record<string, number>; pins: Record<string, string>; lastSyncAt?: string; account?: AccountView }22export interface Member { accountId: string; role: P.Role; handle: string; sigPub: string; encPub: string }23export interface AccountView { accountId: string; handle: string; sigPub: string; encPub: string; keyset: P.KeysetBlob; recoveryEpoch: number; keyEpoch: number }24export interface ItemView { vaultId: string; id: string; rev: number; item: P.Item; pending: boolean; updatedAt?: string }25export interface VaultView { vaultId: string; meta: P.VaultMeta; role: P.Role; ownerId: string; epoch: number; members: Member[]; metaRecordId: string }26export interface DeviceView { deviceId: string; platform: string; hardware: boolean; addedAt: string; lastSeenAt: string | null; current: boolean; verified: boolean; fingerprint: string }27export interface SyncHealth { lastSyncAt?: string; pending: number; online: boolean; warnings: string[]; undecryptable: number }2829const empty = (): Persisted => ({ vaults: {}, outbox: [], maxRev: {}, pins: {} });3031export class Engine {32 identity?: Identity;33 private ark?: P.Bytes;34 private account?: P.AccountKeys;35 private accountView?: AccountView;36 private state: Persisted = empty();37 private vaultKeys = new Map<string, Map<number, P.Bytes>>();38 private items = new Map<string, ItemView>();39 private vaultMeta = new Map<string, VaultView>();40 private health: SyncHealth = { pending: 0, online: true, warnings: [], undecryptable: 0 };41 private syncing?: Promise<void>;42 onChange: () => void = () => {};4344 constructor(private api: Transport, private store: Store, private passkeys: Passkeys, private platform: string) {}4546 async load(): Promise<"none" | "locked"> {47 this.identity = await this.store.get<Identity>("identity");48 this.state = (await this.store.get<Persisted>("state")) ?? empty();49 this.accountView = this.state.account;50 return this.identity ? "locked" : "none";51 }52 get unlocked() { return !!this.ark; }53 get accountInfo() { return this.accountView; }54 private persist = () => this.store.set("state", this.state);5556 // ── account creation ──────────────────────────────────────────────────────────────────────────────────────57 /** Returns the recovery key text. It is shown once; nothing keeps a copy. */58 async register(invite: string, handle: string): Promise<string> {59 const accountId = P.uuid(), deviceId = P.uuid(), createdAt = new Date().toISOString();60 const { challengeId, options } = await this.api.request("POST", "/api/v1/auth/register/options", { invite, handle, accountId });61 const response = await this.passkeys.create(options);62 const ark = P.random(32), account = await P.generateAccountKeys(), keys = await P.generateDeviceKeys(), rk = P.generateRecoveryKey();63 const dev = { deviceId, encPub: P.b64u(keys.enc.pub), sigPub: P.b64u(keys.sig.pub), createdAt };64 const vaultId = P.uuid(), vk = P.random(32), recordId = P.uuid();65 const arkEnvelope = await P.wrapArkForDevice(ark, accountId, deviceId, keys.enc.pub);66 const body = {67 challengeId, response, sigPub: P.b64u(account.sig.pub), encPub: P.b64u(account.enc.pub), keyset: await P.sealKeyset(ark, accountId, account),68 recovery: { epoch: 1, envelope: await P.sealRecoveryEnvelope(rk, accountId, 1, ark), authHash: await P.recoveryAuthHash(rk, accountId) },69 device: { ...dev, cert: await P.signDeviceCert(account, accountId, dev), arkEnvelope, platform: this.platform, hardware: false },70 vault: { vaultId, grant: await P.grantVaultKey(account, accountId, vk, vaultId, 1, accountId, account.enc.pub, "owner"),71 meta: { recordId, envelope: await P.sealRecord(vk, 1, { vaultId, recordId, type: "vault-meta", rev: 1 }, { name: "Personal", kind: "personal" } satisfies P.VaultMeta) } },72 };73 const r = await this.api.request("POST", "/api/v1/auth/register/verify", body);74 this.identity = { accountId, handle, deviceId, createdAt, keys, arkEnvelope };75 await this.store.set("identity", this.identity);76 await this.open(ark, r.account);77 await this.sync();78 return P.encodeRecoveryKey(rk);79 }8081 // ── sign-in / unlock ──────────────────────────────────────────────────────────────────────────────────────82 /** Passkey sign-in. On an enrolled device this also unlocks; otherwise the session is "pending" until pairing or recovery. */83 async signIn(): Promise<"unlocked" | "pending"> {84 const { challengeId, options } = await this.api.request("POST", "/api/v1/auth/login/options", {});85 const response = await this.passkeys.get(options);86 const id = this.identity;87 // A passkey of another account picked on an enrolled device must never reach the "device unknown → erase" path.88 const uh = response?.response?.userHandle;89 if (id && typeof uh === "string" && uh) {90 let who = ""; try { who = P.fromUtf8(P.unb64u(uh)); } catch { /* opaque handle */ }91 if (who && who !== id.accountId) throw new ApiError(400, "wrong_account", "This passkey belongs to another account than the one enrolled on this device. Nothing was changed.");92 }93 const device = id ? { deviceId: id.deviceId, proof: P.b64u(await P.sign(id.keys.sig.privateKey, P.ctx("login", options.challenge, id.deviceId))) } : undefined;94 let r;95 try { r = await this.api.request("POST", "/api/v1/auth/login/verify", { challengeId, response, device }); }96 catch (e) {97 if (e instanceof ApiError && e.code === "device_unknown") { await this.forget(); throw new ApiError(401, "device_revoked", "This device was removed from the account. Its local data was erased."); }98 throw e;99 }100 if (r.kind !== "device") { this.accountView = r.account; return "pending"; }101 if (id!.accountId !== r.account.accountId) throw new ApiError(400, "wrong_account", "This passkey belongs to another account than the one enrolled on this device");102 id!.arkEnvelope = r.arkEnvelope; await this.store.set("identity", id);103 await this.open(await P.unwrapArk(id!.keys, id!.accountId, id!.deviceId, r.arkEnvelope), r.account);104 return "unlocked";105 }106107 /** Offline unlock from the cached envelope (native-style; on the web the UI requires signIn while online). */108 async unlockOffline(): Promise<void> {109 const id = this.identity;110 if (!id?.arkEnvelope || !this.state.account) throw new Error("no cached envelope");111 await this.open(await P.unwrapArk(id.keys, id.accountId, id.deviceId, id.arkEnvelope), this.state.account);112 }113114 private async open(ark: P.Bytes, view: AccountView) {115 const account = await P.openKeyset(ark, view.accountId, view.keyset);116 // the keyset is authenticated by ARK; the public keys the server shows must be the ones inside it117 if (P.b64u(account.sig.pub) !== view.sigPub || P.b64u(account.enc.pub) !== view.encPub) throw new Error("server presented account keys that do not match the keyset");118 this.ark = ark; this.account = account; this.accountView = view; this.state.account = view;119 await this.decryptAll();120 await this.persist();121 this.onChange();122 }123124 lock() {125 this.ark?.fill(0); this.ark = undefined; this.account = undefined;126 for (const m of this.vaultKeys.values()) for (const k of m.values()) k.fill(0);127 this.vaultKeys.clear(); this.items.clear(); this.vaultMeta.clear();128 this.onChange();129 }130131 async signOut() { try { await this.api.request("POST", "/api/v1/auth/logout", {}); } catch { /* offline */ } this.lock(); }132 /** Erases everything local (revoked device, or the user removes the account from this browser). */133 async forget() { this.lock(); this.identity = undefined; this.state = empty(); this.accountView = undefined; await this.store.clear(); }134135 /** Fresh proof of presence for sensitive operations. */136 async stepUp(): Promise<void> {137 const { challengeId, options } = await this.api.request("POST", "/api/v1/auth/stepup/options", {});138 await this.api.request("POST", "/api/v1/auth/stepup/verify", { challengeId, response: await this.passkeys.get(options) });139 }140 private async strong<T>(fn: () => Promise<T>): Promise<T> {141 try { return await fn(); } catch (e) { if (!(e instanceof ApiError) || e.code !== "reauth_required") throw e; }142 await this.stepUp();143 return fn();144 }145146 // ── pairing: new device side ──────────────────────────────────────────────────────────────────────────────147 private pending?: { pairingId: string; keys: P.DeviceKeys; deviceId: string; createdAt: string };148 async startPairing(): Promise<{ code: string; sas: string; expiresInSec: number }> {149 const keys = await P.generateDeviceKeys(), deviceId = P.uuid(), createdAt = new Date().toISOString(), secret = P.random(16);150 const encPub = P.b64u(keys.enc.pub), sigPub = P.b64u(keys.sig.pub);151 const pairingId = P.uuid();152 const r = await this.api.request("POST", "/api/v1/pairings", { pairingId, deviceId, encPub, sigPub, createdAt, tag: await P.pairingTag(secret, pairingId, encPub, sigPub), platform: this.platform, hardware: false });153 this.pending = { pairingId, keys, deviceId, createdAt };154 return { code: P.encodePairingCode(pairingId, secret), sas: await P.pairingSas(pairingId, encPub, sigPub), expiresInSec: r.expiresInSec };155 }156 /** Polls once; resolves true when this device has been approved and enrolled. */157 async checkPairing(): Promise<"pending" | "rejected" | "done"> {158 const p = this.pending;159 if (!p) throw new Error("no pairing in progress");160 const r = await this.api.request("GET", `/api/v1/pairings/${p.pairingId}`);161 if (r.status === "rejected") return "rejected";162 if (r.status !== "approved") return "pending";163 const view: AccountView = r.account;164 const ark = await P.unwrapArk(p.keys, view.accountId, p.deviceId, r.arkEnvelope);165 const account = await P.openKeyset(ark, view.accountId, view.keyset);166 const dev = { deviceId: p.deviceId, encPub: P.b64u(p.keys.enc.pub), sigPub: P.b64u(p.keys.sig.pub), createdAt: p.createdAt, cert: r.cert };167 if (!(await P.verifyDeviceCert(account.sig.pub, view.accountId, dev))) throw new Error("device certificate was not signed by this account");168 await this.api.request("POST", `/api/v1/pairings/${p.pairingId}/complete`, { proof: P.b64u(await P.sign(p.keys.sig.privateKey, P.ctx("pair-complete", p.pairingId))) });169 this.identity = { accountId: view.accountId, handle: view.handle, deviceId: p.deviceId, createdAt: p.createdAt, keys: p.keys, arkEnvelope: r.arkEnvelope };170 await this.store.set("identity", this.identity);171 this.pending = undefined;172 await this.open(ark, view);173 await this.sync();174 return "done";175 }176177 // ── pairing: trusted device side ──────────────────────────────────────────────────────────────────────────178 /** Verifies the code against what the server relays. Throws if the server substituted keys. */179 async inspectPairing(code: string): Promise<{ pairingId: string; sas: string; platform: string; approve: () => Promise<void>; reject: () => Promise<void> }> {180 this.needUnlocked();181 const { pairingId, secret } = P.decodePairingCode(code);182 const r = await this.api.request("GET", `/api/v1/pairings/${pairingId}`);183 if (r.status !== "pending") throw new Error("this pairing request is no longer pending");184 if (!(await P.verifyPairingTag(secret, pairingId, r.encPub, r.sigPub, r.tag))) throw new Error("SECURITY: the keys relayed by the server do not match the code shown by the new device. Pairing refused.");185 const id = this.identity!, dev = { deviceId: r.deviceId, encPub: r.encPub, sigPub: r.sigPub, createdAt: r.createdAt };186 return {187 pairingId, sas: await P.pairingSas(pairingId, r.encPub, r.sigPub), platform: r.platform,188 approve: () => this.strong(async () => this.api.request("POST", `/api/v1/pairings/${pairingId}/approve`, {189 cert: await P.signDeviceCert(this.account!, id.accountId, dev), arkEnvelope: await P.wrapArkForDevice(this.ark!, id.accountId, r.deviceId, P.unb64u(r.encPub)) })),190 reject: () => this.api.request("POST", `/api/v1/pairings/${pairingId}/reject`, {}),191 };192 }193194 // ── recovery onto a fresh device ──────────────────────────────────────────────────────────────────────────195 async recover(handle: string, recoveryKeyText: string): Promise<void> {196 const rk = await P.decodeRecoveryKey(recoveryKeyText); // checksum verified before any network request197 const start = await this.api.request("POST", "/api/v1/recovery/start", { handle });198 const r = await this.api.request("POST", "/api/v1/recovery/verify", { accountId: start.accountId, auth: P.b64u(await P.recoveryAuth(rk, start.accountId)) });199 const view: AccountView = r.account;200 const ark = await P.openRecoveryEnvelope(rk, view.accountId, r.epoch, r.envelope);201 const account = await P.openKeyset(ark, view.accountId, view.keyset);202 const keys = await P.generateDeviceKeys(), deviceId = P.uuid(), createdAt = new Date().toISOString();203 const dev = { deviceId, encPub: P.b64u(keys.enc.pub), sigPub: P.b64u(keys.sig.pub), createdAt };204 const arkEnvelope = await P.wrapArkForDevice(ark, view.accountId, deviceId, keys.enc.pub);205 await this.api.request("POST", "/api/v1/recovery/enroll", { device: { ...dev, cert: await P.signDeviceCert(account, view.accountId, dev), arkEnvelope, platform: this.platform, hardware: false } });206 this.identity = { accountId: view.accountId, handle: view.handle, deviceId, createdAt, keys, arkEnvelope };207 await this.store.set("identity", this.identity);208 await this.open(ark, view);209 await this.sync();210 }211 /** After a recovery the old passkey may be gone: register a new one for this device. */212 async addPasskey(label?: string) {213 await this.strong(async () => {214 const { challengeId, options } = await this.api.request("POST", "/api/v1/auth/passkeys/options", {});215 await this.api.request("POST", "/api/v1/auth/passkeys/verify", { challengeId, response: await this.passkeys.create(options), label });216 });217 }218219 /**220 * Refreshes the cached recovery epoch from the server. Another device may have issued a new recovery key since this one221 * signed in; rotateRecoveryKey() and rekeyAccount() compute "epoch + 1" from the cache and would be refused (409) otherwise.222 * Only the epoch counter is adopted (it is bound into the recovery envelope's AAD, so a lying server gains nothing).223 * A changed key epoch or account key means the account was rekeyed elsewhere: this device must sign in again.224 */225 async refreshAccount(): Promise<void> {226 this.needUnlocked();227 const v: AccountView | undefined = (await this.api.request("GET", "/api/v1/auth/session")).account;228 const cur = this.accountView!;229 if (!v || v.accountId !== cur.accountId) throw new Error("the server returned another account");230 if (v.keyEpoch !== cur.keyEpoch || v.sigPub !== cur.sigPub || v.encPub !== cur.encPub) throw new Error("The account was rekeyed on another device. Lock, then unlock with your passkey before continuing.");231 if (!Number.isInteger(v.recoveryEpoch) || v.recoveryEpoch < cur.recoveryEpoch) throw new Error("SECURITY: the server presented an older recovery epoch than this device already saw (rollback).");232 if (v.recoveryEpoch !== cur.recoveryEpoch) { this.accountView = this.state.account = { ...cur, recoveryEpoch: v.recoveryEpoch }; await this.persist(); }233 }234235 /** New recovery key (shown once). The old one stops working. */236 async rotateRecoveryKey(): Promise<string> {237 this.needUnlocked();238 await this.refreshAccount();239 const id = this.identity!, rk = P.generateRecoveryKey(), epoch = this.accountView!.recoveryEpoch + 1;240 await this.strong(async () => this.api.request("POST", "/api/v1/recovery/rotate", { epoch, envelope: await P.sealRecoveryEnvelope(rk, id.accountId, epoch, this.ark!), authHash: await P.recoveryAuthHash(rk, id.accountId) }));241 this.accountView = this.state.account = { ...this.accountView!, recoveryEpoch: epoch }; await this.persist();242 return P.encodeRecoveryKey(rk);243 }244245 // ── devices ───────────────────────────────────────────────────────────────────────────────────────────────246 async devices(): Promise<DeviceView[]> {247 this.needUnlocked();248 const r = await this.api.request("GET", "/api/v1/devices");249 const out: DeviceView[] = [];250 for (const d of r.devices) {251 const h = await P.sha256(P.ctx("device-fp", d.encPub, d.sigPub));252 out.push({ deviceId: d.deviceId, platform: d.platform, hardware: d.hardware, addedAt: d.addedAt, lastSeenAt: d.lastSeenAt, current: d.deviceId === this.identity!.deviceId,253 verified: await P.verifyDeviceCert(this.account!.sig.pub, this.identity!.accountId, d), fingerprint: P.hex(h.slice(0, 4)).toUpperCase() });254 }255 return out;256 }257 async revokeDevice(deviceId: string) { await this.strong(() => this.api.request("DELETE", `/api/v1/devices/${deviceId}`)); }258259 /**260 * Account rekey after a device compromise: new ARK, new recovery key, envelopes for the remaining *verified* devices,261 * then a new key epoch for every vault this account owns. Returns the new recovery key.262 */263 async rekeyAccount(): Promise<string> {264 this.needUnlocked();265 await this.refreshAccount();266 const id = this.identity!, view = this.accountView!;267 const devices = (await this.api.request("GET", "/api/v1/devices")).devices as any[];268 for (const d of devices) if (!(await P.verifyDeviceCert(this.account!.sig.pub, id.accountId, d))) throw new Error(`device ${d.deviceId} has no valid certificate; revoke it before rekeying`);269 const ark = P.random(32), rk = P.generateRecoveryKey(), recoveryEpoch = view.recoveryEpoch + 1, keyEpoch = view.keyEpoch + 1;270 const keyset = await P.rewrapKeyset(this.ark!, ark, id.accountId, view.keyset);271 const envelopes = await Promise.all(devices.map(async (d) => ({ deviceId: d.deviceId as string, arkEnvelope: await P.wrapArkForDevice(ark, id.accountId, d.deviceId, P.unb64u(d.encPub)) })));272 await this.strong(async () => this.api.request("POST", "/api/v1/account/rekey", { keyEpoch, keyset,273 recovery: { epoch: recoveryEpoch, envelope: await P.sealRecoveryEnvelope(rk, id.accountId, recoveryEpoch, ark), authHash: await P.recoveryAuthHash(rk, id.accountId) }, devices: envelopes }));274 this.ark = ark;275 id.arkEnvelope = envelopes.find((e) => e.deviceId === id.deviceId)!.arkEnvelope; await this.store.set("identity", id);276 this.accountView = this.state.account = { ...view, keyset, recoveryEpoch, keyEpoch };277 await this.persist();278 for (const v of Object.values(this.state.vaults)) if (v.ownerId === id.accountId) await this.rotateVaultKey(v.vaultId, []);279 return P.encodeRecoveryKey(rk);280 }281282 // ── vaults ────────────────────────────────────────────────────────────────────────────────────────────────283 vaults(): VaultView[] { return [...this.vaultMeta.values()]; }284285 async createVault(meta: P.VaultMeta): Promise<string> {286 this.needUnlocked();287 const id = this.identity!, vaultId = P.uuid(), recordId = P.uuid(), vk = P.random(32);288 await this.api.request("POST", "/api/v1/vaults", { vaultId, grant: await P.grantVaultKey(this.account!, id.accountId, vk, vaultId, 1, id.accountId, this.account!.enc.pub, "owner"),289 meta: { recordId, envelope: await P.sealRecord(vk, 1, { vaultId, recordId, type: "vault-meta", rev: 1 }, meta) } });290 await this.sync();291 return vaultId;292 }293 async renameVault(vaultId: string, meta: P.VaultMeta) {294 const v = this.vaultMeta.get(vaultId)!;295 await this.write(vaultId, v.metaRecordId, "vault-meta", meta, false, []);296 }297 async deleteVault(vaultId: string) { await this.strong(() => this.api.request("DELETE", `/api/v1/vaults/${vaultId}`)); await this.sync(); }298299 async lookupAccount(handle: string): Promise<{ accountId: string; handle: string; sigPub: string; encPub: string; fingerprint: string }> {300 const a = await this.api.request("GET", `/api/v1/accounts/lookup?handle=${encodeURIComponent(handle)}`);301 return { ...a, fingerprint: await P.accountFingerprint(P.unb64u(a.sigPub), P.unb64u(a.encPub)) };302 }303 /** Shares a vault: the member receives the vault key of every epoch still in use, each wrapped for their account key. */304 async addMember(vaultId: string, member: { accountId: string; encPub: string }, role: "editor" | "reader") {305 this.needUnlocked();306 const keys = this.vaultKeys.get(vaultId)!, id = this.identity!;307 const grants = await Promise.all([...keys].map(([epoch, vk]) => P.grantVaultKey(this.account!, id.accountId, vk, vaultId, epoch, member.accountId, P.unb64u(member.encPub), role)));308 await this.strong(() => this.api.request("POST", `/api/v1/vaults/${vaultId}/members`, { grants }));309 await this.sync();310 }311 /** New vault key epoch; `remove` lists member accounts to drop. Existing records are re-encrypted right away. */312 async rotateVaultKey(vaultId: string, remove: string[]) {313 this.needUnlocked();314 const v = this.state.vaults[vaultId]!, id = this.identity!, epoch = v.epoch + 1, vk = P.random(32);315 const remaining = v.members.filter((m) => !remove.includes(m.accountId));316 for (const m of remaining) this.checkPin(m);317 const grants = await Promise.all(remaining.map((m) => P.grantVaultKey(this.account!, id.accountId, vk, vaultId, epoch, m.accountId, P.unb64u(m.encPub), m.role)));318 await this.strong(() => this.api.request("POST", `/api/v1/vaults/${vaultId}/rotate`, { epoch, grants, remove }));319 await this.sync();320 await this.reencryptVault(vaultId);321 }322 /** Re-seals every record of a vault under the current epoch (after rotation). */323 async reencryptVault(vaultId: string) {324 const v = this.state.vaults[vaultId]!;325 for (const r of Object.values(v.records)) {326 if (r.envelope.kid === v.epoch) continue;327 const value = await P.openRecord((k) => this.vaultKeys.get(vaultId)?.get(k), { vaultId, recordId: r.id, type: r.type, rev: r.rev }, r.envelope);328 await this.write(vaultId, r.id, r.type, value, r.deleted, r.attachments ?? []);329 }330 }331332 // ── items ─────────────────────────────────────────────────────────────────────────────────────────────────333 list(): ItemView[] { return [...this.items.values()]; }334 get(vaultId: string, id: string): ItemView | undefined { return this.items.get(`${vaultId}/${id}`); }335 search(query: string): ItemView[] { return this.list().filter((v) => !v.item.trashedAt && P.matchesQuery(P.searchText(v.item), query)); }336337 async saveItem(vaultId: string, id: string | null, item: P.Item): Promise<string> {338 this.needUnlocked();339 const recordId = id ?? P.uuid(), prev = id ? this.get(vaultId, id)?.item : undefined;340 const next = prev ? P.applyEdit(prev, item) : { ...item, updatedAt: new Date().toISOString() };341 await this.write(vaultId, recordId, "item", next, false, next.attachments.map((a) => a.id));342 return recordId;343 }344 async trashItem(vaultId: string, id: string) { const it = this.get(vaultId, id)!; await this.saveItem(vaultId, id, { ...it.item, trashedAt: new Date().toISOString() }); }345 async restoreItem(vaultId: string, id: string) { const it = this.get(vaultId, id)!; await this.saveItem(vaultId, id, { ...it.item, trashedAt: undefined }); }346 /** Permanent deletion: an authenticated tombstone replaces the content. */347 async deleteItem(vaultId: string, id: string) { await this.write(vaultId, id, "item", { deleted: true }, true, []); }348 async moveItem(fromVault: string, id: string, toVault: string): Promise<string> {349 const it = this.get(fromVault, id)!;350 if (it.item.attachments.length) throw new Error("items with attachments cannot be moved between vaults yet; download and re-attach");351 const newId = await this.saveItem(toVault, null, it.item);352 await this.deleteItem(fromVault, id);353 return newId;354 }355356 async history(vaultId: string, id: string): Promise<{ rev: number; at: string; item: P.Item }[]> {357 const r = await this.api.request("GET", `/api/v1/vaults/${vaultId}/records/${id}/history`);358 const out = [];359 for (const h of r.history) {360 try { out.push({ rev: h.rev, at: h.at, item: P.normalizeItem(await P.openRecord((k) => this.vaultKeys.get(vaultId)?.get(k), { vaultId, recordId: id, type: "item", rev: h.rev }, h.envelope)) }); } catch { /* skipped */ }361 }362 return out.filter((h) => !h.item.deleted);363 }364365 /** Local write + outbox entry; the network push happens in sync() and survives being offline. */366 private async write(vaultId: string, recordId: string, type: P.RecordType, value: unknown, deleted: boolean, attachments: string[]) {367 await this.enqueue(vaultId, recordId, type, value, deleted, attachments);368 await this.sync().catch(() => {});369 }370 private async enqueue(vaultId: string, recordId: string, type: P.RecordType, value: unknown, deleted: boolean, attachments: string[]) {371 this.needUnlocked();372 const v = this.state.vaults[vaultId];373 if (!v) throw new Error("unknown vault");374 if (v.role === "reader") throw new Error("this vault is read-only for you");375 const queued = this.state.outbox.filter((o) => o.vaultId === vaultId && o.recordId === recordId);376 const baseRev = queued.length ? queued[0]!.baseRev : v.records[recordId]?.rev ?? 0;377 const vk = this.vaultKeys.get(vaultId)!.get(v.epoch)!;378 const envelope = await P.sealRecord(vk, v.epoch, { vaultId, recordId, type, rev: baseRev + 1 }, value);379 // a newer local edit of the same record replaces the queued one (same base revision)380 this.state.outbox = this.state.outbox.filter((o) => !(o.vaultId === vaultId && o.recordId === recordId));381 this.state.outbox.push({ key: P.b64u(P.random(18)), vaultId, recordId, type, baseRev, envelope, deleted, attachments });382 this.applyLocal(vaultId, recordId, type, value, baseRev + 1, deleted, true);383 await this.persist();384 this.onChange();385 }386387 private applyLocal(vaultId: string, id: string, type: P.RecordType, value: any, rev: number, deleted: boolean, pending: boolean, updatedAt?: string) {388 const key = `${vaultId}/${id}`;389 if (type === "item") {390 if (deleted || value?.deleted === true) this.items.delete(key);391 else this.items.set(key, { vaultId, id, rev, item: P.normalizeItem(value), pending, updatedAt });392 } else if (type === "vault-meta" && !deleted) {393 const v = this.state.vaults[vaultId]!;394 this.vaultMeta.set(vaultId, { vaultId, meta: { name: String(value?.name ?? "Vault").slice(0, 80), kind: value?.kind ?? "personal", icon: value?.icon, retentionDays: value?.retentionDays }, role: v.role, ownerId: v.ownerId, epoch: v.epoch, members: v.members, metaRecordId: id });395 }396 }397398 // ── sync ──────────────────────────────────────────────────────────────────────────────────────────────────399 syncHealth(): SyncHealth { return { ...this.health, pending: this.state.outbox.length, lastSyncAt: this.state.lastSyncAt }; }400401 sync(): Promise<void> {402 this.needUnlocked();403 return (this.syncing ??= this.doSync().finally(() => { this.syncing = undefined; this.onChange(); }));404 }405406 private async doSync() {407 try {408 await this.pull();409 await this.push();410 this.health.online = true;411 this.state.lastSyncAt = new Date().toISOString();412 await this.persist();413 } catch (e) {414 if (e instanceof ApiError && e.status > 0 && e.status !== 502 && e.status !== 503) throw e;415 this.health.online = false; // offline: the outbox keeps the writes416 }417 }418419 private warn(msg: string) { if (!this.health.warnings.includes(msg)) this.health.warnings.push(msg); }420 private checkPin(m: Member) {421 const fp = `${m.sigPub}.${m.encPub}`, pinned = this.state.pins[m.accountId];422 if (pinned && pinned !== fp) throw new Error(`SECURITY: the public keys of ${m.handle} changed since first seen. Refusing to use them.`);423 this.state.pins[m.accountId] = fp;424 }425426 private async pull() {427 const me = this.identity!.accountId;428 for (let more = true; more;) {429 const cursors = Object.fromEntries(Object.values(this.state.vaults).map((v) => [v.vaultId, v.cursor]));430 const r = await this.api.request("POST", "/api/v1/sync", { cursors });431 more = false;432 const seen = new Set<string>();433 for (const sv of r.vaults) {434 seen.add(sv.vaultId);435 const v = (this.state.vaults[sv.vaultId] ??= { vaultId: sv.vaultId, epoch: sv.epoch, role: sv.role, ownerId: sv.ownerId, cursor: 0, grants: [], members: [], records: {} });436 if (sv.seq < v.cursor) { this.warn("The server presented an older state of a vault than this device already saw (rollback). Nothing was overwritten."); continue; }437 if (sv.epoch < v.epoch) { this.warn("The server presented an older vault key epoch (rollback)."); continue; }438 v.epoch = sv.epoch; v.role = sv.role; v.ownerId = sv.ownerId; v.members = sv.members; v.grants = sv.grants;439 try { await this.loadVaultKeys(v); } catch (e: any) { this.warn(`Vault keys rejected: ${e.message}`); continue; }440 for (const c of sv.changes as StoredRecord[]) {441 const k = `${v.vaultId}/${c.id}`, known = this.state.maxRev[k] ?? 0;442 if (c.rev < known) { this.warn("The server presented an older revision of a record (rollback). The newer local copy was kept."); continue; }443 try {444 const value = await P.openRecord((kid) => this.vaultKeys.get(v.vaultId)?.get(kid), { vaultId: v.vaultId, recordId: c.id, type: c.type, rev: c.rev }, c.envelope);445 if (c.deleted !== ((value as any)?.deleted === true)) throw new Error("deletion flag does not match the authenticated content");446 v.records[c.id] = c; this.state.maxRev[k] = c.rev;447 if (!this.state.outbox.some((o) => o.vaultId === v.vaultId && o.recordId === c.id)) this.applyLocal(v.vaultId, c.id, c.type, value, c.rev, c.deleted, false, c.updatedAt);448 } catch { this.health.undecryptable++; this.warn("A record failed authentication and was ignored (corrupted or forged)."); }449 v.cursor = Math.max(v.cursor, c.seq);450 }451 if (sv.more) more = true; else v.cursor = Math.max(v.cursor, sv.seq);452 const vm = this.vaultMeta.get(v.vaultId);453 if (vm) Object.assign(vm, { role: v.role, epoch: v.epoch, members: v.members, ownerId: v.ownerId });454 }455 for (const id of Object.keys(this.state.vaults)) if (!seen.has(id)) this.dropVault(id); // access removed or vault deleted456 }457 void me;458 }459460 private dropVault(vaultId: string) {461 delete this.state.vaults[vaultId]; this.vaultKeys.delete(vaultId); this.vaultMeta.delete(vaultId);462 for (const k of [...this.items.keys()]) if (k.startsWith(vaultId + "/")) this.items.delete(k);463 this.state.outbox = this.state.outbox.filter((o) => o.vaultId !== vaultId);464 }465466 private async loadVaultKeys(v: StoredVault) {467 const me = this.identity!.accountId, keys = this.vaultKeys.get(v.vaultId) ?? new Map<number, P.Bytes>();468 for (const g of v.grants) {469 if (keys.has(g.epoch)) continue;470 // grants are accepted only when signed by the vault owner; a foreign owner's key is pinned on first use471 if (g.granterAccountId !== v.ownerId) throw new Error("grant not issued by the vault owner");472 let granterSig: P.Bytes;473 if (v.ownerId === me) granterSig = this.account!.sig.pub;474 else { const owner = v.members.find((m) => m.accountId === v.ownerId); if (!owner) throw new Error("owner missing from member list"); this.checkPin(owner); granterSig = P.unb64u(owner.sigPub); }475 keys.set(g.epoch, await P.acceptVaultGrant(this.account!, g, granterSig));476 }477 if (!keys.has(v.epoch)) throw new Error("no key for the current epoch");478 this.vaultKeys.set(v.vaultId, keys);479 }480481 private async push() {482 while (this.state.outbox.length) {483 const o = this.state.outbox[0]!;484 const v = this.state.vaults[o.vaultId];485 if (!v) { this.state.outbox.shift(); continue; }486 try {487 const r = await this.api.request("PUT", `/api/v1/vaults/${o.vaultId}/records/${o.recordId}`, { type: o.type, baseRev: o.baseRev, envelope: o.envelope, deleted: o.deleted, attachments: o.attachments }, { headers: { "idempotency-key": o.key } });488 v.records[o.recordId] = { id: o.recordId, type: o.type, rev: r.rev, envelope: o.envelope, deleted: o.deleted, seq: r.seq, attachments: o.attachments };489 this.state.maxRev[`${o.vaultId}/${o.recordId}`] = r.rev;490 const it = this.items.get(`${o.vaultId}/${o.recordId}`); if (it) { it.pending = false; it.rev = r.rev; }491 this.state.outbox.shift();492 } catch (e) {493 if (!(e instanceof ApiError) || ![400, 403, 404, 409, 413].includes(e.status)) throw e; // offline, 401, 429, 5xx: keep queued494 // On a conflict the entry leaves the outbox only once the server's state was pulled: if that pull fails495 // (network drop) the edit stays queued instead of vanishing.496 if (e.status === 409) await this.resolveConflict(o, e.body);497 else {498 this.state.outbox.shift();499 // refused for good (permission, quota, validation): never retried forever, never silently kept500 this.warn(`A change was refused by the server (${e.code}) and was not saved.`);501 await this.decryptAll();502 }503 }504 await this.persist();505 }506 }507508 /**509 * Deterministic conflict rule: the server's version stays the record; this device's version is never dropped —510 * it is saved as a separate "conflict copy" item for the user to review (identical content is simply discarded).511 */512 private async resolveConflict(o: OutboxEntry, body: any) {513 const keyFor = (k: number) => this.vaultKeys.get(o.vaultId)?.get(k);514 const mine: any = await P.openRecord(keyFor, { vaultId: o.vaultId, recordId: o.recordId, type: o.type, rev: o.baseRev + 1 }, o.envelope);515 await this.pull();516 this.state.outbox = this.state.outbox.filter((x) => x.key !== o.key);517 const v = this.state.vaults[o.vaultId];518 if (!v) return;519 const cur = v.records[o.recordId];520 if (body?.error === "stale_key" || !cur) { await this.enqueue(o.vaultId, o.recordId, o.type, mine, o.deleted, o.attachments); return; } // re-seal under the new epoch / recreate521 const theirs: any = await P.openRecord(keyFor, { vaultId: o.vaultId, recordId: o.recordId, type: cur.type, rev: cur.rev }, cur.envelope);522 this.applyLocal(o.vaultId, o.recordId, cur.type, theirs, cur.rev, cur.deleted, false);523 if (o.type !== "item") return; // vault metadata: server wins524 const strip = (x: any) => JSON.stringify({ ...x, updatedAt: undefined, passwordHistory: undefined });525 if (o.deleted || strip(mine) === strip(theirs)) return; // my deletion lost to their edit (their version is kept), or no real difference526 const copy = P.normalizeItem({ ...mine, title: `${mine.title || "Untitled"} (conflict copy)`, conflictOf: o.recordId, attachments: cur.deleted ? [] : mine.attachments });527 await this.enqueue(o.vaultId, P.uuid(), "item", copy, false, copy.attachments.map((a) => a.id));528 }529530 private async decryptAll() {531 this.items.clear(); this.vaultMeta.clear(); this.vaultKeys.clear();532 for (const v of Object.values(this.state.vaults)) {533 try { await this.loadVaultKeys(v); } catch { continue; }534 for (const r of Object.values(v.records)) {535 try { this.applyLocal(v.vaultId, r.id, r.type, await P.openRecord((k) => this.vaultKeys.get(v.vaultId)?.get(k), { vaultId: v.vaultId, recordId: r.id, type: r.type, rev: r.rev }, r.envelope), r.rev, r.deleted, false, r.updatedAt); } catch { /* reported on next sync */ }536 }537 for (const o of this.state.outbox.filter((x) => x.vaultId === v.vaultId)) {538 try { this.applyLocal(v.vaultId, o.recordId, o.type, await P.openRecord((k) => this.vaultKeys.get(v.vaultId)?.get(k), { vaultId: v.vaultId, recordId: o.recordId, type: o.type, rev: o.baseRev + 1 }, o.envelope), o.baseRev + 1, o.deleted, true); } catch { /* ignore */ }539 }540 }541 }542543 /** Digest of everything this device holds; two devices in the same state show the same value. */544 async stateDigest(): Promise<string> {545 const lines = Object.values(this.state.vaults).flatMap((v) => Object.values(v.records).map((r) => `${v.vaultId}/${r.id}:${r.rev}:${r.envelope.ct.slice(0, 22)}`)).sort();546 return P.hex((await P.sha256(P.utf8(lines.join("\n")))).slice(0, 6)).toUpperCase().match(/.{4}/g)!.join(" ");547 }548549 // ── attachments ───────────────────────────────────────────────────────────────────────────────────────────550 async upload(vaultId: string, name: string, mime: string, data: P.Bytes, onProgress?: (done: number, total: number) => void): Promise<P.AttachmentRef> {551 this.needUnlocked();552 const id = P.uuid(), { ref, chunks } = await P.newAttachment(id, name, mime, data);553 const { uploaded } = await this.api.request("POST", `/api/v1/vaults/${vaultId}/attachments`, { id, chunks: ref.chunks, size: ref.size });554 for (let i = 0; i < chunks.length; i++) {555 if (!(uploaded as number[]).includes(i)) await this.api.request("PUT", `/api/v1/attachments/${id}/chunks/${i}`, undefined, { binary: chunks[i] });556 onProgress?.(i + 1, chunks.length);557 }558 await this.api.request("POST", `/api/v1/attachments/${id}/complete`, {});559 return ref;560 }561 async download(ref: P.AttachmentRef): Promise<P.Bytes> {562 const chunks: P.Bytes[] = [];563 for (let i = 0; i < ref.chunks; i++) chunks.push(await this.api.request("GET", `/api/v1/attachments/${ref.id}/chunks/${i}`, undefined, { raw: true }));564 return P.openAttachment(ref, chunks);565 }566567 // ── SP Vault Relay ────────────────────────────────────────────────────────────────────────────────────────568 async shareWithAccount(item: P.Item, recipient: { accountId: string; encPub: string }, expiresInSec: number, maxViews?: number): Promise<string> {569 this.needUnlocked();570 const id = P.uuid(), payload = { ...item, attachments: [], passwordHistory: [] };571 const box = await P.sealRelay(this.account!, id, this.identity!.accountId, recipient.accountId, P.unb64u(recipient.encPub), payload);572 await this.strong(() => this.api.request("POST", "/api/v1/shares", { id, kind: "account", recipientAccountId: recipient.accountId, box: box.ct, sig: box.sig, expiresInSec, maxViews }));573 return id;574 }575 /** Returns the URL; the part after # never reaches the server. */576 async shareByLink(item: P.Item, origin: string, expiresInSec: number, maxViews = 1): Promise<string> {577 this.needUnlocked();578 const id = P.uuid(), secret = P.random(32), k = await P.linkKeys(secret, id);579 const box = await P.sealLink(secret, id, { ...item, attachments: [], passwordHistory: [] });580 await this.strong(() => this.api.request("POST", "/api/v1/shares", { id, kind: "link", box, authHash: k.authHash, expiresInSec, maxViews }));581 return `${origin}/#/s/${id}/${P.b64u(secret)}`;582 }583 shares(): Promise<{ sent: any[]; received: any[] }> { return this.api.request("GET", "/api/v1/shares"); }584 async openShare(id: string): Promise<{ item: P.Item; from: string; fingerprintKnown: boolean }> {585 this.needUnlocked();586 const r = await this.api.request("POST", `/api/v1/shares/${id}/open`, {});587 const fp = r.senderSigPub, pinned = this.state.pins[`sig:${r.senderId}`];588 if (pinned && pinned !== fp) throw new Error(`SECURITY: the signing key of ${r.senderHandle} changed since first seen.`);589 this.state.pins[`sig:${r.senderId}`] = fp; await this.persist();590 const item = await P.openRelay<P.Item>(this.account!, id, r.senderId, this.identity!.accountId, P.unb64u(r.senderSigPub), r.box);591 return { item: P.normalizeItem(item), from: r.senderHandle, fingerprintKnown: !!pinned };592 }593 revokeShare(id: string) { return this.api.request("DELETE", `/api/v1/shares/${id}`); }594595 // ── backup / export ───────────────────────────────────────────────────────────────────────────────────────596 private payload(): P.BackupPayload {597 return { vaults: this.vaults().map((v) => ({ id: v.vaultId, meta: v.meta, items: this.list().filter((i) => i.vaultId === v.vaultId).map((i) => ({ id: i.id, item: i.item })) })) };598 }599 /** Encrypted, self-contained backup (restorable with the recovery key, without the server). Attachments are not included. */600 async exportBackup(): Promise<string> {601 this.needUnlocked();602 const rec = await this.strong(() => this.api.request("GET", "/api/v1/recovery"));603 await this.api.request("POST", "/api/v1/audit/client", { kind: "export.backup" });604 return JSON.stringify(await P.createBackup(this.ark!, this.identity!.accountId, rec, this.accountView!.keyset, this.payload()));605 }606 /** Plaintext export: only after a fresh authentication. */607 async exportPlaintext(format: "csv" | "json"): Promise<string> {608 this.needUnlocked();609 await this.stepUp();610 await this.api.request("POST", "/api/v1/audit/client", { kind: "export.plaintext" }); // requires the fresh step-up; leaves a trace on every device611 return format === "csv" ? P.exportCsv(this.list().filter((i) => !i.item.trashedAt).map((i) => i.item)) : JSON.stringify(this.payload(), null, 1);612 }613 /** Restores items from a backup into a new vault of this account. */614 async restoreBackup(text: string, recoveryKeyText?: string): Promise<number> {615 this.needUnlocked();616 const f = P.parseBackup(text);617 let payload: P.BackupPayload;618 try { ({ payload } = await P.openBackup(f, { ark: this.ark! })); }619 catch { if (!recoveryKeyText) throw new Error("this backup was made under another account key; enter the recovery key that was valid when it was created"); ({ payload } = await P.openBackup(f, { recoveryKey: await P.decodeRecoveryKey(recoveryKeyText) })); }620 let n = 0;621 for (const v of payload.vaults) {622 const vaultId = await this.createVault({ ...v.meta, name: `${v.meta.name} (restored ${f.createdAt.slice(0, 10)})` });623 for (const it of v.items) { await this.saveItem(vaultId, null, { ...it.item, attachments: [] }); n++; }624 }625 return n;626 }627628 async importItems(vaultId: string, items: P.Item[]): Promise<number> {629 for (const it of items) await this.saveItem(vaultId, null, it);630 await this.strong(() => this.api.request("POST", "/api/v1/audit/client", { kind: "import" })).catch(() => {});631 return items.length;632 }633634 async audit(before?: number): Promise<any[]> { return (await this.api.request("GET", `/api/v1/audit${before ? `?before=${before}` : ""}`)).events; }635 /** Recomputes the hash chain over a contiguous page of events (newest first, as returned). False = the log was altered. */636 async verifyAuditPage(events: any[]): Promise<boolean> {637 for (let i = 0; i < events.length; i++) {638 const e = events[i];639 if (P.b64u(await P.sha256(P.utf8(P.auditEntryInput(e.prevHash, this.identity!.accountId, new Date(e.at).toISOString(), e.deviceId, e.actor, e.kind, e.detail)))) !== e.hash) return false;640 if (i + 1 < events.length && events[i + 1].hash !== e.prevHash) return false;641 }642 return true;643 }644 async breachCheck(password: string): Promise<number> {645 const { prefix, suffix } = await P.breachPrefix(password);646 return P.breachCount(await this.api.request("GET", `/api/v1/breach/range/${prefix}`, undefined, { raw: true }).then((b: any) => (typeof b === "string" ? b : new TextDecoder().decode(b))), suffix);647 }648649 // ── SP Vault Connect / Agents (managed secrets: NOT zero-knowledge, see services/managed-secrets/THREAT_MODEL.md) ──650 connect(): Promise<any> { return this.api.request("GET", "/api/v1/connect"); }651 /** Creates a workload identity. The private key is returned once, for the workload; the server keeps the public key only. */652 async createIdentity(name: string, kind: "service" | "agent"): Promise<{ id: string; privateKey: string }> {653 const id = P.uuid(), kp = await P.generateSigKey(true);654 await this.strong(() => this.api.request("POST", "/api/v1/connect/identities", { id, name, kind, pub: P.b64u(kp.pub) }));655 return { id, privateKey: P.b64u(await P.exportPrivateX963(kp.privateKey)) };656 }657 revokeIdentity(id: string) { return this.api.request("DELETE", `/api/v1/connect/identities/${id}`); }658 async createManagedSecret(s: { name: string; kind: string; config: object; value: string; rotateEveryDays?: number; expiresAt?: string }): Promise<string> {659 const id = P.uuid();660 await this.strong(() => this.api.request("POST", "/api/v1/connect/secrets", { id, ...s }));661 return id;662 }663 rotateManagedSecret(id: string, value: string) { return this.strong(() => this.api.request("PUT", `/api/v1/connect/secrets/${id}/value`, { value })); }664 deleteManagedSecret(id: string) { return this.strong(() => this.api.request("DELETE", `/api/v1/connect/secrets/${id}`)); }665 async createGrant(g: { identityId: string; secretId: string; mode: "operate" | "read"; approval: "never" | "lease" | "each"; expiresInSec: number; leaseTtlSec?: number; maxUses?: number; constraints?: object }): Promise<string> {666 const id = P.uuid();667 await this.strong(() => this.api.request("POST", "/api/v1/connect/grants", { id, ...g }));668 return id;669 }670 revokeGrant(id: string) { return this.api.request("DELETE", `/api/v1/connect/grants/${id}`); }671 decideApproval(id: string, approve: boolean) { return this.strong(() => this.api.request("POST", `/api/v1/connect/approvals/${id}`, { approve })); }672 setKillSwitch(engaged: boolean) { return this.strong(() => this.api.request("POST", "/api/v1/connect/kill", { engaged })); }673674 private needUnlocked() { if (!this.ark || !this.identity) throw new Error("vault is locked"); }675}676