Privacy-first password manager with built-in email aliasing. Fully encrypted and self-hostable.
/**
* Background script entry point - handles messages from the content script
*/
import '@/platform/ClientServices';
import { broadcastVaultUnlocked, handleAwaitPendingAuth, handleLoginWithMobile, handleLoginWithPassword, handleLoginWithTwoFactor, handleUnlockWithPassword, handleUnlockWithPin } from '@/entrypoints/background/AuthHandler';
import { handleResetAutoLockTimer, handlePopupHeartbeat, handleSetAutoLockTimeout, initializeAutoLockAlarm, handleAutoLockAlarm } from '@/entrypoints/background/AutolockTimeoutHandler';
import { handleClipboardCopied, handleSetClipboardClearTimeout, handleGetClipboardCountdownState } from '@/entrypoints/background/ClipboardClearHandler';
import { handleBlockLoginSaveForDomain, handleDisableAutofillForSite, handleDismissVaultLockedPopup, handleGetContentSettings, handleGetLanguage, handleIsLoginSaveBlocked, restrictContentScriptStorage } from '@/entrypoints/background/ContentSettingsHandler';
import { setupContextMenus } from '@/entrypoints/background/ContextMenu';
import { handleGetWebAuthnSettings, handleWebAuthnCreate, handleWebAuthnGet, handlePasskeyPopupResponse, handleGetRequestData, handleGetMatchingPasskeys, handleWebAuthnGetAssertion } from '@/entrypoints/background/PasskeyHandler';
import { handleOpenPopup, handlePopupWithItem, handleOpenPopupCreateCredential, handleToggleContextMenu } from '@/entrypoints/background/PopupMessageHandler';
import { handleStoreSavePromptState, handleGetSavePromptState, handleClearSavePromptState, handleGetLastAutofilled, handleClearLastAutofilled } from '@/entrypoints/background/SavePromptStateHandler';
import { handleGetTwoFactorPrompt, handleClearTwoFactorState } from '@/entrypoints/background/TwoFactorStateHandler';
import { handleCheckAuthStatus, handleClearPersistedFormValues, handleClearSession, handleClearVaultData, handleLockVault, handleGetFilteredItems, handleGetSearchItems, handleGetEncryptionKey, handleGetUnlockKeyDerivationParams, handleGetPersistedFormValues, handleGetVaultMigrationStatus, handlePersistFormValues, handleStoreAccountKey, handleStoreUnlockKeyDerivationParams, handleStoreEncryptedVaultChunk, handleGetSyncState, handleMigrateVaultManifest, handleFullVaultSync, handleGroupCreateVault, handleGroupInviteMember, handleGroupUpdateVault, handleGroupLookupAccountFingerprint, handleGroupInviteMemberByFingerprint, handleGroupAcceptManifestInvitation, handleEmailClaimTransfer, handleCheckLoginDuplicate, handleSaveLoginCredential, handleAddUrlToCredential, handleIsUrlLinkedToCredential, handleGetLoginSaveSettings, handleGetItemsWithTotp, handleSearchItemsWithTotp, handleGetTotpCodes, handleGenerateTotpCode, handleGetAutofillCredential, handleRecordItemUsage, type AutofillSender } from '@/entrypoints/background/VaultMessageHandler';
import { getCurrentAutofillFrameUrl } from '@/entrypoints/contentScript/AutofillFrameUrl';
import { logFailure } from '@/utils/Diagnostics';
import { LocalPreferencesService } from '@/utils/LocalPreferencesService';
import { onMessage, sendMessage } from "@/utils/messaging/ExtensionMessaging";
import type { IExtensionMessageProtocol } from "@/utils/messaging/ExtensionMessaging";
import { isRpIdAllowedForCaller } from '@/utils/passkey/RelyingPartyValidation';
import type { MatchingPasskeysResponse, WebAuthnAssertionResponse, WebAuthnPublicKeyGetPayload } from '@/utils/passkey/types';
import { getWebAuthnRequestRpId, validateWebAuthnRequest } from '@/utils/passkey/WebAuthnRequestValidation';
import type { WebAuthnBridgeRequest } from '@/utils/passkey/WebAuthnRequestValidation';
import { runStartupMigrations } from '@/migrations';
import type { ExtensionMessage, GetReturnType, MaybePromise, Message } from '@webext-core/messaging';
import { defineBackground, browser } from '#imports';
type WebAuthnMessageSender = {
origin?: string;
url?: string;
tab?: {
url?: string;
};
};
type TrustedWebAuthnSenderContext = {
origin: string;
host: string;
};
/**
* Resolve a trusted origin and host context from the message sender, returning null when the
* sender is not a secure (https or localhost) web origin.
*/
function getTrustedWebAuthnSenderContext(sender: WebAuthnMessageSender): TrustedWebAuthnSenderContext | null {
const senderOrigin = typeof sender.origin === 'string' && sender.origin !== 'null'
? sender.origin
: undefined;
const senderUrl = senderOrigin ?? sender.url ?? sender.tab?.url;
if (!senderUrl) {
return null;
}
try {
const url = new URL(senderUrl);
if (url.protocol !== 'https:' && !(url.protocol === 'http:' && url.hostname === 'localhost')) {
return null;
}
return {
origin: url.origin,
host: url.hostname,
};
} catch {
return null;
}
}
/**
* Resolve a trusted sender context and run a per-message validation check before invoking the
* handler. Returns `onInvalid` when the sender is not a trusted web origin or validation fails,
* so each WebAuthn message keeps its own validation rule and fallback shape while sharing the
* trust resolution and guard plumbing.
*/
async function withTrustedWebAuthnSender<T, U>(
sender: WebAuthnMessageSender,
validate: (context: TrustedWebAuthnSenderContext) => MaybePromise<boolean>,
handle: (context: TrustedWebAuthnSenderContext) => T,
onInvalid: U
): Promise<Awaited<T> | U> {
const senderContext = getTrustedWebAuthnSenderContext(sender);
if (!senderContext || !(await validate(senderContext))) {
return onInvalid;
}
return await handle(senderContext);
}
/**
* Validate a WebAuthn request and check that the sender may use the RP ID it names.
*/
async function isValidWebAuthnRequest(type: 'create' | 'get', request: WebAuthnBridgeRequest, context: TrustedWebAuthnSenderContext): Promise<boolean> {
if (!validateWebAuthnRequest(type, request, context.origin)) {
return false;
}
const rpId = getWebAuthnRequestRpId(type, request);
return rpId === undefined || (typeof rpId === 'string' && await isRpIdAllowedForCaller(rpId, context.origin, context.host));
}
/**
* True when the message comes from one of the extension's own pages (popup, expanded tab, passkey window),
* false for content scripts running inside web pages. Sensitive operations must never be serviceable from a content-script context.
*/
function isTrustedExtensionSender(sender: WebAuthnMessageSender): boolean {
const senderOrigin = typeof sender.origin === 'string' && sender.origin !== 'null' ? sender.origin : undefined;
const senderUrl = senderOrigin ?? sender.url ?? sender.tab?.url;
if (!senderUrl) {
return false;
}
try {
return new URL(senderUrl).origin === new URL(browser.runtime.getURL('')).origin;
} catch {
return false;
}
}
/**
* Register a handler that only the extension's own pages may call; a message from a content script is rejected.
*/
function onExtensionPageMessage<TType extends keyof IExtensionMessageProtocol>(
type: TType,
handler: (message: Message<IExtensionMessageProtocol, TType> & ExtensionMessage) => MaybePromise<GetReturnType<IExtensionMessageProtocol[TType]>>
): void {
onMessage(type, (message) => {
if (!isTrustedExtensionSender(message.sender)) {
throw new Error(`${type} is only available to extension pages`);
}
return handler(message);
});
}
/**
* Resolve the tab and frame URL of a content-script message from the browser-supplied sender.
*/
function getAutofillSender(sender: { url?: string; frameId?: number; tab?: { id?: number; url?: string } }): AutofillSender {
const url = sender.url ?? (sender.frameId === 0 ? sender.tab?.url : undefined);
let pageUrl: string | null = null;
try {
pageUrl = url ? getCurrentAutofillFrameUrl(new URL(url)) : null;
} catch {
pageUrl = null;
}
return { tabId: sender.tab?.id, pageUrl };
}
/**
* Host of the content-script frame that sent a message, from the browser-supplied sender.
*/
function getSenderHostname(sender: { url?: string; frameId?: number; tab?: { id?: number; url?: string } }): string | null {
const { pageUrl } = getAutofillSender(sender);
try {
return pageUrl ? new URL(pageUrl).hostname || null : null;
} catch {
return null;
}
}
/**
* Validate a WebAuthn create request against the sender's trusted origin, then forward it to the
* passkey create flow. Falls back when the sender is untrusted or validation fails.
*/
function handleValidatedWebAuthnCreate(data: WebAuthnBridgeRequest, sender: WebAuthnMessageSender): Promise<unknown> {
return withTrustedWebAuthnSender(
sender,
(ctx) => isValidWebAuthnRequest('create', data, ctx),
(ctx) => handleWebAuthnCreate({ ...data, origin: ctx.origin }),
{ fallback: true }
);
}
/**
* Validate a WebAuthn get request against the sender's trusted origin, then forward it to the
* passkey get flow. Falls back when the sender is untrusted or validation fails.
*/
function handleValidatedWebAuthnGet(data: WebAuthnBridgeRequest, sender: WebAuthnMessageSender): Promise<unknown> {
return withTrustedWebAuthnSender(
sender,
(ctx) => isValidWebAuthnRequest('get', data, ctx),
(ctx) => handleWebAuthnGet({ ...data, origin: ctx.origin }),
{ fallback: true }
);
}
/**
* Validate a request for the passkeys stored at an rpId against the sender's trusted host, then
* return the matching passkeys for the inline conditional-autofill dropdown. This only exposes
* passkeys for an rpId the requesting page is allowed to assert for.
*/
function handleValidatedGetMatchingPasskeys(
data: { rpId: string; allowCredentialIds?: string[] },
sender: WebAuthnMessageSender
): Promise<MatchingPasskeysResponse> {
return withTrustedWebAuthnSender(
sender,
async (ctx) => typeof data?.rpId === 'string' && await isRpIdAllowedForCaller(data.rpId, ctx.origin, ctx.host),
() => handleGetMatchingPasskeys(data),
{ success: false, locked: false, passkeys: [] }
);
}
/**
* Validate an inline passkey assertion request against the sender's trusted origin, then sign.
* The trusted origin is embedded in the signed client data.
*/
function handleValidatedWebAuthnGetAssertion(
data: { passkeyId: string; manifestId: string; origin: string; publicKey: WebAuthnPublicKeyGetPayload },
sender: WebAuthnMessageSender
): Promise<WebAuthnAssertionResponse> {
return withTrustedWebAuthnSender(
sender,
async (ctx) => typeof data?.passkeyId === 'string' && typeof data?.manifestId === 'string' && await isValidWebAuthnRequest('get', data, ctx),
(ctx) => handleWebAuthnGetAssertion({ ...data, origin: ctx.origin }),
{ success: false, error: 'Invalid request' }
);
}
/*
* Register alarm listener at top-level scope.
* [..] Move the event listener registration to the top level of your script.
* This ensures that Chrome will be able to immediately find and invoke your action's click handler,
* even if your extension hasn't finished executing its startup logic. [..]
* See: https://developer.chrome.com/docs/extensions/develop/migrate/to-service-workers
*/
browser.alarms.onAlarm.addListener(handleAutoLockAlarm);
export default defineBackground({
/**
* This is the main entry point for the background script.
*
* IMPORTANT: This function MUST remain synchronous (no async/await directly in
* the body). MV3 service workers can be terminated when idle and woken up by
* events; only listeners registered synchronously during script evaluation are
* guaranteed to be ready when the next event fires. Any asynchronous setup must
* run as a fire-and-forget IIFE so this function returns synchronously.
*/
main() {
// Keep content scripts (and so a compromised page renderer) out of storage.local where the browser supports it.
void restrictContentScriptStorage();
/*
* Register any synchronous event listeners first, before any await,
* so they're attached synchronously on service-worker wake-up.
*/
browser.commands.onCommand.addListener(async (command) => {
if (command !== "show-autofill-popup") {
return;
}
try {
const [tab] = await browser.tabs.query({ active: true, currentWindow: true });
if (!tab?.id) {
return;
}
const results = await browser.scripting.executeScript({
target: { tabId: tab.id },
func: getActiveElementIdentifier,
});
const elementIdentifier = results[0]?.result;
if (elementIdentifier) {
sendMessage('OPEN_AUTOFILL_POPUP', { elementIdentifier }, tab.id);
}
} catch (error) {
logFailure('Error handling show-autofill-popup command', error);
}
});
/*
* Listen for messages via @webext-core/messaging.
*/
onMessage('CHECK_AUTH_STATUS', () => handleCheckAuthStatus());
onExtensionPageMessage('GET_ENCRYPTION_KEY', () => handleGetEncryptionKey());
onExtensionPageMessage('GET_UNLOCK_KEY_DERIVATION_PARAMS', () => handleGetUnlockKeyDerivationParams());
onMessage('GET_FILTERED_ITEMS', ({ data, sender }) => handleGetFilteredItems(data, getAutofillSender(sender)));
onMessage('GET_SEARCH_ITEMS', ({ data }) => handleGetSearchItems(data));
onExtensionPageMessage('STORE_ACCOUNT_KEY', async ({ data }) => {
const result = await handleStoreAccountKey(data);
/*
* Storing the Account Key means the vault just became unlocked; let content scripts
* re-query any conditional passkey requests they parked while the vault was locked.
*/
if (result.success) {
void broadcastVaultUnlocked();
}
return result;
});
onExtensionPageMessage('STORE_UNLOCK_KEY_DERIVATION_PARAMS', ({ data }) => handleStoreUnlockKeyDerivationParams(data));
// Login and unlock run in the background so they complete when the popup closes mid-flow.
onExtensionPageMessage('AUTH_LOGIN', ({ data }) => handleLoginWithPassword(data));
onExtensionPageMessage('AUTH_LOGIN_TWO_FACTOR', ({ data }) => handleLoginWithTwoFactor(data));
onExtensionPageMessage('AUTH_LOGIN_MOBILE', ({ data }) => handleLoginWithMobile(data));
onExtensionPageMessage('AUTH_UNLOCK_PASSWORD', ({ data }) => handleUnlockWithPassword(data));
onExtensionPageMessage('AUTH_UNLOCK_PIN', ({ data }) => handleUnlockWithPin(data));
onExtensionPageMessage('AUTH_AWAIT_PENDING', () => handleAwaitPendingAuth());
onExtensionPageMessage('STORE_ENCRYPTED_VAULT', ({ data }) => handleStoreEncryptedVaultChunk(data));
onExtensionPageMessage('GET_SYNC_STATE', () => handleGetSyncState());
onExtensionPageMessage('FULL_VAULT_SYNC', ({ data }) => handleFullVaultSync(data));
onExtensionPageMessage('START_VAULT_SYNC', () => {
void handleFullVaultSync().catch(error => logFailure('Background vault sync failed', error));
return { success: true };
});
onExtensionPageMessage('GET_VAULT_MIGRATION_STATUS', () => handleGetVaultMigrationStatus());
onExtensionPageMessage('MIGRATE_VAULT_MANIFEST', () => handleMigrateVaultManifest());
onExtensionPageMessage('GROUP_CREATE_VAULT', ({ data }) => handleGroupCreateVault(data));
onExtensionPageMessage('GROUP_UPDATE_VAULT', ({ data }) => handleGroupUpdateVault(data));
onExtensionPageMessage('GROUP_INVITE_MEMBER', ({ data }) => handleGroupInviteMember(data));
onExtensionPageMessage('GROUP_LOOKUP_ACCOUNT_FINGERPRINT', ({ data }) => handleGroupLookupAccountFingerprint(data));
onExtensionPageMessage('GROUP_INVITE_MEMBER_BY_FINGERPRINT', ({ data }) => handleGroupInviteMemberByFingerprint(data));
onExtensionPageMessage('GROUP_ACCEPT_MANIFEST_INVITATION', ({ data }) => handleGroupAcceptManifestInvitation(data));
onExtensionPageMessage('EMAIL_CLAIM_TRANSFER', ({ data }) => handleEmailClaimTransfer(data));
onExtensionPageMessage('LOCK_VAULT', () => handleLockVault());
onExtensionPageMessage('CLEAR_SESSION', () => handleClearSession());
onExtensionPageMessage('CLEAR_VAULT_DATA', () => handleClearVaultData());
onMessage('OPEN_POPUP', () => handleOpenPopup());
onMessage('OPEN_POPUP_WITH_ITEM', ({ data }) => handlePopupWithItem(data));
onMessage('OPEN_POPUP_CREATE_CREDENTIAL', ({ data, sender }) => handleOpenPopupCreateCredential(data, sender));
onExtensionPageMessage('TOGGLE_CONTEXT_MENU', ({ data }) => handleToggleContextMenu(data));
onExtensionPageMessage('PERSIST_FORM_VALUES', ({ data }) => handlePersistFormValues(data));
onExtensionPageMessage('GET_PERSISTED_FORM_VALUES', () => handleGetPersistedFormValues());
onExtensionPageMessage('CLEAR_PERSISTED_FORM_VALUES', () => handleClearPersistedFormValues());
// Remember login save messages
onMessage('CHECK_LOGIN_DUPLICATE', ({ data, sender }) => handleCheckLoginDuplicate(data, getAutofillSender(sender)));
onMessage('SAVE_LOGIN_CREDENTIAL', ({ data, sender }) => handleSaveLoginCredential(data, getAutofillSender(sender)));
onMessage('ADD_URL_TO_CREDENTIAL', ({ data, sender }) => handleAddUrlToCredential(data, getAutofillSender(sender)));
onMessage('IS_URL_LINKED_TO_CREDENTIAL', ({ data, sender }) => handleIsUrlLinkedToCredential(data, getAutofillSender(sender)));
onMessage('GET_LOGIN_SAVE_SETTINGS', () => handleGetLoginSaveSettings());
onMessage('IS_LOGIN_SAVE_BLOCKED', ({ data }) => handleIsLoginSaveBlocked(data.domain));
onMessage('BLOCK_LOGIN_SAVE_FOR_DOMAIN', ({ data }) => handleBlockLoginSaveForDomain(data.domain));
// Local preferences for content scripts, which cannot read storage.local themselves
onMessage('GET_CONTENT_SETTINGS', ({ sender }) => handleGetContentSettings(getSenderHostname(sender)));
onMessage('DISABLE_AUTOFILL_FOR_SITE', ({ data, sender }) => handleDisableAutofillForSite(getSenderHostname(sender), data.temporary));
onMessage('DISMISS_VAULT_LOCKED_POPUP', () => handleDismissVaultLockedPopup());
onMessage('GET_LANGUAGE', () => handleGetLanguage());
// TOTP autofill messages
onMessage('GET_ITEMS_WITH_TOTP', ({ data, sender }) => handleGetItemsWithTotp(data, getAutofillSender(sender)));
onMessage('SEARCH_ITEMS_WITH_TOTP', ({ data }) => handleSearchItemsWithTotp(data));
onMessage('GET_TOTP_CODES', ({ data }) => handleGetTotpCodes(data));
onMessage('GENERATE_TOTP_CODE', ({ data, sender }) => handleGenerateTotpCode(data, getAutofillSender(sender)));
// Fill data for the one item picked in the in-page popup; records the pick (recently selected, last autofilled, usage)
onMessage('GET_AUTOFILL_CREDENTIAL', ({ data, sender }) => handleGetAutofillCredential(data, getAutofillSender(sender)));
// Record item usage (last used + counts) into the Stats data bucket; autofill from content scripts is recorded by the background
onExtensionPageMessage('RECORD_ITEM_USAGE', ({ data }) => handleRecordItemUsage(data));
// Remember login save state (for surviving page navigation)
onMessage('STORE_SAVE_PROMPT_STATE', ({ data, sender }) => handleStoreSavePromptState({ tabId: sender.tab!.id!, state: data }));
onMessage('GET_SAVE_PROMPT_STATE', ({ data, sender }) => handleGetSavePromptState({ tabId: sender.tab!.id!, ...data }));
onMessage('CLEAR_SAVE_PROMPT_STATE', ({ sender }) => handleClearSavePromptState({ tabId: sender.tab!.id! }));
// Track last autofilled credential (for "Add URL to existing credential" prompt)
onMessage('GET_LAST_AUTOFILLED', ({ data, sender }) => handleGetLastAutofilled({ tabId: sender.tab!.id!, ...data }));
onMessage('CLEAR_LAST_AUTOFILLED', ({ sender }) => handleClearLastAutofilled({ tabId: sender.tab!.id! }));
// Two-factor authentication state persistence
onExtensionPageMessage('GET_TWO_FACTOR_STATE', () => handleGetTwoFactorPrompt());
onExtensionPageMessage('CLEAR_TWO_FACTOR_STATE', () => handleClearTwoFactorState());
// Clipboard management messages
onMessage('CLIPBOARD_COPIED', () => handleClipboardCopied());
onExtensionPageMessage('SET_CLIPBOARD_CLEAR_TIMEOUT', ({ data }) => handleSetClipboardClearTimeout(data));
onExtensionPageMessage('GET_CLIPBOARD_COUNTDOWN_STATE', () => handleGetClipboardCountdownState());
// Auto-lock management messages
onMessage('RESET_AUTO_LOCK_TIMER', () => handleResetAutoLockTimer());
onExtensionPageMessage('SET_AUTO_LOCK_TIMEOUT', ({ data }) => handleSetAutoLockTimeout(data));
onExtensionPageMessage('POPUP_HEARTBEAT', () => handlePopupHeartbeat());
// Passkey/WebAuthn settings
onMessage('GET_WEBAUTHN_SETTINGS', ({ data }) => handleGetWebAuthnSettings(data));
// WebAuthn ceremony bridge (navigator.credentials.create/get interception)
onMessage('WEBAUTHN_CREATE', ({ data, sender }) => handleValidatedWebAuthnCreate(data, sender));
onMessage('WEBAUTHN_GET', ({ data, sender }) => handleValidatedWebAuthnGet(data, sender));
onMessage('WEBAUTHN_GET_ASSERTION', ({ data, sender }) => handleValidatedWebAuthnGetAssertion(data, sender));
// Inline conditional passkey autofill
onMessage('GET_MATCHING_PASSKEYS', ({ data, sender }) => handleValidatedGetMatchingPasskeys(data, sender));
// Passkey popup request/response flow
onExtensionPageMessage('GET_REQUEST_DATA', ({ data }) => handleGetRequestData(data));
onExtensionPageMessage('PASSKEY_POPUP_RESPONSE', ({ data }) => handlePasskeyPopupResponse(data));
/*
* Async setup (context menus, alarm restoration) runs in a fire-and-forget
* IIFE so main() returns synchronously. Listener registrations above are
* already synchronous and complete before this runs.
*/
(async () : Promise<void> => {
try {
/*
* Run one-time startup migrations.
*/
await runStartupMigrations();
} catch (error) {
logFailure('Error running startup migrations', error);
}
try {
const isContextMenuEnabled = await LocalPreferencesService.getGlobalContextMenuEnabled();
if (isContextMenuEnabled) {
await setupContextMenus();
}
} catch (error) {
logFailure('Error setting up context menus', error);
}
try {
/*
* Initialize auto-lock alarm system.
* This ensures the alarm is restored if the service worker was terminated.
* Note: The alarm listener is registered at top-level scope (see above).
*/
await initializeAutoLockAlarm();
} catch (error) {
logFailure('Error initializing auto-lock alarm', error);
}
})();
}
});
/**
* Activate AliasVault for the active input element.
*/
function getActiveElementIdentifier() : string {
const target = document.activeElement;
if (target instanceof HTMLInputElement) {
return target.id || target.name || '';
}
return '';
}