Repository Public
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