diff --git a/extension/src/shared/messages.ts b/extension/src/shared/messages.ts
new file mode 100644
index 0000000..a9b3765
--- /dev/null
+++ b/extension/src/shared/messages.ts
@@ -0,0 +1,68 @@
+import type { Entry, Manifest, ManifestEntry, VaultConfig, SetupState } from './types';
+
+// --- Request types (popup/content -> service worker) ---
+
+export type Request =
+  | { type: 'unlock'; passphrase: string }
+  | { type: 'lock' }
+  | { type: 'is_unlocked' }
+  | { type: 'list_entries'; group?: string }
+  | { type: 'get_entry'; id: string }
+  | { type: 'search_entries'; query: string }
+  | { type: 'add_entry'; entry: Entry }
+  | { type: 'update_entry'; id: string; entry: Entry }
+  | { type: 'delete_entry'; id: string }
+  | { type: 'get_totp'; id: string }
+  | { type: 'get_autofill_candidates'; url: string }
+  | { type: 'get_credentials'; id: string }
+  | { type: 'sync' }
+  | { type: 'get_setup_state' }
+  | { type: 'save_setup'; config: VaultConfig; imageBase64: string }
+  | { type: 'generate_password'; length: number }
+  | { type: 'fill_credentials'; username: string; password: string };
+
+// --- Response types (service worker -> popup/content) ---
+
+export type Response =
+  | { ok: true; data?: unknown }
+  | { ok: false; error: string };
+
+export interface UnlockResponse extends Extract<Response, { ok: true }> {
+  data: undefined;
+}
+
+export interface IsUnlockedResponse extends Extract<Response, { ok: true }> {
+  data: { unlocked: boolean };
+}
+
+export interface ListEntriesResponse extends Extract<Response, { ok: true }> {
+  data: { entries: Array<[string, ManifestEntry]> };
+}
+
+export interface GetEntryResponse extends Extract<Response, { ok: true }> {
+  data: { entry: Entry };
+}
+
+export interface SearchEntriesResponse extends Extract<Response, { ok: true }> {
+  data: { entries: Array<[string, ManifestEntry]> };
+}
+
+export interface TotpResponse extends Extract<Response, { ok: true }> {
+  data: { code: string; remaining_seconds: number };
+}
+
+export interface AutofillCandidatesResponse extends Extract<Response, { ok: true }> {
+  data: { candidates: Array<[string, ManifestEntry]> };
+}
+
+export interface CredentialsResponse extends Extract<Response, { ok: true }> {
+  data: { username: string; password: string };
+}
+
+export interface SetupStateResponse extends Extract<Response, { ok: true }> {
+  data: SetupState;
+}
+
+export interface GeneratePasswordResponse extends Extract<Response, { ok: true }> {
+  data: { password: string };
+}
diff --git a/extension/src/shared/types.ts b/extension/src/shared/types.ts
new file mode 100644
index 0000000..5351b1e
--- /dev/null
+++ b/extension/src/shared/types.ts
@@ -0,0 +1,42 @@
+/// Full credential entry (matches Rust Entry struct in idfoto-core).
+export interface Entry {
+  name: string;
+  url?: string;
+  username?: string;
+  password: string;
+  notes?: string;
+  totp_secret?: string;
+  group?: string;
+  created_at: string;
+  updated_at: string;
+}
+
+/// Lightweight manifest entry for listing/searching without full decrypt.
+export interface ManifestEntry {
+  name: string;
+  url?: string;
+  username?: string;
+  group?: string;
+  updated_at: string;
+}
+
+/// Encrypted manifest containing all entry metadata.
+export interface Manifest {
+  entries: Record<string, ManifestEntry>;
+  version: number;
+}
+
+/// Configuration for connecting to a git host.
+export interface VaultConfig {
+  hostType: 'gitea' | 'github';
+  hostUrl: string;
+  repoPath: string;
+  apiToken: string;
+}
+
+/// Persisted setup state in chrome.storage.local.
+export interface SetupState {
+  config: VaultConfig | null;
+  imageBase64: string | null;
+  isConfigured: boolean;
+}