From c185ce4dc9f6aff2e8a7b14c1c99c7e970cb8d57 Mon Sep 17 00:00:00 2001
From: olegberman <bermanoleg@gmail.com>
Date: Wed, 29 Jul 2026 14:21:39 -0400
Subject: [PATCH] Add push notifications and unread counters

---
 .github/workflows/staging-e2e.yml             |   8 +-
 CHANGELOG.md                                  |   8 +
 app/app.tsx                                   |   7 +
 app/components/layout/app-shell.tsx           |   4 +
 app/components/layout/mobile-navigation.tsx   |   4 +
 app/components/layout/sidebar.tsx             |  13 +-
 app/components/layout/top-bar.tsx             |   4 +
 app/features/auth/api.ts                      |   4 +
 app/features/inbox/inbox-page.tsx             |   6 +-
 app/features/notifications/api.ts             |  25 ++
 app/features/notifications/browser.ts         |  80 +++++++
 .../notifications/notification-settings.tsx   | 127 ++++++++++
 app/features/notifications/sign-out.ts        |  14 ++
 app/features/notifications/types.ts           |  28 +++
 .../notifications/use-notifications.ts        | 181 ++++++++++++++
 app/features/settings/settings-page.tsx       |   8 +
 app/lib/api-client.ts                         |   9 +-
 app/lib/routes.ts                             |   9 +-
 docs/deployment.md                            |  13 +-
 migrations/0006_push_notifications.sql        |  16 ++
 package.json                                  |   4 +-
 pnpm-lock.yaml                                | 110 +++++++++
 scripts/build-pwa.mjs                         |  69 ++++++
 scripts/hqbase/reset-d1.sql                   |   1 +
 scripts/release/deploy.mjs                    |  58 +++--
 test/integration/worker/notifications.test.ts | 223 ++++++++++++++++++
 test/unit/app/layout/mail-shell.test.tsx      |   8 +
 .../app/messages/conversation-reader.test.tsx |   2 +
 test/unit/app/notifications/browser.test.ts   |  65 +++++
 .../notification-settings.test.tsx            |  43 ++++
 test/unit/app/notifications/sign-out.test.ts  |  33 +++
 .../settings/settings-presentation.test.tsx   |  12 +
 test/unit/scripts/deploy.test.mjs             |  54 ++++-
 test/unit/scripts/pwa-build.test.mjs          |  13 +
 .../features/notifications/delivery.test.ts   | 134 +++++++++++
 test/unit/worker/index-notifications.test.ts  |  56 +++++
 vitest.worker.config.ts                       |   4 +-
 worker/email/inbound.ts                       |   4 +-
 worker/email/store-email.ts                   |  14 +-
 worker/features/notifications/delivery.ts     |  97 ++++++++
 worker/features/notifications/queries.ts      | 111 +++++++++
 worker/features/notifications/routes.ts       |  67 ++++++
 worker/features/notifications/types.ts        |  24 ++
 worker/index.ts                               |  12 +-
 worker/lib/env.ts                             |   3 +
 worker/routes/index.ts                        |   2 +
 46 files changed, 1751 insertions(+), 40 deletions(-)
 create mode 100644 app/features/notifications/api.ts
 create mode 100644 app/features/notifications/browser.ts
 create mode 100644 app/features/notifications/notification-settings.tsx
 create mode 100644 app/features/notifications/sign-out.ts
 create mode 100644 app/features/notifications/types.ts
 create mode 100644 app/features/notifications/use-notifications.ts
 create mode 100644 migrations/0006_push_notifications.sql
 create mode 100644 test/integration/worker/notifications.test.ts
 create mode 100644 test/unit/app/notifications/browser.test.ts
 create mode 100644 test/unit/app/notifications/notification-settings.test.tsx
 create mode 100644 test/unit/app/notifications/sign-out.test.ts
 create mode 100644 test/unit/worker/features/notifications/delivery.test.ts
 create mode 100644 test/unit/worker/index-notifications.test.ts
 create mode 100644 worker/features/notifications/delivery.ts
 create mode 100644 worker/features/notifications/queries.ts
 create mode 100644 worker/features/notifications/routes.ts
 create mode 100644 worker/features/notifications/types.ts

diff --git a/.github/workflows/staging-e2e.yml b/.github/workflows/staging-e2e.yml
index c35b451..2344415 100644
--- a/.github/workflows/staging-e2e.yml
+++ b/.github/workflows/staging-e2e.yml
@@ -70,7 +70,13 @@ jobs:
           echo "HQBASE_STAGING_AUTH_SECRET=$AUTH_SECRET" >> "$GITHUB_ENV"
           AUTH_SECRET="$AUTH_SECRET" node --input-type=module -e '
             import { writeFileSync } from "node:fs";
-            writeFileSync("/tmp/hqbase-e2e-secrets.json", `${JSON.stringify({ BETTER_AUTH_SECRET: process.env.AUTH_SECRET })}\n`, { mode: 0o600 });
+            import webpush from "web-push";
+            const vapid = webpush.generateVAPIDKeys();
+            writeFileSync("/tmp/hqbase-e2e-secrets.json", `${JSON.stringify({
+              BETTER_AUTH_SECRET: process.env.AUTH_SECRET,
+              VAPID_PUBLIC_KEY: vapid.publicKey,
+              VAPID_PRIVATE_KEY: vapid.privateKey
+            })}\n`, { mode: 0o600 });
           '
           pnpm build
           pnpm exec wrangler d1 migrations apply DB --remote --config "$config"
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0030c6d..897447f 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.1.23
+
+- Add explicit per-device Web Push notifications for installed iOS, Android, and desktop PWAs.
+- Show exact accessible Inbox and Catch-all unread totals in navigation, the document title, and
+  supported installed-app badges.
+- Generate customer-owned VAPID secrets during installation and updates while keeping notification
+  payloads free of mail metadata.
+
 ## 0.1.22
 
 - Keep the mobile and installed PWA shell below the iPhone Dynamic Island while preserving the
diff --git a/app/app.tsx b/app/app.tsx
index d34fec9..cf6c45d 100644
--- a/app/app.tsx
+++ b/app/app.tsx
@@ -12,6 +12,7 @@ import type { Mailbox } from "@/features/mailboxes/types";
 import { listConversations, listMessages } from "@/features/messages/api";
 import { mergeIncomingMessageIds } from "@/features/messages/incoming-sound";
 import type { ConversationSummary } from "@/features/messages/types";
+import { useNotifications } from "@/features/notifications/use-notifications";
 import { SettingsPage } from "@/features/settings/settings-page";
 import { getSetupStatus } from "@/features/setup/api";
 import { SetupPage } from "@/features/setup/setup-page";
@@ -91,6 +92,9 @@ export function App(): React.ReactElement {
     });
     setConversations(nextConversations);
   }, [activeFolder, mailboxId, search, user]);
+  const notifications = useNotifications(currentUserId, () => {
+    void reloadConversations();
+  });
 
   React.useEffect(() => {
     void reload();
@@ -184,6 +188,7 @@ export function App(): React.ReactElement {
         immersiveOnCompact={activeFolder !== "settings" && selectedId !== null}
         mailboxId={mailboxId}
         mailboxes={contentMailboxes}
+        unread={notifications.unread}
         search={search}
         user={user}
         updateInProgress={updateMonitor.progress !== null}
@@ -215,6 +220,7 @@ export function App(): React.ReactElement {
                 activeTab={settingsTab}
                 canManage={user.role === "owner" || user.role === "admin"}
                 mailboxes={mailboxes}
+                notifications={notifications}
                 setup={setup}
                 users={users}
                 onRefresh={() => void reload()}
@@ -231,6 +237,7 @@ export function App(): React.ReactElement {
                 mailboxes={contentMailboxes}
                 selectedId={selectedId}
                 onRefresh={() => void reloadConversations()}
+                onUnreadChange={notifications.refresh}
                 onMessageRouteChange={(folder, messageId) =>
                   navigate({ kind: "mail", folder, messageId })
                 }
diff --git a/app/components/layout/app-shell.tsx b/app/components/layout/app-shell.tsx
index f7d24b4..1e1f1a9 100644
--- a/app/components/layout/app-shell.tsx
+++ b/app/components/layout/app-shell.tsx
@@ -1,6 +1,7 @@
 import type * as React from "react";
 import type { CurrentUser } from "@/features/auth/types";
 import type { Mailbox } from "@/features/mailboxes/types";
+import type { UnreadCounts } from "@/features/notifications/types";
 import type { UpdateStatus } from "@/features/updates/types";
 import { UpdateBanner } from "@/features/updates/update-banner";
 import { cn } from "@/lib/cn";
@@ -18,6 +19,7 @@ type AppShellProps = {
   user: CurrentUser;
   updateInProgress: boolean;
   updateStatus: UpdateStatus | null;
+  unread: UnreadCounts;
   onCompose: () => void;
   onFolderChange: (folder: FolderId) => void;
   onMailboxChange: (mailboxId: string) => void;
@@ -31,6 +33,7 @@ export function AppShell(props: AppShellProps): React.ReactElement {
     <div className="flex h-screen h-[100dvh] overflow-hidden bg-background pt-[env(safe-area-inset-top)] text-foreground">
       <Sidebar
         activeFolder={props.activeFolder}
+        unread={props.unread}
         user={props.user}
         onFolderChange={props.onFolderChange}
         onSignedOut={props.onSignedOut}
@@ -39,6 +42,7 @@ export function AppShell(props: AppShellProps): React.ReactElement {
         <div className={cn(props.immersiveOnCompact && "hidden lg:contents")}>
           <TopBar
             activeFolder={props.activeFolder}
+            unread={props.unread}
             mailboxId={props.mailboxId}
             mailboxes={props.mailboxes}
             search={props.search}
diff --git a/app/components/layout/mobile-navigation.tsx b/app/components/layout/mobile-navigation.tsx
index 292725a..e82b71f 100644
--- a/app/components/layout/mobile-navigation.tsx
+++ b/app/components/layout/mobile-navigation.tsx
@@ -5,18 +5,21 @@ import { Button } from "@/components/ui/button";
 import { Sheet, SheetContent, SheetTitle, SheetTrigger } from "@/components/ui/sheet";
 import type { CurrentUser } from "@/features/auth/types";
 import { McpConnectionDialog } from "@/features/mcp/connection-dialog";
+import type { UnreadCounts } from "@/features/notifications/types";
 import type { FolderId } from "@/lib/routes";
 import { Sidebar } from "./sidebar";
 
 type MobileNavigationProps = {
   activeFolder: FolderId;
   user: CurrentUser;
+  unread: UnreadCounts;
   onFolderChange: (folder: FolderId) => void;
   onSignedOut: () => void;
 };
 
 export function MobileNavigation({
   activeFolder,
+  unread,
   user,
   onFolderChange,
   onSignedOut
@@ -61,6 +64,7 @@ export function MobileNavigation({
           <SheetTitle className="sr-only">Navigation</SheetTitle>
           <Sidebar
             activeFolder={activeFolder}
+            unread={unread}
             drawerAction={
               <Button
                 className="h-11 w-full justify-start gap-2.5 px-2.5 text-sm font-normal text-muted-foreground"
diff --git a/app/components/layout/sidebar.tsx b/app/components/layout/sidebar.tsx
index 36bbc00..95f3e54 100644
--- a/app/components/layout/sidebar.tsx
+++ b/app/components/layout/sidebar.tsx
@@ -4,6 +4,7 @@ import type * as React from "react";
 
 import { Button } from "@/components/ui/button";
 import type { CurrentUser } from "@/features/auth/types";
+import type { UnreadCounts } from "@/features/notifications/types";
 import { ThemeSwitcher } from "@/features/theme/theme-switcher";
 import { cn } from "@/lib/cn";
 import type { FolderId } from "@/lib/routes";
@@ -14,6 +15,7 @@ type SidebarProps = {
   activeFolder: FolderId;
   drawerAction?: React.ReactNode;
   user: CurrentUser;
+  unread: UnreadCounts;
   onFolderChange: (folder: FolderId) => void;
   onSignedOut: () => void;
   variant?: "desktop" | "drawer";
@@ -32,6 +34,7 @@ const icons: Record<FolderId, LucideIcon> = {
 export function Sidebar({
   activeFolder,
   drawerAction,
+  unread,
   user,
   onFolderChange,
   onSignedOut,
@@ -55,6 +58,8 @@ export function Sidebar({
       <nav className="flex flex-1 flex-col gap-0.5">
         {mailFolders.map((folder) => {
           const Icon = icons[folder.id];
+          const unreadCount =
+            folder.id === "inbox" ? unread.inbox : folder.id === "catchall" ? unread.catchall : 0;
           return (
             <Button
               asChild
@@ -77,7 +82,13 @@ export function Sidebar({
                 }}
               >
                 <Icon />
-                {folder.label}
+                <span className="min-w-0 flex-1 truncate">{folder.label}</span>
+                {unreadCount > 0 ? (
+                  <span className="ml-auto font-mono text-[11px] text-foreground">
+                    <span className="sr-only">{unreadCount} unread</span>
+                    <span aria-hidden="true">{unreadCount.toLocaleString()}</span>
+                  </span>
+                ) : null}
               </a>
             </Button>
           );
diff --git a/app/components/layout/top-bar.tsx b/app/components/layout/top-bar.tsx
index ae69b6d..94e2755 100644
--- a/app/components/layout/top-bar.tsx
+++ b/app/components/layout/top-bar.tsx
@@ -14,6 +14,7 @@ import {
 import type { CurrentUser } from "@/features/auth/types";
 import type { Mailbox } from "@/features/mailboxes/types";
 import { McpConnectionDialog } from "@/features/mcp/connection-dialog";
+import type { UnreadCounts } from "@/features/notifications/types";
 import type { FolderId } from "@/lib/routes";
 import { MobileNavigation } from "./mobile-navigation";
 
@@ -23,6 +24,7 @@ type TopBarProps = {
   mailboxes: Mailbox[];
   mailboxId: string;
   search: string;
+  unread: UnreadCounts;
   onCompose: () => void;
   onFolderChange: (folder: FolderId) => void;
   onMailboxChange: (mailboxId: string) => void;
@@ -36,6 +38,7 @@ export function TopBar({
   mailboxes,
   mailboxId,
   search,
+  unread,
   onCompose,
   onFolderChange,
   onMailboxChange,
@@ -49,6 +52,7 @@ export function TopBar({
     <header className="flex h-14 w-full shrink-0 items-center gap-2 border-b bg-background px-3 md:px-4">
       <MobileNavigation
         activeFolder={activeFolder}
+        unread={unread}
         user={user}
         onFolderChange={onFolderChange}
         onSignedOut={onSignedOut}
diff --git a/app/features/auth/api.ts b/app/features/auth/api.ts
index 12f0196..3432d7c 100644
--- a/app/features/auth/api.ts
+++ b/app/features/auth/api.ts
@@ -1,3 +1,4 @@
+import { disableCurrentDeviceNotificationsBeforeSignOut } from "@/features/notifications/sign-out";
 import { apiGet } from "@/lib/api-client";
 import type { CurrentUser } from "./types";
 
@@ -30,6 +31,9 @@ export async function signIn(email: string, password: string): Promise<string |
 }
 
 export async function signOut(): Promise<void> {
+  await disableCurrentDeviceNotificationsBeforeSignOut().catch(() => {
+    // Signing out remains available if browser notification cleanup is unavailable.
+  });
   await fetch("/api/auth/sign-out", {
     body: JSON.stringify({}),
     credentials: "include",
diff --git a/app/features/inbox/inbox-page.tsx b/app/features/inbox/inbox-page.tsx
index 3950b87..58c7b90 100644
--- a/app/features/inbox/inbox-page.tsx
+++ b/app/features/inbox/inbox-page.tsx
@@ -18,6 +18,7 @@ type InboxPageProps = {
   mailboxes: Mailbox[];
   selectedId: string | null;
   onRefresh: () => void;
+  onUnreadChange: () => void;
   onMessageRouteChange: (folder: MailFolderId, messageId: string | null) => void;
   onSelect: (messageId: string) => void;
 };
@@ -28,6 +29,7 @@ export function InboxPage({
   mailboxes,
   selectedId,
   onRefresh,
+  onUnreadChange,
   onMessageRouteChange,
   onSelect
 }: InboxPageProps): React.ReactElement {
@@ -76,6 +78,7 @@ export function InboxPage({
                 );
               }
               onRefreshRef.current();
+              onUnreadChange();
             })
             .catch(() => undefined);
         }
@@ -91,7 +94,7 @@ export function InboxPage({
     return () => {
       cancelled = true;
     };
-  }, [activeFolder, selectedId]);
+  }, [activeFolder, onUnreadChange, selectedId]);
 
   const selectedThreadId =
     thread[0]?.threadId ??
@@ -117,6 +120,7 @@ export function InboxPage({
     if (!selectedId) return;
     await runConversationAction(selectedId, action, activeFolder);
     onRefresh();
+    onUnreadChange();
     if (
       action === "archive" ||
       action === "trash" ||
diff --git a/app/features/notifications/api.ts b/app/features/notifications/api.ts
new file mode 100644
index 0000000..61423c2
--- /dev/null
+++ b/app/features/notifications/api.ts
@@ -0,0 +1,25 @@
+import { apiDelete, apiGet, apiPut } from "@/lib/api-client";
+import type { NotificationStatus } from "./types";
+
+export type SerializedPushSubscription = {
+  endpoint: string;
+  expirationTime: number | null;
+  keys: {
+    auth: string;
+    p256dh: string;
+  };
+};
+
+export function getNotificationStatus(): Promise<NotificationStatus> {
+  return apiGet<NotificationStatus>("/api/notifications/status");
+}
+
+export async function saveNotificationSubscription(
+  subscription: SerializedPushSubscription
+): Promise<void> {
+  await apiPut("/api/notifications/subscription", subscription);
+}
+
+export async function deleteNotificationSubscription(endpoint: string): Promise<void> {
+  await apiDelete("/api/notifications/subscription", { endpoint });
+}
diff --git a/app/features/notifications/browser.ts b/app/features/notifications/browser.ts
new file mode 100644
index 0000000..98c72df
--- /dev/null
+++ b/app/features/notifications/browser.ts
@@ -0,0 +1,80 @@
+import type { SerializedPushSubscription } from "./api";
+import type { UnreadCounts } from "./types";
+
+type BadgeNavigator = Navigator & {
+  clearAppBadge?: () => Promise<void>;
+  setAppBadge?: (count?: number) => Promise<void>;
+};
+
+export function supportsPushNotifications(): boolean {
+  return "Notification" in window && "serviceWorker" in navigator && "PushManager" in window;
+}
+
+export async function currentPushSubscription(): Promise<PushSubscription | null> {
+  if (!supportsPushNotifications()) return null;
+  const registration = await navigator.serviceWorker.ready;
+  return registration.pushManager.getSubscription();
+}
+
+export async function subscribeToPush(publicKey: string): Promise<PushSubscription> {
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") {
+    throw new Error(
+      permission === "denied"
+        ? "Notifications are blocked in your browser or system settings."
+        : "Notification permission was not granted."
+    );
+  }
+  const registration = await navigator.serviceWorker.ready;
+  return (
+    (await registration.pushManager.getSubscription()) ??
+    (await registration.pushManager.subscribe({
+      applicationServerKey: base64UrlToBytes(publicKey),
+      userVisibleOnly: true
+    }))
+  );
+}
+
+export function serializePushSubscription(
+  subscription: PushSubscription
+): SerializedPushSubscription {
+  const serialized = subscription.toJSON();
+  const auth = serialized.keys?.auth;
+  const p256dh = serialized.keys?.p256dh;
+  if (!serialized.endpoint || !auth || !p256dh) {
+    throw new Error("The browser returned an incomplete push subscription.");
+  }
+  return {
+    endpoint: serialized.endpoint,
+    expirationTime: serialized.expirationTime ?? null,
+    keys: { auth, p256dh }
+  };
+}
+
+export async function applyUnreadIndicators(unread: UnreadCounts): Promise<void> {
+  document.title = unread.total > 0 ? `(${unread.total}) HQBase` : "HQBase";
+  const badgeNavigator = navigator as BadgeNavigator;
+  try {
+    if (unread.total > 0 && badgeNavigator.setAppBadge) {
+      await badgeNavigator.setAppBadge(unread.total);
+    } else if (unread.total === 0 && badgeNavigator.clearAppBadge) {
+      await badgeNavigator.clearAppBadge();
+    }
+  } catch {
+    // In-app counts remain authoritative when the platform declines app badging.
+  }
+}
+
+export function notificationPermission(): NotificationPermission | "unsupported" {
+  return supportsPushNotifications() ? Notification.permission : "unsupported";
+}
+
+function base64UrlToBytes(value: string): Uint8Array<ArrayBuffer> {
+  const padding = "=".repeat((4 - (value.length % 4)) % 4);
+  const binary = atob(`${value}${padding}`.replaceAll("-", "+").replaceAll("_", "/"));
+  const bytes = new Uint8Array(new ArrayBuffer(binary.length));
+  for (let index = 0; index < binary.length; index += 1) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
diff --git a/app/features/notifications/notification-settings.tsx b/app/features/notifications/notification-settings.tsx
new file mode 100644
index 0000000..aef40e0
--- /dev/null
+++ b/app/features/notifications/notification-settings.tsx
@@ -0,0 +1,127 @@
+import { Bell, BellOff } from "lucide-react";
+import type * as React from "react";
+
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import { Button } from "@/components/ui/button";
+import { SettingsSection } from "@/features/settings/settings-section";
+import type { NotificationController, NotificationDeviceState } from "./types";
+
+export function NotificationSettings({
+  notifications
+}: {
+  notifications: NotificationController;
+}): React.ReactElement {
+  const stateCopy = copyForState(notifications.deviceState);
+  return (
+    <SettingsSection
+      action={
+        notifications.deviceState === "enabled" ? (
+          <Button
+            disabled={notifications.isBusy}
+            size="sm"
+            type="button"
+            variant="outline"
+            onClick={() => void notifications.disable()}
+          >
+            <BellOff />
+            {notifications.isBusy ? "Disabling…" : "Disable on this device"}
+          </Button>
+        ) : (
+          <Button
+            disabled={
+              notifications.isBusy ||
+              notifications.deviceState === "checking" ||
+              notifications.deviceState === "blocked" ||
+              notifications.deviceState === "unsupported" ||
+              notifications.deviceState === "unconfigured"
+            }
+            size="sm"
+            type="button"
+            onClick={() => void notifications.enable()}
+          >
+            <Bell />
+            {notifications.isBusy ? "Enabling…" : "Enable notifications"}
+          </Button>
+        )
+      }
+      description="New-mail alerts and unread badges for this browser or installed app"
+      title="Notifications"
+    >
+      <div className="divide-y border-y text-sm">
+        <div className="flex items-start justify-between gap-6 py-3">
+          <div>
+            <p className="font-medium">This device</p>
+            <p className="mt-1 text-xs text-muted-foreground">{stateCopy.description}</p>
+          </div>
+          <span className="shrink-0 text-xs text-muted-foreground">{stateCopy.label}</span>
+        </div>
+        <div className="flex items-start justify-between gap-6 py-3">
+          <div>
+            <p className="font-medium">Unread mail</p>
+            <p className="mt-1 text-xs text-muted-foreground">
+              Inbox and Catch-all messages you can access
+            </p>
+          </div>
+          <span className="shrink-0 font-mono text-xs">
+            <span className="sr-only">{notifications.unread.total} unread messages</span>
+            <span aria-hidden="true">{notifications.unread.total}</span>
+          </span>
+        </div>
+      </div>
+      <p className="text-xs leading-relaxed text-muted-foreground">
+        Notifications use a minimal encrypted payload with an unread count and an HQBase route.
+        Sender, recipient, subject, message text, and attachment details are never included.
+        Enabling another device does not disable this one.
+      </p>
+      {notifications.deviceState === "blocked" ? (
+        <Alert>
+          <AlertDescription>
+            Notifications are blocked. Allow HQBase in your browser or system notification settings,
+            then return here.
+          </AlertDescription>
+        </Alert>
+      ) : null}
+      {notifications.error ? (
+        <Alert variant="destructive">
+          <AlertDescription>{notifications.error}</AlertDescription>
+        </Alert>
+      ) : null}
+    </SettingsSection>
+  );
+}
+
+function copyForState(state: NotificationDeviceState): {
+  description: string;
+  label: string;
+} {
+  switch (state) {
+    case "enabled":
+      return {
+        description: "This device receives visible alerts when accessible mail arrives.",
+        label: "Enabled"
+      };
+    case "available":
+      return {
+        description: "Permission is requested only after you choose Enable notifications.",
+        label: "Off"
+      };
+    case "blocked":
+      return {
+        description: "Permission is disabled in the browser or operating-system settings.",
+        label: "Blocked"
+      };
+    case "unsupported":
+      return {
+        description:
+          "Install HQBase to the iOS Home Screen, or use a browser that supports Web Push.",
+        label: "Unavailable"
+      };
+    case "unconfigured":
+      return {
+        description: "This installation needs its generated Web Push keys before alerts can start.",
+        label: "Unavailable"
+      };
+    case "checking":
+      return { description: "Checking this device and installation.", label: "Checking" };
+  }
+}
diff --git a/app/features/notifications/sign-out.ts b/app/features/notifications/sign-out.ts
new file mode 100644
index 0000000..8eaaf29
--- /dev/null
+++ b/app/features/notifications/sign-out.ts
@@ -0,0 +1,14 @@
+import { deleteNotificationSubscription } from "./api";
+import { currentPushSubscription } from "./browser";
+
+export async function disableCurrentDeviceNotificationsBeforeSignOut(): Promise<void> {
+  const subscription = await currentPushSubscription();
+  if (!subscription) return;
+  try {
+    await deleteNotificationSubscription(subscription.endpoint);
+  } finally {
+    // Stop this browser from receiving mail even when the server cleanup must
+    // be retried through the push service's normal 404/410 pruning.
+    await subscription.unsubscribe();
+  }
+}
diff --git a/app/features/notifications/types.ts b/app/features/notifications/types.ts
new file mode 100644
index 0000000..f153ca1
--- /dev/null
+++ b/app/features/notifications/types.ts
@@ -0,0 +1,28 @@
+export type UnreadCounts = {
+  catchall: number;
+  inbox: number;
+  total: number;
+};
+
+export type NotificationStatus = {
+  unread: UnreadCounts;
+  vapidPublicKey: string | null;
+};
+
+export type NotificationDeviceState =
+  | "checking"
+  | "enabled"
+  | "available"
+  | "blocked"
+  | "unsupported"
+  | "unconfigured";
+
+export type NotificationController = {
+  deviceState: NotificationDeviceState;
+  disable: () => Promise<void>;
+  enable: () => Promise<void>;
+  error: string | null;
+  isBusy: boolean;
+  refresh: () => Promise<void>;
+  unread: UnreadCounts;
+};
diff --git a/app/features/notifications/use-notifications.ts b/app/features/notifications/use-notifications.ts
new file mode 100644
index 0000000..093643d
--- /dev/null
+++ b/app/features/notifications/use-notifications.ts
@@ -0,0 +1,181 @@
+import * as React from "react";
+
+import {
+  deleteNotificationSubscription,
+  getNotificationStatus,
+  saveNotificationSubscription
+} from "./api";
+import {
+  applyUnreadIndicators,
+  currentPushSubscription,
+  notificationPermission,
+  serializePushSubscription,
+  subscribeToPush,
+  supportsPushNotifications
+} from "./browser";
+import type {
+  NotificationController,
+  NotificationDeviceState,
+  NotificationStatus,
+  UnreadCounts
+} from "./types";
+
+const emptyUnread: UnreadCounts = { catchall: 0, inbox: 0, total: 0 };
+const refreshIntervalMs = 10_000;
+
+export function useNotifications(
+  userId: string | null,
+  onForegroundPush: () => void
+): NotificationController {
+  const [status, setStatus] = React.useState<NotificationStatus>({
+    unread: emptyUnread,
+    vapidPublicKey: null
+  });
+  const [deviceState, setDeviceState] = React.useState<NotificationDeviceState>("checking");
+  const [isBusy, setIsBusy] = React.useState(false);
+  const [error, setError] = React.useState<string | null>(null);
+  const reconciledEndpoint = React.useRef<string | null>(null);
+  const onForegroundPushRef = React.useRef(onForegroundPush);
+  React.useEffect(() => {
+    onForegroundPushRef.current = onForegroundPush;
+  }, [onForegroundPush]);
+
+  const refresh = React.useCallback(async () => {
+    if (!userId) {
+      setStatus({ unread: emptyUnread, vapidPublicKey: null });
+      setDeviceState("checking");
+      await applyUnreadIndicators(emptyUnread);
+      return;
+    }
+    const nextStatus = await getNotificationStatus();
+    setStatus(nextStatus);
+    await applyUnreadIndicators(nextStatus.unread);
+    await reconcileDevice(nextStatus, reconciledEndpoint, setDeviceState);
+  }, [userId]);
+
+  React.useEffect(() => {
+    if (!userId) {
+      void applyUnreadIndicators(emptyUnread);
+      return;
+    }
+    let active = true;
+    const runRefresh = async () => {
+      try {
+        await refresh();
+        if (active) setError(null);
+      } catch {
+        // A later focus, foreground push, or interval retries without interrupting mail.
+      }
+    };
+    const handleFocus = () => void runRefresh();
+    const handleServiceWorkerMessage = (event: MessageEvent) => {
+      if (event.data?.type !== "hqbase:push-received") return;
+      onForegroundPushRef.current();
+      void runRefresh();
+    };
+
+    void runRefresh();
+    window.addEventListener("focus", handleFocus);
+    navigator.serviceWorker?.addEventListener("message", handleServiceWorkerMessage);
+    const interval = window.setInterval(runRefresh, refreshIntervalMs);
+    return () => {
+      active = false;
+      window.clearInterval(interval);
+      window.removeEventListener("focus", handleFocus);
+      navigator.serviceWorker?.removeEventListener("message", handleServiceWorkerMessage);
+    };
+  }, [refresh, userId]);
+
+  const enable = React.useCallback(async () => {
+    setIsBusy(true);
+    setError(null);
+    let nextStatus = status;
+    try {
+      nextStatus = status.vapidPublicKey ? status : await getNotificationStatus();
+      setStatus(nextStatus);
+      if (!nextStatus.vapidPublicKey) {
+        throw new Error("Push notifications are not configured for this HQBase installation.");
+      }
+      const subscription = await subscribeToPush(nextStatus.vapidPublicKey);
+      const serialized = serializePushSubscription(subscription);
+      await saveNotificationSubscription(serialized);
+      reconciledEndpoint.current = serialized.endpoint;
+      setStatus(nextStatus);
+      setDeviceState("enabled");
+      await applyUnreadIndicators(nextStatus.unread);
+    } catch (nextError) {
+      setError(
+        nextError instanceof Error ? nextError.message : "Notifications could not be enabled."
+      );
+      setDeviceState(deviceStateFromBrowser(nextStatus.vapidPublicKey));
+    } finally {
+      setIsBusy(false);
+    }
+  }, [status]);
+
+  const disable = React.useCallback(async () => {
+    setIsBusy(true);
+    setError(null);
+    try {
+      const subscription = await currentPushSubscription();
+      if (subscription) {
+        try {
+          await deleteNotificationSubscription(subscription.endpoint);
+        } finally {
+          // Local unsubscribe is the privacy boundary. A stale server row is
+          // harmless and is pruned when its push endpoint returns 404/410.
+          await subscription.unsubscribe();
+        }
+      }
+      reconciledEndpoint.current = null;
+      setDeviceState(deviceStateFromBrowser(status.vapidPublicKey));
+    } catch (nextError) {
+      setError(
+        nextError instanceof Error ? nextError.message : "Notifications could not be disabled."
+      );
+    } finally {
+      setIsBusy(false);
+    }
+  }, [status.vapidPublicKey]);
+
+  return {
+    deviceState,
+    disable,
+    enable,
+    error,
+    isBusy,
+    refresh,
+    unread: status.unread
+  };
+}
+
+async function reconcileDevice(
+  status: NotificationStatus,
+  reconciledEndpoint: React.MutableRefObject<string | null>,
+  setDeviceState: React.Dispatch<React.SetStateAction<NotificationDeviceState>>
+): Promise<void> {
+  const initialState = deviceStateFromBrowser(status.vapidPublicKey);
+  if (initialState !== "available") {
+    setDeviceState(initialState);
+    return;
+  }
+  const subscription = await currentPushSubscription();
+  if (!subscription) {
+    reconciledEndpoint.current = null;
+    setDeviceState("available");
+    return;
+  }
+  if (reconciledEndpoint.current !== subscription.endpoint) {
+    await saveNotificationSubscription(serializePushSubscription(subscription));
+    reconciledEndpoint.current = subscription.endpoint;
+  }
+  setDeviceState("enabled");
+}
+
+function deviceStateFromBrowser(publicKey: string | null): NotificationDeviceState {
+  if (!supportsPushNotifications()) return "unsupported";
+  if (!publicKey) return "unconfigured";
+  const permission = notificationPermission();
+  if (permission === "denied") return "blocked";
+  return "available";
+}
diff --git a/app/features/settings/settings-page.tsx b/app/features/settings/settings-page.tsx
index c888d91..eff4707 100644
--- a/app/features/settings/settings-page.tsx
+++ b/app/features/settings/settings-page.tsx
@@ -4,6 +4,8 @@ import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs";
 import { DomainSettings } from "@/features/domains/domain-settings";
 import { MailboxSettings } from "@/features/mailboxes/mailbox-settings";
 import type { Mailbox } from "@/features/mailboxes/types";
+import { NotificationSettings } from "@/features/notifications/notification-settings";
+import type { NotificationController } from "@/features/notifications/types";
 import { DebugSettings } from "@/features/settings/debug-settings";
 import { SettingsSection } from "@/features/settings/settings-section";
 import type { SetupStatus } from "@/features/setup/types";
@@ -18,6 +20,7 @@ type SettingsPageProps = {
   activeTab: SettingsTabId;
   canManage: boolean;
   mailboxes: Mailbox[];
+  notifications: NotificationController;
   setup: SetupStatus;
   users: WorkspaceUser[];
   onRefresh: () => void;
@@ -32,6 +35,7 @@ export function SettingsPage({
   activeTab,
   canManage,
   mailboxes,
+  notifications,
   setup,
   users,
   onRefresh,
@@ -58,6 +62,7 @@ export function SettingsPage({
             <SettingsTab value="mailboxes">Mailboxes</SettingsTab>
             <SettingsTab value="users">Users</SettingsTab>
             {canManage ? <SettingsTab value="domains">Domains</SettingsTab> : null}
+            <SettingsTab value="notifications">Notifications</SettingsTab>
             {canManage ? <SettingsTab value="updates">Updates</SettingsTab> : null}
             <SettingsTab value="debug">Debug</SettingsTab>
           </TabsList>
@@ -77,6 +82,9 @@ export function SettingsPage({
               <DomainSettings portalHostname={setup.portalHostname} onChanged={onRefresh} />
             </TabsContent>
           ) : null}
+          <TabsContent className="mt-5" value="notifications">
+            <NotificationSettings notifications={notifications} />
+          </TabsContent>
           {canManage ? (
             <TabsContent className="mt-5" value="updates">
               <UpdateSettings
diff --git a/app/lib/api-client.ts b/app/lib/api-client.ts
index dfe4808..f665e87 100644
--- a/app/lib/api-client.ts
+++ b/app/lib/api-client.ts
@@ -34,8 +34,13 @@ export async function apiPut<T>(path: string, body: unknown): Promise<T> {
   });
 }
 
-export async function apiDelete(path: string): Promise<void> {
-  await apiRequest<null>(path, { method: "DELETE" });
+export async function apiDelete(path: string, body?: unknown): Promise<void> {
+  await apiRequest<null>(path, {
+    ...(body === undefined
+      ? {}
+      : { body: JSON.stringify(body), headers: { "content-type": "application/json" } }),
+    method: "DELETE"
+  });
 }
 
 async function apiRequest<T>(path: string, init: RequestInit): Promise<T> {
diff --git a/app/lib/routes.ts b/app/lib/routes.ts
index 146c8b1..4f72382 100644
--- a/app/lib/routes.ts
+++ b/app/lib/routes.ts
@@ -9,7 +9,14 @@ export const mailFolders = [
 
 export const folders = [...mailFolders, { id: "settings", label: "Settings" }] as const;
 
-export const settingsTabs = ["mailboxes", "users", "domains", "updates", "debug"] as const;
+export const settingsTabs = [
+  "mailboxes",
+  "users",
+  "domains",
+  "notifications",
+  "updates",
+  "debug"
+] as const;
 
 export type MailFolderId = (typeof mailFolders)[number]["id"];
 export type FolderId = (typeof folders)[number]["id"];
diff --git a/docs/deployment.md b/docs/deployment.md
index 4843fe2..0a36944 100644
--- a/docs/deployment.md
+++ b/docs/deployment.md
@@ -14,12 +14,19 @@ pnpm run deploy
 
 The installer creates a D1 database, R2 bucket, queue, Worker, and routes using public source and
 signed public release artifacts from `HQBase/hqbase`. It generates the Better Auth secret if one is
-not supplied.
+not supplied and generates the installation's Web Push VAPID key pair.
 
 ## Runtime secret
 
-The first Workers Build generates `BETTER_AUTH_SECRET` inside the customer account when it does not
-already exist. Operators may supply it explicitly for controlled automation.
+The first Workers Build generates `BETTER_AUTH_SECRET`, `VAPID_PUBLIC_KEY`, and
+`VAPID_PRIVATE_KEY` inside the customer account when they do not already exist. Existing
+installations receive a VAPID pair during the first compatible signed update without rotating
+their authentication secret. Operators may supply these values explicitly for controlled
+automation.
+
+The VAPID private key never leaves the customer's Worker secrets. Browser push subscription
+endpoints and encryption keys stay in the customer's D1 database. Notification payloads are
+encrypted and contain no sender, recipient, subject, snippet, body, or attachment metadata.
 
 Cloudflare OAuth client configuration is compiled public product configuration. Temporary OAuth
 grants used for setup or updates are encrypted, scoped to the operation, and revoked after use.
diff --git a/migrations/0006_push_notifications.sql b/migrations/0006_push_notifications.sql
new file mode 100644
index 0000000..bd2391e
--- /dev/null
+++ b/migrations/0006_push_notifications.sql
@@ -0,0 +1,16 @@
+PRAGMA foreign_keys = ON;
+
+CREATE TABLE push_subscriptions (
+  id TEXT PRIMARY KEY NOT NULL,
+  user_id TEXT NOT NULL REFERENCES "user"(id) ON DELETE CASCADE,
+  endpoint TEXT NOT NULL UNIQUE,
+  p256dh_key TEXT NOT NULL,
+  auth_key TEXT NOT NULL,
+  expiration_time INTEGER,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  last_success_at TEXT
+);
+
+CREATE INDEX push_subscriptions_user_idx
+ON push_subscriptions(user_id, updated_at DESC);
diff --git a/package.json b/package.json
index 66354b0..41e03bd 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "hqbase",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "private": true,
   "type": "module",
   "packageManager": "pnpm@11.7.0",
@@ -90,6 +90,7 @@
     "sanitize-html": "^2.17.6",
     "sonner": "^2.0.6",
     "tailwind-merge": "^3.3.1",
+    "web-push": "^3.6.7",
     "zod": "^4.0.5"
   },
   "devDependencies": {
@@ -100,6 +101,7 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@types/sanitize-html": "^2.16.1",
+    "@types/web-push": "^3.6.4",
     "@vitejs/plugin-react": "^4.6.0",
     "@vitest/coverage-v8": "4.1.10",
     "autoprefixer": "^10.4.21",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index a8ae33d..7833758 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -101,6 +101,9 @@ importers:
       tailwind-merge:
         specifier: ^3.3.1
         version: 3.6.0
+      web-push:
+        specifier: ^3.6.7
+        version: 3.6.7
       zod:
         specifier: ^4.0.5
         version: 4.4.3
@@ -126,6 +129,9 @@ importers:
       '@types/sanitize-html':
         specifier: ^2.16.1
         version: 2.16.1
+      '@types/web-push':
+        specifier: ^3.6.4
+        version: 3.6.4
       '@vitejs/plugin-react':
         specifier: ^4.6.0
         version: 4.7.0(vite@7.3.6(@types/node@26.0.1)(jiti@1.21.7)(yaml@2.9.0))
@@ -1695,6 +1701,9 @@ packages:
   '@types/use-sync-external-store@0.0.6':
     resolution: {integrity: sha512-zFDAD+tlpf2r4asuHEj0XH6pY6i0g5NeAHPn+15wk3BV6JA69eERFXC1gyGThDkVa1zCyKr5jox1+2LbV/AMLg==}
 
+  '@types/web-push@3.6.4':
+    resolution: {integrity: sha512-GnJmSr40H3RAnj0s34FNTcJi1hmWFV5KXugE0mYWnYhgTAHLJ/dJKAwDmvPJYMke0RplY2XE9LnM4hqSqKIjhQ==}
+
   '@types/whatwg-mimetype@3.0.2':
     resolution: {integrity: sha512-c2AKvDT8ToxLIOUlN51gTiHXflsfIFisS4pO7pDPoKouJCESkhZnEy623gwP9laCy5lnLDAw1vAzu2vM2YLOrA==}
 
@@ -1749,6 +1758,10 @@ packages:
     resolution: {integrity: sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==}
     engines: {node: '>= 0.6'}
 
+  agent-base@7.1.4:
+    resolution: {integrity: sha512-MnA+YT8fwfJPgBx3m60MNqakm30XOkyIoH1y6huTQvC0PwZG7ki8NacLBcrPbNoo8vEZy7Jpuk7+jMO+CUovTQ==}
+    engines: {node: '>= 14'}
+
   ajv-formats@3.0.1:
     resolution: {integrity: sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==}
     peerDependencies:
@@ -1774,6 +1787,9 @@ packages:
     resolution: {integrity: sha512-ik3ZgC9dY/lYVVM++OISsaYDeg1tb0VtP5uL3ouh1koGOaUMDPpbFIei4JkFimWUFPn90sbMNMXQAIVOlnYKJA==}
     engines: {node: '>=10'}
 
+  asn1.js@5.4.1:
+    resolution: {integrity: sha512-+I//4cYPccV8LdmBLiX8CYvf9Sp3vQsrqu2QNXRcrbiWvcx/UdlFiqUJJzxRQxgsZmvhXhn4cSKeSmoFjVdupA==}
+
   assertion-error@2.0.1:
     resolution: {integrity: sha512-Izi8RQcffqCeNVgFigKli1ssklIbpHnCYc6AknXGYoB6grJqyeby7jv12JUQgmTAnIDnbck1uxksT4dzN3PWBA==}
     engines: {node: '>=12'}
@@ -1870,6 +1886,9 @@ packages:
   blake3-wasm@2.1.5:
     resolution: {integrity: sha512-F1+K8EbfOZE49dtoPtmxUQrpXaBIl3ICvasLh+nJta0xkz+9kF/7uet9fLnwKqhDrmj6g+6K3Tw9yQPUg2ka5g==}
 
+  bn.js@4.12.5:
+    resolution: {integrity: sha512-3aRg6/JxfffFD+OlOjOFR3Vo79l39ooBTFucxx+MT3dhCtzn3EmiUPQo+6/OZuI2jbXi3YKgmiTFBgChQMwIRQ==}
+
   body-parser@2.3.0:
     resolution: {integrity: sha512-2cGmJupaNgg+QUwVLAucDuWuoMZ6EX9iHDRswZ5lsNYEmwPaRknMPCLZz07yTzVq/83p4o/wzbDZbBrTvGGTIw==}
     engines: {node: '>=18'}
@@ -1883,6 +1902,9 @@ packages:
     engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
     hasBin: true
 
+  buffer-equal-constant-time@1.0.1:
+    resolution: {integrity: sha512-zRpUiDwd/xk6ADqPMATG8vc9VPrkck7T07OIx0gnjmJAnHnTVXNQG3vfvWNuiZIkwu9KrKdA1iJKfsfTVxE6NA==}
+
   buffer-image-size@0.6.4:
     resolution: {integrity: sha512-nEh+kZOPY1w+gcCMobZ6ETUp9WfibndnosbpwB1iJk/8Gt5ZF2bhS6+B6bPYz424KtwsR6Rflc3tCz1/ghX2dQ==}
     engines: {node: '>=4.0'}
@@ -2040,6 +2062,9 @@ packages:
     resolution: {integrity: sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==}
     engines: {node: '>= 0.4'}
 
+  ecdsa-sig-formatter@1.0.11:
+    resolution: {integrity: sha512-nagl3RYrbNv6kQkeJIpt6NJZy8twLB/2vtz6yN9Z4vRKHN4/QZJIEbqohALSgwKdnksuY3k5Addp5lg8sVoVcQ==}
+
   ee-first@1.1.1:
     resolution: {integrity: sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==}
 
@@ -2245,6 +2270,14 @@ packages:
     resolution: {integrity: sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==}
     engines: {node: '>= 0.8'}
 
+  http_ece@1.2.0:
+    resolution: {integrity: sha512-JrF8SSLVmcvc5NducxgyOrKXe3EsyHMgBFgSaIUGmArKe+rwr0uphRkRXvwiom3I+fpIfoItveHrfudL8/rxuA==}
+    engines: {node: '>=16'}
+
+  https-proxy-agent@7.0.6:
+    resolution: {integrity: sha512-vK9P5/iUfdl95AI+JVyUuIcVtd4ofvtrOr3HNtM2yxC9bnMbEdp3x01OhQNnjb8IJYi38VlTE3mBXwcfvywuSw==}
+    engines: {node: '>= 14'}
+
   iconv-lite@0.7.3:
     resolution: {integrity: sha512-IKXpvIzjnC9XTAUbVBcMfGS0EPaIXtW6v+zr+RRp+hqULEpo0owZax6wyRwPOJbWbzjYspQwusTsfVr0ifh4uQ==}
     engines: {node: '>=0.10.0'}
@@ -2331,6 +2364,12 @@ packages:
     engines: {node: '>=6'}
     hasBin: true
 
+  jwa@2.0.1:
+    resolution: {integrity: sha512-hRF04fqJIP8Abbkq5NKGN0Bbr3JxlQ+qhZufXVr0DvujKy93ZCbXZMHDL4EOtodSbCWxOqR8MS1tXA5hwqCXDg==}
+
+  jws@4.0.1:
+    resolution: {integrity: sha512-EKI/M/yqPncGUUh44xz0PxSidXFr/+r0pA70+gIYhjv+et7yxM+s29Y+VGDkovRofQem0fs7Uvf4+YmAdyRduA==}
+
   kleur@4.1.5:
     resolution: {integrity: sha512-o+NO+8WrRiQEE4/7nwRJhN1HWpVmJm511pBHUxPLtp0BUISzlBplORYSmTclCnJvQq2tKu/sgl3xVpkc7ZWuQQ==}
     engines: {node: '>=6'}
@@ -2403,6 +2442,12 @@ packages:
     engines: {node: '>=22.0.0'}
     hasBin: true
 
+  minimalistic-assert@1.0.1:
+    resolution: {integrity: sha512-UtJcAD4yEaGtjPezWuO9wC4nwUnVH/8/Im3yEHQP4b67cXlD/Qr9hdITCU1xDbSEXg2XKNaP8jsReV7vQd00/A==}
+
+  minimist@1.2.8:
+    resolution: {integrity: sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==}
+
   ms@2.1.3:
     resolution: {integrity: sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==}
 
@@ -2701,6 +2746,9 @@ packages:
   run-parallel@1.2.0:
     resolution: {integrity: sha512-5l4VyZR86LZ/lDxZTR6jqL8AFE2S0IFLMP26AbjsLVADxHdhB/c0GUsH+y39UfCi3dzz8OlQuPmnaJOMoDHQBA==}
 
+  safe-buffer@5.2.1:
+    resolution: {integrity: sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==}
+
   safer-buffer@2.1.2:
     resolution: {integrity: sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==}
 
@@ -2991,6 +3039,11 @@ packages:
   w3c-keyname@2.2.8:
     resolution: {integrity: sha512-dpojBhNsCNN7T82Tm7k26A6G9ML3NkhDsnw9n/eoxSRlVBB4CEtIQ/KTCLI2Fwf3ataSXRhYFkQi3SlnFwPvPQ==}
 
+  web-push@3.6.7:
+    resolution: {integrity: sha512-OpiIUe8cuGjrj3mMBFWY+e4MMIkW3SVT+7vEIjvD9kejGUypv8GPDf84JdPWskK8zMRIJ6xYGm+Kxr8YkPyA0A==}
+    engines: {node: '>= 16'}
+    hasBin: true
+
   whatwg-mimetype@3.0.0:
     resolution: {integrity: sha512-nt+N2dzIutVRxARx1nghPKGv1xHikU7HKdfafKkLNLindmPU/ch3U31NOCGGA/dmPcmb1VlofO0vnKAcsm0o/Q==}
     engines: {node: '>=12'}
@@ -4396,6 +4449,10 @@ snapshots:
 
   '@types/use-sync-external-store@0.0.6': {}
 
+  '@types/web-push@3.6.4':
+    dependencies:
+      '@types/node': 26.0.1
+
   '@types/whatwg-mimetype@3.0.2':
     optional: true
 
@@ -4476,6 +4533,8 @@ snapshots:
       mime-types: 3.0.2
       negotiator: 1.0.0
 
+  agent-base@7.1.4: {}
+
   ajv-formats@3.0.1(ajv@8.20.0):
     optionalDependencies:
       ajv: 8.20.0
@@ -4500,6 +4559,13 @@ snapshots:
     dependencies:
       tslib: 2.8.1
 
+  asn1.js@5.4.1:
+    dependencies:
+      bn.js: 4.12.5
+      inherits: 2.0.4
+      minimalistic-assert: 1.0.1
+      safer-buffer: 2.1.2
+
   assertion-error@2.0.1: {}
 
   ast-v8-to-istanbul@1.0.4:
@@ -4559,6 +4625,8 @@ snapshots:
 
   blake3-wasm@2.1.5: {}
 
+  bn.js@4.12.5: {}
+
   body-parser@2.3.0:
     dependencies:
       bytes: 3.1.2
@@ -4585,6 +4653,8 @@ snapshots:
       node-releases: 2.0.50
       update-browserslist-db: 1.2.3(browserslist@4.28.4)
 
+  buffer-equal-constant-time@1.0.1: {}
+
   buffer-image-size@0.6.4:
     dependencies:
       '@types/node': 26.0.1
@@ -4721,6 +4791,10 @@ snapshots:
       es-errors: 1.3.0
       gopd: 1.2.0
 
+  ecdsa-sig-formatter@1.0.11:
+    dependencies:
+      safe-buffer: 5.2.1
+
   ee-first@1.1.1: {}
 
   electron-to-chromium@1.5.380: {}
@@ -4966,6 +5040,15 @@ snapshots:
       statuses: 2.0.2
       toidentifier: 1.0.1
 
+  http_ece@1.2.0: {}
+
+  https-proxy-agent@7.0.6:
+    dependencies:
+      agent-base: 7.1.4
+      debug: 4.4.3
+    transitivePeerDependencies:
+      - supports-color
+
   iconv-lite@0.7.3:
     dependencies:
       safer-buffer: 2.1.2
@@ -5027,6 +5110,17 @@ snapshots:
 
   json5@2.2.3: {}
 
+  jwa@2.0.1:
+    dependencies:
+      buffer-equal-constant-time: 1.0.1
+      ecdsa-sig-formatter: 1.0.11
+      safe-buffer: 5.2.1
+
+  jws@4.0.1:
+    dependencies:
+      jwa: 2.0.1
+      safe-buffer: 5.2.1
+
   kleur@4.1.5: {}
 
   kysely@0.29.2: {}
@@ -5094,6 +5188,10 @@ snapshots:
       - bufferutil
       - utf-8-validate
 
+  minimalistic-assert@1.0.1: {}
+
+  minimist@1.2.8: {}
+
   ms@2.1.3: {}
 
   mz@2.7.0:
@@ -5403,6 +5501,8 @@ snapshots:
     dependencies:
       queue-microtask: 1.2.3
 
+  safe-buffer@5.2.1: {}
+
   safer-buffer@2.1.2: {}
 
   sanitize-html@2.17.6:
@@ -5700,6 +5800,16 @@ snapshots:
 
   w3c-keyname@2.2.8: {}
 
+  web-push@3.6.7:
+    dependencies:
+      asn1.js: 5.4.1
+      http_ece: 1.2.0
+      https-proxy-agent: 7.0.6
+      jws: 4.0.1
+      minimist: 1.2.8
+    transitivePeerDependencies:
+      - supports-color
+
   whatwg-mimetype@3.0.0:
     optional: true
 
diff --git a/scripts/build-pwa.mjs b/scripts/build-pwa.mjs
index 8be6164..c2506a5 100644
--- a/scripts/build-pwa.mjs
+++ b/scripts/build-pwa.mjs
@@ -71,6 +71,59 @@ self.addEventListener("message", (event) => {
   if (event.data?.type === "SKIP_WAITING") self.skipWaiting();
 });
 
+self.addEventListener("push", (event) => {
+  const payload = readPushPayload(event.data);
+  const unreadCount =
+    Number.isSafeInteger(payload.unreadCount) && payload.unreadCount >= 0
+      ? payload.unreadCount
+      : 0;
+  const body =
+    unreadCount === 1
+      ? "1 unread message in HQBase"
+      : \`\${unreadCount} unread messages in HQBase\`;
+  const tasks = [
+    self.registration.showNotification("New email", {
+      badge: "/icons/icon-192.png",
+      body,
+      data: { url: safeNotificationPath(payload.url) },
+      icon: "/icons/icon-192.png",
+      tag: typeof payload.tag === "string" ? payload.tag : "hqbase-new-mail"
+    }),
+    self.clients
+      .matchAll({ includeUncontrolled: true, type: "window" })
+      .then((clients) =>
+        Promise.all(
+          clients.map((client) =>
+            client.postMessage({ type: "hqbase:push-received", unreadCount })
+          )
+        )
+      )
+  ];
+  if (self.navigator.setAppBadge) {
+    tasks.push(
+      unreadCount > 0
+        ? self.navigator.setAppBadge(unreadCount)
+        : self.navigator.clearAppBadge?.()
+    );
+  }
+  event.waitUntil(Promise.all(tasks.filter(Boolean)));
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  const target = new URL(safeNotificationPath(event.notification.data?.url), self.location.origin);
+  event.waitUntil(
+    self.clients.matchAll({ includeUncontrolled: true, type: "window" }).then(async (clients) => {
+      const client = clients.find((candidate) => new URL(candidate.url).origin === target.origin);
+      if (client) {
+        if ("navigate" in client) await client.navigate(target.href);
+        return client.focus();
+      }
+      return self.clients.openWindow(target.href);
+    })
+  );
+});
+
 self.addEventListener("fetch", (event) => {
   const request = event.request;
   const url = new URL(request.url);
@@ -93,6 +146,22 @@ self.addEventListener("fetch", (event) => {
     event.respondWith(caches.match(request).then((cached) => cached || fetch(request)));
   }
 });
+
+function readPushPayload(data) {
+  if (!data) return {};
+  try {
+    const value = data.json();
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return {};
+  }
+}
+
+function safeNotificationPath(value) {
+  if (typeof value !== "string" || !value.startsWith("/")) return "/inbox";
+  const url = new URL(value, self.location.origin);
+  return url.origin === self.location.origin ? \`\${url.pathname}\${url.search}\` : "/inbox";
+}
 `;
 }
 
diff --git a/scripts/hqbase/reset-d1.sql b/scripts/hqbase/reset-d1.sql
index 8512ef8..0c86e18 100644
--- a/scripts/hqbase/reset-d1.sql
+++ b/scripts/hqbase/reset-d1.sql
@@ -4,6 +4,7 @@ DROP TABLE IF EXISTS oauthConsent;
 DROP TABLE IF EXISTS oauthAccessToken;
 DROP TABLE IF EXISTS oauthRefreshToken;
 DROP TABLE IF EXISTS oauthClient;
+DROP TABLE IF EXISTS push_subscriptions;
 DROP TABLE IF EXISTS message_sender_preferences;
 DROP TABLE IF EXISTS update_history;
 DROP TABLE IF EXISTS release_state;
diff --git a/scripts/release/deploy.mjs b/scripts/release/deploy.mjs
index e635937..7fb4688 100644
--- a/scripts/release/deploy.mjs
+++ b/scripts/release/deploy.mjs
@@ -4,6 +4,7 @@ import { createHash, createPublicKey, randomBytes, verify } from "node:crypto";
 import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { resolve } from "node:path";
+import webpush from "web-push";
 import { inspectActiveRelease, isWorkerNotFound } from "./active-version.mjs";
 
 const root = resolve(import.meta.dirname, "../..");
@@ -312,35 +313,52 @@ export function deploySource(cwd, options = {}) {
     ["exec", "wrangler", "secret", "list", "--format", "json"],
     cwd
   );
-  let needsSecret;
+  let missingSecrets;
   try {
-    needsSecret = needsInitialAuthSecret(inspection, "BETTER_AUTH_SECRET");
+    missingSecrets = missingRequiredSecrets(inspection, [
+      "BETTER_AUTH_SECRET",
+      "VAPID_PUBLIC_KEY",
+      "VAPID_PRIVATE_KEY"
+    ]);
   } catch (error) {
     emitCommandOutput(inspection);
     throw error;
   }
-  if (!needsSecret) {
+  if (missingSecrets.length === 0) {
     execute("pnpm", deployArgs, cwd);
     return;
   }
 
-  deployArgs.push(
-    "--var",
-    `HQBASE_INSTALLATION_ID:${options.randomUUID?.() ?? crypto.randomUUID()}`
-  );
+  if (missingSecrets.includes("BETTER_AUTH_SECRET")) {
+    deployArgs.push(
+      "--var",
+      `HQBASE_INSTALLATION_ID:${options.randomUUID?.() ?? crypto.randomUUID()}`
+    );
+  }
 
   const workspace = mkdtempSync(resolve(tmpdir(), "hqbase-secrets-"));
   const secretsFile = resolve(workspace, "secrets.json");
   try {
-    const configuredSecret = process.env.HQBASE_AUTH_SECRET;
-    const bytes = configuredSecret ? null : (options.randomBytes ?? randomBytes)(32);
-    writeFileSync(
-      secretsFile,
-      `${JSON.stringify({
-        BETTER_AUTH_SECRET: configuredSecret ?? bytes?.toString("base64url")
-      })}\n`,
-      { mode: 0o600 }
-    );
+    const secrets = {};
+    if (missingSecrets.includes("BETTER_AUTH_SECRET")) {
+      const configuredSecret = process.env.HQBASE_AUTH_SECRET;
+      const bytes = configuredSecret ? null : (options.randomBytes ?? randomBytes)(32);
+      secrets.BETTER_AUTH_SECRET = configuredSecret ?? bytes?.toString("base64url");
+    }
+    if (
+      missingSecrets.includes("VAPID_PUBLIC_KEY") ||
+      missingSecrets.includes("VAPID_PRIVATE_KEY")
+    ) {
+      const configuredPublicKey = process.env.HQBASE_VAPID_PUBLIC_KEY;
+      const configuredPrivateKey = process.env.HQBASE_VAPID_PRIVATE_KEY;
+      const generated =
+        configuredPublicKey && configuredPrivateKey
+          ? { publicKey: configuredPublicKey, privateKey: configuredPrivateKey }
+          : (options.generateVapidKeys ?? webpush.generateVAPIDKeys)();
+      secrets.VAPID_PUBLIC_KEY = generated.publicKey;
+      secrets.VAPID_PRIVATE_KEY = generated.privateKey;
+    }
+    writeFileSync(secretsFile, `${JSON.stringify(secrets)}\n`, { mode: 0o600 });
     execute("pnpm", [...deployArgs, "--secrets-file", secretsFile], cwd);
   } finally {
     rmSync(workspace, { recursive: true, force: true });
@@ -356,13 +374,17 @@ function workerNameFromConfigFile(configFile) {
   return workerNameFromConfig(JSON.parse(readFileSync(configFile, "utf8")));
 }
 export function needsInitialAuthSecret(result, secretName) {
+  return missingRequiredSecrets(result, [secretName]).length > 0;
+}
+export function missingRequiredSecrets(result, secretNames) {
   if (result.status === 0) {
     const secrets = JSON.parse(result.stdout || "[]");
     if (!Array.isArray(secrets)) throw new Error("Wrangler returned an invalid secret list.");
-    return !secrets.some((secret) => secret?.name === secretName);
+    const configured = new Set(secrets.map((secret) => secret?.name).filter(Boolean));
+    return secretNames.filter((secretName) => !configured.has(secretName));
   }
   if (isWorkerNotFound(result)) {
-    return true;
+    return [...secretNames];
   }
   throw result.error ?? new Error(`wrangler secret list exited with status ${result.status}.`);
 }
diff --git a/test/integration/worker/notifications.test.ts b/test/integration/worker/notifications.test.ts
new file mode 100644
index 0000000..1354e2d
--- /dev/null
+++ b/test/integration/worker/notifications.test.ts
@@ -0,0 +1,223 @@
+import { env, SELF } from "cloudflare:test";
+import { beforeAll, describe, expect, it } from "vitest";
+
+import initialMigration from "../../../migrations/0001_initial.sql?raw";
+import workspaceMigration from "../../../migrations/0002_workspace.sql?raw";
+import oauthResourcesMigration from "../../../migrations/0003_oauth_resources.sql?raw";
+import conversationMigration from "../../../migrations/0004_conversations.sql?raw";
+import threadRebuildMigration from "../../../migrations/0005_rebuild_threads.sql?raw";
+import pushMigration from "../../../migrations/0006_push_notifications.sql?raw";
+import { createAuth } from "../../../worker/auth/auth";
+import {
+  countUnreadMessages,
+  listPushSubscriptionsForMailbox,
+  removePushSubscription,
+  savePushSubscription
+} from "../../../worker/features/notifications/queries";
+
+describe("notification persistence", () => {
+  beforeAll(async () => {
+    for (const migration of [
+      initialMigration,
+      workspaceMigration,
+      oauthResourcesMigration,
+      conversationMigration,
+      threadRebuildMigration,
+      pushMigration
+    ]) {
+      await applyMigration(migration);
+    }
+    const now = "2026-07-29T12:00:00.000Z";
+    await env.DB.batch([
+      env.DB.prepare(
+        `INSERT INTO "user"
+         (id, name, email, emailVerified, createdAt, updatedAt, role, banned)
+         VALUES
+           ('usr_owner', 'Owner', 'owner@example.com', 1, ?, ?, 'owner', 0),
+           ('usr_member', 'Member', 'member@example.com', 1, ?, ?, 'member', 0),
+           ('usr_other', 'Other', 'other@example.com', 1, ?, ?, 'member', 0),
+           ('usr_banned', 'Banned', 'banned@example.com', 1, ?, ?, 'owner', 1)`
+      ).bind(now, now, now, now, now, now, now, now),
+      env.DB.prepare(
+        `INSERT INTO mailboxes (id, address, display_name, is_active, created_at, updated_at)
+         VALUES
+           ('mbx_one', 'support@example.com', 'Support', 1, ?, ?),
+           ('mbx_two', 'privacy@example.com', 'Privacy', 1, ?, ?)`
+      ).bind(now, now, now, now),
+      env.DB.prepare(
+        `INSERT INTO mailbox_grants
+         (mailbox_id, user_id, access_level, created_by, created_at, updated_at)
+         VALUES ('mbx_one', 'usr_member', 'read', 'usr_owner', ?, ?)`
+      ).bind(now, now),
+      env.DB.prepare(
+        `INSERT INTO threads
+         (id, subject_normalized, last_message_at, created_at, updated_at)
+         VALUES ('thr_push', 'push', ?, ?, ?)`
+      ).bind(now, now, now)
+    ]);
+    await insertMessage("msg_inbox", "mbx_one", "inbox", null);
+    await insertMessage("msg_catchall", "mbx_one", "catchall", null);
+    await insertMessage("msg_read", "mbx_one", "inbox", now);
+    await insertMessage("msg_other", "mbx_two", "inbox", null);
+
+    for (const [userId, endpoint] of [
+      ["usr_owner", "https://push.example/owner"],
+      ["usr_member", "https://push.example/member"],
+      ["usr_other", "https://push.example/other"],
+      ["usr_banned", "https://push.example/banned"]
+    ] as const) {
+      await savePushSubscription(env.DB, userId, subscription(endpoint));
+    }
+  });
+
+  it("counts only accessible unread attention folders", async () => {
+    await expect(countUnreadMessages(env.DB, ["mbx_one"])).resolves.toEqual({
+      catchall: 1,
+      inbox: 1,
+      total: 2
+    });
+    await expect(countUnreadMessages(env.DB, ["mbx_one", "mbx_two"])).resolves.toEqual({
+      catchall: 1,
+      inbox: 2,
+      total: 3
+    });
+  });
+
+  it("targets owners and live mailbox grants but not unrelated or banned users", async () => {
+    const subscriptions = await listPushSubscriptionsForMailbox(env.DB, "mbx_one");
+    expect(subscriptions.map((row) => row.user_id).sort()).toEqual(["usr_member", "usr_owner"]);
+  });
+
+  it("moves an endpoint to the current signed-in user and scopes removal by ownership", async () => {
+    const endpoint = "https://push.example/shared-device";
+    await savePushSubscription(env.DB, "usr_owner", subscription(endpoint));
+    await savePushSubscription(env.DB, "usr_member", subscription(endpoint));
+    await removePushSubscription(env.DB, "usr_owner", endpoint);
+    expect(
+      await env.DB.prepare("SELECT user_id FROM push_subscriptions WHERE endpoint = ?")
+        .bind(endpoint)
+        .first<{ user_id: string }>()
+    ).toEqual({ user_id: "usr_member" });
+    await removePushSubscription(env.DB, "usr_member", endpoint);
+    expect(
+      await env.DB.prepare("SELECT id FROM push_subscriptions WHERE endpoint = ?")
+        .bind(endpoint)
+        .first()
+    ).toBeNull();
+  });
+
+  it("requires an authenticated user and validates subscription endpoints at the API boundary", async () => {
+    const origin = "https://hqbase.test";
+    const email = "push-user@example.com";
+    const auth = createAuth(env, new Request(`${origin}/api/auth/sign-up/email`));
+    const signUp = await auth.handler(
+      new Request(`${origin}/api/auth/sign-up/email`, {
+        body: JSON.stringify({
+          email,
+          name: "Push User",
+          password: "correct-horse-battery-staple",
+          rememberMe: false
+        }),
+        headers: { "content-type": "application/json", origin },
+        method: "POST"
+      })
+    );
+    expect(signUp.status, await signUp.text()).toBe(200);
+    const cookie = extractSessionCookie(signUp);
+    const user = await env.DB.prepare(`SELECT id FROM "user" WHERE email = ?`)
+      .bind(email)
+      .first<{ id: string }>();
+    expect(user).not.toBeNull();
+    await env.DB.prepare(
+      `INSERT INTO mailbox_grants
+       (mailbox_id, user_id, access_level, created_by, created_at, updated_at)
+       VALUES ('mbx_one', ?, 'read', 'usr_owner', ?, ?)`
+    )
+      .bind(user?.id, "2026-07-29T12:00:00.000Z", "2026-07-29T12:00:00.000Z")
+      .run();
+
+    const unauthenticated = await SELF.fetch(`${origin}/api/notifications/status`);
+    expect(unauthenticated.status).toBe(401);
+    const status = await SELF.fetch(`${origin}/api/notifications/status`, {
+      headers: { cookie }
+    });
+    expect(status.status, await status.clone().text()).toBe(200);
+    expect(await status.json()).toEqual({
+      unread: { catchall: 1, inbox: 1, total: 2 },
+      vapidPublicKey: "integration-vapid-public-key"
+    });
+
+    const invalid = await SELF.fetch(`${origin}/api/notifications/subscription`, {
+      body: JSON.stringify(subscription("http://push.example/insecure")),
+      headers: { "content-type": "application/json", cookie, origin },
+      method: "PUT"
+    });
+    expect(invalid.status).toBe(400);
+
+    const endpoint = "https://push.example/api-device";
+    const saved = await SELF.fetch(`${origin}/api/notifications/subscription`, {
+      body: JSON.stringify(subscription(endpoint)),
+      headers: { "content-type": "application/json", cookie, origin },
+      method: "PUT"
+    });
+    expect(saved.status, await saved.text()).toBe(200);
+    expect(
+      await env.DB.prepare("SELECT user_id FROM push_subscriptions WHERE endpoint = ?")
+        .bind(endpoint)
+        .first<{ user_id: string }>()
+    ).toEqual({ user_id: user?.id });
+
+    const removed = await SELF.fetch(`${origin}/api/notifications/subscription`, {
+      body: JSON.stringify({ endpoint }),
+      headers: { "content-type": "application/json", cookie, origin },
+      method: "DELETE"
+    });
+    expect(removed.status, await removed.text()).toBe(200);
+  });
+});
+
+function subscription(endpoint: string) {
+  return {
+    endpoint,
+    expirationTime: null,
+    keys: {
+      auth: "auth_key_123456789",
+      p256dh: "p256dh_key_123456789"
+    }
+  };
+}
+
+async function insertMessage(
+  id: string,
+  mailboxId: string,
+  folder: "catchall" | "inbox",
+  readAt: string | null
+): Promise<void> {
+  const now = "2026-07-29T12:00:00.000Z";
+  await env.DB.prepare(
+    `INSERT INTO messages (
+       id, thread_id, mailbox_id, direction, folder, from_address, to_json, cc_json, bcc_json,
+       subject, snippet, text_body, references_json, received_at, read_at, has_attachments,
+       created_at, updated_at
+     ) VALUES (?, 'thr_push', ?, 'inbound', ?, 'sender@example.com', '[]', '[]', '[]',
+       'Subject', 'Snippet', 'Body', '[]', ?, ?, 0, ?, ?)`
+  )
+    .bind(id, mailboxId, folder, now, readAt, now, now)
+    .run();
+}
+
+async function applyMigration(source: string): Promise<void> {
+  for (const statement of source
+    .split(";")
+    .map((value) => value.trim())
+    .filter(Boolean)) {
+    await env.DB.prepare(statement).run();
+  }
+}
+
+function extractSessionCookie(response: Response): string {
+  const serialized = response.headers.get("set-cookie") ?? "";
+  const match = serialized.match(/(?:^|,\s*)((?:__Secure-)?better-auth\.session_token=[^;,]+)/);
+  if (!match?.[1]) throw new Error("Better Auth session cookie was not returned.");
+  return match[1];
+}
diff --git a/test/unit/app/layout/mail-shell.test.tsx b/test/unit/app/layout/mail-shell.test.tsx
index c00e299..43028a9 100644
--- a/test/unit/app/layout/mail-shell.test.tsx
+++ b/test/unit/app/layout/mail-shell.test.tsx
@@ -14,6 +14,7 @@ const user = {
   name: "Olivia Berman",
   role: "owner" as const
 };
+const unread = { catchall: 2, inbox: 7, total: 9 };
 
 describe("mail shell", () => {
   it("uses the full header width and keeps mail actions in a right-aligned group", () => {
@@ -23,6 +24,7 @@ describe("mail shell", () => {
         mailboxId="all"
         mailboxes={[]}
         search=""
+        unread={unread}
         user={user}
         onCompose={() => undefined}
         onFolderChange={() => undefined}
@@ -49,6 +51,7 @@ describe("mail shell", () => {
     const html = renderToStaticMarkup(
       <Sidebar
         activeFolder="inbox"
+        unread={unread}
         user={user}
         onFolderChange={() => undefined}
         onSignedOut={() => undefined}
@@ -59,6 +62,8 @@ describe("mail shell", () => {
     expect(html).toContain('href="/inbox"');
     expect(html).toContain('href="/catch-all"');
     expect(html).toContain('href="/settings/mailboxes"');
+    expect(html).toContain("7 unread");
+    expect(html).toContain("2 unread");
     expect(html).toContain("Open profile menu");
     expect(html).toContain("OB");
     expect(html.indexOf("Settings")).toBeLessThan(html.indexOf("Open profile menu"));
@@ -83,6 +88,7 @@ describe("mail shell", () => {
     const html = renderToStaticMarkup(
       <MobileNavigation
         activeFolder="catchall"
+        unread={unread}
         user={user}
         onFolderChange={() => undefined}
         onSignedOut={() => undefined}
@@ -102,6 +108,7 @@ describe("mail shell", () => {
       <Sidebar
         activeFolder="inbox"
         drawerAction={<button type="button">Connect MCP</button>}
+        unread={unread}
         user={user}
         onFolderChange={() => undefined}
         onSignedOut={() => undefined}
@@ -127,6 +134,7 @@ describe("mail shell", () => {
         onMessageRouteChange={() => undefined}
         onRefresh={() => undefined}
         onSelect={() => undefined}
+        onUnreadChange={() => undefined}
       />
     );
 
diff --git a/test/unit/app/messages/conversation-reader.test.tsx b/test/unit/app/messages/conversation-reader.test.tsx
index 10796dd..19116ae 100644
--- a/test/unit/app/messages/conversation-reader.test.tsx
+++ b/test/unit/app/messages/conversation-reader.test.tsx
@@ -94,6 +94,7 @@ describe("conversation reader", () => {
         onMessageRouteChange={() => undefined}
         onRefresh={() => undefined}
         onSelect={() => undefined}
+        onUnreadChange={() => undefined}
       />
     );
     const conversationHtml = renderToStaticMarkup(
@@ -105,6 +106,7 @@ describe("conversation reader", () => {
         onMessageRouteChange={() => undefined}
         onRefresh={() => undefined}
         onSelect={() => undefined}
+        onUnreadChange={() => undefined}
       />
     );
 
diff --git a/test/unit/app/notifications/browser.test.ts b/test/unit/app/notifications/browser.test.ts
new file mode 100644
index 0000000..d49f2aa
--- /dev/null
+++ b/test/unit/app/notifications/browser.test.ts
@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import {
+  applyUnreadIndicators,
+  serializePushSubscription,
+  subscribeToPush
+} from "@/features/notifications/browser";
+
+describe("browser notifications", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+  });
+
+  it("sets and clears the exact app badge and document title", async () => {
+    const setAppBadge = vi.fn().mockResolvedValue(undefined);
+    const clearAppBadge = vi.fn().mockResolvedValue(undefined);
+    vi.stubGlobal("navigator", { setAppBadge, clearAppBadge });
+    vi.stubGlobal("document", { title: "" });
+
+    await applyUnreadIndicators({ catchall: 1, inbox: 2, total: 3 });
+    expect(document.title).toBe("(3) HQBase");
+    expect(setAppBadge).toHaveBeenCalledWith(3);
+    await applyUnreadIndicators({ catchall: 0, inbox: 0, total: 0 });
+    expect(document.title).toBe("HQBase");
+    expect(clearAppBadge).toHaveBeenCalledOnce();
+  });
+
+  it("requests permission only when subscribing and uses the VAPID application key", async () => {
+    const subscription = {
+      endpoint: "https://push.example/device",
+      expirationTime: null,
+      toJSON: () => ({
+        endpoint: "https://push.example/device",
+        expirationTime: null,
+        keys: { auth: "auth", p256dh: "p256dh" }
+      }),
+      unsubscribe: vi.fn()
+    } as unknown as PushSubscription;
+    const subscribe = vi.fn().mockResolvedValue(subscription);
+    const requestPermission = vi.fn().mockResolvedValue("granted");
+    vi.stubGlobal("window", { Notification: {}, PushManager: {} });
+    vi.stubGlobal("Notification", { permission: "default", requestPermission });
+    vi.stubGlobal("navigator", {
+      serviceWorker: {
+        ready: Promise.resolve({
+          pushManager: { getSubscription: vi.fn().mockResolvedValue(null), subscribe }
+        })
+      }
+    });
+
+    await expect(subscribeToPush("AQIDBA")).resolves.toBe(subscription);
+    expect(requestPermission).toHaveBeenCalledOnce();
+    expect(subscribe).toHaveBeenCalledWith({
+      applicationServerKey: new Uint8Array([1, 2, 3, 4]),
+      userVisibleOnly: true
+    });
+  });
+
+  it("rejects incomplete browser subscription keys", () => {
+    const subscription = {
+      toJSON: () => ({ endpoint: "https://push.example/device", keys: {} })
+    } as unknown as PushSubscription;
+    expect(() => serializePushSubscription(subscription)).toThrow("incomplete");
+  });
+});
diff --git a/test/unit/app/notifications/notification-settings.test.tsx b/test/unit/app/notifications/notification-settings.test.tsx
new file mode 100644
index 0000000..888162e
--- /dev/null
+++ b/test/unit/app/notifications/notification-settings.test.tsx
@@ -0,0 +1,43 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { describe, expect, it } from "vitest";
+
+import { NotificationSettings } from "@/features/notifications/notification-settings";
+import type { NotificationController } from "@/features/notifications/types";
+
+describe("notification settings", () => {
+  it("shows the current unread count, device scope, and minimal payload boundary", () => {
+    const html = renderToStaticMarkup(
+      <NotificationSettings notifications={controller("enabled")} />
+    );
+    expect(html).toContain("Disable on this device");
+    expect(html).toContain("3 unread messages");
+    expect(html).toContain("minimal encrypted payload");
+    expect(html).toContain("Sender, recipient, subject, message text");
+    expect(html).toContain("Enabling another device does not disable this one.");
+  });
+
+  it("keeps blocked and unsupported permission controls non-actionable", () => {
+    const blocked = renderToStaticMarkup(
+      <NotificationSettings notifications={controller("blocked")} />
+    );
+    const unsupported = renderToStaticMarkup(
+      <NotificationSettings notifications={controller("unsupported")} />
+    );
+    expect(blocked).toContain("Notifications are blocked.");
+    expect(blocked).toContain("disabled");
+    expect(unsupported).toContain("Install HQBase to the iOS Home Screen");
+    expect(unsupported).toContain("disabled");
+  });
+});
+
+function controller(deviceState: NotificationController["deviceState"]): NotificationController {
+  return {
+    deviceState,
+    disable: async () => undefined,
+    enable: async () => undefined,
+    error: null,
+    isBusy: false,
+    refresh: async () => undefined,
+    unread: { catchall: 1, inbox: 2, total: 3 }
+  };
+}
diff --git a/test/unit/app/notifications/sign-out.test.ts b/test/unit/app/notifications/sign-out.test.ts
new file mode 100644
index 0000000..71e0e9f
--- /dev/null
+++ b/test/unit/app/notifications/sign-out.test.ts
@@ -0,0 +1,33 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("@/features/notifications/api", () => ({
+  deleteNotificationSubscription: mocks.deleteNotificationSubscription
+}));
+vi.mock("@/features/notifications/browser", () => ({
+  currentPushSubscription: mocks.currentPushSubscription
+}));
+
+const mocks = vi.hoisted(() => ({
+  currentPushSubscription: vi.fn(),
+  deleteNotificationSubscription: vi.fn()
+}));
+
+import { disableCurrentDeviceNotificationsBeforeSignOut } from "@/features/notifications/sign-out";
+
+describe("notification sign-out cleanup", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it("unsubscribes the browser even when server cleanup fails", async () => {
+    const unsubscribe = vi.fn().mockResolvedValue(true);
+    mocks.currentPushSubscription.mockResolvedValue({
+      endpoint: "https://push.example/device",
+      unsubscribe
+    });
+    mocks.deleteNotificationSubscription.mockRejectedValue(new Error("offline"));
+
+    await expect(disableCurrentDeviceNotificationsBeforeSignOut()).rejects.toThrow("offline");
+    expect(unsubscribe).toHaveBeenCalledOnce();
+  });
+});
diff --git a/test/unit/app/settings/settings-presentation.test.tsx b/test/unit/app/settings/settings-presentation.test.tsx
index e39b42e..ca9522a 100644
--- a/test/unit/app/settings/settings-presentation.test.tsx
+++ b/test/unit/app/settings/settings-presentation.test.tsx
@@ -62,6 +62,15 @@ const connectedDomain: MailDomain = {
   isEnabled: true,
   updatedAt: "2026-07-20T00:00:00.000Z"
 };
+const notifications = {
+  deviceState: "enabled" as const,
+  disable: async () => undefined,
+  enable: async () => undefined,
+  error: null,
+  isBusy: false,
+  refresh: async () => undefined,
+  unread: { catchall: 1, inbox: 2, total: 3 }
+};
 
 describe("settings presentation", () => {
   it("renders mailbox content at the top level and opens creation from a dialog trigger", () => {
@@ -199,6 +208,7 @@ describe("settings presentation", () => {
         activeTab="mailboxes"
         canManage
         mailboxes={[]}
+        notifications={notifications}
         setup={setup}
         updateStatus={null}
         users={[]}
@@ -215,7 +225,9 @@ describe("settings presentation", () => {
     expect(html).not.toContain('value="access"');
     expect(html).not.toContain("Mail clients");
     expect(html).toContain(">Debug<");
+    expect(html).toContain(">Notifications<");
     expect(html).toContain('href="/settings/mailboxes"');
+    expect(html).toContain('href="/settings/notifications"');
     expect(html).toContain('href="/settings/debug"');
     expect(html.indexOf(">Debug<")).toBeGreaterThan(html.indexOf(">Updates<"));
   });
diff --git a/test/unit/scripts/deploy.test.mjs b/test/unit/scripts/deploy.test.mjs
index 4f0ae63..b9bfc39 100644
--- a/test/unit/scripts/deploy.test.mjs
+++ b/test/unit/scripts/deploy.test.mjs
@@ -14,6 +14,7 @@ import {
   executeSql,
   hqbaseReleaseTag,
   loadVerifiedRelease,
+  missingRequiredSecrets,
   needsInitialAuthSecret,
   normalizeConfig,
   verifyManifest,
@@ -227,7 +228,7 @@ describe("HQBase release deployment", () => {
     expect(workerNameFromConfig({ name: "hqbase-deeptake-test" })).toBe("hqbase-deeptake-test");
     expect(() => workerNameFromConfig({ name: "" })).toThrow("deployed Worker name");
   });
-  it("generates a masked auth secret only when the first Workers Build needs it", () => {
+  it("generates masked auth and Web Push secrets when the first Workers Build needs them", () => {
     let secretFile;
     deploySource("/customer/repo", {
       workersCi: true,
@@ -239,6 +240,10 @@ describe("HQBase release deployment", () => {
       }),
       randomBytes: () => Buffer.alloc(32, 7),
       randomUUID: () => "00000000-0000-4000-8000-000000000123",
+      generateVapidKeys: () => ({
+        publicKey: "generated-public-key",
+        privateKey: "generated-private-key"
+      }),
       releaseTag: `hqbase:0.1.15:${"a".repeat(64)}`,
       run: (command, args, cwd) => {
         expect(command).toBe("pnpm");
@@ -252,20 +257,26 @@ describe("HQBase release deployment", () => {
         secretFile = args.at(-1);
         expect(statSync(secretFile).mode & 0o777).toBe(0o600);
         expect(JSON.parse(readFileSync(secretFile, "utf8"))).toEqual({
-          BETTER_AUTH_SECRET: Buffer.alloc(32, 7).toString("base64url")
+          BETTER_AUTH_SECRET: Buffer.alloc(32, 7).toString("base64url"),
+          VAPID_PUBLIC_KEY: "generated-public-key",
+          VAPID_PRIVATE_KEY: "generated-private-key"
         });
       }
     });
     expect(existsSync(secretFile)).toBe(false);
   });
-  it("preserves an existing auth secret and does not mask unrelated deploy failures", () => {
+  it("preserves existing secrets and detects only missing installation secrets", () => {
     let deployCalls = 0;
     deploySource("/customer/repo", {
       workersCi: true,
       workerName: "hqbase-deeptake-test",
       attempt: () => ({
         status: 0,
-        stdout: JSON.stringify([{ name: "BETTER_AUTH_SECRET", type: "secret_text" }]),
+        stdout: JSON.stringify([
+          { name: "BETTER_AUTH_SECRET", type: "secret_text" },
+          { name: "VAPID_PUBLIC_KEY", type: "secret_text" },
+          { name: "VAPID_PRIVATE_KEY", type: "secret_text" }
+        ]),
         stderr: ""
       }),
       run: () => {
@@ -273,6 +284,16 @@ describe("HQBase release deployment", () => {
       }
     });
     expect(deployCalls).toBe(1);
+    expect(
+      missingRequiredSecrets(
+        {
+          status: 0,
+          stdout: JSON.stringify([{ name: "BETTER_AUTH_SECRET", type: "secret_text" }]),
+          stderr: ""
+        },
+        ["BETTER_AUTH_SECRET", "VAPID_PUBLIC_KEY", "VAPID_PRIVATE_KEY"]
+      )
+    ).toEqual(["VAPID_PUBLIC_KEY", "VAPID_PRIVATE_KEY"]);
     expect(
       needsInitialAuthSecret(
         {
@@ -291,6 +312,29 @@ describe("HQBase release deployment", () => {
       )
     ).toThrow("wrangler secret list exited");
   });
+  it("adds a VAPID pair to an existing installation without rotating its auth identity", () => {
+    deploySource("/customer/repo", {
+      workersCi: true,
+      workerName: "hqbase-existing",
+      attempt: () => ({
+        status: 0,
+        stdout: JSON.stringify([{ name: "BETTER_AUTH_SECRET", type: "secret_text" }]),
+        stderr: ""
+      }),
+      generateVapidKeys: () => ({
+        publicKey: "upgrade-public-key",
+        privateKey: "upgrade-private-key"
+      }),
+      run: (_command, args) => {
+        expect(args.some((arg) => arg.startsWith("HQBASE_INSTALLATION_ID:"))).toBe(false);
+        const secretFile = args.at(-1);
+        expect(JSON.parse(readFileSync(secretFile, "utf8"))).toEqual({
+          VAPID_PUBLIC_KEY: "upgrade-public-key",
+          VAPID_PRIVATE_KEY: "upgrade-private-key"
+        });
+      }
+    });
+  });
   it("hides successful release bookkeeping output but preserves D1 failures", () => {
     let emitted = "";
     executeSql("/release", "UPDATE release_state SET installed_version = '0.1.12'", {
@@ -320,7 +364,9 @@ describe("HQBase release deployment", () => {
   it("keeps the generated secret out of Deploy to Cloudflare form metadata", () => {
     const packageJson = JSON.parse(readFileSync("package.json", "utf8"));
     expect(packageJson.cloudflare.bindings).not.toHaveProperty("BETTER_AUTH_SECRET");
+    expect(packageJson.cloudflare.bindings).not.toHaveProperty("VAPID_PRIVATE_KEY");
     expect(readFileSync(".env.example", "utf8")).not.toMatch(/^BETTER_AUTH_SECRET=/m);
+    expect(readFileSync(".env.example", "utf8")).not.toMatch(/^VAPID_PRIVATE_KEY=/m);
   });
   it("routes browser navigations to API endpoints before the SPA fallback", () => {
     const wranglerConfig = JSON.parse(readFileSync("wrangler.jsonc", "utf8"));
diff --git a/test/unit/scripts/pwa-build.test.mjs b/test/unit/scripts/pwa-build.test.mjs
index 9b023cf..9674e4c 100644
--- a/test/unit/scripts/pwa-build.test.mjs
+++ b/test/unit/scripts/pwa-build.test.mjs
@@ -50,4 +50,17 @@ describe("PWA build contract", () => {
     expect(worker).toContain('event.data?.type === "SKIP_WAITING"');
     expect(worker).not.toContain("/api/");
   });
+
+  it("generates visible push notifications, unread badging, and safe message navigation", () => {
+    const worker = renderServiceWorker({
+      cacheName: "hqbase-pwa-test-1",
+      precacheUrls: ["/assets/app-abc.js", "/offline.html"]
+    });
+    expect(worker).toContain('addEventListener("push"');
+    expect(worker).toContain('showNotification("New email"');
+    expect(worker).toContain("setAppBadge(unreadCount)");
+    expect(worker).toContain('"hqbase:push-received"');
+    expect(worker).toContain('addEventListener("notificationclick"');
+    expect(worker).toContain('return "/inbox"');
+  });
 });
diff --git a/test/unit/worker/features/notifications/delivery.test.ts b/test/unit/worker/features/notifications/delivery.test.ts
new file mode 100644
index 0000000..fb39d26
--- /dev/null
+++ b/test/unit/worker/features/notifications/delivery.test.ts
@@ -0,0 +1,134 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("web-push", () => {
+  class WebPushError extends Error {
+    statusCode: number;
+    constructor(statusCode: number) {
+      super("push failed");
+      this.statusCode = statusCode;
+    }
+  }
+  return {
+    default: {
+      WebPushError,
+      sendNotification: vi.fn(),
+      setVapidDetails: vi.fn()
+    }
+  };
+});
+vi.mock("@worker/auth/mailbox-access", () => ({ accessibleMailboxIds: vi.fn() }));
+vi.mock("@worker/features/notifications/queries", () => ({
+  countUnreadMessages: vi.fn(),
+  listPushSubscriptionsForMailbox: vi.fn(),
+  markPushSubscriptionSuccessful: vi.fn(),
+  removePushSubscriptionsById: vi.fn()
+}));
+
+import { accessibleMailboxIds } from "@worker/auth/mailbox-access";
+import { notifyInboundMessage } from "@worker/features/notifications/delivery";
+import {
+  countUnreadMessages,
+  listPushSubscriptionsForMailbox,
+  markPushSubscriptionSuccessful,
+  removePushSubscriptionsById
+} from "@worker/features/notifications/queries";
+import type { WorkerEnv } from "@worker/lib/env";
+import webpush from "web-push";
+
+const message = {
+  id: "msg_1",
+  threadId: "thr_1",
+  mailboxId: "mbx_1",
+  direction: "inbound" as const,
+  folder: "inbox" as const,
+  fromAddress: "sender@example.com",
+  to: ["support@example.com"],
+  subject: "Private subject",
+  snippet: "Private snippet",
+  receivedAt: "2026-07-29T12:00:00.000Z",
+  sentAt: null,
+  readAt: null,
+  starredAt: null,
+  hasAttachments: false,
+  createdAt: "2026-07-29T12:00:00.000Z"
+};
+const env = {
+  DB: {} as D1Database,
+  VAPID_PRIVATE_KEY: "private",
+  VAPID_PUBLIC_KEY: "public",
+  VAPID_SUBJECT: "https://hqbase.io"
+} as unknown as WorkerEnv;
+
+describe("push delivery", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.mocked(accessibleMailboxIds).mockResolvedValue(["mbx_1"]);
+    vi.mocked(countUnreadMessages).mockResolvedValue({ catchall: 1, inbox: 2, total: 3 });
+    vi.mocked(listPushSubscriptionsForMailbox).mockResolvedValue([
+      {
+        id: "push_1",
+        user_id: "usr_1",
+        endpoint: "https://push.example/one",
+        p256dh_key: "p256dh",
+        auth_key: "auth",
+        expiration_time: null,
+        role: "owner"
+      },
+      {
+        id: "push_2",
+        user_id: "usr_1",
+        endpoint: "https://push.example/two",
+        p256dh_key: "p256dh",
+        auth_key: "auth",
+        expiration_time: null,
+        role: "owner"
+      }
+    ]);
+  });
+
+  it("sends a minimal encrypted payload to every device and records success", async () => {
+    vi.mocked(webpush.sendNotification).mockResolvedValue({
+      body: "",
+      headers: {},
+      statusCode: 201
+    });
+    await notifyInboundMessage(env, message);
+
+    expect(webpush.sendNotification).toHaveBeenCalledTimes(2);
+    const payload = JSON.parse(
+      vi.mocked(webpush.sendNotification).mock.calls[0]?.[1] as string
+    ) as Record<string, unknown>;
+    expect(payload).toEqual({
+      tag: "hqbase-thread-thr_1",
+      unreadCount: 3,
+      url: "/inbox/msg_1"
+    });
+    expect(JSON.stringify(payload)).not.toContain(message.fromAddress);
+    expect(JSON.stringify(payload)).not.toContain(message.subject);
+    expect(JSON.stringify(payload)).not.toContain(message.snippet);
+    expect(markPushSubscriptionSuccessful).toHaveBeenCalledTimes(2);
+    expect(removePushSubscriptionsById).toHaveBeenCalledWith(env.DB, []);
+  });
+
+  it("prunes gone subscriptions and isolates transient delivery failures", async () => {
+    vi.mocked(webpush.sendNotification)
+      .mockRejectedValueOnce({ statusCode: 410 })
+      .mockRejectedValueOnce({ statusCode: 503 });
+    await expect(notifyInboundMessage(env, message)).resolves.toBeUndefined();
+    expect(removePushSubscriptionsById).toHaveBeenCalledWith(env.DB, ["push_1"]);
+    expect(markPushSubscriptionSuccessful).not.toHaveBeenCalled();
+  });
+
+  it("rechecks live mailbox access before sending", async () => {
+    vi.mocked(accessibleMailboxIds).mockResolvedValue([]);
+    await notifyInboundMessage(env, message);
+    expect(webpush.sendNotification).not.toHaveBeenCalled();
+    expect(countUnreadMessages).not.toHaveBeenCalled();
+  });
+
+  it("does nothing when the stored message has no mailbox", async () => {
+    await notifyInboundMessage(env, { ...message, mailboxId: null });
+    expect(listPushSubscriptionsForMailbox).not.toHaveBeenCalled();
+    expect(webpush.sendNotification).not.toHaveBeenCalled();
+  });
+});
diff --git a/test/unit/worker/index-notifications.test.ts b/test/unit/worker/index-notifications.test.ts
new file mode 100644
index 0000000..10ba549
--- /dev/null
+++ b/test/unit/worker/index-notifications.test.ts
@@ -0,0 +1,56 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  handleInboundEmail: vi.fn(),
+  notifyInboundMessage: vi.fn()
+}));
+
+vi.mock("@worker/email/inbound", () => ({ handleInboundEmail: mocks.handleInboundEmail }));
+vi.mock("@worker/features/notifications/delivery", () => ({
+  notifyInboundMessage: mocks.notifyInboundMessage
+}));
+
+import worker from "@worker/index";
+import type { WorkerEnv } from "@worker/lib/env";
+
+const storedMessage = {
+  id: "msg_1",
+  mailboxId: "mbx_1",
+  threadId: "thr_1"
+};
+
+describe("inbound notification scheduling", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mocks.notifyInboundMessage.mockResolvedValue(undefined);
+  });
+
+  it("does not schedule push for a duplicate inbound message", async () => {
+    mocks.handleInboundEmail.mockResolvedValue({ inserted: false, message: storedMessage });
+    const waitUntil = vi.fn();
+
+    await worker.email(
+      {} as ForwardableEmailMessage,
+      {} as WorkerEnv,
+      { waitUntil } as unknown as ExecutionContext
+    );
+
+    expect(mocks.notifyInboundMessage).not.toHaveBeenCalled();
+    expect(waitUntil).not.toHaveBeenCalled();
+  });
+
+  it("schedules push after a newly stored inbound message", async () => {
+    mocks.handleInboundEmail.mockResolvedValue({ inserted: true, message: storedMessage });
+    const waitUntil = vi.fn();
+
+    await worker.email(
+      {} as ForwardableEmailMessage,
+      {} as WorkerEnv,
+      { waitUntil } as unknown as ExecutionContext
+    );
+
+    expect(mocks.notifyInboundMessage).toHaveBeenCalledWith({}, storedMessage);
+    expect(waitUntil).toHaveBeenCalledOnce();
+    await expect(waitUntil.mock.calls[0]?.[0]).resolves.toBeUndefined();
+  });
+});
diff --git a/vitest.worker.config.ts b/vitest.worker.config.ts
index e6cb6ae..ba03746 100644
--- a/vitest.worker.config.ts
+++ b/vitest.worker.config.ts
@@ -9,7 +9,9 @@ export default defineConfig({
       },
       miniflare: {
         bindings: {
-          BETTER_AUTH_SECRET: "integration-auth-secret-A7x9Q2m4V8p6L1s3"
+          BETTER_AUTH_SECRET: "integration-auth-secret-A7x9Q2m4V8p6L1s3",
+          VAPID_PRIVATE_KEY: "integration-vapid-private-key",
+          VAPID_PUBLIC_KEY: "integration-vapid-public-key"
         },
         serviceBindings: {
           ASSETS: async () => new Response("Not found", { status: 404 })
diff --git a/worker/email/inbound.ts b/worker/email/inbound.ts
index dc35b53..f363d4a 100644
--- a/worker/email/inbound.ts
+++ b/worker/email/inbound.ts
@@ -6,10 +6,10 @@ import { storeInboundEmail } from "./store-email";
 export async function handleInboundEmail(
   message: ForwardableEmailMessage,
   env: WorkerEnv
-): Promise<void> {
+): Promise<Awaited<ReturnType<typeof storeInboundEmail>>> {
   const raw = await new Response(message.raw).arrayBuffer();
   const parsed = await parseRawEmail(raw);
-  await storeInboundEmail(env.DB, env.MAIL_OBJECTS, {
+  return storeInboundEmail(env.DB, env.MAIL_OBJECTS, {
     envelopeRecipient: message.to,
     raw,
     parsed
diff --git a/worker/email/store-email.ts b/worker/email/store-email.ts
index 637eb75..508309f 100644
--- a/worker/email/store-email.ts
+++ b/worker/email/store-email.ts
@@ -15,11 +15,16 @@ export type StoreInboundInput = {
   parsed: ParsedEmail;
 };
 
+export type StoreInboundResult = {
+  inserted: boolean;
+  message: MessageDetail | MessageSummary;
+};
+
 export async function storeInboundEmail(
   db: D1Database,
   bucket: R2Bucket,
   input: StoreInboundInput
-): Promise<MessageDetail | MessageSummary> {
+): Promise<StoreInboundResult> {
   const recipient = input.envelopeRecipient.toLowerCase();
   const initialPlan = planInboundStorage({
     envelopeRecipient: recipient,
@@ -29,7 +34,7 @@ export async function storeInboundEmail(
   const dedupeKey = initialPlan.dedupeKey;
   const duplicate = dedupeKey ? await findDuplicate(db, dedupeKey) : null;
   if (duplicate) {
-    return duplicate;
+    return { inserted: false, message: duplicate };
   }
 
   const timestamp = input.parsed.date ?? nowIso();
@@ -100,7 +105,10 @@ export async function storeInboundEmail(
     });
   }
 
-  return (await getMessageDetail(db, message.id)) ?? message;
+  return {
+    inserted: true,
+    message: (await getMessageDetail(db, message.id)) ?? message
+  };
 }
 
 async function findDuplicate(db: D1Database, dedupeKey: string): Promise<MessageSummary | null> {
diff --git a/worker/features/notifications/delivery.ts b/worker/features/notifications/delivery.ts
new file mode 100644
index 0000000..17bd499
--- /dev/null
+++ b/worker/features/notifications/delivery.ts
@@ -0,0 +1,97 @@
+import webpush from "web-push";
+
+import { accessibleMailboxIds } from "../../auth/mailbox-access";
+import type { WorkerEnv } from "../../lib/env";
+import type { WorkspaceRole } from "../../lib/validation";
+import type { MessageSummary } from "../messages/types";
+import {
+  countUnreadMessages,
+  listPushSubscriptionsForMailbox,
+  markPushSubscriptionSuccessful,
+  removePushSubscriptionsById
+} from "./queries";
+import type { PushSubscriptionRow } from "./types";
+
+export async function notifyInboundMessage(env: WorkerEnv, message: MessageSummary): Promise<void> {
+  const mailboxId = message.mailboxId;
+  if (!mailboxId || !env.VAPID_PUBLIC_KEY || !env.VAPID_PRIVATE_KEY) {
+    return;
+  }
+
+  const subscriptions = await listPushSubscriptionsForMailbox(env.DB, mailboxId);
+  if (subscriptions.length === 0) return;
+
+  webpush.setVapidDetails(
+    env.VAPID_SUBJECT ?? "https://hqbase.io",
+    env.VAPID_PUBLIC_KEY,
+    env.VAPID_PRIVATE_KEY
+  );
+  const byUser = groupSubscriptionsByUser(subscriptions);
+  const deadSubscriptionIds: string[] = [];
+
+  await Promise.all(
+    [...byUser.entries()].map(async ([userId, userSubscriptions]) => {
+      const role = workspaceRole(userSubscriptions[0]?.role);
+      if (!role) return;
+      const mailboxIds = await accessibleMailboxIds(env.DB, userId, role, "read");
+      if (!mailboxIds.includes(mailboxId)) return;
+      const unread = await countUnreadMessages(env.DB, mailboxIds);
+      const payload = JSON.stringify({
+        tag: `hqbase-thread-${message.threadId}`,
+        unreadCount: unread.total,
+        url: message.folder === "catchall" ? `/catch-all/${message.id}` : `/inbox/${message.id}`
+      });
+
+      await Promise.all(
+        userSubscriptions.map(async (subscription) => {
+          try {
+            await webpush.sendNotification(
+              {
+                endpoint: subscription.endpoint,
+                expirationTime: subscription.expiration_time,
+                keys: {
+                  auth: subscription.auth_key,
+                  p256dh: subscription.p256dh_key
+                }
+              },
+              payload,
+              { TTL: 24 * 60 * 60, urgency: "normal" }
+            );
+            await markPushSubscriptionSuccessful(env.DB, subscription.id);
+          } catch (error: unknown) {
+            if (isExpiredSubscription(error)) deadSubscriptionIds.push(subscription.id);
+          }
+        })
+      );
+    })
+  );
+
+  await removePushSubscriptionsById(env.DB, deadSubscriptionIds);
+}
+
+function groupSubscriptionsByUser(
+  subscriptions: PushSubscriptionRow[]
+): Map<string, PushSubscriptionRow[]> {
+  const grouped = new Map<string, PushSubscriptionRow[]>();
+  for (const subscription of subscriptions) {
+    grouped.set(subscription.user_id, [...(grouped.get(subscription.user_id) ?? []), subscription]);
+  }
+  return grouped;
+}
+
+function workspaceRole(value: string | null | undefined): WorkspaceRole | null {
+  return value === "owner" || value === "admin" || value === "member" ? value : null;
+}
+
+function isExpiredSubscription(error: unknown): boolean {
+  const statusCode =
+    error instanceof webpush.WebPushError
+      ? error.statusCode
+      : typeof error === "object" &&
+          error !== null &&
+          "statusCode" in error &&
+          typeof error.statusCode === "number"
+        ? error.statusCode
+        : 0;
+  return statusCode === 404 || statusCode === 410;
+}
diff --git a/worker/features/notifications/queries.ts b/worker/features/notifications/queries.ts
new file mode 100644
index 0000000..9ab9a66
--- /dev/null
+++ b/worker/features/notifications/queries.ts
@@ -0,0 +1,111 @@
+import { newId, nowIso } from "../../db/client";
+import type { PushSubscriptionInput, PushSubscriptionRow, UnreadCounts } from "./types";
+
+export async function countUnreadMessages(
+  db: D1Database,
+  mailboxIds: string[]
+): Promise<UnreadCounts> {
+  if (mailboxIds.length === 0) {
+    return { catchall: 0, inbox: 0, total: 0 };
+  }
+
+  const result = await db
+    .prepare(
+      `SELECT folder, COUNT(*) AS unread_count
+       FROM messages
+       WHERE direction = 'inbound'
+         AND read_at IS NULL
+         AND folder IN ('inbox', 'catchall')
+         AND mailbox_id IN (${mailboxIds.map(() => "?").join(", ")})
+       GROUP BY folder`
+    )
+    .bind(...mailboxIds)
+    .all<{ folder: "catchall" | "inbox"; unread_count: number }>();
+  const inbox = result.results.find((row) => row.folder === "inbox")?.unread_count ?? 0;
+  const catchall = result.results.find((row) => row.folder === "catchall")?.unread_count ?? 0;
+  return { catchall, inbox, total: inbox + catchall };
+}
+
+export async function savePushSubscription(
+  db: D1Database,
+  userId: string,
+  subscription: PushSubscriptionInput
+): Promise<void> {
+  const timestamp = nowIso();
+  await db
+    .prepare(
+      `INSERT INTO push_subscriptions (
+         id, user_id, endpoint, p256dh_key, auth_key, expiration_time, created_at, updated_at
+       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+       ON CONFLICT(endpoint) DO UPDATE SET
+         user_id = excluded.user_id,
+         p256dh_key = excluded.p256dh_key,
+         auth_key = excluded.auth_key,
+         expiration_time = excluded.expiration_time,
+         updated_at = excluded.updated_at`
+    )
+    .bind(
+      newId("push"),
+      userId,
+      subscription.endpoint,
+      subscription.keys.p256dh,
+      subscription.keys.auth,
+      subscription.expirationTime,
+      timestamp,
+      timestamp
+    )
+    .run();
+}
+
+export async function removePushSubscription(
+  db: D1Database,
+  userId: string,
+  endpoint: string
+): Promise<void> {
+  await db
+    .prepare("DELETE FROM push_subscriptions WHERE user_id = ? AND endpoint = ?")
+    .bind(userId, endpoint)
+    .run();
+}
+
+export async function listPushSubscriptionsForMailbox(
+  db: D1Database,
+  mailboxId: string
+): Promise<PushSubscriptionRow[]> {
+  const result = await db
+    .prepare(
+      `SELECT subscription.id, subscription.user_id, subscription.endpoint,
+         subscription.p256dh_key, subscription.auth_key, subscription.expiration_time, user.role
+       FROM push_subscriptions subscription
+       JOIN "user" user ON user.id = subscription.user_id
+       WHERE COALESCE(user.banned, 0) = 0
+         AND (
+           user.role = 'owner'
+           OR EXISTS (
+             SELECT 1
+             FROM mailbox_grants grant_row
+             WHERE grant_row.user_id = subscription.user_id
+               AND grant_row.mailbox_id = ?
+               AND grant_row.access_level IN ('read', 'agent', 'manager')
+           )
+         )`
+    )
+    .bind(mailboxId)
+    .all<PushSubscriptionRow>();
+  return result.results;
+}
+
+export async function markPushSubscriptionSuccessful(db: D1Database, id: string): Promise<void> {
+  await db
+    .prepare("UPDATE push_subscriptions SET last_success_at = ?, updated_at = ? WHERE id = ?")
+    .bind(nowIso(), nowIso(), id)
+    .run();
+}
+
+export async function removePushSubscriptionsById(db: D1Database, ids: string[]): Promise<void> {
+  if (ids.length === 0) return;
+  await db
+    .prepare(`DELETE FROM push_subscriptions WHERE id IN (${ids.map(() => "?").join(", ")})`)
+    .bind(...ids)
+    .run();
+}
diff --git a/worker/features/notifications/routes.ts b/worker/features/notifications/routes.ts
new file mode 100644
index 0000000..74d9b9e
--- /dev/null
+++ b/worker/features/notifications/routes.ts
@@ -0,0 +1,67 @@
+import { Hono } from "hono";
+import { z } from "zod";
+
+import { accessibleMailboxIds } from "../../auth/mailbox-access";
+import { requireAuthContext } from "../../auth/session";
+import type { HonoApp } from "../../lib/env";
+import { AppError } from "../../lib/errors";
+import { parseWith } from "../../lib/validation";
+import { countUnreadMessages, removePushSubscription, savePushSubscription } from "./queries";
+
+export const notificationRoutes = new Hono<HonoApp>();
+
+const base64UrlSchema = z
+  .string()
+  .min(16)
+  .max(256)
+  .regex(/^[A-Za-z0-9_-]+$/);
+const endpointSchema = z
+  .string()
+  .url()
+  .max(2048)
+  .refine((value) => value.startsWith("https://"), {
+    message: "Push subscription endpoints must use HTTPS."
+  });
+const subscriptionSchema = z.object({
+  endpoint: endpointSchema,
+  expirationTime: z.number().int().nonnegative().nullable(),
+  keys: z.object({
+    auth: base64UrlSchema,
+    p256dh: base64UrlSchema
+  })
+});
+const unsubscribeSchema = z.object({ endpoint: endpointSchema });
+
+notificationRoutes.get("/status", async (c) => {
+  const auth = await requireAuthContext(c.env, c.req.raw);
+  const mailboxIds = await accessibleMailboxIds(c.env.DB, auth.user.id, auth.user.role, "read");
+  return c.json({
+    unread: await countUnreadMessages(c.env.DB, mailboxIds),
+    vapidPublicKey: configuredPublicKey(c.env)
+  });
+});
+
+notificationRoutes.put("/subscription", async (c) => {
+  const auth = await requireAuthContext(c.env, c.req.raw);
+  if (!configuredPublicKey(c.env) || !c.env.VAPID_PRIVATE_KEY) {
+    throw new AppError(
+      "PUSH_NOT_CONFIGURED",
+      "Push notifications are not configured for this HQBase installation.",
+      503
+    );
+  }
+  const subscription = parseWith(subscriptionSchema, await c.req.json<unknown>().catch(() => ({})));
+  await savePushSubscription(c.env.DB, auth.user.id, subscription);
+  return c.json({ ok: true });
+});
+
+notificationRoutes.delete("/subscription", async (c) => {
+  const auth = await requireAuthContext(c.env, c.req.raw);
+  const { endpoint } = parseWith(unsubscribeSchema, await c.req.json<unknown>().catch(() => ({})));
+  await removePushSubscription(c.env.DB, auth.user.id, endpoint);
+  return c.json({ ok: true });
+});
+
+function configuredPublicKey(env: HonoApp["Bindings"]): string | null {
+  return env.VAPID_PUBLIC_KEY?.trim() || null;
+}
diff --git a/worker/features/notifications/types.ts b/worker/features/notifications/types.ts
new file mode 100644
index 0000000..f98f5fa
--- /dev/null
+++ b/worker/features/notifications/types.ts
@@ -0,0 +1,24 @@
+export type UnreadCounts = {
+  catchall: number;
+  inbox: number;
+  total: number;
+};
+
+export type PushSubscriptionInput = {
+  endpoint: string;
+  expirationTime: number | null;
+  keys: {
+    auth: string;
+    p256dh: string;
+  };
+};
+
+export type PushSubscriptionRow = {
+  auth_key: string;
+  endpoint: string;
+  expiration_time: number | null;
+  id: string;
+  p256dh_key: string;
+  role: string | null;
+  user_id: string;
+};
diff --git a/worker/index.ts b/worker/index.ts
index e649ff2..0f20527 100644
--- a/worker/index.ts
+++ b/worker/index.ts
@@ -1,5 +1,6 @@
 import { handleInboundEmail } from "./email/inbound";
 import { handleMcpRoute } from "./features/mcp/route";
+import { notifyInboundMessage } from "./features/notifications/delivery";
 import { consumeJobs } from "./jobs/consumer";
 import type { WorkerEnv } from "./lib/env";
 import { apiRoutes } from "./routes";
@@ -35,9 +36,16 @@ export default {
   async email(
     message: ForwardableEmailMessage,
     env: WorkerEnv,
-    _ctx: ExecutionContext
+    ctx: ExecutionContext
   ): Promise<void> {
-    await handleInboundEmail(message, env);
+    const stored = await handleInboundEmail(message, env);
+    if (stored.inserted) {
+      ctx.waitUntil(
+        notifyInboundMessage(env, stored.message).catch(() => {
+          // Push delivery is additive and never changes accepted inbound mail.
+        })
+      );
+    }
   },
 
   async scheduled(_controller: ScheduledController, env: WorkerEnv): Promise<void> {
diff --git a/worker/lib/env.ts b/worker/lib/env.ts
index 0da8d9d..e0b47a8 100644
--- a/worker/lib/env.ts
+++ b/worker/lib/env.ts
@@ -12,6 +12,9 @@ type WorkerEnvOverrides = {
   HQBASE_RELEASE_PUBLIC_KEY?: string;
   HQBASE_INSTALLATION_ID?: string;
   HQBASE_JOBS?: Queue;
+  VAPID_PRIVATE_KEY?: string;
+  VAPID_PUBLIC_KEY?: string;
+  VAPID_SUBJECT?: string;
 };
 
 export type WorkerEnv = Omit<Cloudflare.Env, keyof WorkerEnvOverrides> & WorkerEnvOverrides;
diff --git a/worker/routes/index.ts b/worker/routes/index.ts
index 0fc1ab6..ee47574 100644
--- a/worker/routes/index.ts
+++ b/worker/routes/index.ts
@@ -8,6 +8,7 @@ import { mailboxAccessRoutes } from "../features/mailbox-access/routes";
 import { mailboxRoutes } from "../features/mailboxes/routes";
 import { conversationRoutes } from "../features/messages/conversation-routes";
 import { attachmentRoutes, messageRoutes } from "../features/messages/routes";
+import { notificationRoutes } from "../features/notifications/routes";
 import { operationRoutes } from "../features/operations/routes";
 import { sendRoutes } from "../features/send/routes";
 import { sessionControlRoutes } from "../features/sessions/routes";
@@ -56,6 +57,7 @@ apiRoutes.route("/api/operations", operationRoutes);
 apiRoutes.route("/api/mailboxes", mailboxRoutes);
 apiRoutes.route("/api/conversations", conversationRoutes);
 apiRoutes.route("/api/messages", messageRoutes);
+apiRoutes.route("/api/notifications", notificationRoutes);
 apiRoutes.route("/api/attachments", attachmentRoutes);
 apiRoutes.route("/api/users", userRoutes);
 apiRoutes.route("/api/updates", updateRoutes);