SPB Git

Repository Public

engine.ts 48.3 KB 676 lines typescript

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
Files main
Menu

Theme