sync-types.ts

1// Chirp Sync — type definitions.2//3// This file is in the middle of a v2.14 → v3 migration. The v3 chirp-sync4// architecture (audio-bootstrapped pairing + manifest-diff WebSocket sync)5// is being added alongside the v2.14 full-blob-over-native-host types.6// The v2.14 types are scheduled for removal once every consumer in7// messages.ts has been migrated; do not write new code against them.8//9// v3 — audio pairing once per device pair (Phase 1). All ongoing vault sync10// after that runs over a direct WebSocket on the local network (Phase 2).11// The two phases never overlap.1213// ---------------------------------------------------------------------------14// v3 chirp pairing — on-air audio frame15// ---------------------------------------------------------------------------1617export type DeviceType = "extension" | "android" | "ios" | "desktop";1819// Numeric tags used in the on-air chirp payload. The audio frame is a20// fixed 64-byte struct (see chirp-payload.ts); these are the byte values21// that go on the wire — not the string DeviceType.22export const DEVICE_TYPE_EXTENSION = 0x01 as const;23export const DEVICE_TYPE_ANDROID = 0x02 as const;24export const DEVICE_TYPE_IOS = 0x03 as const;25export const DEVICE_TYPE_DESKTOP = 0x04 as const;2627export type DeviceTypeByte =28  | typeof DEVICE_TYPE_EXTENSION29  | typeof DEVICE_TYPE_ANDROID30  | typeof DEVICE_TYPE_IOS31  | typeof DEVICE_TYPE_DESKTOP;3233export const CHIRP_MAGIC_BYTES = Uint8Array.of(0x50, 0x45, 0x41, 0x43); // "PEAC"34export const CHIRP_PROTOCOL_VERSION = 0x01 as const;35export const CHIRP_PAYLOAD_LENGTH = 64 as const;3637export function deviceTypeFromByte(b: DeviceTypeByte): DeviceType {38  switch (b) {39    case DEVICE_TYPE_EXTENSION: return "extension";40    case DEVICE_TYPE_ANDROID: return "android";41    case DEVICE_TYPE_IOS: return "ios";42    case DEVICE_TYPE_DESKTOP: return "desktop";43  }44}4546export function deviceTypeToByte(t: DeviceType): DeviceTypeByte {47  switch (t) {48    case "extension": return DEVICE_TYPE_EXTENSION;49    case "android": return DEVICE_TYPE_ANDROID;50    case "ios": return DEVICE_TYPE_IOS;51    case "desktop": return DEVICE_TYPE_DESKTOP;52  }53}5455export interface ChirpPayload {56  version: number;57  deviceType: DeviceTypeByte;58  ephemeralPublicKey: Uint8Array; // 32 bytes59  sessionNonce: Uint8Array; // 16 bytes60}6162// ---------------------------------------------------------------------------63// v3 chirp pairing — long-term paired device registry64// ---------------------------------------------------------------------------6566/**67 * v3 paired-device record. Stored in `chrome.storage.sync` so the registry68 * roams across browser profiles signed into Chrome/Firefox sync.69 *70 * `longTermPublicKeyHex` is the counterpart's vault-derived sync identity71 * static X25519 public key — see `deriveSyncIdentityKeypair`. Mutual Noise72 * XX authentication on every WebSocket connection rejects any peer not73 * present in this registry.74 *75 * `lastKnownIp` is intentionally NOT stored here — it's per-network and76 * lives in `chrome.storage.local` keyed by `longTermPublicKeyHex`. See77 * `getLastKnownIp` / `setLastKnownIp` in sync-storage.ts.78 *79 * Legacy v2.14 fields `displayName`, `x25519PublicKey`, `lastSeenAt`,80 * `lastSyncAt`, `lastKnownIp` are kept for migration only; new code reads81 * `deviceName`, `longTermPublicKeyHex`, `lastSyncedAt`.82 */83export interface PairedDevice {84  deviceId: string;85  deviceName?: string;86  deviceType?: DeviceType;87  longTermPublicKeyHex?: string;88  pairedAt: number;89  lastSyncedAt?: number;9091  // v2.14 legacy — kept readable so the migration sweep doesn't crash92  // every test that still constructs the old shape. New writers must use93  // the v3 fields above.94  displayName?: string;95  x25519PublicKey?: string;96  lastSeenAt?: number;97  lastSyncAt?: number;98  lastKnownIp?: string;99}100101// ---------------------------------------------------------------------------102// v3 chirp pairing — phase-1 UI state103// ---------------------------------------------------------------------------104105/**106 * Phase 1 pairing state, surfaced to the SyncPairing view. The view binds107 * its bird-animation acts directly to these states: `listening` and108 * `chirping` map to Act 1, `handshake` maps to Act 2, `paired` to Act 3.109 */110export type PairingPhase =111  | "idle"112  | "listening"113  | "chirping"114  | "handshake"115  | "paired"116  | "timeout"117  | "mic_denied"118  | "version_mismatch"119  | "handshake_failed";120121export interface PairingProgress {122  phase: PairingPhase;123  peerDeviceName?: string;124  errorMessage?: string;125}126127// ---------------------------------------------------------------------------128// v3 wire protocol — phase-2 WebSocket manifest sync129// ---------------------------------------------------------------------------130131/**132 * v3 wire protocol — after Noise XX is open.133 *134 * Every frame is JSON, then ChaCha20-Poly1305 encrypted by Noise XX. The135 * WebSocket transport sees only ciphertext.136 *137 * The manifest carries per-entry timestamps; the receiver requests entries138 * where the remote timestamp beats its own. Entries traverse as opaque139 * encrypted blobs — the sync layer never decrypts vault data.140 */141export type ChirpSyncMessage =142  | { type: "SYNC_HELLO"; vaultId: string; deviceId: string }143  | { type: "SYNC_MANIFEST"; entries: Record<string, number>; tombstones: Record<string, number> }144  | { type: "SYNC_REQUEST"; entryIds: string[] }145  | { type: "SYNC_ENTRIES"; entries: Record<string, string> }146  | { type: "SYNC_TOMBSTONES"; tombstones: Record<string, number> }147  | { type: "SYNC_DONE" }148  | { type: "SYNC_ERROR"; error: string };149150export type SyncStatusV3 = "up_to_date" | "syncing" | "unreachable" | "never";151152// ---------------------------------------------------------------------------153// v2.14 legacy types — DO NOT USE IN NEW CODE154//155// These remain only because messages.ts and the v2.14 coordinator/network156// modules import them. Once the migration sweep lands, this whole block157// goes away.158// ---------------------------------------------------------------------------159160export interface TrustedNetwork {161  ssid?: string;162  bssid?: string;163  isTailscale: boolean;164  addedAt: number;165}166167export interface SyncableDevice {168  publicKeyHex: string;169  deviceName: string;170  pairedAt: number;171}172173export type SyncMessage =174  | { type: 'SYNC_HELLO' }175  | { type: 'SYNC_VAULT_SEND'; blob: string; timestamp: number; license?: string; devices: SyncableDevice[] }176  | { type: 'SYNC_VAULT_ACK'; applied: boolean }177  | { type: 'SYNC_DONE' }178  | { type: 'SYNC_ERROR'; error: string };179180export type SyncStatus = "synced" | "syncing" | "no_peers" | "not_trusted" | "offline";181182export interface IncomingPairingRequest {183  deviceName: string;184  publicKeyHex: string;185  receivedAt: number;186  expiresAt: number;187  connectionId?: string;188}