sync-types.ts

1// Vault sync — type definitions.2//3// Pairing happens once per device pair over a relay rendezvous; all ongoing4// sync afterwards runs over that same relay with Noise KK. There is one5// transport — LAN peer-to-peer sync is retired6// (docs/sync-lan-retirement.md).78// ---------------------------------------------------------------------------9// Device types10// ---------------------------------------------------------------------------1112export type DeviceType = "extension" | "android" | "ios";1314// Numeric tags for DeviceType on the wire — not the string form.15export const DEVICE_TYPE_EXTENSION = 0x01 as const;16export const DEVICE_TYPE_ANDROID = 0x02 as const;17export const DEVICE_TYPE_IOS = 0x03 as const;1819export type DeviceTypeByte =20  | typeof DEVICE_TYPE_EXTENSION21  | typeof DEVICE_TYPE_ANDROID22  | typeof DEVICE_TYPE_IOS;2324// ---------------------------------------------------------------------------25// Long-term paired device registry26// ---------------------------------------------------------------------------2728/**29 * Trust source of a paired-device entry — per v2 brief §4.2.30 *31 *   "direct"  — established via a pairing-code session with this device.32 *   "vouched" — introduced by a directly-paired peer via a signed device33 *               manifest during a normal sync. A valid v3 route is admitted34 *               automatically as same-vault membership. It is equivalent to35 *               direct for sync, but cannot issue manifests itself;36 *               surfaced with an "Added automatically" badge in Settings.37 */38export type TrustSource = "direct" | "vouched";3940/**41 * v3 paired-device record. Stored in `chrome.storage.local` — cryptographic42 * keys must not leave the device via a third-party cloud service.43 *44 * `longTermPublicKeyHex` is the counterpart's vault-derived X25519 sync45 * identity static key — see `deriveSyncIdentityKeypair`. Every WebSocket46 * reconnect runs Noise KK with both local static keys, followed by a47 * PAIR_IDENTITY exchange bound to the authenticated keys.48 *49 * `lastKnownIp` is intentionally NOT stored here — it's per-network and50 * lives in `chrome.storage.local` keyed by `longTermPublicKeyHex`. See51 * `getLastKnownIp` / `setLastKnownIp` in `paired-devices.ts`.52 */53export interface PairedDevice {54  deviceId: string;55  deviceName?: string;56  deviceType?: DeviceType;57  longTermPublicKeyHex?: string;58  /**59   * Long-term Ed25519 verification key for the peer's device-manifest60   * signatures (v2 brief §4.3). Derived deterministically from the same61   * master key as `longTermPublicKeyHex`, via `deriveSyncSigningKeypair`.62   */63  signingPublicKeyHex?: string;64  /** v2 brief §4.2 — distinguishes direct-paired vs vouched-via-manifest. */65  trustSource?: TrustSource;66  /**67   * The peer's WebSocket sync port. Current Android hosts use fixed port 4914268   * and announce it inside the encrypted pairing channel.69   */70  wsPort?: number;71  /** Pair-only 32-byte reconnect capability, derived from the first handshake. */72  rendezvousSecretHex?: string;73  /** Validated wss relay used by this pair. */74  relayUrl?: string;75  pairedAt: number;76  lastSyncedAt?: number;77}7879// ---------------------------------------------------------------------------80// v3 wire protocol — phase-2 WebSocket manifest sync81// ---------------------------------------------------------------------------8283/**84 * v3 wire protocol — after reconnect Noise KK is open and PAIR_IDENTITY has85 * been bound to both authenticated static keys.86 *87 * Every frame is JSON, then ChaCha20-Poly1305 encrypted by Noise KK. The88 * WebSocket transport sees only ciphertext.89 *90 * The manifest carries per-entry timestamps; the receiver requests entries91 * where the remote timestamp beats its own. Entries traverse as opaque92 * encrypted blobs — the sync layer never decrypts vault data.93 */94export type SyncMessage =95  | {96      type: "SYNC_HELLO";97      vaultId: string;98      deviceId: string;99      version: number;100      deviceTime: number;101      /**102       * Advertises equal-version device-graph exchange support. Older peers103       * omit this field and retain the legacy SYNC_DONE fast path.104       */105      deviceManifestVersion?: number;106    }107  | { type: "SYNC_MANIFEST"; entries: Record<string, number>; tombstones: Record<string, number> }108  | { type: "SYNC_REQUEST"; entryIds: string[] }109  | { type: "SYNC_ENTRIES"; entries: Record<string, string> }110  | { type: "SYNC_TOMBSTONES"; tombstones: Record<string, number> }111  | { type: "SYNC_DEVICE_MANIFEST"; manifest: SignedDeviceManifest | null }112  | { type: "SYNC_DONE"; entriesReceived?: number; entriesSent?: number }113  | { type: "SYNC_ERROR"; error: string };114115// ---------------------------------------------------------------------------116// Browser-to-browser relay frames (phone forwards; see peach-android's117// RelayFrames.kt / RelayHub.kt, the source of truth this mirrors — NOT the118// older 4-frame PEACH_SYNC_RELAY_DESIGN.md sketch, which is stale).119//120// Type-only for now: nothing in this repo sends or handles these yet — no121// browser can listen, so relaying laptop-to-laptop traffic through a shared122// phone is unbuilt browser-side work, tracked separately. This exists so123// that work starts from the real wire contract instead of the stale doc.124// ---------------------------------------------------------------------------125126/** RelayMessage.targetDeviceId/peerDeviceId are the destination's Noise127 *  static public key as lowercase hex — NOT `PairedDevice.deviceId`. */128export type RelayMessage =129  | { type: "RELAY_REQUEST"; targetDeviceId: string }130  | { type: "RELAY_ACCEPT" }131  | { type: "RELAY_UNAVAILABLE" }132  | { type: "RELAY_DISABLED" }133  | { type: "RELAY_OPEN"; peerDeviceId: string }134  | { type: "RELAY_FRAME"; payload: string }135  | { type: "RELAY_CLOSE" };136137// ---------------------------------------------------------------------------138// v3 device manifest — propagates trust between mobile devices (v2 brief §4.3)139// ---------------------------------------------------------------------------140141/** 0x03 adds each peer edge's relay URL so a newly introduced pair can agree142 *  on a route without depending on the introducing device. Coordinated wire143 *  change with peach-android. */144export const DEVICE_MANIFEST_VERSION = 0x03 as const;145/** Manifests older than this are silently rejected (v2 brief §4.3). */146export const DEVICE_MANIFEST_FRESHNESS_MS = 5 * 60_000;147148/**149 * One device entry inside a signed manifest. `longTermPublicKeyHex` is the150 * X25519 sync identity key the receiver will use for Noise KK reconnect.151 * `signingPublicKeyHex` is the152 * peer's Ed25519 manifest-verification key — needed so a vouched mobile153 * can in turn verify manifests issued by the same vault from a different154 * device.155 */156export interface ManifestDeviceEntry {157  deviceId: string;158  deviceName: string;159  deviceType: DeviceType;160  longTermPublicKeyHex: string;161  signingPublicKeyHex: string;162  /**163   * Optional sync WebSocket port for native/mobile hosts. Preserving this in164   * vouched entries lets mobile peers connect without another audio pairing.165   */166  wsPort?: number;167  /** Relay the issuer currently uses for this peer edge. */168  relayUrl?: string;169  pairedAt: number;170}171172/**173 * A device that must no longer be synced with. Revocation is TERMINAL: once a174 * deviceId OR its long-term key appears here, no manifest may re-vouch it and175 * no pending entry carrying it may be confirmed. That is deliberate —176 * tombstone-style "newest timestamp wins" ordering would let a peer resurrect a177 * revoked device just by issuing a manifest with a fresh `pairedAt`, and every178 * timestamp in a manifest is peer-supplied. Re-admitting a device requires a179 * direct, SAS-confirmed re-pair with a physically present user.180 *181 * HONEST LIMIT: every mesh member holds the vault root key, and signing keys182 * are derived from it (`deriveSyncSigningKeypair(rootKey, deviceId)`), so these183 * signatures prove *vault membership*, not device identity. A revoked device184 * still holds the root key and, running modified software, can ignore its own185 * revocation. This mechanism stops honest peers from talking to a revoked186 * device; it is not a cryptographic ejection. See HOLE 4 — a genuinely187 * compromised device needs the master password and recovery words rotated.188 */189export interface DeviceRevocation {190  deviceId: string;191  /** X25519 sync identity key at the moment of revocation. Load-bearing, not192   *  descriptive: `deviceId` is whatever an issuing manifest says it is, so the193   *  key is what re-vouching is actually matched against. `0`×64 means no key194   *  was ever stored for the device and matches nothing. */195  longTermPublicKeyHex: string;196  revokedAt: number;197  /** deviceId that issued the revocation, for display only. */198  revokedByDeviceId: string;199}200201/** Body that gets canonicalised + signed. Wire format JSON-stable. */202export interface DeviceManifestBody {203  manifestVersion: number;204  issuerDeviceId: string;205  issuedAt: number;206  devices: ManifestDeviceEntry[];207  revoked: DeviceRevocation[];208}209210export interface SignedDeviceManifest {211  body: DeviceManifestBody;212  /** Hex-encoded 64-byte Ed25519 signature over canonicalised body. */213  signatureHex: string;214}215216export type SyncStatusV3 = "up_to_date" | "syncing" | "unreachable" | "never";