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}5859/** One past password kept in an entry's {@link VaultEntry.passwordHistory}. */60export interface PasswordHistoryItem {61  /** The old password value, replaced by a newer one. */62  password: string;63  /**64   * When this password stopped being current — i.e. the `passwordChangedAt`65   * (or `createdAt`) it carried at the moment it was swapped out.66   */67  changedAt: number;68}6970export interface VaultEntry {71  id: string; // crypto.randomUUID()72  /**73   * Entry type. As of v2.11.0 passkeys are stored on `type:"login"` entries74   * via the `passkey` sub-object — `"passkey"` here is a legacy value still75   * accepted on read but rewritten to `"login"` on next vault save.76   */77  type?: "login" | "note" | "passkey" | "card";78  title: string;79  username?: string; // only for login entries80  email?: string; // separate email address — for sites that require both a username and an email81  password?: string; // only for login entries82  url?: string; // only for login entries83  /**84   * Additional sites this entry should match for autofill. Login entries only.85   * Each value is a full origin or URL (e.g. `https://login.foo.com`).86   * The vault domain index keys against the hostname of every entry in this87   * list, in addition to `url`.88   */89  additionalUrls?: string[];90  totp?: string; // base32 seed, stored encrypted — only for login entries91  notes?: string;92  breach?: number; // HIBP exposure count; 0 or undefined = clean — only for login entries93  /**94   * When the password field was last changed. Set on first-write of `password`95   * and refreshed on every subsequent change. Defaults to `createdAt` when96   * legacy entries are read by the advanced health analyser.97   */98  passwordChangedAt?: number;99  /**100   * Previously-used passwords for this entry, newest first. A snapshot of the101   * old password is pushed here automatically whenever the password changes102   * (see `updateEntry` in vault.ts). Capped at PASSWORD_HISTORY_MAX. Lets the103   * user reveal, copy, or restore a password they used before — handy when a104   * site rejects a rotation or an old credential resurfaces.105   */106  passwordHistory?: PasswordHistoryItem[];107  canary?: Canary;108  createdAt: number; // Date.now()109  modifiedAt: number;110  deletedAt?: number;111  tags?: string[];112  /** Passkey credential attached to this entry, if any. */113  passkey?: PasskeyData;114  // ── Legacy passkey flat fields (pre-v2.11.0). Populated by vault read115  // migration so that the old import/sanitize paths keep typing; new code116  // should always read `entry.passkey?.*` instead. The migration drops these117  // on next vault save. Do not introduce new readers of these fields.118  rpId?: string;119  rpName?: string;120  credentialId?: string;121  publicKeyCose?: string;122  privateKeyJwk?: JsonWebKey;123  userHandle?: string;124  userName?: string;125  userDisplayName?: string;126  algorithm?: -7 | -8;127  signCount?: number;128  aaguid?: string;129  backupEligible?: boolean;130  backupState?: boolean;131  lastUsedAt?: number;132  browser?: "chrome" | "firefox";133  transports?: string[];134  // Card entry fields135  cardholderName?: string;136  cardNumber?: string;       // full PAN, stored encrypted in vault137  expMonth?: string;138  expYear?: string;139  cvc?: string;140  cardNickname?: string;141  network?: CardNetwork;142  last4?: string;143}144145/**146 * Returns true when an entry has a passkey credential attached. After v2.11.0147 * migration this is the canonical check; pre-migration entries with a flat148 * `rpId`/`credentialId` shape get rewritten by the vault read pass before149 * any consumer sees them.150 */151export function hasPasskey(entry: VaultEntry): boolean {152  return entry.passkey !== undefined && entry.passkey.credentialId.length > 0;153}154155/**156 * Returns true when an entry is "passkey-only" — has a passkey credential157 * but no password to fill into a form. Login fields hide for these entries158 * and the inline autofill selector filters them out (signing in via the159 * passkey is a separate WebAuthn flow). Username may still be populated160 * (the migration mirrors passkey.userName onto the entry's username so the161 * domain-index/search keep working) and is not part of this discriminator.162 */163export function isPasskeyOnly(entry: VaultEntry): boolean {164  // An entry is "passkey only" when it holds SOLELY a passkey credential —165  // no password, no TOTP, and no dedicated email. Username is intentionally166  // excluded (the migration copies passkey.userName onto username for search).167  // Entries with passkey + TOTP or passkey + email are NOT passkey-only: they168  // carry fillable credentials and must show the full login-fields UI.169  return hasPasskey(entry) && !entry.password && !entry.totp && !entry.email;170}171172export interface LegacyVaultEntry {173  id: string;174  title: string;175  username: string;176  password: string;177  url: string;178  totp?: string;179  notes?: string;180  breach?: number;181  created: number;182  updated: number;183  deletedAt?: number;184}185186export interface CardEntry extends VaultEntry {187  type: "card";188  cardholderName: string;189  cardNumber: string;190  expMonth: string;191  expYear: string;192  cvc: string;193}194195196export interface PendingPasskeyRequest {197  requestId: number;198  type: "create" | "get";199  rpId: string;200  rpName: string;201  userName: string;202  userDisplayName?: string;203  /**204   * Firefox path: when present, the popup performs the navigator.credentials205   * call itself rather than completing a chrome.webAuthenticationProxy206   * request. Absent for Chrome (the existing webAuthenticationProxy flow).207   */208  browser?: "chrome" | "firefox";209  /** Firefox create: base64url challenge minted by the popup-context flow. */210  challenge?: string;211  /** Firefox create: base64url user handle. Generated if absent. */212  userHandle?: string;213}214215export interface PasskeyProviderState {216  supported: boolean;217  enabled: boolean;218  attached: boolean;219  browserLabel: string;220  statusLabel: string;221  conflict?: string;222}223224export interface StoredVault {225  version: 1; // AAD for AES-GCM --- prevents downgrade226  salt: string; // hex --- 16 bytes, CSPRNG, stored not secret227  nonce: string; // hex --- 12 bytes, CSPRNG, fresh per write228  ciphertext: string; // hex --- AES-256-GCM output229  tag: string; // hex --- 16-byte GCM auth tag230  // Recovery escrow: root key wrapped under recovery words via AES-256-GCM.231  // Absent on vaults created before v2.12 (migrateToRecovery adds them on first unlock).232  recovery_salt?: string; // hex --- 16 bytes, CSPRNG, HKDF salt for recovery key233  recovery_wrapped_root_key?: string; // hex --- AES-256-GCM ciphertext of 32-byte root key234  recovery_nonce?: string; // hex --- 12 bytes, fresh nonce for the above235  recovery_tag?: string; // hex --- 16-byte GCM auth tag for the above236  // Second wrapping of the same root key under the password-derived key.237  // Lets unlock() recover the rootKey bytes without the user's recovery238  // words, so GET_RECOVERY_WORDS works across lock/unlock cycles. Refreshed239  // on every password change so the words stay valid (H2/COR-006).240  pw_root_ciphertext?: string; // hex --- AES-256-GCM ciphertext of 32-byte root key (hex-encoded)241  pw_root_nonce?: string; // hex --- 12-byte nonce242  pw_root_tag?: string; // hex --- 16-byte GCM auth tag243}244245// Background-bound message types — sent from popup/content scripts,246// handled in src/background/messages.ts. Everything in this group must247// have a matching case in that file's switch statement.248export type MessageType =249  | "GET_SYNC_ALERTS"250  | "CLEAR_CLIPBOARD"251  | "GET_PENDING_VOUCHED_DEVICES"252  | "CONFIRM_VOUCHED_DEVICE"253  | "REJECT_VOUCHED_DEVICE"254  | "VOUCHED_DEVICE_PENDING"255  | "UNLOCK"256  | "LOCK"257  | "IS_UNLOCKED"258  | "HAS_VAULT"259  | "GET_ENTRIES"260  | "ADD_ENTRY"261  | "BATCH_ADD_ENTRIES"262  | "RESTORE_ENTRIES"263  | "CLEAR_VAULT_ENTRIES"264  | "UPDATE_ENTRY"265  | "ADD_ADDITIONAL_URL"266  | "DELETE_ENTRY"267  | "AUTOFILL_QUERY"268  | "COPY"269  | "CREATE_VAULT"270  | "GET_ENTRY_FOR_FILL"271  | "GET_ENTRY_FOR_EDIT"272  | "CHECK_ALL_BREACHES"273  | "GET_SETTINGS"274  | "UPDATE_SETTINGS"275  | "FIRE_CANARY_PING"276  | "ACTIVATE_LICENSE"277  | "GET_LICENSE"278  | "GET_LICENSE_KEY"279  | "IS_DURESS_ENABLED"280  | "SETUP_DURESS"281  | "DISABLE_DURESS"282  | "VERIFY_MAIN_PASSWORD"283  | "CHANGE_PASSWORD"284  | "GET_SITE_PASSWORD_POLICY"285  | "CHIRP_GET_LOCAL_IDENTITY"286  | "CHIRP_COMPLETE_PAIRING"287  | "CHIRP_LIST_PAIRED_DEVICES"288  | "CHIRP_UNPAIR_DEVICE"289  | "CHIRP_RENAME_LOCAL_DEVICE"290  | "TRIGGER_SYNC"291  | "GET_SYNC_STATE"292  | "GET_PENDING_PASSKEY"293  | "APPROVE_PASSKEY"294  | "DENY_PASSKEY"295  | "GET_PASSKEY_PROVIDER_STATE"296  | "SET_PASSKEY_PROVIDER_ENABLED"297  | "GET_DELETED_ENTRIES"298  | "RESTORE_ENTRY"299  | "PURGE_ENTRY"300  | "PURGE_EXPIRED_TRASH"301  | "GET_VAULT_HISTORY"302  | "RESTORE_VAULT_SNAPSHOT"303  | "COUNT_DUPLICATES"304  | "DEDUPLICATE_ENTRIES"305  | "RECORD_MANUAL_SUMMON"306  | "DECLINE_CARD_SAVE"307  | "IS_CARD_DECLINED"308  | "SUBMIT_FEEDBACK"309  | "GET_VAULT_STATUS"310  | "GET_ADVANCED_HEALTH_REPORT"311  | "DEACTIVATE_LICENSE"312  | "GET_IDENTITIES"313  | "DESTROY_VAULT"314  | "INITIATE_FIREFOX_PASSKEY_CREATE"315  | "COMPLETE_FIREFOX_PASSKEY_CREATE"316  | "PASSKEY_OFFER_DECLINE"317  | "GET_PASSKEY_OFFER_DECLINED"318  | "GET_PASSKEY_FOR_DOMAIN"319  // Firefox content-script proxy path (v2.12.0). Sent FROM the page-world320  // monkey-patch through the extension-world relay TO the background. See321  // src/shared/passkey-flags.ts for removal conditions.322  | "PASSKEY_HAS_CREDENTIALS"323  | "PASSKEY_CREATE"324  | "PASSKEY_GET"325  // Android / iOS message types — activate only when Capacitor.isNativePlatform() is true.326  | "UNLOCK_WITH_KEY"327  | "GET_DERIVED_KEY"328  // Recovery word messages329  | "VALIDATE_RECOVERY_WORDS"330  | "RECOVER_WITH_WORDS"331  | "GET_RECOVERY_WORDS"332  | "GET_IDENTITY_SUGGESTIONS"333  | "TOUCH_AUTO_LOCK"334  | "POPULATE_INLINE_VAULT"335  | "SAVE_NOTE"336  | "DELETE_NOTE"337  | "GET_NOTES"338  | "SEARCH_VAULT"339  | "ML_INIT"340  | "ML_PREDICT_BATCH"341  // Content-script-bound message types — sent BY the background TO content342  // scripts. They never reach messages.ts's switch. Kept in this union so343  // existing call sites type-check; do not add cases for them in the344  // background handler.345  | "PING"            // background → content: liveness probe346  | "SUMMON_AUTOFILL" // background → content: open the in-page palette347  | "VAULT_LOCKED"    // background → content/popup: vault just locked348  | "VAULT_UNLOCKED"  // background → content/popup: vault just unlocked349  | "PRO_GATE_TRIGGERED" // background → popup: a Pro feature was attempted on free350  | "PASSKEY_PRO_GATE" // background → content: show passkey Pro gate in inline popup351  | "OPEN_PRO_GATE" // content → background: open popup and navigate to License section352  | "OPEN_POPUP" // content → background: open the extension popup (e.g. to unlock)353  | "SHOW_PASSKEY_TOAST"    // background → content tab: show passkey auth toast354  | "DISMISS_PASSKEY_TOAST" // background → content tab: dismiss passkey auth toast355  | "PASSKEY_AUTH_RESPONSE" // content → background: user approved or denied the toast356  | "SHOULD_PLAY_CELEBRATION"357  | "MARK_CELEBRATION_PLAYED"358  // Peach Codex (v2.42.0). Generation runs in the popup — the SW only359  // sources vault data and applies the restored slots.360  | "GET_CODEX_VAULT_DATA"361  | "ESTIMATE_CODEX_PAGES"362  | "GENERATE_CODEX"363  | "RESTORE_FROM_CODEX";364365export type ProFeature =366  | "sync"367  | "passkeys"368  | "advanced_health"369  | "ios_app"370  | "codex"371  | "canary_entry"372  | "duress_vault";373374/**375 * License export shape included in PeachScript and encrypted JSON backups.376 * `celebrationPlayed` is intentionally absent — a new device deserves the moment.377 */378export interface PeachLicenseExport {379  key: string;380  activatedAt?: number;381}382383export interface AdvancedHealthEntryReport {384  id: string;385  title: string;386  domain: string;387  url?: string;388  score: number;389  ageDays: number;390  reasons: string[];391  factors: {392    breached: boolean;393    breachCount: number;394    reused: boolean;395    aged: boolean;396    weak: boolean;397    missingTotpOnSensitive: boolean;398  };399}400401export interface AdvancedHealthReport {402  vaultScore: number;403  generatedAt: number;404  entryCount: number;405  reusedGroups: number;406  agedCount: number;407  remediation: AdvancedHealthEntryReport[];408}409410export const ACCENT_COLORS = [411  { name: "peach",    hex: "#F49C70" },412  { name: "rose",     hex: "#FF8AA6" },413  { name: "plum",     hex: "#D597F2" },414  { name: "lavender", hex: "#A6A8FF" },415  { name: "sky",      hex: "#5BC8EE" },416  { name: "mint",     hex: "#5EE0B0" },417  { name: "sage",     hex: "#B5D870" },418  { name: "butter",   hex: "#FFD45A" },419  { name: "sand",     hex: "#EDBC85" },420  { name: "clay",     hex: "#F08660" },421  { name: "slate",    hex: "#80BEDE" },422  { name: "stone",    hex: "#C8B8A8" },423] as const;424425export type AccentColorName = typeof ACCENT_COLORS[number]["name"];426427export interface SavedIdentity {428  value: string;429  type: "email" | "username";430  lastUsed: number;431  useCount: number;432  exampleDomain?: string;433}434435export interface PasswordPolicy {436  minLength?: number;437  maxLength?: number;438  requiresUppercase?: boolean;439  requiresLowercase?: boolean;440  requiresNumbers?: boolean;441  requiresSymbols?: boolean;442  forbidsSymbols?: boolean;443  allowedSymbols?: string;444  /** Characters the site explicitly disallows. Filtered from every pool before generation. */445  forbiddenChars?: string;446}447448/**449 * A single vault history snapshot. The `vault_a` and `vault_b` fields are the450 * raw encrypted blobs from chrome.storage.local — already AES-256-GCM451 * protected by the master password, so storing them in history adds no452 * security surface.453 *454 * Snapshots are taken BEFORE every vault write so the saved blob represents455 * what is about to be lost, not what was just written. The reason field456 * documents the trigger so the UI can render "saved" / "synced" / "imported"457 * / "restored" labels next to each row.458 */459export interface VaultSnapshot {460  id: string;461  savedAt: number;462  reason: "local_save" | "sync_received" | "import" | "restore";463  vault_a: string;464  vault_b: string;465  /** Active entry count when the snapshot was taken; null if vault was locked. */466  entryCount: number | null;467}468469export interface VaultHistory {470  /** Newest first; capped at HISTORY_MAX (10). */471  snapshots: VaultSnapshot[];472}473474export interface Message {475  type: MessageType;476  payload?: unknown;477}478479// Canonical snake_case error codes returned by message handlers. Keep this480// union the authoritative catalogue — new handlers must reuse an entry or481// add one here. Free-form strings still appear (network/operation failures482// surface their raw .message), so error stays string at runtime; the union483// is the documented set callers should switch on.484export type ErrorCode =485  | "vault_locked"486  | "vault_corrupted"487  | "no_vault"488  | "entry_not_found"489  | "invalid_payload"490  | "invalid_message"491  | "invalid_sender"492  | "wrong_passphrase"493  | "incorrect_current_password"494  | "recovery_not_setup"495  | "android_only"496  | "not_available"497  | "pro_required"498  | "pairing_not_verified"499  | "sync_rejected_unpaired_initiator"500  | "vault_not_applied"501  | "url_required"502  | "domain_required"503  | "rpid_required"504  | "rpid_and_username_required"505  | "publickeyhex_required"506  | "missing_payload"507  | "login_entries_only"508  | "passkey_not_fillable"509  | "invalid_webhook_url"510  | "invalid_feedback_endpoint"511  | "message_empty"512  | "network_error"513  | "operation_failed"514  | "unknown_message_type";515516export interface MessageResponse {517  ok: boolean;518  data?: unknown;519  error?: string;520  unlocked?: boolean;521  // Set on UNLOCK responses when the vault decrypted but failed schema522  // validation (M7/COR-007). The popup may offer a history-restore flow.523  canRestoreFromHistory?: boolean;524}