SPB Git

Repository Public

sync.ts 12.9 KB 201 lines typescript

1// SP Sync: an end-to-end encrypted change feed.2// The server stores opaque AEAD ciphertext per (collection, record id) and a per-user sequence number.3// It never receives the account key: devices exchange it sealed to each other's public key (envelopes),4// or recover it from a blob sealed under the user's recovery key. What the server can see is documented in5// docs/SECURITY.md: collection names, opaque record ids, sizes, timestamps and which device wrote.6import type { FastifyInstance } from "fastify";7import { requireSession, setRecovery, type Deps } from "./auth.ts";8import { transaction } from "./db.ts";9import { HttpError, now, safeEqual, sha256 } from "./util.ts";1011// "canvas" and "handoff" were added for SP Browser 3.0 (AURA Canvas boards the user opted in, Portal hand-offs).12// Clients that predate them never push them and ignore them when pulled.13export const COLLECTIONS = ["history", "bookmarks", "favorites", "tabs", "closed", "reading", "searches", "prefs", "canvas", "handoff"];14const ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;15const B64 = /^[A-Za-z0-9+/_-]*={0,2}$/;16const MAX_PAYLOAD = 350_000;17const MAX_CHANGES = 500;18const MAX_RECORDS_PER_USER = 250_000;1920export function registerSyncRoutes(app: FastifyInstance, deps: Deps): void {21  const { db, log } = deps;2223  function keyRow(userId: string) {24    return db.prepare("SELECT key_version, key_check, recovery_blob FROM account_keys WHERE user_id = ?").get(userId) as any;25  }2627  /** A device proves it holds the account key by presenting a value derived from it; the server only keeps its hash. */28  function requireKeyHolder(userId: string, proof: unknown): void {29    const row = keyRow(userId);30    if (!row) throw new HttpError(409, "sync_not_initialized", "Sync is not set up for this account");31    if (typeof proof !== "string" || !safeEqual(sha256(proof), row.key_check)) throw new HttpError(403, "key_proof_invalid", "This device does not hold the account key");32  }3334  function blob(value: unknown, name: string, max = 4000): string {35    if (typeof value !== "string" || !value || value.length > max || !B64.test(value)) throw new HttpError(400, "invalid_" + name, name + " missing or malformed");36    return value;37  }3839  // ---- Key material ----40  app.get("/api/sync/keys", async (request) => {41    const session = requireSession(deps, request);42    const row = keyRow(session.userId);43    const device = db.prepare("SELECT key_envelope, key_envelope_from FROM devices WHERE id = ?").get(session.deviceId) as any;44    let envelope = null;45    if (device?.key_envelope && device.key_envelope !== "holder") {46      const from = db.prepare("SELECT name, enc_public_key FROM devices WHERE id = ?").get(device.key_envelope_from) as any;47      envelope = { sealed: device.key_envelope, fromDeviceId: device.key_envelope_from, fromDeviceName: from?.name ?? "", fromPublicKey: from?.enc_public_key ?? "" };48    }49    return { initialized: !!row, keyVersion: row?.key_version ?? null, keyCheck: row?.key_check ?? null, isHolder: !!device?.key_envelope, envelope };50  });5152  /** First device: creates the account key locally and uploads only its verifier and the recovery-sealed copy. */53  app.post("/api/sync/keys/bootstrap", async (request) => {54    const session = requireSession(deps, request);55    const body = request.body as any;56    const proof = blob(body?.keyProof, "keyProof", 200);57    const recoveryBlob = blob(body?.recoveryBlob, "recoveryBlob");58    transaction(db, () => {59      if (keyRow(session.userId)) throw new HttpError(409, "sync_already_initialized", "Sync is already set up; approve this device from another one or use the recovery key");60      db.prepare("INSERT INTO account_keys(user_id, key_version, key_check, recovery_blob, created_at, updated_at) VALUES(?,?,?,?,?,?)")61        .run(session.userId, 1, sha256(proof), recoveryBlob, now(), now());62      setRecovery(db, session.userId, body?.recoveryAuth);63      db.prepare("UPDATE devices SET key_envelope = 'holder', key_envelope_from = id WHERE id = ?").run(session.deviceId);64    });65    log.add("info", "sync", "account key initialized");66    return { ok: true, keyVersion: 1, keyCheck: sha256(proof) };67  });6869  app.get("/api/sync/keys/recovery", async (request) => {70    const session = requireSession(deps, request);71    const row = keyRow(session.userId);72    if (!row) throw new HttpError(409, "sync_not_initialized", "Sync is not set up for this account");73    return { recoveryBlob: row.recovery_blob, keyCheck: row.key_check, keyVersion: row.key_version };74  });7576  /** A device that unwrapped the key itself (recovery key) declares itself a holder by proving it. */77  app.post("/api/sync/keys/claim", async (request) => {78    const session = requireSession(deps, request);79    requireKeyHolder(session.userId, (request.body as any)?.keyProof);80    db.prepare("UPDATE devices SET key_envelope = COALESCE(key_envelope, 'holder'), key_envelope_from = COALESCE(key_envelope_from, id) WHERE id = ?").run(session.deviceId);81    return { ok: true };82  });8384  /** Replaces the recovery key (new sealed copy + new recovery authenticator). Only a key holder can. */85  app.put("/api/sync/keys/recovery", async (request) => {86    const session = requireSession(deps, request);87    const body = request.body as any;88    requireKeyHolder(session.userId, body?.keyProof);89    const recoveryBlob = blob(body?.recoveryBlob, "recoveryBlob");90    transaction(db, () => {91      db.prepare("UPDATE account_keys SET recovery_blob = ?, updated_at = ? WHERE user_id = ?").run(recoveryBlob, now(), session.userId);92      setRecovery(db, session.userId, body?.recoveryAuth);93    });94    log.add("info", "sync", "recovery key replaced");95    return { ok: true };96  });9798  /** Devices signed in to the account that are still waiting for the account key. */99  app.get("/api/sync/keys/pending", async (request) => {100    const session = requireSession(deps, request);101    const rows = db.prepare(`102      SELECT id, name, platform, model, enc_public_key, created_at FROM devices103      WHERE user_id = ? AND revoked_at IS NULL AND key_envelope IS NULL AND id != ? ORDER BY created_at DESC`).all(session.userId, session.deviceId) as any[];104    return { devices: rows.map((d) => ({ id: d.id, name: d.name, platform: d.platform, model: d.model, encPublicKey: d.enc_public_key, createdAt: d.created_at })) };105  });106107  /** A trusted device hands the account key to a waiting one, sealed to that device's public key. */108  app.post("/api/sync/keys/approve", async (request) => {109    const session = requireSession(deps, request);110    const body = request.body as any;111    requireKeyHolder(session.userId, body?.keyProof);112    const sealed = blob(body?.envelope, "envelope");113    const target = db.prepare("SELECT id, enc_public_key FROM devices WHERE id = ? AND user_id = ? AND revoked_at IS NULL").get(body?.deviceId, session.userId) as any;114    if (!target) throw new HttpError(404, "not_found", "Device not found");115    // The approver sealed to the key it displayed; refuse if the stored key changed in between.116    if (body?.encPublicKey !== target.enc_public_key) throw new HttpError(409, "device_key_changed", "The device key changed; review the request again");117    db.prepare("UPDATE devices SET key_envelope = ?, key_envelope_from = ? WHERE id = ?").run(sealed, session.deviceId, target.id);118    log.add("info", "sync", "device approved for sync");119    return { ok: true };120  });121122  // ---- Change feed ----123  app.post("/api/sync/push", { bodyLimit: 24 * 1024 * 1024 }, async (request) => {124    const session = requireSession(deps, request);125    const row = keyRow(session.userId);126    if (!row) throw new HttpError(409, "sync_not_initialized", "Sync is not set up for this account");127    const changes = (request.body as any)?.changes;128    if (!Array.isArray(changes) || changes.length > MAX_CHANGES) throw new HttpError(400, "invalid_changes", `changes must be an array of at most ${MAX_CHANGES} items`);129    for (const c of changes) {130      if (!COLLECTIONS.includes(c?.collection)) throw new HttpError(400, "invalid_collection", "unknown collection");131      if (typeof c.id !== "string" || !ID_PATTERN.test(c.id)) throw new HttpError(400, "invalid_id", "invalid record id");132      if (!Number.isInteger(c.baseSeq) || c.baseSeq < 0) throw new HttpError(400, "invalid_base", "baseSeq must be a non-negative integer");133      if (c.deleted !== true) {134        if (typeof c.payload !== "string" || !c.payload || c.payload.length > MAX_PAYLOAD || !B64.test(c.payload)) throw new HttpError(400, "invalid_payload", "payload missing, malformed or too large");135        if (c.keyVersion !== row.key_version) throw new HttpError(409, "key_version_mismatch", "This device uses an outdated account key");136      }137    }138    const applied: any[] = [], conflicts: any[] = [];139    const latest = transaction(db, () => {140      const total = (db.prepare("SELECT COUNT(*) AS n FROM sync_records WHERE user_id = ?").get(session.userId) as any).n;141      if (total + changes.length > MAX_RECORDS_PER_USER) throw new HttpError(413, "quota_exceeded", "The account holds too many synchronized records");142      const select = db.prepare("SELECT seq, deleted, payload, key_version FROM sync_records WHERE user_id = ? AND collection = ? AND id = ?");143      const bump = db.prepare("UPDATE users SET seq = seq + 1 WHERE id = ? RETURNING seq");144      const upsert = db.prepare(`145        INSERT INTO sync_records(user_id, collection, id, seq, deleted, payload, key_version, device_id, updated_at) VALUES(?,?,?,?,?,?,?,?,?)146        ON CONFLICT(user_id, collection, id) DO UPDATE SET seq = excluded.seq, deleted = excluded.deleted, payload = excluded.payload,147          key_version = excluded.key_version, device_id = excluded.device_id, updated_at = excluded.updated_at`);148      for (const c of changes) {149        const current = select.get(session.userId, c.collection, c.id) as any;150        // Optimistic concurrency: the writer must have seen the latest version of the record.151        if (current && current.seq !== c.baseSeq) {152          conflicts.push({ collection: c.collection, id: c.id, seq: current.seq, deleted: !!current.deleted, payload: current.payload, keyVersion: current.key_version });153          continue;154        }155        if (!current && c.deleted === true) { applied.push({ collection: c.collection, id: c.id, seq: 0 }); continue; }156        const seq = (bump.get(session.userId) as any).seq as number;157        upsert.run(session.userId, c.collection, c.id, seq, c.deleted === true ? 1 : 0, c.deleted === true ? "" : c.payload, row.key_version, session.deviceId, now());158        applied.push({ collection: c.collection, id: c.id, seq });159      }160      db.prepare("UPDATE devices SET last_sync_at = ? WHERE id = ?").run(now(), session.deviceId);161      return (db.prepare("SELECT seq FROM users WHERE id = ?").get(session.userId) as any).seq as number;162    });163    return { applied, conflicts, latest };164  });165166  app.get("/api/sync/pull", async (request) => {167    const session = requireSession(deps, request);168    const row = keyRow(session.userId);169    if (!row) throw new HttpError(409, "sync_not_initialized", "Sync is not set up for this account");170    const query = request.query as any;171    const since = Number(query.since ?? 0);172    const limit = Math.min(Math.max(Number(query.limit ?? 500) || 500, 1), 1000);173    if (!Number.isInteger(since) || since < 0) throw new HttpError(400, "invalid_since", "since must be a non-negative integer");174    const rows = db.prepare(`175      SELECT collection, id, seq, deleted, payload, key_version, device_id, updated_at FROM sync_records176      WHERE user_id = ? AND seq > ? ORDER BY seq ASC LIMIT ?`).all(session.userId, since, limit + 1) as any[];177    const more = rows.length > limit;178    const page = rows.slice(0, limit);179    const latest = (db.prepare("SELECT seq FROM users WHERE id = ?").get(session.userId) as any).seq as number;180    db.prepare("UPDATE devices SET last_sync_at = ? WHERE id = ?").run(now(), session.deviceId);181    return {182      changes: page.map((r) => ({ collection: r.collection, id: r.id, seq: r.seq, deleted: !!r.deleted, payload: r.payload, keyVersion: r.key_version, deviceId: r.device_id, updatedAt: r.updated_at })),183      next: page.length ? page[page.length - 1].seq : since, latest, more, keyVersion: row.key_version,184    };185  });186187  /** Erases every synchronized record and the key material, keeping the account and its passkeys. */188  app.delete("/api/sync/data", async (request) => {189    const session = requireSession(deps, request);190    requireKeyHolder(session.userId, (request.headers["x-sp-key-proof"] as string) ?? "");191    transaction(db, () => {192      db.prepare("DELETE FROM sync_records WHERE user_id = ?").run(session.userId);193      db.prepare("DELETE FROM account_keys WHERE user_id = ?").run(session.userId);194      db.prepare("UPDATE devices SET key_envelope = NULL, key_envelope_from = NULL WHERE user_id = ?").run(session.userId);195      db.prepare("UPDATE users SET recovery_hash = NULL, recovery_salt = NULL WHERE id = ?").run(session.userId);196    });197    log.add("warn", "sync", "synchronized data erased");198    return { ok: true };199  });200}201
Files main
Menu

Theme