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// ---------------------------------------------------------------------------15// Long-term paired device registry16// ---------------------------------------------------------------------------1718/**19 * Trust source of a paired-device entry — per v2 brief §4.2.20 *21 *   "direct"  — established via a pairing-code session with this device.22 *   "vouched" — introduced by a directly-paired peer via a signed device23 *               manifest during a normal sync. A valid v3 route is admitted24 *               automatically as same-vault membership. It is equivalent to25 *               direct for sync, but cannot issue manifests itself;26 *               surfaced with an "Added automatically" badge in Settings.27 */28export type TrustSource = "direct" | "vouched";2930/**31 * v3 paired-device record. Stored in `chrome.storage.local` — cryptographic32 * keys must not leave the device via a third-party cloud service.33 *34 * `longTermPublicKeyHex` is the counterpart's vault-derived X25519 sync35 * identity static key — see `deriveSyncIdentityKeypair`. Every WebSocket36 * reconnect runs Noise KK with both local static keys, followed by a37 * PAIR_IDENTITY exchange bound to the authenticated keys.38 */39export interface PairedDevice {40  deviceId: string;41  deviceName?: string;42  /** User-chosen label stored only on this device; never sent to peers. */43  localAlias?: string;44  deviceType?: DeviceType;45  longTermPublicKeyHex?: string;46  /**47   * Long-term Ed25519 verification key for the peer's device-manifest48   * signatures (v2 brief §4.3). Derived deterministically from the same49   * master key as `longTermPublicKeyHex`, via `deriveSyncSigningKeypair`.50   */51  signingPublicKeyHex?: string;52  /** v2 brief §4.2 — distinguishes direct-paired vs vouched-via-manifest. */53  trustSource?: TrustSource;54  /**55   * The peer's WebSocket sync port. Current Android hosts use fixed port 4914256   * and announce it inside the encrypted pairing channel.57   */58  wsPort?: number;59  /** Pair-only 32-byte reconnect capability, derived from the first handshake. */60  rendezvousSecretHex?: string;61  /** Validated wss relay used by this pair. */62  relayUrl?: string;63  pairedAt: number;64  lastSyncedAt?: number;65}6667// ---------------------------------------------------------------------------68// v3 wire protocol — phase-2 WebSocket manifest sync69// ---------------------------------------------------------------------------7071/**72 * v3 wire protocol — after reconnect Noise KK is open and PAIR_IDENTITY has73 * been bound to both authenticated static keys.74 *75 * Every frame is JSON, then ChaCha20-Poly1305 encrypted by Noise KK. The76 * WebSocket transport sees only ciphertext.77 *78 * The manifest carries per-entry timestamps; the receiver requests entries79 * where the remote timestamp beats its own. Entries traverse as opaque80 * encrypted blobs — the sync layer never decrypts vault data.81 */82export type SyncMessage =83  | {84      type: "SYNC_HELLO";85      vaultId: string;86      deviceId: string;87      version: number;88      deviceTime: number;89      /**90       * Advertises equal-version device-graph exchange support. Older peers91       * omit this field and retain the legacy SYNC_DONE fast path.92       */93      deviceManifestVersion?: number;94    }95  | { type: "SYNC_MANIFEST"; entries: Record<string, number>; tombstones: Record<string, number> }96  | { type: "SYNC_REQUEST"; entryIds: string[] }97  | { type: "SYNC_ENTRIES"; entries: Record<string, string> }98  | { type: "SYNC_TOMBSTONES"; tombstones: Record<string, number> }99  | { type: "SYNC_DEVICE_MANIFEST"; manifest: SignedDeviceManifest | null }100  | { type: "SYNC_DONE"; entriesReceived?: number; entriesSent?: number }101  | { type: "SYNC_ERROR"; error: string };102103// ---------------------------------------------------------------------------104// v3 device manifest — propagates trust between mobile devices (v2 brief §4.3)105// ---------------------------------------------------------------------------106107/** 0x03 adds each peer edge's relay URL so a newly introduced pair can agree108 *  on a route without depending on the introducing device. Coordinated wire109 *  change with peach-android. */110export const DEVICE_MANIFEST_VERSION = 0x03 as const;111/** Manifests older than this are silently rejected (v2 brief §4.3). */112export const DEVICE_MANIFEST_FRESHNESS_MS = 5 * 60_000;113114/**115 * One device entry inside a signed manifest. `longTermPublicKeyHex` is the116 * X25519 sync identity key the receiver will use for Noise KK reconnect.117 * `signingPublicKeyHex` is the118 * peer's Ed25519 manifest-verification key — needed so a vouched mobile119 * can in turn verify manifests issued by the same vault from a different120 * device.121 */122export interface ManifestDeviceEntry {123  deviceId: string;124  deviceName: string;125  deviceType: DeviceType;126  longTermPublicKeyHex: string;127  signingPublicKeyHex: string;128  /**129   * Optional sync WebSocket port for native/mobile hosts. Preserving this in130   * vouched entries lets mobile peers connect without another audio pairing.131   */132  wsPort?: number;133  /** Relay the issuer currently uses for this peer edge. */134  relayUrl?: string;135  pairedAt: number;136}137138/**139 * A device that must no longer be synced with. Revocation is TERMINAL: once a140 * deviceId OR its long-term key appears here, no manifest may re-vouch it and141 * no pending entry carrying it may be confirmed. That is deliberate —142 * tombstone-style "newest timestamp wins" ordering would let a peer resurrect a143 * revoked device just by issuing a manifest with a fresh `pairedAt`, and every144 * timestamp in a manifest is peer-supplied. Re-admitting a device requires a145 * direct, SAS-confirmed re-pair with a physically present user.146 *147 * HONEST LIMIT: every mesh member holds the vault root key, and signing keys148 * are derived from it (`deriveSyncSigningKeypair(rootKey, deviceId)`), so these149 * signatures prove *vault membership*, not device identity. A revoked device150 * still holds the root key and, running modified software, can ignore its own151 * revocation. This mechanism stops honest peers from talking to a revoked152 * device; it is not a cryptographic ejection. See HOLE 4 — a genuinely153 * compromised device needs the master password and recovery words rotated.154 */155export interface DeviceRevocation {156  deviceId: string;157  /** X25519 sync identity key at the moment of revocation. Load-bearing, not158   *  descriptive: `deviceId` is whatever an issuing manifest says it is, so the159   *  key is what re-vouching is actually matched against. `0`×64 means no key160   *  was ever stored for the device and matches nothing. */161  longTermPublicKeyHex: string;162  revokedAt: number;163  /** deviceId that issued the revocation, for display only. */164  revokedByDeviceId: string;165}166167/** Body that gets canonicalised + signed. Wire format JSON-stable. */168export interface DeviceManifestBody {169  manifestVersion: number;170  issuerDeviceId: string;171  issuedAt: number;172  devices: ManifestDeviceEntry[];173  revoked: DeviceRevocation[];174}175176export interface SignedDeviceManifest {177  body: DeviceManifestBody;178  /** Hex-encoded 64-byte Ed25519 signature over canonicalised body. */179  signatureHex: string;180}