// Vault sync — type definitions (Master Brief v2).
//
// v3 — code pairing once per device pair (Phase 1). All ongoing vault sync
// after that runs over a direct WebSocket on the local network (Phase 2).
// The two phases never overlap.

// ---------------------------------------------------------------------------
// Device types
// ---------------------------------------------------------------------------

export type DeviceType = "extension" | "android" | "ios";

// Numeric tags for DeviceType on the wire — not the string form.
export const DEVICE_TYPE_EXTENSION = 0x01 as const;
export const DEVICE_TYPE_ANDROID = 0x02 as const;
export const DEVICE_TYPE_IOS = 0x03 as const;

export type DeviceTypeByte =
  | typeof DEVICE_TYPE_EXTENSION
  | typeof DEVICE_TYPE_ANDROID
  | typeof DEVICE_TYPE_IOS;

// ---------------------------------------------------------------------------
// Long-term paired device registry
// ---------------------------------------------------------------------------

/**
 * Trust source of a paired-device entry — per v2 brief §4.2.
 *
 *   "direct"  — established via a pairing-code session with this device.
 *   "vouched" — introduced by a directly-paired peer via a signed device
 *               manifest during a normal sync, then confirmed by the user
 *               (MV-7). Functionally equivalent to direct for sync purposes;
 *               surfaced with an "Added automatically" badge in Settings.
 */
export type TrustSource = "direct" | "vouched";

/**
 * v3 paired-device record. Stored in `chrome.storage.local` — cryptographic
 * keys must not leave the device via a third-party cloud service.
 *
 * `longTermPublicKeyHex` is the counterpart's vault-derived X25519 sync
 * identity static key — see `deriveSyncIdentityKeypair`. Every WebSocket
 * reconnect runs Noise NK against this key (authenticating the responder
 * only) followed by a PAIR_IDENTITY exchange checked against this registry —
 * see HANDSHAKE_STANDARDIZE_ON_NK.md.
 *
 * `lastKnownIp` is intentionally NOT stored here — it's per-network and
 * lives in `chrome.storage.local` keyed by `longTermPublicKeyHex`. See
 * `getLastKnownIp` / `setLastKnownIp` in `paired-devices.ts`.
 */
export interface PairedDevice {
  deviceId: string;
  deviceName?: string;
  deviceType?: DeviceType;
  longTermPublicKeyHex?: string;
  /**
   * Long-term Ed25519 verification key for the peer's device-manifest
   * signatures (v2 brief §4.3). Derived deterministically from the same
   * master key as `longTermPublicKeyHex`, via `deriveSyncSigningKeypair`.
   */
  signingPublicKeyHex?: string;
  /** v2 brief §4.2 — distinguishes direct-paired vs vouched-via-manifest. */
  trustSource?: TrustSource;
  /**
   * The peer's WebSocket sync port. Mobile hosts pick a random high port
   * (49152–65535) at first launch and announce it inside the encrypted
   * pairing channel; the extension caches it here.
   */
  wsPort?: number;
  /** Pair-only 32-byte reconnect capability, derived from the first handshake. */
  rendezvousSecretHex?: string;
  /** Validated wss relay used by this pair. */
  relayUrl?: string;
  pairedAt: number;
  lastSyncedAt?: number;
}

// ---------------------------------------------------------------------------
// v3 wire protocol — phase-2 WebSocket manifest sync
// ---------------------------------------------------------------------------

/**
 * v3 wire protocol — after Noise NK is open and PAIR_IDENTITY has been
 * exchanged (see HANDSHAKE_STANDARDIZE_ON_NK.md).
 *
 * Every frame is JSON, then ChaCha20-Poly1305 encrypted by Noise NK. The
 * WebSocket transport sees only ciphertext.
 *
 * The manifest carries per-entry timestamps; the receiver requests entries
 * where the remote timestamp beats its own. Entries traverse as opaque
 * encrypted blobs — the sync layer never decrypts vault data.
 */
export type SyncMessage =
  | { type: "SYNC_HELLO"; vaultId: string; deviceId: string; version: number; deviceTime: number }
  | { type: "SYNC_MANIFEST"; entries: Record<string, number>; tombstones: Record<string, number> }
  | { type: "SYNC_REQUEST"; entryIds: string[] }
  | { type: "SYNC_ENTRIES"; entries: Record<string, string> }
  | { type: "SYNC_TOMBSTONES"; tombstones: Record<string, number> }
  | { type: "SYNC_DEVICE_MANIFEST"; manifest: SignedDeviceManifest | null }
  | { type: "SYNC_DONE"; entriesReceived?: number; entriesSent?: number }
  | { type: "SYNC_ERROR"; error: string };

// ---------------------------------------------------------------------------
// Browser-to-browser relay frames (phone forwards; see peach-android's
// RelayFrames.kt / RelayHub.kt, the source of truth this mirrors — NOT the
// older 4-frame PEACH_SYNC_RELAY_DESIGN.md sketch, which is stale).
//
// Type-only for now: nothing in this repo sends or handles these yet — no
// browser can listen, so relaying laptop-to-laptop traffic through a shared
// phone is unbuilt browser-side work, tracked separately. This exists so
// that work starts from the real wire contract instead of the stale doc.
// ---------------------------------------------------------------------------

/** RelayMessage.targetDeviceId/peerDeviceId are the destination's Noise NK
 *  static public key as lowercase hex — NOT `PairedDevice.deviceId`. */
export type RelayMessage =
  | { type: "RELAY_REQUEST"; targetDeviceId: string }
  | { type: "RELAY_ACCEPT" }
  | { type: "RELAY_UNAVAILABLE" }
  | { type: "RELAY_DISABLED" }
  | { type: "RELAY_OPEN"; peerDeviceId: string }
  | { type: "RELAY_FRAME"; payload: string }
  | { type: "RELAY_CLOSE" };

// ---------------------------------------------------------------------------
// v3 device manifest — propagates trust between mobile devices (v2 brief §4.3)
// ---------------------------------------------------------------------------

export const DEVICE_MANIFEST_VERSION = 0x01 as const;
/** Manifests older than this are silently rejected (v2 brief §4.3). */
export const DEVICE_MANIFEST_FRESHNESS_MS = 5 * 60_000;

/**
 * One device entry inside a signed manifest. `longTermPublicKeyHex` is the
 * X25519 sync identity key the receiver will use for Noise NK, exactly as
 * if the entry had been audio-paired locally. `signingPublicKeyHex` is the
 * peer's Ed25519 manifest-verification key — needed so a vouched mobile
 * can in turn verify manifests issued by the same vault from a different
 * device.
 */
export interface ManifestDeviceEntry {
  deviceId: string;
  deviceName: string;
  deviceType: DeviceType;
  longTermPublicKeyHex: string;
  signingPublicKeyHex: string;
  /**
   * Optional sync WebSocket port for native/mobile hosts. Preserving this in
   * vouched entries lets mobile peers connect without another audio pairing.
   */
  wsPort?: number;
  pairedAt: number;
}

/** Body that gets canonicalised + signed. Wire format JSON-stable. */
export interface DeviceManifestBody {
  manifestVersion: number;
  issuerDeviceId: string;
  issuedAt: number;
  devices: ManifestDeviceEntry[];
}

export interface SignedDeviceManifest {
  body: DeviceManifestBody;
  /** Hex-encoded 64-byte Ed25519 signature over canonicalised body. */
  signatureHex: string;
}

export type SyncStatusV3 = "up_to_date" | "syncing" | "unreachable" | "never";