types.ts

1/**2 * types.ts — cross-boundary types and the `MessageType` union.3 *4 * `MessageType` mixes background-bound and content-script-bound messages.5 * Background-bound types have a case in `src/background/messages.ts`.6 * Content-script-bound types (PING, SUMMON_AUTOFILL, VAULT_LOCKED,7 * RESTART_AUTO_LOCK, etc.) are sent *to* content scripts or the popup and8 * have no handler in messages.ts by design — that absence is not a missing9 * handler. Add new cross-boundary types here, not inline in call sites.10 */1112export interface ManualSummonRecord {13  firstSummonedAt: number;14  summonCount: number;15  lastSummonedAt: number;16}1718export interface Canary {19  webhookUrl: string;20  label?: string;21  lastPinged?: number;22  pingCount?: number;23}2425export type CardNetwork = "visa" | "mastercard" | "amex" | "discover" | "unknown";2627/**28 * Passkey credential data attached to a VaultEntry. New in v2.11.0 — passkeys29 * are no longer a separate entry type; instead they hang off any login entry.30 * A passkey-only entry is a `type:"login"` entry with no username/password31 * but a `passkey` sub-object set. A login that ALSO has a passkey is just a32 * normal login with `passkey` populated.33 *34 * privateKeyJwk is present only on Chrome-created passkeys, where Peach is35 * the authenticator. Firefox-created passkeys delegate to the platform36 * authenticator, so the field is absent — `browser` distinguishes the two.37 */38export interface PasskeyData {39  rpId: string;40  rpName: string;41  credentialId: string;42  publicKeyCose: string;43  privateKeyJwk?: JsonWebKey;44  userHandle: string;45  userName: string;46  userDisplayName: string;47  algorithm: -7 | -8;48  signCount: number;49  aaguid: string;50  backupEligible: boolean;51  backupState: boolean;52  lastUsedAt?: number;53  browser?: "chrome" | "firefox";54  transports?: string[];55  /** When the credential was first registered with Peach. */56  createdAt: number;57}5859export interface VaultEntry {60  id: string; // crypto.randomUUID()61  /**62   * Entry type. As of v2.11.0 passkeys are stored on `type:"login"` entries63   * via the `passkey` sub-object — `"passkey"` here is a legacy value still64   * accepted on read but rewritten to `"login"` on next vault save.65   */66  type?: "login" | "note" | "passkey" | "card";67  title: string;68  username?: string; // only for login entries69  email?: string; // separate email address — for sites that require both a username and an email70  password?: string; // only for login entries71  url?: string; // only for login entries72  /**73   * Additional sites this entry should match for autofill. Login entries only.74   * Each value is a full origin or URL (e.g. `https://login.foo.com`).75   * The vault domain index keys against the hostname of every entry in this76   * list, in addition to `url`.77   */78  additionalUrls?: string[];79  totp?: string; // base32 seed, stored encrypted — only for login entries80  notes?: string;81  breach?: number; // HIBP exposure count; 0 or undefined = clean — only for login entries82  /**83   * When the password field was last changed. Set on first-write of `password`84   * and refreshed on every subsequent change. Defaults to `createdAt` when85   * legacy entries are read by the advanced health analyser.86   */87  passwordChangedAt?: number;88  canary?: Canary;89  createdAt: number; // Date.now()90  modifiedAt: number;91  deletedAt?: number;92  tags?: string[];93  /** Passkey credential attached to this entry, if any. */94  passkey?: PasskeyData;95  // ── Legacy passkey flat fields (pre-v2.11.0). Populated by vault read96  // migration so that the old import/sanitize paths keep typing; new code97  // should always read `entry.passkey?.*` instead. The migration drops these98  // on next vault save. Do not introduce new readers of these fields.99  rpId?: string;100  rpName?: string;101  credentialId?: string;102  publicKeyCose?: string;103  privateKeyJwk?: JsonWebKey;104  userHandle?: string;105  userName?: string;106  userDisplayName?: string;107  algorithm?: -7 | -8;108  signCount?: number;109  aaguid?: string;110  backupEligible?: boolean;111  backupState?: boolean;112  lastUsedAt?: number;113  browser?: "chrome" | "firefox";114  transports?: string[];115  // Card entry fields116  cardholderName?: string;117  cardNumber?: string;       // full PAN, stored encrypted in vault118  expMonth?: string;119  expYear?: string;120  cvc?: string;121  cardNickname?: string;122  network?: CardNetwork;123  last4?: string;124}125126/**127 * Returns true when an entry has a passkey credential attached. After v2.11.0128 * migration this is the canonical check; pre-migration entries with a flat129 * `rpId`/`credentialId` shape get rewritten by the vault read pass before130 * any consumer sees them.131 */132export function hasPasskey(entry: VaultEntry): boolean {133  return entry.passkey !== undefined && entry.passkey.credentialId.length > 0;134}135136/**137 * Returns true when an entry is "passkey-only" — has a passkey credential138 * but no password to fill into a form. Login fields hide for these entries139 * and the inline autofill selector filters them out (signing in via the140 * passkey is a separate WebAuthn flow). Username may still be populated141 * (the migration mirrors passkey.userName onto the entry's username so the142 * domain-index/search keep working) and is not part of this discriminator.143 */144export function isPasskeyOnly(entry: VaultEntry): boolean {145  return hasPasskey(entry) && !entry.password;146}147148export interface LegacyVaultEntry {149  id: string;150  title: string;151  username: string;152  password: string;153  url: string;154  totp?: string;155  notes?: string;156  breach?: number;157  created: number;158  updated: number;159  deletedAt?: number;160}161162export interface CardEntry extends VaultEntry {163  type: "card";164  cardholderName: string;165  cardNumber: string;166  expMonth: string;167  expYear: string;168  cvc: string;169}170171172export interface PendingPasskeyRequest {173  requestId: number;174  type: "create" | "get";175  rpId: string;176  rpName: string;177  userName: string;178  userDisplayName?: string;179  /**180   * Firefox path: when present, the popup performs the navigator.credentials181   * call itself rather than completing a chrome.webAuthenticationProxy182   * request. Absent for Chrome (the existing webAuthenticationProxy flow).183   */184  browser?: "chrome" | "firefox";185  /** Firefox create: base64url challenge minted by the popup-context flow. */186  challenge?: string;187  /** Firefox create: base64url user handle. Generated if absent. */188  userHandle?: string;189}190191export interface PasskeyProviderState {192  supported: boolean;193  enabled: boolean;194  attached: boolean;195  browserLabel: string;196  statusLabel: string;197  conflict?: string;198}199200export interface StoredVault {201  version: 1; // AAD for AES-GCM --- prevents downgrade202  salt: string; // hex --- 16 bytes, CSPRNG, stored not secret203  nonce: string; // hex --- 12 bytes, CSPRNG, fresh per write204  ciphertext: string; // hex --- AES-256-GCM output205  tag: string; // hex --- 16-byte GCM auth tag206  // Recovery escrow: root key wrapped under recovery words via AES-256-GCM.207  // Absent on vaults created before v2.12 (migrateToRecovery adds them on first unlock).208  recovery_salt?: string; // hex --- 16 bytes, CSPRNG, HKDF salt for recovery key209  recovery_wrapped_root_key?: string; // hex --- AES-256-GCM ciphertext of 32-byte root key210  recovery_nonce?: string; // hex --- 12 bytes, fresh nonce for the above211  recovery_tag?: string; // hex --- 16-byte GCM auth tag for the above212  // Second wrapping of the same root key under the password-derived key.213  // Lets unlock() recover the rootKey bytes without the user's recovery214  // words, so GET_RECOVERY_WORDS works across lock/unlock cycles. Refreshed215  // on every password change so the words stay valid (H2/COR-006).216  pw_root_ciphertext?: string; // hex --- AES-256-GCM ciphertext of 32-byte root key (hex-encoded)217  pw_root_nonce?: string; // hex --- 12-byte nonce218  pw_root_tag?: string; // hex --- 16-byte GCM auth tag219}220221// Background-bound message types — sent from popup/content scripts,222// handled in src/background/messages.ts. Everything in this group must223// have a matching case in that file's switch statement.224export type MessageType =225  | "UNLOCK"226  | "LOCK"227  | "IS_UNLOCKED"228  | "HAS_VAULT"229  | "GET_ENTRIES"230  | "ADD_ENTRY"231  | "BATCH_ADD_ENTRIES"232  | "RESTORE_ENTRIES"233  | "CLEAR_VAULT_ENTRIES"234  | "UPDATE_ENTRY"235  | "ADD_ADDITIONAL_URL"236  | "DELETE_ENTRY"237  | "AUTOFILL_QUERY"238  | "COPY"239  | "CREATE_VAULT"240  | "GET_ENTRY_FOR_FILL"241  | "CHECK_ALL_BREACHES"242  | "GET_SETTINGS"243  | "UPDATE_SETTINGS"244  | "FIRE_CANARY_PING"245  | "ACTIVATE_LICENSE"246  | "GET_LICENSE"247  | "GET_LICENSE_KEY"248  | "IS_DURESS_ENABLED"249  | "SETUP_DURESS"250  | "DISABLE_DURESS"251  | "VERIFY_MAIN_PASSWORD"252  | "CHANGE_PASSWORD"253  | "GET_SITE_PASSWORD_POLICY"254  | "GET_SYNC_STATE"255  | "GET_PAIRED_DEVICES"256  | "GET_SYNC_STATUS"257  | "TRIGGER_SYNC"258  | "ACCEPT_PAIRING"259  | "REMOVE_PAIRED_DEVICE"260  | "REMOVE_TRUSTED_NETWORK"261  | "MARK_NETWORK_TRUSTED"262  | "RESET_SYNC_IDENTITY"263  | "CHIRP_GET_LOCAL_IDENTITY"264  | "CHIRP_COMPLETE_PAIRING"265  | "CHIRP_LIST_PAIRED_DEVICES"266  | "CHIRP_UNPAIR_DEVICE"267  | "CHIRP_RENAME_LOCAL_DEVICE"268  | "GET_INCOMING_PAIRING_REQUEST"269  | "RESPOND_INCOMING_PAIRING"270  | "DEBUG_INJECT_INCOMING_PAIRING"271  | "START_PAIRING_SERVER"272  | "STOP_PAIRING_SERVER"273  | "GET_RECENT_PAIRING"274  | "GET_PENDING_PASSKEY"275  | "APPROVE_PASSKEY"276  | "DENY_PASSKEY"277  | "GET_PASSKEY_PROVIDER_STATE"278  | "SET_PASSKEY_PROVIDER_ENABLED"279  | "GET_DELETED_ENTRIES"280  | "RESTORE_ENTRY"281  | "PURGE_ENTRY"282  | "PURGE_EXPIRED_TRASH"283  | "GET_VAULT_HISTORY"284  | "RESTORE_VAULT_SNAPSHOT"285  | "COUNT_DUPLICATES"286  | "DEDUPLICATE_ENTRIES"287  | "RECORD_MANUAL_SUMMON"288  | "DECLINE_CARD_SAVE"289  | "IS_CARD_DECLINED"290  | "SUBMIT_FEEDBACK"291  | "GET_VAULT_STATUS"292  | "GET_ADVANCED_HEALTH_REPORT"293  | "INITIATE_PASSWORD_CHANGE"294  | "DEACTIVATE_LICENSE"295  | "GET_IDENTITIES"296  | "DESTROY_VAULT"297  | "INITIATE_FIREFOX_PASSKEY_CREATE"298  | "COMPLETE_FIREFOX_PASSKEY_CREATE"299  | "PASSKEY_OFFER_DECLINE"300  | "GET_PASSKEY_OFFER_DECLINED"301  | "GET_PASSKEY_FOR_DOMAIN"302  // Firefox content-script proxy path (v2.12.0). Sent FROM the page-world303  // monkey-patch through the extension-world relay TO the background. See304  // src/shared/passkey-flags.ts for removal conditions.305  | "PASSKEY_HAS_CREDENTIALS"306  | "PASSKEY_CREATE"307  | "PASSKEY_GET"308  // Android / iOS message types — activate only when Capacitor.isNativePlatform() is true.309  | "UNLOCK_WITH_KEY"310  | "GET_DERIVED_KEY"311  // Recovery word messages312  | "VALIDATE_RECOVERY_WORDS"313  | "RECOVER_WITH_WORDS"314  | "GET_RECOVERY_WORDS"315  | "SCAN_PAIRING_QR"316  | "SYNC_SESSION_STARTED"317  | "GET_LOCAL_IP"318  | "GET_IDENTITY_SUGGESTIONS"319  | "TOUCH_AUTO_LOCK"320  | "POPULATE_INLINE_VAULT"321  | "SAVE_NOTE"322  | "DELETE_NOTE"323  | "GET_NOTES"324  | "SEARCH_VAULT"325  | "PAIRING_COMPLETED"326  | "ML_INIT"327  | "ML_PREDICT_BATCH"328  // Content-script-bound message types — sent BY the background TO content329  // scripts. They never reach messages.ts's switch. Kept in this union so330  // existing call sites type-check; do not add cases for them in the331  // background handler.332  | "PING"            // background → content: liveness probe333  | "SUMMON_AUTOFILL" // background → content: open the in-page palette334  | "VAULT_LOCKED"    // background → content/popup: vault just locked335  | "VAULT_UNLOCKED"  // background → content/popup: vault just unlocked336  | "PRO_GATE_TRIGGERED" // background → popup: a Pro feature was attempted on free337  | "PASSKEY_PRO_GATE" // background → content: show passkey Pro gate in inline popup338  | "OPEN_PRO_GATE" // content → background: open popup and navigate to License section339  | "SHOW_PASSKEY_TOAST"    // background → content tab: show passkey auth toast340  | "DISMISS_PASSKEY_TOAST" // background → content tab: dismiss passkey auth toast341  | "PASSKEY_AUTH_RESPONSE" // content → background: user approved or denied the toast342  | "SHOULD_PLAY_CELEBRATION"343  | "MARK_CELEBRATION_PLAYED"344  // Peach Codex (v2.42.0). Generation runs in the popup — the SW only345  // sources vault data and applies the restored slots.346  | "GET_CODEX_VAULT_DATA"347  | "ESTIMATE_CODEX_PAGES"348  | "GENERATE_CODEX"349  | "RESTORE_FROM_CODEX";350351export type ProFeature =352  | "sync"353  | "passkeys"354  | "advanced_health"355  | "smart_password_change"356  | "ios_app"357  | "codex";358359/**360 * License export shape included in PeachScript and encrypted JSON backups.361 * `celebrationPlayed` is intentionally absent — a new device deserves the moment.362 */363export interface PeachLicenseExport {364  key: string;365  activatedAt?: number;366}367368export interface AdvancedHealthEntryReport {369  id: string;370  title: string;371  domain: string;372  url?: string;373  score: number;374  ageDays: number;375  reasons: string[];376  factors: {377    breached: boolean;378    breachCount: number;379    reused: boolean;380    aged: boolean;381    weak: boolean;382    missingTotpOnSensitive: boolean;383  };384}385386export interface AdvancedHealthReport {387  vaultScore: number;388  generatedAt: number;389  entryCount: number;390  reusedGroups: number;391  agedCount: number;392  remediation: AdvancedHealthEntryReport[];393}394395export const ACCENT_COLORS = [396  { name: "peach",    hex: "#F49C70" },397  { name: "rose",     hex: "#FF8AA6" },398  { name: "plum",     hex: "#D597F2" },399  { name: "lavender", hex: "#A6A8FF" },400  { name: "sky",      hex: "#5BC8EE" },401  { name: "mint",     hex: "#5EE0B0" },402  { name: "sage",     hex: "#B5D870" },403  { name: "butter",   hex: "#FFD45A" },404  { name: "sand",     hex: "#EDBC85" },405  { name: "clay",     hex: "#F08660" },406  { name: "slate",    hex: "#80BEDE" },407  { name: "stone",    hex: "#C8B8A8" },408] as const;409410export type AccentColorName = typeof ACCENT_COLORS[number]["name"];411412export interface SavedIdentity {413  value: string;414  type: "email" | "username";415  lastUsed: number;416  useCount: number;417  exampleDomain?: string;418}419420export interface PasswordPolicy {421  minLength?: number;422  maxLength?: number;423  requiresUppercase?: boolean;424  requiresLowercase?: boolean;425  requiresNumbers?: boolean;426  requiresSymbols?: boolean;427  forbidsSymbols?: boolean;428  allowedSymbols?: string;429  /** Characters the site explicitly disallows. Filtered from every pool before generation. */430  forbiddenChars?: string;431}432433/**434 * A single vault history snapshot. The `vault_a` and `vault_b` fields are the435 * raw encrypted blobs from chrome.storage.local — already AES-256-GCM436 * protected by the master password, so storing them in history adds no437 * security surface.438 *439 * Snapshots are taken BEFORE every vault write so the saved blob represents440 * what is about to be lost, not what was just written. The reason field441 * documents the trigger so the UI can render "saved" / "synced" / "imported"442 * / "restored" labels next to each row.443 */444export interface VaultSnapshot {445  id: string;446  savedAt: number;447  reason: "local_save" | "sync_received" | "import" | "restore";448  vault_a: string;449  vault_b: string;450  /** Active entry count when the snapshot was taken; null if vault was locked. */451  entryCount: number | null;452}453454export interface VaultHistory {455  /** Newest first; capped at HISTORY_MAX (10). */456  snapshots: VaultSnapshot[];457}458459export interface Message {460  type: MessageType;461  payload?: unknown;462}463464// Canonical snake_case error codes returned by message handlers. Keep this465// union the authoritative catalogue — new handlers must reuse an entry or466// add one here. Free-form strings still appear (network/operation failures467// surface their raw .message), so error stays string at runtime; the union468// is the documented set callers should switch on.469export type ErrorCode =470  | "vault_locked"471  | "vault_corrupted"472  | "no_vault"473  | "entry_not_found"474  | "invalid_payload"475  | "invalid_message"476  | "invalid_sender"477  | "wrong_passphrase"478  | "incorrect_current_password"479  | "recovery_not_setup"480  | "android_only"481  | "not_available"482  | "pro_required"483  | "pairing_not_verified"484  | "sync_rejected_unpaired_initiator"485  | "vault_not_applied"486  | "url_required"487  | "domain_required"488  | "rpid_required"489  | "rpid_and_username_required"490  | "publickeyhex_required"491  | "missing_payload"492  | "login_entries_only"493  | "passkey_not_fillable"494  | "invalid_webhook_url"495  | "invalid_feedback_endpoint"496  | "message_empty"497  | "network_error"498  | "no_reset_url"499  | "failed_to_open_tab"500  | "operation_failed"501  | "unknown_message_type";502503export interface MessageResponse {504  ok: boolean;505  data?: unknown;506  error?: string;507  unlocked?: boolean;508  // Set on UNLOCK responses when the vault decrypted but failed schema509  // validation (M7/COR-007). The popup may offer a history-restore flow.510  canRestoreFromHistory?: boolean;511}